PSD2 API - Documentation

Welcome

Welcome to the TFS PSD2 API Reference!

TFS offers easy to use and easy to implement Service API. The API provides an interface for connecting and extracting online banking account information and payment initiation services.

After fulfilling the regulatory requirements and obtaining licence to provide payment services from your national regulator, you will be able to consume various set of production API.

Getting started

To get started with our API you will need to:

  • browse the available API and find if there is any suitable for your applications
  • use valid eIDAS QSEAL electronic seal certificate. Access to our APIs requires usage of an eIDAS QSEAL electronic seal certificate. Use the EU Trust Service Browser to find a local qualified trust service provider that can issue QSEAL certificates. You will need it for both developer and production API.
  • test your application on development enviroment.
  • access production API.

If you have technical questions please write us an email developer@tfs.bg

URLs

For development environment:
BASE API: https://developer.transcard.bg/v1

For production environment:
BASE API: https://gateway.transcard.bg/v1

API requests

request_token

POST /request_token

Description:
This request starts each session to access the customer's resources. It is always initiated with a valid certificate. Two options are met:
- upon initial submission of consent by a consumers
- in case of a valid access_token and preparation for access to resources before the call for a specific request.

Parameters:
authorization
Optional in header
string

In the case of a request with access_token in this parameter, a access_token shall be submitted in the following format:

Bearer REPLACE_ACCESS_TOKEN
x-request-id
Required in header
string

Unique query number as generated by the initiating party.

"pattern": "^[a-zA-Z1-9\-]{200}$"
request_roles
Optional in body
string

Specifies the requested access to the resources. Valid values are:

AIS - access to account information
PIS - initiation of payment orders

"enum": [
        "AIS",
        "PIS",
    ]

Required upon request of consent

back_url
Optional in body
string

It shall be submitted by the initiating Party and the url at which the customer user will be redirected after completing the consent process on the TFS website shall be completed in this URL.

Required upon request of consent

Responses:

Depending on the type of request (whether to request consent for access or access to a resource), a specific response is returned.

200

ОК

By the event of an resource access session, the following parameters are returned:

request_token - request token
granted_roles - ist of approved roles (AIS,PIS)

In case of consent session, we have a parameter:

authorization_url - url to redirect a customer user to an in-depth identification form to confirm the requested access. The link is valid for a single call.

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//Request for consent
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'x-request-id: 12345678-1234-1234-1234-1234567890'
-d 'request_roles=AIS,PIS'
--data-urlencode "back_url=https://linktotpp.com/process-auth"
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the consent request
{
"request_token":"F7712BF6CC62CB75CBE6ED2AC12FEDCF79C29FFC8FCD562547BD0F3309CD7F20",
"authorization_url":"https:\/\/developer.transcard.bg\/sca-gw\/authorization\/F7712BF6CC62CB75CBE6ED7AC12BBDCF79C29FFC8FCD562547BD0F3309CD7F20"
}

show more

access_token

POST /access_token

Description:
With this request, the payment service provider receives a access_token with which it can initiate requests for access to the customer's resources. The request shall be called immediately upon receipt of the response_token following the consent of the customer. It is always initiated with a valid certificate.

Parameters:
authorization
Required in header
string

The resulting response_token is presented here as a result of consent and the passage of the customer through an in-depth identification process. The parameter shall be submitted in the following format:

Bearer REPLACE_RESPONSE_TOKEN

Responses:
200

ОК

By a successful consent, a pair of tokens and additional parameters related to the given access shall be returned:

access_token - used to access resources for multiple use. There's a life specified in expires_in. After the token expires, it can be resumed with a refresh_token request.
expires_in - access_token validity in seconds.
refresh_token - access_token renewal token if it has expired or compromised. After use, deactivate.
granted_roles - list of approved roles (AIS,PIS)
x_request_id - unique session number supplied in request_token request.

In case of a valid token but denied access, a code 2 error shall be returned:

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//request to receive access_token
curl -X POST 'https://developer.transcard.bg/v1/access_token'
-H 'Authorization: Bearer E527E232CB06C68B2D4FE02CF41E9AE1E0A327742F685D76F45C871CF3679E34 '
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//response to the request
{
"access_token":"D302ACE946BACA789633931DCAG7B559940B8C45C380ACEC89F7B4287B6CA015",
"expires_in":"5184000",
"refresh_token":"4TGBF2FF6F1CD10C63DB152E626148B2Z1E2173E146BEB8BF46F03A0EA8466E0",
"granted_roles":"AIS,PIS",
"x_request_id":"12345678-1234-1234-1234-123456789"
}

show more

refresh_token

POST /refresh_token

Description:
The request allows a new token pair - access_token and refresh_token to be generated when the access_token has expired/invalid or must be resumed due to compression. Reissue occurs automatically by filing the request and certificate + refresh_token. The refresh_token renewal token can only be used once and it is invalid. Using refresh_token automatically makes the last access_token invalid.

Parameters:
authorization
Required in header
string

The received refresh_token is being submitted here. The parameter shall be submitted in the following format:

Bearer REPLACE_REFRESH_TOKEN

Responses:
200

ОК

The request returns the following data:

access_token - used to access resources for multiple use. There's a life specified in expires_in. After token expiration can be resumed with a refresh_token request
expires_in - access_token validity in seconds.
refresh_token - access_token renewal token if it has expired or compromised. After use, deactivate.

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//refresh_token request
curl -X POST 'https://developer.transcard.bg/v1/refresh_token'
-H 'Authorization: Bearer E527E232CB06C68B2D4FE02CF41E9AE1E0A327742F685D76F45C871CF3679E34 '
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"access_token":"D302ACE946BACA789633931DCAG7B559940B8C45C380ACEC89F7B4287B6CA015",
"expires_in":"5184000",
"refresh_token":"4TGBF2FF6F1CD10C63DB152E626148B2Z1E2173E146BEB8BF46F03A0EA8466E0"
}

