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 body
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

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 5-times for 24 hours. A strong customer authentication(SCA) is required after reaching the request count limit. If a flag (sca-flag) is submitted for a required SCA, the query is not included in the query counter.

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. After successful verification it will be possible to make up to 5 AIS requests with the originally generated request token before deactivating token. A return address after SCA - back_url is required when a 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 SCA 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 strong customer authentication (SCA), 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 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"
}

//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://online.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://online.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:\/\/online.transcard.bg\/sca-gw\/auth-request\/230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD"
}

//balance request after SCA
curl -X POST 'https://online.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 transactions 5-times for 24 hours. A strong customer authentication(SCA) is required after reaching the limit. It is mandatory to pass through SCA when a period of more than 90 days is set. If a flag (sca-flag) is submitted for a required SCA, the query is not included in the query counter and transactions can be received in old from 90 days.

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 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. After successful verification it will be possible to make up to 5 AIS requests with the originally generated request token before deactivating token. A return address after SCA - back_url is required when a 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 SCA 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 strong customer authentication (SCA), 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_from=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://online.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://online.transcard.bg/v1/card-account/transactions'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'resp_format=json&date_from=2019.08.01&date_from=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:\/\/online.transcard.bg\/sca-gw\/auth-request\/230F4B9D35B7F1AJ982640CB7EB9D8DD314AF04D6AD7FC2B12EA9720123A06DD"
}

//transaction request after SCA
curl -X POST 'https://online.transcard.bg/v1/card-account/transactions'
-H 'Authorization: Bearer E277DBFB8SV6Q420689DC6A85553EA96B5E5F42FFE5F0B98107807B4DB2BB602'
-d 'resp_format=json&date_from=2019.08.01&date_from=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
Obligatory in body
string

payment type

Used for payment operations:
- domestic-budget-transfers

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

document type

Used for payment operations:
- domestic-budget-transfers

 "pattern": "^[0-9]+$"
document_name
Obligatory 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

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