show more

delete_token

POST /delete_token

Description:
The request allows you to deactivate/delete the token with this and the consent given by the consumers. Deletion occurs by filing the request and certificate + access_token.

Parameters:
authorization
Required in header
string

The received access_token is being submitted here. The parameter shall be submitted in the following format:

Bearer REPLACE_ACCESS_TOKEN

Responses:
200

ОК

The request returns the following data:

expires_in - token validity in seconds. If the operation was successfully returned 0 seconds

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//delete_token request
curl -X POST 'https://developer.transcard.bg/v1/delete_token'
-H 'Authorization: Bearer E527E232CB06C68B2D4FE02CF41E9AE1E0A327742F685D76F45C871CF3679E34 '
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"expires_in":"0",
}

show more

A list of available accounts

GET /accounts

Description:
Read the identifiers of the available payment accounts, depending on the consent granted. The request is called directly by the payment service provider. Requires a previously received valid access_token with rights to perform operations with AIS. As a result, data are returned to JSON format.
If the request limit is reached, a redirect link to the TFS SCA form is returned.

Parameters:
authorization
Required in header
string

The request_token received is being submitted here. The parameter shall be submitted in the following format:

Bearer REPLACE_REQUEST_TOKEN
Accept
Optional in query
string

Parameter defining the format of the data to be returned json only.

application/json
back_url
Optional in body
string

It shall be submitted by the initiating Party and the url at which the customer user will be redirected after verification process on the TFS website is completed in this URL.

Required in verification

Responses:

Depending on whether the request is subject to a customer authentication, a specific response is returned.

200

ОК

- In case of return of available accounts:

"schema": {
    "type": "object",
    "properties": {
    "accounts": {
        "type": "array",
        "items": {
            [{
                "type": "object",
                "required": [
                    "currency",
                    "resourceId",
                    "iban",
                    "name",
                    "product"
                ],
                "properties": {
                    "resourceId": {
                        "type": "string",
                        "description": "This is the data element to be used in the path when retrieving data from a dedicated account."
                    },
                    "iban": {
                        "type": "string",
                        "description": "IBAN of account"
                    },
                    "name": {
                        "type": "string",
                        "description": "Masked PAN [***789] "
                    },
                    "product": {
                        "type": "string",
                        "description": "Product Name of the Bank for this account"
                    },
                    "currency": {
                        "type": "string",
                        "description": "ISO 4217 code"
                    },
                    
                }
            }]

        }
    }
}

- In the event of a redirection to perform a customer authentication of the user, the following parameters shall be returned:

authorization_url - url to redirect a customer to a form for a customer authentication to confirm the operation. The link is valid for a single call.

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//accounts request
curl -X POST 'https://developer.transcard.bg/v1/accounts'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'accept=application/json'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{ "accounts":[{
"resourceId":"BG12TRIV40031234567890",
"iban":"BG12TRIV40031234567890",
"currency":"BGN",
"product":"trans.cash Mastercard",
"name":"***1234"
}
]}
}
 show more

//required SCA request
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//accounts request
curl -X POST 'https://developer.transcard.bg/v1/accounts'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
--data-urlencode "back_url=https://link-to-tpp/process-auth/"
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"redirect_token":"230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD",
"authorization_url":"https:\/\/developer.transcard.bg\/sca-gw\/auth-request\/230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD"
}

//accounts request after SCA
curl -X POST 'https://developer.transcard.bg/v1/accounts'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{ "accounts":[{
"resourceId":"BG12TRIV40031234567890",
"iban":"BG12TRIV40031234567890",
"currency":"BGN",
"product":"trans.cash Mastercard",
"name":"***1234"
}
]}
}
 show more

Account details

GET /accounts/{resourceId}

Description:
Reads details about an account, depending on the consent granted. The request is called directly by the payment service provider. Requires a previously received valid access_token with rights to perform operations with AIS. As a result, data are returned to JSON format.
If the request limit is reached, a redirect link to the TFS SCA form is returned.

Parameters:
authorization
Required in header
string

The request_token received is being submitted here. The parameter shall be submitted in the following format:

Bearer REPLACE_REQUEST_TOKEN
resourceId
Required in path
string

This identification is denoting the addressed account. The resourceId is retrieved by using a "Read Account List" call. Its value is constant at least throughout the lifecycle of a given consent.

Accept
Optional in query
string

Parameter defining the format of the data to be returned json only.

application/json
back_url
Optional in body
string

It shall be submitted by the initiating Party and the url at which the customer user will be redirected after verification process on the TFS website is completed in this URL.

Required in verification

Responses:

Depending on whether the request is subject to a customer authentication, a specific response is returned.

200

ОК

- In case of return of available account details:

"schema": {
    "type": "object",
    "properties": {
        "account": {
            
            "type": "object",
            "required": [
                "currency",
                "resourceId",
                "iban",
                "name",
                "product"
            ],
            "properties": {
                "resourceId": {
                    "type": "string",
                    "description": "This is the data element to be used in the path when retrieving data from a dedicated account."
                },
                "iban": {
                    "type": "string",
                    "description": "IBAN of account"
                },
                "name": {
                    "type": "string",
                    "description": "Masked PAN [***789] "
                },
                "product": {
                    "type": "string",
                    "description": "Product Name of the Bank for this account"
                },
                "currency": {
                    "type": "string",
                    "description": "ISO 4217 code"
                },
                
            }
        }

    }
}

- In the event of a redirection to perform a customer authentication of the user, the following parameters shall be returned:

authorization_url - url to redirect a customer to a form for a customer authentication to confirm the operation. The link is valid for a single call.

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//account details request
curl -X POST 'https://developer.transcard.bg/v1/accounts/BG12TRIV40031234567890'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'accept=application/json'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{ "account":{
"resourceId":"BG12TRIV40031234567890",
"iban":"BG12TRIV40031234567890",
"currency":"BGN",
"product":"trans.cash Mastercard",
"name":"***1234"
}
}
 show more

//required SCA request
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//account details request
curl -X POST 'https://developer.transcard.bg/v1/accounts/BG12TRIV40031234567890'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
--data-urlencode "back_url=https://link-to-tpp/process-auth/"
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"redirect_token":"230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD",
"authorization_url":"https:\/\/developer.transcard.bg\/sca-gw\/auth-request\/230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD"
}

//accounts request after SCA
curl -X POST 'https://developer.transcard.bg/v1/accounts/BG12TRIV40031234567890'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{ "account":{
"resourceId":"BG12TRIV40031234567890",
"iban":"BG12TRIV40031234567890",
"currency":"BGN",
"product":"trans.cash Mastercard",
"name":"***1234"
}
}
 show more

Account balance list

GET /accounts/{resourceId}/balances

Description:
Reads the balance list for a given account addressed by "resourceId". The request is called directly by the payment service provider. Requires a previously received valid access_token with rights to perform operations with AIS. As a result, data are returned to JSON format.
If the request limit is reached, a redirect link to the TFS SCA form is returned.

Parameters:
authorization
Required in header
string

The request_token received is being submitted here. The parameter shall be submitted in the following format:

Bearer REPLACE_REQUEST_TOKEN
resourceId
Required in path
string

This identification is denoting the addressed account. The resourceId is retrieved by using a "Read Account List" call. Its value is constant at least throughout the lifecycle of a given consent.

Accept
Optional in query
string

Parameter defining the format of the data to be returned json only.

application/json
back_url
Optional in body
string

It shall be submitted by the initiating Party and the url at which the customer user will be redirected after verification process on the TFS website is completed in this URL.

Required in verification

Responses:

Depending on whether the request is subject to a customer authentication, a specific response is returned.

200

ОК

- In case of return of available balance list:

"schema": {
    "type": "object",
    "properties": {
        "account": {
            "properties": {
                "iban": {
                    "type": "string"
                },
                "bban": {
                    "type": "string"
                }
            }
        },
        "balances": {
            "type": "array",
            "items": {
                "type": "object",
                "required": [
                    "balanceAmount"
                ],
                "properties": {
                    "balanceType": {
                        "type": "string"
                    },
                    "balanceAmount": {
                        {
                            "type": "object",
                            "required": [
                                "currency",
                                "amount"
                            ],
                            "properties": {
                                "currency": {
                                    "type": "string",
                                    "description": "ISO 4217 code"
                                },
                                "amount": {
                                    "type": "string",
                                    "pattern": "^[0-9]\\d{0,13}(\\.\\d{1,2})?$"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

- In the event of a redirection to perform a customer authentication of the user, the following parameters shall be returned:

authorization_url - url to redirect a customer to a form for a customer authentication to confirm the operation. The link is valid for a single call.

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//account balance list request
curl -X POST 'https://developer.transcard.bg/v1/accounts/BG12TRIV40031234567890/balances'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'accept=application/json'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{"account":{
 "iban":"BG12TRIV40031234567890",
 "bban":"TRIV40031234567890"
 },
 "balances":[{
  "balanceType":"interimAvailable",
  "balanceAmount":{
    "currency":"BGN",
    "amount":"709.20" }
  }]
}
 show more

//required SCA request
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//account balance list request
curl -X POST 'https://developer.transcard.bg/v1/accounts/BG12TRIV40031234567890/balances'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
--data-urlencode "back_url=https://link-to-tpp/process-auth/"
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"redirect_token":"230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD",
"authorization_url":"https:\/\/developer.transcard.bg\/sca-gw\/auth-request\/230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD"
}

//accounts balance list after SCA
curl -X POST 'https://developer.transcard.bg/v1/accounts/BG12TRIV40031234567890/balances'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{"account":{
 "iban":"BG12TRIV40031234567890",
 "bban":"TRIV40031234567890"
 },
 "balances":[{
  "balanceType":"interimAvailable",
  "balanceAmount":{
    "currency":"BGN",
    "amount":"709.20" }
  }]
}
 show more

Account transaction list

GET /accounts/{resourceId}/transactions

Description:
Read transaction lists of a given account dressed by "resourceId", depending on the steering parameter "bookingStatus" . The request is called directly by the payment service provider. Requires a previously received valid access_token with rights to perform operations with AIS. As a result, data are returned to JSON format for all of the specified account and period.
The request allows access to the Cardholder's transactions after client identification in the TFS Web form. After successful verification it will be possible to make direct AIS requests with the initially generated request token. There is a limit of 50 direct requests per 6 hours. If the request limit is reached, a redirect link to the TFS SCA form is returned. It is mandatory to pass through SCA when a period of more than 180 days is set.
If the request limit is reached, a redirect link to the TFS SCA form is returned.

Parameters:
authorization
Required in header
string

The request_token received is being submitted here. The parameter shall be submitted in the following format:

Bearer REPLACE_REQUEST_TOKEN
resourceId
Required in path
string

This identification is denoting the addressed account. The resourceId is retrieved by using a "Read Account List" call. Its value is constant at least throughout the lifecycle of a given consent.

accept
Optional in query
string

Parameter defining the format of the data to be returned json only.

application/json
date_from
Optional in query
string / ISOdate

the start date of the lookup period. The date shall be submitted in format [YYYY.MM.DD]

 "pattern": "([12]\\d{3}.(0[1-9]|1[0-2]).(0[1-9]|[12]\\d|3[01]))"
date_to
Optional in query
string / ISOdate

end date of the lookup period. The date shall be submitted in format [YYYY.MM.DD]

 "pattern": "([12]\\d{3}.(0[1-9]|1[0-2]).(0[1-9]|[12]\\d|3[01]))"
back_url
Optional in body
string

It shall be submitted by the initiating Party and the url at which the customer user will be redirected after verification process on the TFS website is completed in this URL.

Required in verification

Responses:

Depending on whether the request is subject to a customer authentication, a specific response is returned.

200

ОК

- In case of return of available transaction list:

"schema": {
    "type": "object",
    "properties": {
        "account": {
            "properties": {
                "iban": {
                    "type": "string"
                },
                "bban": {
                    "type": "string"
                }
            }
        },
        "transactions": {
             "properties": {
                "booked": {
                    "type": "array",
                    "items": {

                        "type": "object",
                        "required": [
                            "transactionAmount"
                        ],
                        "properties": {
                            "transactionId": {
                                "type": "string",
                                "description": "Unique identification number"
                            },
                            "bookingDate": {
                                "type": "string",
                                "format": "date"
                            },
                            "valueDate": {
                                "type": "string",
                                "format": "date"
                            },
                            "transactionAmount": {
                                "type": "object",
                                "required": [
                                    "currency",
                                    "amount"
                                ],
                                "properties": {
                                    "currency": {
                                        "type": "string",
                                        "description": "ISO 4217 code"
                                    },
                                    "amount": {
                                        "type": "string",
                                        "pattern": "^[0-9]\\d{0,13}(\\.\\d{1,2})?$"
                                    }
                                }
                            },

                            currencyExchange:   {

                                "description": "Exchange Rate",
                                "type": "object",
                                "required": [
                                    "currencyFrom",
                                    "rateFrom",
                                    "currencyTo",
                                    "rateTo",
                                    "rateDate"
                                ],
                                    "properties": {
                                        "currencyFrom": {
                                        "type" : "string",
                                        "description":  "From currency."                                                    
                                    },
                                    
                                    "rateFrom": {
                                        "type" : "string",
                                        "description":  "Conversion factor from target to source currency."
                                    },
                                    "currencyTo":   {
                                        "type" : "string",
                                        "description":  "To currency."
                                    },
                                    "rateTo":   {
                                        "type" : "string",
                                        "description":  "Conversion factor from source to target currency."
                                    },
                                    "rateDate": {
                                        "type" : "string",
                                        "format": "ISODate",
                                        "description":  "Quotation date of the exchange rate."
                                    }                                                           
                                    }
                            },


                            "creditorName": {
                                "type": "string",
                                "description": "Name of the creditor if a “Debited” transaction"
                            },
                            "creditorAccount": {
                                "properties": {
                                    "iban": {
                                        "type": "string"
                                    },
                                    "bban": {
                                        "type": "string"
                                    }
                                }
                            },
                            "debtorName": {
                                "type": "string",
                                "description": "Name of the debtor if a “Credited” transaction"
                            },
                            "debtorAccount": {
                                "properties": {
                                    "iban": {
                                        "type": "string"
                                    },
                                    "bban": {
                                        "type": "string"
                                    }
                                }
                            },
                            "remittanceInformationUnstructured": {
                                "type": "string"
                            }
                        }
                    }
                },
                "pending": {
                    "type": "array",
                    "items": {
                    
                        "type": "object",
                        "required": [
                            "transactionAmount"
                        ],
                        "properties": {
                            "transactionId": {
                                "type": "string",
                                "description": "Unique identification number"
                            },
                            "bookingDate": {
                                "type": "string",
                                "format": "date"
                            },
                            "valueDate": {
                                "type": "string",
                                "format": "date"
                            },
                            "transactionAmount": {
                                "type": "object",
                                "required": [
                                    "currency",
                                    "amount"
                                ],
                                "properties": {
                                    "currency": {
                                        "type": "string",
                                        "description": "ISO 4217 code"
                                    },
                                    "amount": {
                                        "type": "string",
                                        "pattern": "^[0-9]\\d{0,13}(\\.\\d{1,2})?$"
                                    }
                                }
                            },

                            currencyExchange:   {

                                "description": "Exchange Rate",
                                "type": "object",
                                "required": [
                                    "currencyFrom",
                                    "rateFrom",
                                    "currencyTo",
                                    "rateTo",
                                    "rateDate"
                                ],
                                    "properties": {
                                        "currencyFrom": {
                                            "type" : "string",
                                            "description":  "From currency."                                                    
                                        },
                                        
                                        "rateFrom": {
                                            "type" : "string",
                                            "description":  "Conversion factor from target to source currency."
                                        },
                                        "currencyTo":   {
                                            "type" : "string",
                                            "description":  "To currency."
                                        },
                                        "rateTo":   {
                                            "type" : "string",
                                            "description":  "Conversion factor from source to target currency."
                                        },
                                        "rateDate": {
                                            "type" : "string",
                                            "format": "ISODate",
                                            "description":  "Quotation date of the exchange rate."
                                        }                                                           
                                    }
                            },


                            "creditorName": {
                                "type": "string",
                                "description": "Name of the creditor if a “Debited” transaction"
                            },
                            "creditorAccount": {
                                "properties": {
                                    "iban": {
                                        "type": "string"
                                    },
                                    "bban": {
                                        "type": "string"
                                    }
                                }
                            },
                            "debtorName": {
                                "type": "string",
                                "description": "Name of the debtor if a “Credited” transaction"
                            },
                            "debtorAccount": {
                                "properties": {
                                    "iban": {
                                        "type": "string"
                                    },
                                    "bban": {
                                        "type": "string"
                                    }
                                }
                            },
                            "remittanceInformationUnstructured": {
                                "type": "string"
                            }
                        }
                    }
                }
            }
        }
    }
}

- In the event of a redirection to perform a customer authentication of the user, the following parameters shall be returned:

authorization_url - url to redirect a customer to a form for a customer authentication to confirm the operation. The link is valid for a single call.

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//account transaction list request
curl -X POST 'https://developer.transcard.bg/v1/accounts/BG12TRIV40031234567890/transactions'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'accept=application/json&date_from=2023.07.01&date_to=2023.07.07&bookingStatus=both'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{account":{
 "iban":"BG12TRIV40031234567890",
 "bban":"TRIV40031234567890"
 },
 "transactions":{
  "pending":[{
  "transactionId":"032529112050G",
  "creditorName":"Iva Ivanova",
  "creditorAccount":{
    "iban":"GR1234567890123456789012345"
  },
  "transactionAmount":{
    "currency":"EUR",
    "amount":"1.00"},
    "debtorName": "Иван Петров Иванов",
    "debtorAccount":{
      "iban":"BG12TRIV40031234567890"
    },
    "bookingDate":"2023-07-07",
    "valueDate":"",
    "remittanceInformationUnstructured":"Нареден превод , рег. № 032529112050G Получател: Iva Ivanova, GR1234567890123456789012345",
    "currencyExchange":{
    "currencyFrom":"EUR",
    "rateFrom":"0.51129",
    "currencyTo":"BGN",
    "rateTo":"1.95583",
    "rateDate":"2023-07-07"
    }
  }
  ],
  "booked":[{
  "transactionId":"032528112046G",
  "creditorName":"Иван Петров Иванов",
  "creditorAccount":{
    iban":"BG12TRIV40031234567890"
  },
  "transactionAmount":{
    "currency":"BGN",
    "amount":"1000.00"
  },
  "debtorName":"Иван Георгиев",
  "debtorAccount":{
    "iban":"BG21TRIV40030987654321"
  },   "bookingDate":"2023-07-07",
  "valueDate":"2023-07-07",
  "remittanceInformationUnstructured":"Получен превод от карта, рег. № 032528112046G, Наредител: Иван Георгиев, 5126**1234, BG21TRIV40030987654321 1000 лева"
  }
  ]
 }
}
 show more

//required SCA request
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//account transactions list request
curl -X POST 'https://developer.transcard.bg/v1/accounts/BG12TRIV40031234567890/transactions'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
--data-urlencode "back_url=https://link-to-tpp/process-auth/&date_from=2023.07.01&date_to=2023.07.07&bookingStatus=both"
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"redirect_token":"230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD",
"authorization_url":"https:\/\/developer.transcard.bg\/sca-gw\/auth-request\/230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD"
}

//accounts transaction list after SCA
curl -X POST 'https://developer.transcard.bg/v1/accounts/BG12TRIV40031234567890/transactions'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
--data-urlencode "date_from=2023.07.01&date_to=2023.07.07&bookingStatus=both&back_url=https://link-to-tpp/process-auth/"
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{account":{
 "iban":"BG12TRIV40031234567890",
 "bban":"TRIV40031234567890"
 },
 "transactions":{
  "pending":[{
  "transactionId":"032529112050G",
  "creditorName":"Iva Ivanova",
  "creditorAccount":{
    "iban":"GR1234567890123456789012345"
  },
  "transactionAmount":{
    "currency":"EUR",
    "amount":"1.00"},
    "debtorName": "Иван Петров Иванов",
    "debtorAccount":{
      "iban":"BG12TRIV40031234567890"
    },
    "bookingDate":"2023-07-07",
    "valueDate":"",
    "remittanceInformationUnstructured":"Нареден превод , рег. № 032529112050G Получател: Iva Ivanova, GR1234567890123456789012345",
    "currencyExchange":{
    "currencyFrom":"EUR",
    "rateFrom":"0.51129",
    "currencyTo":"BGN",
    "rateTo":"1.95583",
    "rateDate":"2023-07-07"
    }
  }
  ],
  "booked":[{
  "transactionId":"032528112046G",
  "creditorName":"Иван Петров Иванов",
  "creditorAccount":{
    iban":"BG12TRIV40031234567890"
  },
  "transactionAmount":{
    "currency":"BGN",
    "amount":"1000.00"
  },
  "debtorName":"Иван Георгиев",
  "debtorAccount":{
    "iban":"BG21TRIV40030987654321"
  },   "bookingDate":"2023-07-07",
  "valueDate":"2023-07-07",
  "remittanceInformationUnstructured":"Получен превод от карта, рег. № 032528112046G, Наредител: Иван Георгиев, 5126**1234, BG21TRIV40030987654321 1000 лева"
  }
  ]
 }
}
 show more

Balance Information

POST /card-account/balance

Description:
View account balance. The request is called directly by the payment service provider. Requires a previously received valid access_token with rights to perform operations with AIS. As a result, data are returned to HTML/JSON format.
The request allows access to the Cardholder's data after client identification in the TFS Web form. After successful verification it will be possible to make direct AIS requests with the initially generated request token. There is a limit of 50 direct requests per 6 hours. If the request limit is reached, a redirect link to the TFS SCA form is returned.

Parameters:
authorization
Required in header
string

The request_token received is being submitted here. The parameter shall be submitted in the following format:

Bearer REPLACE_REQUEST_TOKEN
resp_format
Optional in query
string

Parameter defining the format of the data to be returned(html/json). Default is html.

"enum": [
        "html",
        "json",
    ]
sca_flag
Optional in body
string

When the user's SCA is required, this parameter must have a value of 1. In this case, the query will not return data but information about redirecting the customer to the Web form of the TFS. A return address - back_url is required when sca-flag is submitted.

back_url
Optional in body
string

It shall be submitted by the initiating Party and the url at which the customer user will be redirected after verification process on the TFS website is completed in this URL.

Required in verification

Responses:

Depending on whether the request is subject to a customer authentication, a specific response is returned.

200

ОК

- In case of return of balance account data:

The request returns the following data in HTML/JSON format.

bank_name - organization name
account_name - name of customer
account_iban - IBAN of account
available_sum - disposable amount in the integer[BGN]

- In the event of a redirection to perform a customer authentication of the user, the following parameters shall be returned:

authorization_url - url to redirect a customer to a form for a customer authentication to confirm the operation. The link is valid for a single call.

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//balance request
curl -X POST 'https://developer.transcard.bg/v1/card-account/balance'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'resp_format=json'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"bank_name":"Transcard Financial Services AD",
"account_name":"Иван Петров Иванов",
"account_iban":"BG12TRIV40031234567890",
"available_sum":"26441713"
}
 show more

//required SCA request
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//balance request
curl -X POST 'https://developer.transcard.bg/v1/card-account/balance'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'resp_format=json&sca_flag=1'
--data-urlencode "back_url=https://link-to-tpp/process-auth/"
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"redirect_token":"230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD",
"authorization_url":"https:\/\/developer.transcard.bg\/sca-gw\/auth-request\/230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD"
}

//balance request after SCA
curl -X POST 'https://developer.transcard.bg/v1/card-account/balance'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'resp_format=json'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"bank_name":"Transcard Financial Services AD",
"account_name":"Иван Петров Иванов",
"account_iban":"BG12TRIV40031234567890",
"available_sum":"26441713"
}
 show more

Transaction list

POST /card-account/transactions

Description:
View account transactions. The request shall be invoked directly by the payment service provider to the TFS. Requires a previously received valid request_token with rights to perform AIS operations. As a result, data are returned to HTML/JSON format for all maps of the specified account and period.
The request allows access to the Cardholder's transactions after client identification in the TFS Web form. After successful verification it will be possible to make direct AIS requests with the initially generated request token. There is a limit of 50 direct requests per 6 hours. If the request limit is reached, a redirect link to the TFS SCA form is returned. It is mandatory to pass through SCA when a period of more than 180 days is set.

Parameters:
authorization
Required in header
string

The request_token received is being submitted here. The parameter shall be submitted in the following format:

Bearer REPLACE_REQUEST_TOKEN
resp_format
Optional in query
string

Parameter defining the format of the data to be returned(html/json). Default is html.

"enum": [
        "html",
        "json",
    ]
date_from
Optional in query
string / ISOdate

the start date of the lookup period. The date shall be submitted in format [YYYY.MM.DD]

 "pattern": "([12]\\d{3}.(0[1-9]|1[0-2]).(0[1-9]|[12]\\d|3[01]))"
date_to
Optional in query
string / ISOdate

end date of the lookup period. The date shall be submitted in format [YYYY.MM.DD]

 "pattern": "([12]\\d{3}.(0[1-9]|1[0-2]).(0[1-9]|[12]\\d|3[01]))"
sca_flag
Optional in body
string

When the user's authentication is required, this parameter must have a value of 1. In this case, the query will not return data but information about redirecting the customer to the Web form of the TFS. A return address - back_url is required when sca-flag is submitted.

back_url
Optional in body
string

It shall be submitted by the initiating Party and the url at which the customer user will be redirected after completing the authentication process on the TFS website shall be completed in this URL.

Required upon request of SCA

Responses:

Depending on whether the request is subject to a customer authentication, a specific response is returned.

200

ОК

- In case of return of transaction data:

The request returns the following data in HTML/JSON format.

date - initiation transaction date - format [YYYYMMDDHHmm]
value_date - date value - format [YYYYMMDD]
pan - masked PAN.
amount_origin - transaction amount in original currency
amount_origin_curency - currency code in which the transaction was initiated - ISO 4217
amount_bgn - amount of transaction in BGN
fee_amount - operation fee in BGN
description - transaction information
status - Transaction Status - Processed/Unprocessed

- In the event of a redirection to perform a strong customer authentication of the user, the following parameters shall be returned:

authorization_url - url to redirect a customer to a form for a strong customer authentication to confirm the operation. The link is valid for a single call.

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//transaction request
curl -X POST 'https://developer.transcard.bg/v1/card-account/transactions'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'resp_format=json&date_from=2019.08.01&date_to=2019.08.15'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"transactions":[
{"date":"201908131011","value_date":"","pan":"1234********6789","amount_origin":"1033","amount_origin_curency":"BGN","amount_bgn":"1033","fee_amount":"","description":"ПЛАЩАНЕ MYCOFFEE","status":"необработена"},
{"date":"201908101801","value_date":"20190813","pan":"1234********6789","amount_origin":"168","amount_origin_curency":"BGN","amount_bgn":"168","fee_amount":"","description":"ПЛАЩАНЕ MYSHOP ONLINE","status":"обработена"}
]
}
 show more

//required SCA request
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//transaction request
curl -X POST 'https://developer.transcard.bg/v1/card-account/transactions'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'resp_format=json&date_from=2019.08.01&date_to=2019.08.15&sca_flag=1'
--data-urlencode "back_url=https://link-to-tpp/process-auth/"
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"redirect_token":"230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD",
"authorization_url":"https:\/\/developer.transcard.bg\/sca-gw\/auth-request\/230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD"
}

//transaction request after SCA
curl -X POST 'https://developer.transcard.bg/v1/card-account/transactions'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'resp_format=json&date_from=2019.08.01&date_to=2019.08.15'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"transactions":[
{"date":"201908131011","value_date":"","pan":"1234********6789","amount_origin":"1033","amount_origin_curency":"BGN","amount_bgn":"1033","fee_amount":"","description":"ПЛАЩАНЕ MYCOFFEE","status":"необработена"},
{"date":"201908101801","value_date":"20190813","pan":"1234********6789","amount_origin":"168","amount_origin_curency":"BGN","amount_bgn":"168","fee_amount":"","description":"ПЛАЩАНЕ MYSHOP ONLINE","status":"обработена"}
]
}
 show more

Payment Initiation Service

POST /payments/{payment-product}

Description:
This request initiates a payment transaction (local bank order or to the BG budget) through the TFS. A valid access_token with a rights to perform PIS operations must be received in advance. The certificate, the token and the order parameters shall be made. The result returns a url where the order data is previewed and additional authentication is performed on the TFS's page. The payment transaction is set to the query path {payment-product} and different parameters are sent depending on the type. Payment initiation are maintained:
domestic-credit-transfers - bank transfer to TFS/other local bank
domestic-budget-transfers - order to the BG budget

Parameters:
authorization
Required in header
string

The request_token received is being submitted here. The parameter shall be submitted in the following format:

Bearer REPLACE_REQUEST_TOKEN
back_url
Required in body
string

Submitted by the initiating party and the URL of which the customer will be redirected after completion of the TFS site identification process is completed in this URL.

amount
Required in body
string

amount of bank order. It is set in the pennies[BGN].

Used for payment operations:
- domestic-credit-transfers
- domestic-budget-transfers

pattern": "(\d)"
recipient_name
Obligatory in body
string

recipient name

Used for payment operations:
- domestic-credit-transfers
- domestic-budget-transfers

 "pattern": "^[a-zA-Z0-9\s\-\.\,\/а-яА-Я]{1,35}$"
recipient_iban
Obligatory in body
string

recipient IBAN

Used for payment operations:
- domestic-credit-transfers
- domestic-budget-transfers

 "pattern": "^[a-zA-Z0-9]{22}$"
transfer_cause
Obligatory in body
string

Description field 1

Used for payment operations:
- domestic-credit-transfers
- domestic-budget-transfers

 "pattern": "^[a-zA-Z0-9\s\-\.\,\/а-яА-Я]{1,35}$"
transfer_more_causes
Optional in body
string

Description field 2

Used for payment operations:
- domestic-credit-transfers
- domestic-budget-transfers

 "pattern": "^[a-zA-Z0-9\s\-\.\,\/а-яА-Я]{1,35}$"
payment_type
Optional in body
string

payment type

Used for payment operations:
- domestic-budget-transfers

 "pattern": "^[0-9]+$"
document_type
Optional in body
string

document type

Used for payment operations:
- domestic-budget-transfers

 "pattern": "^[0-9]+$"
document_name
Optional in body
string

document name

Used for payment operations:
- domestic-budget-transfers

 "pattern": "^[a-zA-Z0-9\s\-\.\,\/а-яА-Я]{1,17}$"
document_date
Optional in body
string / ISODate

date of the document. Date is submitted in format [YYYY.MM.DD]

Used for payment operations:
- domestic-budget-transfers

"pattern": "([12]\\d{3}.(0[1-9]|1[0-2]).(0[1-9]|[12]\\d|3[01]))"
period_from
Optional in body
string / ISODate

date period. Date is submitted in format [YYYY.MM.DD]

Used for payment operations:
- domestic-budget-transfers

"pattern": "([12]\\d{3}.(0[1-9]|1[0-2]).(0[1-9]|[12]\\d|3[01]))"
period_to
Optional in body
string / ISODate

period up to date. Date is submitted in format [YYYY.MM.DD]

Used for payment operations:
- domestic-budget-transfers

"pattern": "([12]\\d{3}.(0[1-9]|1[0-2]).(0[1-9]|[12]\\d|3[01]))"
liable_name
Optional in body
string

name of the obligated person

Used for payment operations:
- domestic-budget-transfers

 "pattern": "^[a-zA-Z0-9\s\-\.\,\/а-яА-Я]{1,17}$"
liable_egn
Optional in body
string

obligated person's EGN

Used for payment operations:
- domestic-budget-transfers

 "pattern": "^[0-9]{10}$"
liable_eik
Optional in body
string

obligated person's BULSTAT

Used for payment operations:
- domestic-budget-transfers

 "pattern": "^[0-9]{9,13}$"

Responses:
200

ОК

The query returns a link to redirect the user to a TFS's form for additional identification.

authorization_url - url to redirect a customer to a form for review and in-depth identification to confirm the operation. The link is valid for a single call.

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//Initiate Bank Transfer
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//Bank Transfer request
curl -X POST 'https://developer.transcard.bg/v1/payments/domestic-credit-transfers'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'amount=470&transfer_cause=description1&transfer_more_causes=description2&recipient_name=Иван%20Петров%20Петров&recipient_iban=BG12ABCD12011234567890'
--data-urlencode "back_url=https://link-to-tpp/process-auth/"
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"redirect_token":"61B23B9B3ED401ECBB90E961B3CFB93E5E9000367004469A9100FA9D471AC67E",
"authorization_url":"https:\/\/developer.transcard.bg\/sca-gw\/auth-payment\/61B23B9B3ED401ECBB90E961B3CFB93E5E9000367004469A9100FA9D471AC67E"
}
 show more

// Initializing BG budgetary order
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//budgetary order request
curl -X POST 'https://developer.transcard.bg/v1/payments/domestic-budget-transfers'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'amount=470&transfer_cause=description1&transfer_more_causes=description2&recipient_name=Иван%20Петров%20Петров&recipient_iban=BG12ABCD12011234567890&payment_type=441400&document_type=1&document_name=12345678900&document_date=2019-06-02&period_from=2018-02-01&period_to=2018-06-01&liable_name=Пламен%20Иванов&liable_egn=1234567890&liable_eik='
--data-urlencode "back_url=https://link-to-tpp/process-auth/"
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"redirect_token":"61B23B9B3ED401ECBB90E961B3CFB93E5E9000367004469A9100FA9D471AC67E",
"authorization_url":"https:\/\/developer.transcard.bg\/sca-gw\/auth-payment\/61B23B9B3ED401ECBB90E961B3CFB93E5E9000367004469A9100FA9D471AC67E"
}
 show more

Payment initiation - details

POST /payments/{payment-product}/{x-request-id}

Description:
Request for verification of a payment initiation request. This request completes the payment initiation process. Upon completion of the in-depth identification of the payment at the TFS, the consumer shall return to the third service provider with a token, with the help of which it can obtain information about the operation carried out. The payment transaction to be checked is set to the query path {payment-product} and x-request-id for which a check is made. Payment initiation are maintained:
domestic-credit-transfers - bank transfer to TFS/other local bank
domestic-budget-transfers - order to the BG budget

Parameters:
authorization
Required in header
string

The request_token received is being submitted here. The parameter shall be submitted in the following format:

Bearer REPLACE_REQUEST_TOKEN

Responses:
200

ОК

The request returns parameters depending on the type of payment order made.

money_transfer_type - type of payment initiation TransferTypes
x_request_id - unique request number
tfs_transfer_id - payment transaction number in the TFS
status - status of the payment transaction PaymentStatus
amount - the amount of the payment transaction in [BGN]
order_bank - name of the financial organisation
order_name - name of the receiver's
order_iban - IBAN на наредителя
recipient_name - recipient Name
recipient_iban - IBAN of the beneficiary
recipient_bic - Beneficiary BIC
recipient_bank - name of recipient bank
transfer_cause - transfer description
transfer_more_causes - transfer description second line
payment_type - payment type
document_type - document type
document_name - document name
liable_name - name of the obligated person
liable_eik - BULSTAT of the obligated person
liable_egn - EGN of the obligated person
document_date - date of document
period_from - period start date
period_to - period end date

4xx

Error

In case of error, a JSON object of type ErrorResponse is returned

Example:
//Initiate bank transfer request validation
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//bank transfer validation request
curl -X POST 'https://developer.transcard.bg/v1/payments/domestic-credit-transfers/1'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"money_transfer_type":"1",
"x_request_id":"1",
"tfs_transfer_id":"407",
"status":"1",
"amount":"1033",
"order_bank":"Transcard Financial Services AD",
"order_name":"Иван Иванов Иванов",
"order_iban":"BG12TRIV40031234567890",
"recipient_name":"Пламен Петров Иванов",
"recipient_iban":"BG12ABVG97901234567890",
"recipient_bic":"ABCDEF0",
"recipient_bank":"Име банка получател",
"transfer_cause":"описание 1",
"transfer_more_causes":"описание 2" }
 show more

//verification of budgetary order
//request_token request
curl -X POST 'https://developer.transcard.bg/v1/request_token'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
-H 'x-request-id: 1'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"request_token":"E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602",
"granted_roles":"AIS,PIS"
}

//verification of budgetary order request
curl -X POST 'https://developer.transcard.bg/v1/payments/domestic-budget-transfers/2'
-H 'Authorization: Bearer 7AFD2311B8795DXJK8C982322AE40C7CD4E0654424D6579EE4300DB02E88ADE0'
--cert ~/gtsp/tpp.crt.pem --key ~/qrsp/tpp.key.pem

//Response to the request
{
"money_transfer_type":"2",
"x_request_id":"2",
"tfs_transfer_id":"408",
"status":"1",
"amount":"10033",
"order_bank":"Transcard Financial Services AD",
"order_name":"Иван Иванов Иванов",
"order_iban":"BG12TRIV40031234567890",
"recipient_name":"Пламен Петров Иванов",
"recipient_iban":"BG12ABVG97901234567890",
"recipient_bic":"ABCDEF0",
"recipient_bank":"Име банка получател",
"transfer_cause":"описание 1",
"transfer_more_causes":"описание 2"
"payment_type":"441400",
"document_type":"1",
"document_name":"12345678900",
"liable_name":"ПЕТКО ИВАНОВ ИВАНОВ",
"liable_eik":null,"liable_egn":"1234567890",
"document_date":"19000101",
"period_from":"20190801",
"period_to":"20190821"
}
 show more

SCA flow

When the user is subject to a process of identification for different processes – consent, access, acknowledgement of identity, the “Redirect” method shall be used.
Under this method, the PSPs receive a link with which the consumer redirects to a form of the TFS where the identity is processed. After completing the TFS process, the user is redirected back to the payment service provider's application, which can directly request the TFS API to access the required resources. A kick type of identification will change the consumer depends on what resources should be made available and tailored to the overall policy of the availability of resources by consumers in the TFS system.

The customer authentication process takes place as follows:
1. PSP initiates a direct request to a resource API that returns a single URL where the user is redirected.
2. Load the one-time link to the user. In the middle of the TFS, the consumer passes through a series of actions for identification and strong customer authentication and identities.
3. After completion of the identification process, the user returns back to PSP and in some cases returns a response_token for direct requests to check the result or gain access to the required resources. Accidentally, when no response_token PSP can use request_token to get the result of the identification.

Definitions

code - error code
9 - Invalid Token
10 - Invalid Certificate
11 - Invalid URL
12 - Invalid Parameters
13 - Invalid Roles
14 - System Error
15 - Invalid x-request-id
16 - Invalid Payment Operation
300 - the operation requires a strong customer authentication

error_description - text description of error


1 - Bank order
2 - Budgetary order



0 - refused payment transaction - by user
1 - successful payment transaction
2 - payment transaction refused - by system