Authentication
For merchant authentication in the payment gateway two methods can be used.
- Using login and password of the merchant's API user (account with
-api
postfix) received on registration. These values are passed inuserName
andpassword
parameters correspondingly (see the table below).
Mandatory | Name | Type | Description |
---|---|---|---|
See description | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
- Using a special token - you can request its value in the technical support service. In requests its value is passed in
token
parameter (see the table below).
Mandatory | Name | Type | Description |
---|---|---|---|
See description | token |
String | Value that is used for merchant authentication when requests are sent to the payment gateway. If you pass this parameter do not pass userName and password . |
Using REST protocol send requests with application/x-www-form-urlencoded
type, not multipart/form-data
type.
Errors
HTTP status codes:
200
- in case of the Payment Gateway API calls the JSON payload from the response must be inspected to determine whether processing was successful or not. Success is indicated by either:
- thesuccess
parameter value beingtrue
- theerrorCode
parameter value being0
If both parameters are present,success
overrideserrorCode
.400
- an internal error occurred in the system.404
- error while calling API - URL is incorrect (does not exist).429
- this code means that the system is overloaded. Most often the main reason is that the limit of requests per second or limit of simultaneous requests is reached. But it may also be due to the fact that the system as a whole is overloaded (regardless of your requests).500 or 502
- this code means that something went wrong on our side.
If the request, associated with an order payment, is processed successfully, it does not directly mean that the payment itself was successful.
To determine whether the payment was successful or not, you may refer to the description of the request used, where the intepretation of the payment success is thoroughly described, or you may follow the rule of thumb here:
- Call getOrderStatusExtended.do;
- Check the
orderStatus
field in the response: the order is considered to be payed only if theorderStatus
value is1
or2
.
API request signature
Facing insecure integration you may be requested to implement an asymmetric request signature. Usually this requirement is applied only if you carry out P2P/AFT/OCT requests.
To have a possibility to sign requests you need first to upload a certificate needed by contacting the technical support service.
Having an appropriate signature key uploaded, you need to generate a hash and a signature using your secret key, in the process of sending a request used in the API interface.
Thus, the correct hash (X-Hash) and the signature value (X-Signature) must be passed in the request header. The header is filled in using SHA256 and RSA algorithms. The request header will look like this:
X-Hash: GDrobAlCcpdOOlVuqra7Oogl/4s3vToGOXGpf3t/wJ0=
X-Signature: TJrm6jYAf2ssp/iYoDb3B+nuPqQ572oe/3a2RQ4oG2BFbmeRcoiITvR6tybNsbRHvRRlJys/2xFB W9ilee9GCN9WwYJ9h/MDyUEktj6NLZOztBAWi+7S8LDaiEWd+MUdTqe0hdiqo/lY2uIlEMTtkqTB 7LsbEhrJ6NhJdpSxrstAnpyGIrGfldt0Vz+gz+YQ5XXrwhD6HyGShqV+tXzxcMdezWJJJ8vH5C0s 4jij2PuoauUSHkTrSc4vIJl/TPMliLJNsC5KCXka4/1hSr0exawFBekRldFnv5YvFakWJUN3kEc8 w3uauzTDh+CG0/Vxs/3gNun7e9ik9kCpwdiSMw==
Payment status
The most straightforward way to know the status of the payment is to use a dedicated API call:
- Call getOrderStatusExtended.do;
- Check the
orderStatus
field in the response: the order is considered to be payed only if theorderStatus
value is1
or2
.
Another way to check whether the payment was successful or not is to refer to the callback notification.
Order management
You can download Postman collection of some basic API methods below. Make sure to send requests as POST with attributes in the body.
Order registration
To register an order, use register.do
request.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
See description | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Using jsonParams
You can use jsonParams to pass additional order information for further usage and storage. You can view additional parameters in the merchant console of the payment gateway.
Additional parameters are passed as follows {"<name1>":"<value1>",...,"<nameN>":"<valueN>"}
These fields can be passed to the bank registries.
As additional parameters you can, in particular, pass the following:
Name Data type Mandatory |
Description | Example |
---|---|---|
email ANS..255 Conditional |
Email to be displayed on the payment page. Customer's email must be passed if client notification is configured for the merchant | {"email": "client_mail@email.com"} |
phone AN..11 Mandatory |
Customer's phone number - it will be displayed on the payment page | {"phone": "9001234567"} |
backToShopUrl ANS..255 Optional |
To display a button tha would allow a customer to return to the online store the address of the store must be specified in this parameter | {"backToShopUrl": "https://mybestmerchantreturnurl.com"} |
backToShopName ANS..255 Conditional |
Name of the button that would allow a customer to return back to the online store (if backToShopUrl parameter is used) |
{"backToShopName": "Cancel"} |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/register.do </span>
--header 'content-type: application/x-www-form-urlencoded' </span>
--data amount=2000 </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data orderNumber=1218637308 </span>
--data returnUrl=https://mybestmerchantreturnurl.com </span>
--data failUrl=https://mybestmerchantfailurl.com </span>
--data email=test@test.com </span>
--data clientId=259753456 </span>
--data language=en
Response example
{
"orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
"formUrl": "https://dev.bpcbt.com/payment/merchants/rbs/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}
Order pre-authorization
The method used for registration of an order with preauthorization is registerPreAuth.do
.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
See description | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/registerPreAuth.do </span>
--header 'content-type: application/x-www-form-urlencoded' </span>
--data amount=2000 </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data returnUrl=https://mybestmerchantreturnurl.com </span>
--data orderNumber=1255555555555 </span>
--data clientId=259753456 </span>
--data language=en
Response example
{
"orderId": "01492437-d2fb-77fa-8db7-9e2900a7d8c0",
"formUrl": "https://dev.bpcbt.com/payment/merchants/rbs/payment_en.html?mdOrder=01492437-d2fb-77fa-8db7-9e2900a7d8c0"
}
Deposit order
To complete a pre-authorized order use deposit.do
request.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/deposit.do </span>
--header 'content-type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data amount=2000 </span>
--data orderId=01492437-d2fb-77fa-8db7-9e2900a7d8c0 </span>
--data language=en
Response example
{
"errorCode": 0,
"errorMessage":"Success"
}
Payment reversal
The request used for reversing an order payment is reverse.do
. Reversals can be done only within a specific time frame after the payment. Contact your bank to know the exact period, as it varies.
The payment can be reversed only once. If it ends with an error, then subsequent payment reversal operations will not work.
Availability of this feature is subject to agreement by the Bank. Reversals can be done only by users to whom the appropriate system permissions have been granted.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
Yes | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
No | jsonParams |
String | A set of additional free-form parameters, structure:{name1:value1,…,nameN:valueN} Some pre-defined jsonParams attributes:
|
No | language |
Alphabetic | ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
No | errorMessage |
String | Information parameter that is an error description in a case of error occurance. errorMessage value can vary, so it should not be hardcoded. Language of the description is set in language parameter of the request. |
Examples
POST request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/reverse.do </span>
--header 'content-type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 </span>
--data language=en
Response example
{
"errorCode": 0,
"errorMessage":"Success"
}
Refund
Use refund.do
to make refund requests.
You cannot refund orders that initialize recurrent payments, as no money are actually charged.
Upon this request, the funds for the specified order are to be returned to the payer. The request will end with an error if the funds have not been debited for this order. The system permits returning funds more than once, but for a total amount not exceeding the initial debit amount.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/refund.do </span>
--header 'content-type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 </span>
--data amount=2000 </span>
--data language=en
Response example
{
"errorCode": 0,
"errorMessage":"Success"
}
Cancel order
To cancel a pending order, use the decline.do
request. Only an order that has not been completed can be cancelled.
After successful execution of this request, the order is placed in the DECLINED status.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/decline.do </span>
--header 'content-type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data orderId=8cf0409e-857e-7f95-8ab1-b6810009d884 </span>
--data orderNumber=12345678 </span>
--data merchantLogin=merch_test418 </span>
--data language=en
Response example
{
"errorCode": 0,
"errorMessage":"Success"
}
Direct payments
Payment for order
To make a payment with card data collected on your side, paymentOrder.do
request is used.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Possible values of tii
(read about the stored credential types supported by the Payment Gateway here):
tii value |
Description | Transaction type | Transaction initiator | Card data for transaction | Card data saved after transaction | Note |
---|---|---|---|---|---|---|
Empty | Regular | Customer | Entered by Customer | No | An e-commerce transaction, credential is not stored. | |
CI | Initial Common CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
II | Initial Installment CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
RI | Initial Recurrent CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
F | Unscheduled CIT | Subsequent | Customer | Customer selects card instead of manual entry | No | An e-commerce transaction that uses a stored credential. |
U | Unscheduled MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | An e-commerce transaction that uses a stored credential |
R | Recurrent MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | A recurrent transaction that uses a stored credential. |
I | Installment MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | An installment transaction that uses a stored credential. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/rest/paymentorder.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data MDORDER=014932b6-9dc7-7782-aeec-a07500a7d8c0 \
--data '$PAN=4000001111111118' \
--data '$CVC=123' \
--data YYYY=2030 \
--data MM=12 \
--data 'TEXT=TEST CARDHOLDER' \
--data language=en
Response examples
Response example when 3-D Secure authentication is not required.
{
"redirect": "https://dev.bpcbt.com/payment/merchants/temp/finish.html?orderId=014932b6-9dc7-7782-aeec-a07500a7d8c0&lang=en",
"info": "Your order is proceeded, redirecting...",
"errorCode": 0
}
Response example when 3-D Secure authentication is required.
{
"info": "Your order is proceeded, redirecting...",
"errorCode": 0,
"acsUrl": "https://web.rbsuat.com/acs/auth/start.do",
"paReq": "eJxVUsFWwjAQ...Lruc",
"termUrl": "https://dev.bpcbt.com/payment/rest/finish3ds.do?lang=en"
}
Instant payment
The request used to register an order and at the same time carry out the payment for it is instantPayment.do
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
See description | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
Description of parameters in orderBundle
object:
Mandatory | Name | Type | Description |
---|---|---|---|
No | orderCreationDate |
String | Order creation date in the following format: YYYY-MM-DDTHH:MM:SS . |
Description of parameters in customerDetails
object:
Mandatory | Name | Type | Description |
---|---|---|---|
See description | email |
String | Customer's email address. Multiple emails can be passed as comma-separated values. Either of email or phone must be passed. |
Description of parameters in deliveryInfo
object.
Mandatory | Name | Type | Description |
---|---|---|---|
No | deliveryType |
String | Delivery method. |
Description of parameters in cartItems
object.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | items |
See description | An element of the array containing cart item attributes. The description of the tag attributes is given below. |
Description of parameters in items
object.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | positionId |
Integer | Unique product identifier in the cart. |
Description of parameters in itemDetails
object.
Mandatory | Name | Type | Description |
---|---|---|---|
No | itemDetailsParams |
See description | Parameter describing additional information regarding a line item. The description of the tag attributes is given below. |
Description of parameters in itemDetailsParams
object.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | value |
String | Additional item info. |
Description of parameters in quantity
object.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | value |
String | Number of items in one positionId . Use a decimal point as a separator in fractions. |
Description of parameters in discount
object.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | discountType |
String | Type of discount applicable to an item. |
Description of parameters in agentInterest
object:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | interestType |
String | Agent fee type. |
Description of parameters in tax
object:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | taxType |
Integer | VAT rate, the following values are allowed:
|
Description of parameters in itemAttributes
object:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | paymentMethod |
Integer | Payment type, the available values are:
|
Description of parameters in agentInterest
object:
Mandatory | Name | Type | Description |
---|---|---|---|
No | cashier |
String | Cashier's name. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
orderStatus
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
if acsUrl
is not null, then 3DS flow should be initiated. Otherwise see orderStatus
:
-
1
- order is APPROVED -
2
- order is DEPOSITED -
5
- redirect to ACS, see acsUrl (order is CREATED, but not paid yet)
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/rest/instantPayment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data amount=100 \
--data currency=978 \
--data description=my_first_order \
--data orderNumber=1218637308 \
--data pan=5000001111111115 \
--data cvc=123 \
--data expiry=203012 \
--data cardHolderName="TEST CARDHOLDER" \
--data language=en \
--data backUrl=https%3A%2F%2Fmybestmerchantreturnurl.com \
--data failUrl=https%3A%2F%2Fmybestmerchantreturnurl.com
Response example
{
"errorCode": "0",
"orderId": "eee72f6e-b980-79c5-92e8-6f4200b1eae0",
"info": "Your order is proceeded, redirecting...",
"redirect": "https://www.test.com/payment/merchants/gateway/finish.html?orderId=eee72f6e-b980-79c5-92e8-6f4200b1eae0&lang=en",
"orderStatus": {
"expiration": "202412",
"cardholderName": "TEST CARDHOLDER",
"depositAmount": 100,
"currency": "978",
"approvalCode": "123456",
"authCode": 2,
"ErrorCode": "0",
"ErrorMessage": "Success",
"OrderStatus": 2,
"OrderNumber": "2011",
"Pan": "500000**1115",
"Amount": 100,
"Ip": "10.99.50.35"
}
}
Payment card validation is done as shown in the table below.
Parameter | Description | Validation |
---|---|---|
|
Full payment card number | Luhn validation (if payment card number is real), number of digits in a card number is from 13 to 20 |
MOTO payment
The request used to carry out MOTO paymenents is motoPayment.do
.
To use this API, you need PCI SAQ D.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | success |
String | Main parameter which indicates directly that the request was successful. The following values are available:
Note that the value true here simply means that the request was proccessed, not that the order was paid. The status of the payment is reflected by the value of another parameter - orderStatus . |
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/rest/motoPayment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data amount=2000 \
--data currency=978 \
--data userName=test_user \
--data password=test_user_password \
--data returnUrl=https://mybestmerchantreturnurl.com \
--data description=my_first_order \
--data pan=4000001111111118 \
--data expiry=203012 \
--data cvc=123 \
--data cardholder="TEST CARDHOLDER" \
--data language=en
Response example (successful payment)
{
"errorCode":"0",
"success":true,
"mdOrder":"088433e9-e34d-769e-9366-696200a7d8c0",
"orderNumber":"62001"
}
Stored credential (COF)
COF payment
The request used to make a credential-on-file (COF) payment is paymentOrderBinding.do
.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Possible values of tii
(read about the stored credential types supported by the Payment Gateway here):
tii value |
Description | Transaction type | Transaction initiator | Card data for transaction | Card data saved after transaction | Note |
---|---|---|---|---|---|---|
Empty | Regular | Customer | Entered by Customer | No | An e-commerce transaction, credential is not stored. | |
CI | Initial Common CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
II | Initial Installment CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
RI | Initial Recurrent CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
F | Unscheduled CIT | Subsequent | Customer | Customer selects card instead of manual entry | No | An e-commerce transaction that uses a stored credential. |
U | Unscheduled MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | An e-commerce transaction that uses a stored credential |
R | Recurrent MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | A recurrent transaction that uses a stored credential. |
I | Installment MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | An installment transaction that uses a stored credential. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/rest/paymentOrderBinding.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
--data bindingId=01491394-63a6-7d45-a88f-7bce00a7d8c0 \
--data clientId=259753456 \
--data ip=1d0d:db8:6:1::77 \
--data cvc=123 \
--data language=en
Example of a success response for an SSL-payment (no 3-D Secure)
{
"redirect": "https://dev.bpcbt.com/payment/merchants/temp/finish.html?orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0&lang=en",
"info": "Your order is proceeded, redirecting...",
"errorCode": 0
}
An example of a success response for a 3D-Secure payment
{
"info": "Your order is proceeded, redirecting...",
"errorCode": 0,
"acsUrl": "https://theacsserver.com/acs/auth/start.do",
"paReq": "eJxVUu9vgjAQ/...4BaHYvAI=",
"termUrl": "https://dev.bpcbt.com/payment/rest/finish3ds.do?lang=en"
}
Example of a response with an error
{
"error": "Access denied",
"errorCode": 5,
"errorMessage": "Access denied"
}
Get stored credentials
The request used to get the list of client's stored credentials is getBindings.do
.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | clientId |
Alphanumeric | Customer number (ID) in the merchant's system — up to 255 characters . Used to implement the functionality of COF transactions. Can be returned in the response if the merchant is allowed to store credentials. Specifying this parameter in COF transactions is mandatory. Otherwise, a payment will be unsuccessful. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
bindings
element contains blocks with the following parameters.
Mandatory | Name | Type | Description |
---|---|---|---|
No | maskedPan |
String | Masked number of the card used for the payment. This parameter is to be specified only after the order has been paid. |
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/getBindings.do </span>
--header 'Content-Type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data clientId=dos-clientos </span>
--data bindingType=C
Example of a success response
{
"errorCode":"0",
"errorMessage":"Success",
"bindings": [
{
"bindingId":"69d6a793-afb5-79be-8ce7-63ff00a8656a",
"maskedPan":"400000*1118",
"expiryDate":"203012",
"paymentWay":"CARD",
"displayLabel":"XXXXXXXXXXXX1118"
}
]
}
Get stored credentials by card number
The request used to get the list of all stored credentials of a bank card is getBindingsByCardOrId.do
.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/getBindingsByCardOrId.do </span>
--header 'Content-Type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data pan=4000001111111118
Example of a success response
{
"errorCode":"0",
"errorMessage":"Success",
"bindings": [
{
"bindingId":"69d6a793-afb5-79be-8ce7-63ff00a8656a",
"maskedPan":"4000001118",
"expiryDate":"203012",
"clientId":"12"
}
{
"bindingId":"6a8c0738-cc88-4200-acf6-afc264d66cb0",
"maskedPan":"400000*1118",
"expiryDate":"203012",
"clientId":"13"
}
]
}
Deactivate a stored credential
The request used to deactivate a stored credential is unBindCard.do
.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/unBindCard.do </span>
--header 'Content-Type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
Response example (error)
{
"errorCode":"2",
"errorMessage":"Binging isn't active",
}
Enable a stored credential
The request used to activate an existing stored credential that has been deactivated is bindCard.do
.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/bindCard.do </span>
--header 'Content-Type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
Response example (error)
{
"errorCode":"2",
"errorMessage":"Binging is active",
}
Extend a stored credential expiration date
The request used to extend the expiration date of a stored credential is extendBinding.do
.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/extendBinding.do </span>
--header 'Content-Type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
--data newExpiry=202212
--data language=en
Response example
{
"errorCode":"0",
"errorMessage":"Success",
}
Recurrent payment
The request used to make recurrent payments is recurrentPayment.do
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | success |
String | Main parameter which indicates directly that the request was successful. The following values are available:
Note that the value true here simply means that the request was proccessed, not that the order was paid. The status of the payment is reflected by the value of another parameter - orderStatus . |
See description | error |
N/A | This parameter is returned only if the payment failed. See the description below. |
data
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
error
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
code |
Integer | Code as an information parameter stating an error occurred. |
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/rest/recurrentPayment.do \
--header 'Content-Type: application/json' \
--data-raw '{
"userName" : "test_user",
"password" : "test_user_password",
"orderNumber" : "UAF-203974-DE-12",
"language" : "EN",
"bindingId": "bindingId",
"amount" : 1200,
"currency" : "978",
"description" : "Test description",
"additionalParameters" : {
"firstParamName" : "firstParamValue",
"secondParamName" : "secondParamValue"
"email" : "email@email.com"
}
}'
Response examples
Success
{
"success": true,
"data": {
"orderId": "f7beebe4-7c9a-43cf-8e26-67ab741f9b9e"
},
"orderStatus": {
"errorCode": "0",
"orderNumber": "UAF-203974-DE-12",
"orderStatus": 2,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 12300,
"currency": "978",
"date": 1491333938243,
"orderDescription": "Test description",
"merchantOrderParams": [
{
"name": "firstParamName",
"value": "firstParamValue"
},
{
"name": "secondParamName",
"value": "secondParamValue"
}
],
"attributes": [],
"cardAuthInfo": {
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "12345678",
"paymentSystem": "VISA",
"pan": "6777770000**0006"
},
"authDateTime": 1491333939454,
"terminalId": "11111",
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "DEPOSITED",
"approvedAmount": 12300,
"depositedAmount": 12300,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryName": "<unknown>"
},
"chargeback": false,
"operations": [
{
"amount": 12300,
"cardHolder": "TEST CARDHOLDER",
"authCode": "123456"
}
]
}
}
Error
{
"error": {
"code": "10",
"description": "Order with this number is already registered in the system.",
"message": "Order with this number is already registered in the system."
},
"success": false
}
Installment payment
The request used to make an installment payments is installmentPayment.do
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
Yes | email |
String | cardholder Billing email. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
orderStatus
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
See description | attributes |
N/A | Attributes of the order in the payment system (order number). See the description below. |
See description | cardAuthInfo |
N/A | Information about the buyer's payment card. See the description below. |
No | authDateTime |
String | Authorization date and time, shown as the amount of milliseconds since 00:00 January 1, 1970 GMT (UNIX time). |
See description | bankInfo |
N/A | Contains the embedded bankCountryName parameter. See the description below. |
See description | bindingInfo |
N/A | Block containing information on the binding with which the payment is performed. See the description below. |
See description | operations |
N/A | Block containing the operations information. See the description below. |
merchantOrderParams
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | name |
Alphanumeric | Name of the merchant's additional parameter. |
attributes
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | name |
Alphanumeric | Name of an additional parameter. |
cardAuthInfo
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | expiration |
Integer | Card expiration in the following format: YYYYMM . This parameter is to be specified only after the order has been paid. |
paymentAmountInfo
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | paymentState |
String | Order status, this parameter can have the following values:
|
bankInfo
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | bankCountryName |
String | Country of the issuing bank. |
bindingInfo
element contains the following parameters.
Name | Type | Mandatory | Description |
---|---|---|---|
No | clientId |
Alphanumeric | Customer number (ID) in the merchant's system — up to 255 characters . Used to implement the functionality of COF transactions. Can be returned in the response if the merchant is allowed to store credentials. Specifying this parameter in COF transactions is mandatory. Otherwise, a payment will be unsuccessful. |
operations
element contains the following parameters.
Name | Type | Mandatory | Description |
---|---|---|---|
No | amount |
Integer | Payment amount in minor currency units (e.g. in cents etc.). |
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/rest/installmentPayment.do \
--header 'Content-Type: application/json' \
--data '{
"userName": "test_user",
"password": "test_user_password",
"orderNumber": "UAF-203974-DE-12",
"language": "EN",
"bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820",
"amount": 12300,
"currency": "978",
"description" : "Test description",
"additionalParameters": {
"firstParamName": "firstParamValue",
"secondParamName": "secondParamValue"
}
}'
Response examples
{
"errorCode": 0,
"errorMessage": "Success",
"orderId": "0e441115-f3bc-711c-8827-2fdc00b4f820",
"orderStatus": {
"errorCode": "0",
"orderNumber": "7033",
"orderStatus": 2,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 12300,
"currency": "978",
"date": 1618340470944,
"orderDescription": "Test description",
"merchantOrderParams": [
{
"name": "firstParamName",
"value": "firstParamValue"
},
{
"name": "secondParamName",
"value": "secondParamValue"
}
],
"transactionAttributes": [],
"attributes": [
{
"name": "mdOrder",
"value": "0e441115-f3bc-711c-8827-2fdc00b4f820"
}
],
"cardAuthInfo": {
"maskedPan": "400000**1118",
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "123456",
"paymentSystem": "VISA",
"product": "visa-product",
"secureAuthInfo": {
"eci": 7
},
"pan": "400000**1118"
},
"bindingInfo": {
"clientId": "TEST CARDHOLDER",
"bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820"
},
"authDateTime": 1618340471076,
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "DEPOSITED",
"approvedAmount": 12300,
"depositedAmount": 12300,
"refundedAmount": 0,
"totalAmount": 12300
},
"bankInfo": {
"bankName": "ES TEST BANK",
"bankCountryCode": "ES",
"bankCountryName": "Spain"
},
"chargeback": false,
"operations": [
{
"amount": 12300,
"cardHolder": "TEST CARDHOLDER",
"authCode": "123456"
}
]
},
"error": false
}
Statuses
Order status
The request used to get the order status is getOrderStatusExtended.do
.
Learn more about Refusal reasons.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
Response parameters
There are several sets of the response parameters. Which set of parameters is returned in the response, depends on the version of getOrderStatusExtended
specified in the merchant's settings in the payment gateway.
Version | Mandatory | Name | Type | Description |
---|---|---|---|---|
All versions. | No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
attributes
block contains information on the order number in the payment gateway. name
parameter contains the word mdOrder
, and value
parameter contains the actual order number in the payment gateway.
Version | Name | Type | Mandatory | Description |
---|---|---|---|---|
All versions. | No | name |
Numeric | Name of an additional parameter. |
transactionAttributes
block contains the set of additional attributes of the transaction. Used for version 14 and later. Below is the list of the included parameters.
Version | Name | Type | Mandatory | Description |
---|---|---|---|---|
All versions. | No | name |
Numeric | Name of an additional parameter. |
merchantOrderParams
block is passed in the response, if the order contains merchant additional parameters. Each additional parameter is passed in a separate merchantOrderParams
element.
Version | Name | Type | Mandatory | Description |
---|---|---|---|---|
All versions. | No | name |
Numeric | Name of an additional parameter. |
cardAuthInfo
element contains a structure consisting of secureAuthInfo
element list and the following parameters.
Version | Name | Type | Mandatory | Description |
---|---|---|---|---|
All versions. | No | maskedPan |
String | Masked number of the card used for the payment. This parameter is to be specified only after the order has been paid. |
secureAuthInfo
element consists of eci
element and threeDSInfo
element that is a list of cavv
and xid
parameters).
Version | Name | Type | Mandatory | Description |
---|---|---|---|---|
All versions. | No | eci |
Integer | Electronic commerce indicator. The indicator is specified only after an order has been paid and in case the corresponding permission is present. Below is the explanation of ECI codes.
|
bindingInfo
element contains the following parameters.
Version | Name | Type | Mandatory | Description |
---|---|---|---|---|
All versions. | No | clientId |
Alphanumeric | Customer number (ID) in the merchant's system — up to 255 characters . Used to implement the functionality of COF transactions. Can be returned in the response if the merchant is allowed to store credentials. Specifying this parameter in COF transactions is mandatory. Otherwise, a payment will be unsuccessful. |
paymentAmountInfo
element contains the following parameters.
Version | Name | Type | Mandatory | Description |
---|---|---|---|---|
03 and later. | No | approvedAmount |
Integer | Amount in minimum currency units (e.g. cents) that was put on hold on buyer's account. Used in two-phase payments only. |
bankInfo
element contains the following parameters.
Version | Name | Type | Mandatory | Description |
---|---|---|---|---|
03 and later. | No | bankName |
String | Issuing bank name. |
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/getOrderStatusExtended.do </span>
--header 'content-type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 </span>
--data language=en
Response example
{
"errorCode": "0",
"errorMessage": "Success",
"orderNumber": "7005",
"orderStatus": 2,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 2000,
"currency": "978",
"date": 1617972915659,
"orderDescription": "",
"merchantOrderParams": [],
"transactionAttributes": [],
"attributes": [
{
"name": "mdOrder",
"value": "01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}
],
"cardAuthInfo": {
"maskedPan": "500000*1115",
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "12345678",
"pan": "500000*1115"
},
"bindingInfo": {
"clientId": "259753456",
"bindingId": "01491394-63a6-7d45-a88f-7bce00a7d8c0"
},
"authDateTime": 1617973059029,
"terminalId": "123456",
"authRefNum": "714105591198",
"paymentAmountInfo": {
"paymentState": "DEPOSITED",
"approvedAmount": 2000,
"depositedAmount": 2000,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryCode": "UNKNOWN",
"bankCountryName": "<Unknown>"
}
}
Wallets
Apple Pay order registration
The request used for order registration is/applepay/payment.do
.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | merchant |
String | Merchant login in the payment gateway. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | success |
String | Main parameter which indicates directly that the request was successful. The following values are available:
Note that the value true here simply means that the request was proccessed, not that the order was paid. The status of the payment is reflected by the value of another parameter - orderStatus . |
See description | error |
N/A | This parameter is returned only if the payment failed. See the description below. |
See description | orderStatus |
N/A | Contains order status parameters and is returned only if the payment gateway has recognized all request parameters as correct. See the description below. |
data
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
error
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
code |
Integer | Code as an information parameter stating an error occurred. |
orderStatus
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
See description | attributes |
N/A | Attributes of the order in the payment system (order number). See the description below. |
See description | cardAuthInfo |
N/A | Information about the buyer's payment card. See the description below. |
No | authDateTime |
String | Authorization date and time, shown as the amount of milliseconds since 00:00 January 1, 1970 GMT (UNIX time). |
See description | bankInfo |
N/A | Contains the embedded bankCountryName parameter. See the description below. |
merchantOrderParams
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | name |
Alphanumeric | Name of the merchant's additional parameter. |
attributes
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | name |
Alphanumeric | Name of an additional parameter. |
cardAuthInfo
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | expiration |
Integer | Card expiration in the following format: YYYYMM . This parameter is to be specified only after the order has been paid. |
paymentAmountInfo
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | paymentState |
String | Order status, this parameter can have the following values:
|
bankInfo
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | bankCountryName |
String | Country of the issuing bank. |
Then you should see orderStatus
:
-
1
- order is APPROVED -
2
- order is DEPOSITED
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/applepay/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
"additionalParameters" : {
"phone" : "9521235847",
"order-pain" : "111",
"email" : "apple@pay.com"
},
"features" : [ ],
"language" : "ru",
"merchant" : "sandbox_merchant",
"orderNumber" : "281477871",
"paymentToken" : "eyJkYXRhIjoiYPhK3M1bEtm...YjM2NWMzZWNmYjE5fIkVDX3YxIn0=",
"preAuth" : false,
"recurrent" : false,
"recurrentInitialize" : false
}'
Response in case of a successful payment
{
"success": true,
"data": {
"orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
},
"orderStatus": {
"errorCode": "0",
"orderNumber": "229",
"orderStatus": 1,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 960000,
"currency": "978",
"date": 1478682458102,
"ip": "81.18.144.51",
"merchantOrderParams": [
{
"name": "param2",
"value": "param2"
},
{
"name": "param1",
"value": "param1"
}
],
"attributes": [
{
"name": "mdOrder",
"value": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
}
],
"cardAuthInfo": {
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "123456",
"pan": "500000**1115"
},
"authDateTime": 1478682459082,
"terminalId": "12345678",
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "APPROVED",
"approvedAmount": 960000,
"depositedAmount": 0,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryName": "<UNKNOWN>"
}
}
}
Response in case of a failed payment
{
"error": {
"code": 10,
"description": "Processing Error",
"message": "Auth is invalid"
},
"success": false
}
Apple Pay Direct
The request used to make a direct payment via Apple Pay is apple/paymentDirect.do
. This request can be used for integrations that involve payment data decoding on Merchant side.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Possible values of tii
(read about the stored credential types supported by the Payment Gateway here):
tii value |
Description | Transaction type | Transaction initiator | Card data for transaction | Card data saved after transaction | Note |
---|---|---|---|---|---|---|
Empty | Regular | Customer | Entered by Customer | No | An e-commerce transaction, credential is not stored. | |
CI | Initial Common CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
II | Initial Installment CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
RI | Initial Recurrent CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
F | Unscheduled CIT | Subsequent | Customer | Customer selects card instead of manual entry | No | An e-commerce transaction that uses a stored credential. |
U | Unscheduled MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | An e-commerce transaction that uses a stored credential |
R | Recurrent MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | A recurrent transaction that uses a stored credential. |
I | Installment MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | An installment transaction that uses a stored credential. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | success |
String | Main parameter which indicates directly that the request was successful. The following values are available:
Note that the value true here simply means that the request was proccessed, not that the order was paid. The status of the payment is reflected by the value of another parameter - orderStatus . |
Parameters in data
block:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
Parameters in error
block:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | code |
Integer | Code as an information parameter stating an error occurred. |
Parameters in orderStatus
block:
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Parameters in cardAuthInfo
block:
Mandatory | Name | Type | Description |
---|---|---|---|
No | expiration |
String | Year and month of card expiration. |
Parameters in paymentAmountInfo
block:
Mandatory | Name | Type | Description |
---|---|---|---|
No | paymentState |
String | Order status, this parameter can have the following values:
|
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/apple/paymentDirect.do \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "test_user",
"password": "test_user_password",
"orderNumber": "1534175806640",
"description": "description of the order",
"language": "en",
"paymentToken": "eyJnYXR<skipped>lBQT0ifX0=",
Response examples
Response example (successful payment)
{
"success": true,
"data": {
"orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
},
"orderStatus": {
"errorCode": "0",
"orderNumber": "229",
"orderStatus": 1,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 960000,
"currency": "978",
"date": 1478682458102,
"ip": "81.18.144.51",
"merchantOrderParams": [
{
"name": "param2",
"value": "param2"
},
{
"name": "param1",
"value": "param1"
}
],
"attributes": [
{
"name": "mdOrder",
"value": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
}
],
"cardAuthInfo": {
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "123456",
"pan": "500000**1115"
},
"authDateTime": 1478682459082,
"terminalId": "12345678",
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "APPROVED",
"approvedAmount": 960000,
"depositedAmount": 0,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryName": "<UNKNOWN>"
}
}
}
Response example (payment error)
{
"error": {
"code": 1,
"description": "Processing Error",
"message": "Insufficient amount on card"
},
"success": false
}
Google Pay order registration
Request parameters
The /google/payment.do
request is used to register an order.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | merchant |
String | Merchant login in the payment gateway. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | success |
String | Main parameter which indicates directly that the request was successful. The following values are available:
Note that the value true here simply means that the request was proccessed, not that the order was paid. The status of the payment is reflected by the value of another parameter - orderStatus . |
See description | error |
N/A | This parameter is returned only if the payment failed. See the description below. |
See description | orderStatus |
N/A | Contains order status parameters and is returned only if the payment gateway has recognized all request parameters as correct. See the description below. |
data
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
error
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
code |
Integer | Code as an information parameter stating an error occurred. |
If acsUrl
is not null, then 3DS flow should be initiated. Otherwise you should request getOrderStatusExtended.do and check the status of transaction.
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/google/payment.do </span>
--header 'Content-Type: application/json' </span>
--data-raw '{
"amount" : 1000,
"features" : [ ],
"merchant" : "sandbox_merchant",
"orderNumber" : "350467565",
"paymentToken" : "eyJzaWduYXR1cmUiOiJNRVF...dGM3NHUxQWY5L1pNPVwifSJ9",
"preAuth" : false,
"returnUrl" : "https://mybestmerchantreturnurl.com/"
}'
Response in case of a successful payment
{
"success":true,
"data": {
"orderId": "12312312123"
}
}
Example of the response to the request with the non-tokenized card and redirect to ACS
{
"success":true,
"data":{
"orderId":"e757d0cf-a028-7bdc-acb9-44480008afa2",
"acsUrl":"https://test.com/acs/auth/start.do",
"paReq":"eJxV....DOm3R/rFG/TvQ/wAgGS/bg==",
"termUrl":"https://dev.bpcbt.com/payment/rest/finish3ds.do"
}
}
Response in case of a failed payment
{
"error": {
"code": 1,
"description":"Processing Error",
"message":"The funds on the card are not sufficient"
},
"success": false
}
Google Pay Direct
The request used to make a direct payment via Google Pay is google/paymentDirect.do
. This request can be used for integrations that involve payment data decoding on Merchant side.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Possible values of tii
(read about the stored credential types supported by the Payment Gateway here):
tii value |
Description | Transaction type | Transaction initiator | Card data for transaction | Card data saved after transaction | Note |
---|---|---|---|---|---|---|
Empty | Regular | Customer | Entered by Customer | No | An e-commerce transaction, credential is not stored. | |
CI | Initial Common CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
II | Initial Installment CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
RI | Initial Recurrent CIT | Initiating | Customer | Entered by Customer | Yes | An e-commerce transaction, credential is stored. |
F | Unscheduled CIT | Subsequent | Customer | Customer selects card instead of manual entry | No | An e-commerce transaction that uses a stored credential. |
U | Unscheduled MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | An e-commerce transaction that uses a stored credential |
R | Recurrent MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | A recurrent transaction that uses a stored credential. |
I | Installment MIT | Subsequent | Merchant | No manual entry, Merchant passes the data | No | An installment transaction that uses a stored credential. |
If 3DS 2.0 is used, the following parameters should be passed as well:
Mandatory | Name | Type | Description |
---|---|---|---|
See description | threeDSServerTransId |
String | Transaction identifier created on 3DS Server. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | success |
String | Main parameter which indicates directly that the request was successful. The following values are available:
Note that the value true here simply means that the request was proccessed, not that the order was paid. The status of the payment is reflected by the value of another parameter - orderStatus . |
data
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
If 3DS 2.0 protocol is used, the response to initial request also includes the following parameters in the data
block:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | is3DSVer2 |
String | Possible values: true or false . Flag showing that payment uses 3DS 2.0. |
Parameters in error
block:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | code |
Integer | Code as an information parameter stating an error occurred. |
Examples
Example of initial request
curl --request POST </span>
--url https://dev.bpcbt.com/payment/google/paymentDirect.do </span>
--header 'Content-Type: application/json' </span>
--data-raw '{
"amount" : "1000",
"orderNumber" : "350467565",
"features" : [ ],
"language" : "EN",
"password" : "test_user_password",
"paymentToken" : "eyJnYXRldTWVY2hRJ...b25ZZWFyyMD0fX0=",
"preAuth" : true,
"returnUrl" : "https://mybestmerchantreturnurl.com",
"username" : "test_user"
}'
Example of second request
curl --request POST </span>
--url https://dev.bpcbt.com/payment/google/paymentDirect.do </span>
--header 'Content-Type: application/json' </span>
--data-raw '{
"username": "test_user",
"password": "test_user_password",
"paymentToken": "eyJnYXR<skipped>lBQT0ifX0=",
"amount": 100,
"orderNumber": "1534175806640",
"ip": "0.0.0.0",
"description": "description",
"language": "en",
"preAuth": false,
"returnUrl": "https://mybestmerchantreturnurl.com",
"currencyCode": "978",
"threeDSVer2FinishUrl" : "https:test.com"
}'
Response examples
Example of response to initial request
{
"success": true,
"data": {
"orderId": "12312312123"
}
}
Example of response to second request
{
"success": true,
"data": {
"orderId": "12312312123",
"acsUrl": "https://test.com/acs2/acs/creq",
"is3DSVer2": true,
"packedCReq": "eyJ0aHJl<skipped>IuMS4wIn0="
}
}
Samsung Pay order registration
The /samsung/payment.do
request is used to register an order in Samsung Pay. See Connection coordinates. This request is only used when paying from the mobile application.
Below an example of a request for a payment through Samsung Pay is given.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | merchant |
String | Merchant login in the payment gateway. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | success |
String | Main parameter which indicates directly that the request was successful. The following values are available:
Note that the value true here simply means that the request was proccessed, not that the order was paid. The status of the payment is reflected by the value of another parameter - orderStatus . |
See description | error |
N/A | This parameter is returned only if the payment failed. See the description below. |
data
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
error
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
code |
Integer | Code as an information parameter stating an error occurred. |
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/samsung/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
"additionalParameters" : {
"phone" : "9521235847",
"order-pain" : "111",
"email" : "samsung@pay.com"
},
"language" : "en",
"merchant" : "sandbox_merchant",
"orderNumber" : "1218637308",
"paymentToken" : ".II-jot36URBzoJMmtU6B0vS...LC46IJLgqIRwjL85BjKPRQ",
"preAuth" : false
}'
Response in case of a successful payment
{
"success":true,
"data": {
"orderId": "12312312123"
}
}
Response in case of a failed payment
{
"error": {
"code": 1,
"description": "Processing Error",
"message": "Not enough money"
},
"success": false
}
Samsung Pay Direct
The request used to make a direct payment via Samsung Pay is samsung/paymentDirect.do
. This request can be used for integrations that involve payment data decoding on Merchant side.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | merchant |
String | Merchant login in the payment gateway. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | success |
String | Main parameter which indicates directly that the request was successful. The following values are available:
Note that the value true here simply means that the request was proccessed, not that the order was paid. The status of the payment is reflected by the value of another parameter - orderStatus . |
data
block contains the following elements.
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
Parameters in error
block:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | code |
Integer | Code as an information parameter stating an error occurred. |
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/samsung/paymentDirect.do </span>
--header 'Content-Type: application/json' </span>
--data-raw '{
{
"merchant": "OurBestMerchantLogin",
"orderNumber": "UAF-203974-DE",
"language": "EN",
"preAuth": true,
"description" : "Test description",
"additionalParameters":
{
"firstParamName": "firstParamValue",
"secondParamName": "secondParamValue"
},
"paymentToken": "ew0KICB7DQoJICA...0KICB9DQp9",
"ip" : "127.0.0.1"
}
Response examples
Response example (successful payment)
{
"success": true,
"data": {
"orderId": "12312312123"
}
}
Response example (payment error)
{
"error": {
"code": 1,
"description": "Processing Error",
"message": "Insufficint amount on card"
},
"success": false
}
P2P functionality
To use the P2P (card-to-card) functionality in full, the electronic signature to be passed in the P2P request header is a must.
P2P order registration
To register an order for the card-to-card money transfer, use registerP2P.do
request.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/registerP2P.do' -H 'Content-Type: application/json' --data-raw '{
"username":"test_user",
"password":"test_user_password",
"amount" : 50000,
"currency" : "978",
"returnUrl" : "https://mybestmerchantreturnurl.com",
"orderNumber": "1"
}'
Response example
{
"errorCode": 0,
"errorMessage": "Successful",
"orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
"formUrl": "https://dev.bpcbt.com/payment/merchants/ecom/payment.html?mdOrder=0a4eaae8-653a-71a9-8259-46fc00a8ea58&language=en",
"orderNumber": "2009"
}
Fee amount
To obtain the fee amount for the money transfer, use verifyP2P.do
request.
The structure of the verifyP2P.do request assumes the existence of the fromCard
block to pass the attributes of the card to be debited and the toCard
block to pass the attributes of the card to be credited.
Depending on the business processes of the bank and the online store, the following options are possible when carrying out a card-to-card money transfer:
- The online store passes the data of the card to be debited and of the card to be credited to the payment gateway. In this case both blocks of parameters —
fromCard
andtoCard
— must be presented in the request. - If the money is transferred to the card by a third-party system, the online store passes only the data of the card to be debited to the payment gateway. In this case the request must include only one block of parameters —
fromCard
. - If debiting is performed by a third-party system, the online store passes only the data of the card to be credited to the payment gateway. In this case the request must include only one block of parameters –
toCard
.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
The fromCard
block (if debiting is done by a third-party system, this block must be absent) includes the following possible parameters:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | pan |
String | The number of the card to be debited. |
The toCard
block (if crediting is done by a third-party system, this block must be absent) consists of the following possible parameters:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | pan |
String | The number of the card to be credited. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
The feeDescriptionList
block includes the following parameters:
Mandatory | Name | Type | Description |
---|---|---|---|
No | feeAmount |
Integer | Fee amount. |
Examples
Request example
curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/verifyP2P.do' -H 'Content-Type: application/json' --data-raw '{
"username":"test_user",
"password":"test_user_password",
"orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
"fromCard": {
"cardholderName": "TEST CARDHOLDER",
"cvc": "123",
"expirationMonth": 12,
"expirationYear": 2030,
"pan": "5000001111111115"
},
"toCard": {
"pan": "4000001111111118"
},
"amount" : 50000
}'
Response example
{
"errorCode": 0,
"errorMessage": "Successful",
"feeDescriptionList: [ {
"feeAmount": 500,
"feeCurrency": "978",
"feeDescription": "Acquirer fee"
} ]
}
P2P transfer
To perform a card-to-card money transfer, use performP2P.do
request.
The structure of the performP2P.do
request assumes the presence of the fromCard
block to pass the attributes of the card to be debited and the toCard
block to pass the attributes of the card to be credited. Depending on the business processes of the bank and the online store, the following options are possible when carrying out a card-to-card money transfer:
- The online store passes the data of the card to be debited and of the card to be credited to the payment gateway. In this case both blocks of parameters —
fromCard
andtoCard
— must be present in the request. - If the money is transferred to the card by a third-party system, the online store passes only the data of the card to be debited to the payment gateway. In this case the request must include only one block of parameters —
fromCard
. - If debiting is performed by a third-party system, the online store passes only the data on the card to be credited to the payment gateway. In this case the request must include only one block of parameters —
toCard
.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
The fromCard
block (if debiting is done by a third-party system, this block must be absent) includes the following possible parameters:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | pan |
String | The number of the card to be debited. |
The toCard
block (if crediting is done by a third-party system, this block must be absent) consists of the following possible parameters:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | pan |
String | The number of the card to be credited. |
The following parameters are also passed during the authentication via the 3DS 2.0 protocol:
Mandatory | Name | Type | Description |
---|---|---|---|
No | threeDSDsTransID |
String | Unique identifier of transaction witin IPS. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
When authenticating via the 3DS 2.0 protocol, the following parameters are returned during the initial request:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | is3DSVer2 |
String | Possible values: true or false . Flag showing that payment uses 3DS 2.0. |
Below are the parameters to be present in the response, after a repeated request for the payment and the need to redirect the client to the ACS during the authentication via the 3DS 2.0 protocol:
Mandatory | Name | Type | Description |
---|---|---|---|
Yes, if the redirect to the ACS is needed | acsUrl |
String | In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS. |
To complete the transaction use finish3dsVer2.do
method.
Examples
Request example
Example of the first request:
curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/performP2P.do' -H 'Content-Type: application/json' --data-raw '{
"username":"test_user",
"password":"test_user_password",
"orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
"fromCard": {
"cardholderName": "TEST CARDHOLDER",
"cvc": "123",
"expirationMonth": 12,
"expirationYear": 2030,
"pan": "5000001111111115"
},
"toCard": {
"pan": "4000001111111118"
},
"amount" : 50000
}'
Example of the second request:
curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/performP2P.do' -H 'Content-Type: application/json' --data-raw '{
"username":"test_user",
"password":"test_user_password",
"orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
"fromCard": {
"cardholderName": "TEST CARDHOLDER",
"cvc": "123",
"expirationMonth": 12,
"expirationYear": 2030,
"pan": "5000001111111115"
},
"toCard": {
"pan": "4000001111111118"
},
"amount" : 50000,
"threeDSServerTransId" : "3afc168a-94b4-4eb3-8e2e-80f6c186669d",
"threeDSVer2FinishUrl" : "https://example.com/acs2/acs/3dsMethod"
}'
Response example
Example of the response to the first request:
{
"errorCode": 0,
"is3DSVer2": true,
"threeDSServerTransId": "3afc168a-94b4-4eb3-8e2e-80f6c186669d",
"threeDSMethodURL": "https://example.com/acs2/acs/3dsMethod",
"threeDSMethodURLServer": "https://example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=3afc168a-94b4-4eb3-8e2e-80f6c186669d",
"threeDSMethodDataPacked": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9jb21tb24wMy50c3QucmJzdGVzdC5ydS8zZHNzZXJ2ZXIvYXBpL3YxL2Fjcy9ub3RpZmljYXRpb24_dGhyZWVEU1NlcnZlclRyYW5zSUQ9M2FmYzE2OGEtOTRiNC00ZWIzLThlMmUtODBmNmMxODY2NjlkIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIzYWZjMTY4YS05NGI0LTRlYjMtOGUyZS04MGY2YzE4NjY2OWQifQ"
}
Example of the response to the second request:
{
"errorCode": 0,
"info": "Your order is proceeded, redirecting...",
"acsUrl": "https://example.com/acs2/acs/creq",
"is3DSVer2": true,
"packedCReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhZmMxNjhhLTk0YjQtNGViMy04ZTJlLTgwZjZjMTg2NjY5ZCIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4xLjAiLCJhY3NUcmFuc0lEIjoiOWM3NTkxMmEtZTg0NC00ODgyLWI5YzctYzZmYmMzNjIyNGQ3IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
}
P2P transfer status
To obtain the status of a registered P2P order, use getP2PStatus.do
request.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Below are possible parameters of the operationList
block.
Mandatory | Name | Type | Description |
---|---|---|---|
No | operationType |
String | Transaction type. The following values are available:
|
Examples
Request example
curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/getP2PStatus.do' -H 'Content-Type: application/json' --data-raw '{
"username": "test_user",
"password": "test_user_password",
"orderId" : "0a4eaae8-653a-71a9-8259-46fc00a8ea58"
}'
Response example
{
"orderStatus": 0,
"errorCode": 0,
"errorMessage": "Successful",
"orderNumber": "2009",
"amount": 50000,
"fee": 0,
"currency": "978",
"creationDate": 1674137044330,
"orderParams": [],
"operationList": [],
"resultCode": 0
}
Stored-credential P2P transfer
To perform a card-to-card transfer by binding, use performP2PByBinding.do
request.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
The fromCard
block (if debiting is done by a third-party system, this block must be absent) includes the following possible parameters:
Mandatory | Name | Type | Description |
---|---|---|---|
No | bindingId |
String | Identifier of the credentials sored when paying for the order or used for payment. Available only if the merchant is allowed to store credentials. |
The toCard
block (if crediting is done by a third-party system, this block must be absent) consists of the following possible parameters:
Mandatory | Name | Type | Description |
---|---|---|---|
No ( | bindingId |
String | Identifier of the credentials sored when paying for the order or used for payment. Available only if the merchant is allowed to store credentials. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/performP2PByBinding.do' -H 'Content-Type: application/json' --data-raw '{
"amountInput" : 1000,
"currency" : "643",
"fromCard" : {
"bindingId" : "03e9492a-536c-7ab4-85e6-b44000f26b04",
"cvc" : "123"
},
"orderId" : "3dbaf8bb-1d68-76b3-b4e6-784700f26b04",
"password" : "testPwd",
"type" : "WITHOUT_TO_CARD",
"username" : "RBS2-33-autotest-api"
}'
Response example
{
"errorCode" : 0,
"errorMessage" : "Успешно",
"info" : "Your order is proceeded, redirecting...",
"redirect" : "https://ya.ru/?orderId=47743354-be15-7c70-b9ef-4bfc482e68dc&lang=ru",
"is3DSVer2" : false
}
Stored-credential P2P fee amount
To get the amount of commission when transferring funds by a stored-credential transaction, use the verifyP2PByBinding.do
request.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
The fromCard
block (if debiting is done by a third-party system, this block must be absent) includes the following possible parameters:
Mandatory | Name | Type | Description |
---|---|---|---|
No ( | bindingId |
String | Identifier of the credentials sored when paying for the order or used for payment. Available only if the merchant is allowed to store credentials. |
The toCard
block (if crediting is done by a third-party system, this block must be absent) consists of the following possible parameters:
Mandatory | Name | Type | Description |
---|---|---|---|
No ( | bindingId |
String | Identifier of the credentials sored when paying for the order or used for payment. Available only if the merchant is allowed to store credentials. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl -X POST 'https://dev.bpcbt.com/payment/rest/api/p2p/verifyP2PByBinding.do' -H 'Content-Type: application/json' --data-raw '{
"amount" : 1000,
"currency" : "643",
"fromCard" : {
"bindingId" : "03ef0b87-05c1-7fa9-8491-7679482e68dc"
},
"orderId" : "47743354-be15-7c70-b9ef-4bfc482e68dc",
"password" : "testPwd",
"username" : "kzntest_p2p-api"
}'
Response example
{
"errorCode" : 0,
"errorMessage" : "Успешно",
"feeDescriptionList" : [ {
"feeAmount" : 10,
"feeCurrency" : "643",
"feeDescription" : "Acquirer fee"
} ]
}
3DS utilities
Redirect to ACS (simplified)
If 3-D Secure is required, then, after receiving a payment order response (paymentOrder
or instantPayment.do
), the customer must be redirected to ACS. In this case, the payment order response contains the the acsUrl
parameter that will be used for the redirect.
The acsRedirect.do
request allows to redirect a customer to the ACS authentication page in a simplified way - just using orderId
parameter received after an order registration.
It is also possible to redirect a customer to ACS with a POST request (regular redirect). The description of this method can be found here.
Without other actions required from customer, the payment gateway redirects them to the ACS page, where customer authenticates.
Then, depending on the authentication result, the customer is redirected to the following URL:
- if authentication succeeds -
returnUrl
with appendedorderId
parameter; - if authentication fails -
failUrl
(orreturnUrl
iffailUrl
was not passed) with appendedorderID
parameter.
To redirect a customer to the ACS, use the following URL:
https://dev.bpcbt.com/payment/acsRedirect.do?orderId=<order number in the system>
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | orderId |
String | Order number in the payment gateway. Unique within the payment gateway. |
Example
Request example
https://dev.bpcbt.com/payment/acsRedirect.do?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1
Redirect URL example
https://mybestmerchantreturnurl.com/?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1
Finishing 3DS payment via API
This method is used in a scheme where issuing bank ACS executes authentication of the cardholder and redirects them to the Merchant.
PARes from ACS is sent to the merchant. Then the Merchant passes it to the Payment Gateway by the finish3dsPayment.do
method.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/rest/finish3dsPayment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data mdOrder=906bf262-bd53-4ac7-983c-07127954681b \
--data paRes=eJzFV2uTokoS%...%ADPms%0D%0A \
--data userName=test_user \
--data password=test_user_password
Response example
{
"redirect": "https://mybestmerchantreturnurl.com?orderId=906bf262-bd53-4ac7-983c-07127954681b",
"errorCode": 0,
}
Finishing a 3DS2 payment via API
The method used for finishing a 3DS2 order via API is finish3dsVer2Payment.do
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | userName |
String | Merchant's API account login. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
Yes | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST \
--url https://dev.bpcbt.com/payment/rest/finish3dsVer2Payment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data threeDSServerTransId=33b17cb5-b4a5-48ac-a3b8-bc8d6d979a46 \
--data userName=test_user \
--data password=test_user_password \
Response example
{
"redirect": "http://test.com?orderId=f61e2a41-34b9-7a2d-b4d6-83ac00c305c8&lang=en",
"errorCode": 0,
"is3DSVer2": true
}
Request example with threeDSVer2MdOrder parameter
curl --request POST \
--url https://dev.bpcbt.com/payment/rest/finish3dsVer2Payment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data threeDSServerTransId=33b17cb5-b4a5-48ac-a3b8-bc8d6d979a46 \
--data threeDSVer2MdOrder=fbcb596f-25ba-70e7-a6cf-4fb100c305c8 \
--data userName=test_user \
--data password=test_user_password \
Response example
{
"redirect": "http://test.com?orderId=f61e2a41-34b9-7a2d-b4d6-83ac00c305c8&lang=en",
"errorCode": 0,
"is3DSVer2": true
}
Miscellaneous
Card verification
verifyCard.do
method can be used in verification opertaions. The payment is not made and goes directly to REVERSED
status.
Request parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | userName |
String | Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter. |
Below are the parameters of the billingPayerData
block (data about the client registration address).
Mandatory | Name | Type | Description |
---|---|---|---|
No | billingCity |
String | The city registered on a specific card of the Issuing Bank. |
Response parameters
Mandatory | Name | Type | Description |
---|---|---|---|
No | errorCode |
Integer | Information parameter in case of an error, which may have different code values:
|
Examples
Request example
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/verifyCard.do </span>
--header 'content-type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data pan=4000001111111118 </span>
--data cvc=123 </span>
--data expiry=203012
Response example
{
"errorCode": "0",
"errorMessage": "Success",
"orderId": "cfc238ca-68f9-745c-ba7e-eb9100af79e0",
"orderNumber": "12017",
"rrn": "111111111115",
"authCode": "123456",
"actionCode": 0,
"actionCodeDescription": "",
"time": 1595284781180,
"eci": "07",
"amount": 0,
"currency": "978"
}
Callback notifications
The payment gateway API allows you to receive callback notifications on changes of payment statuses.
General information
Events that can trigger notifications
You can receive notifications about changes in order payment status and other events in the Payment Gateway.
The most common notifications describe changes in order status, such as:
deposit of funds on Merchant's account
hold of funds on buyer's account
payment reversal
refund
More advanced integrations may make use of additional callback triggers like:
- saving of a card (i.e., storing a credential)
- enabling/disabling an existing stored credential
- payments being declined, etc.
The trigger type is passed in the operation
parameter of the callback (see details below). For convenience, the callbacks for addional triggers can be directed to another URL by using the dynamicCallbackUrl
parameter in order registration requests.
Integration with callback
Instead of the last step of the Redirect integration you may choose to use one of the following approaches.
Make use of returnUrl
When your web-site code located at returnUrl
(for example, https://mybestmerchantreturnurl.com/?back&orderId=61c33664-85a0-7d6b-af26-09ee009c4000&lang=en
) identifies a cardholder being redirected back from the gateway after a payment attempt, you can check the order status using the API request getOrderStatusExtended
.
This option is the easiest one but it is not completely reliable because the cardholder redirect may fail (for example, as a result of a broken connection or the cardholder closing the browser) and returnUrl
may not get the "trigger" to proceed with getOrderStatusExtended
.
curl --request POST </span>
--url https://dev.bpcbt.com/payment/rest/getOrderStatusExtended.do </span>
--header 'content-type: application/x-www-form-urlencoded' </span>
--data userName=test_user </span>
--data password=test_user_password </span>
--data orderId=016b6f47-4628-7ea2-80f5-6c6e00a7d8c0 </span>
--data language=en
{
"errorCode": "0",
"errorMessage": "Success",
"orderNumber": "11008",
"orderStatus": 2,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 2000,
"currency": "978",
"date": 1618577250840,
"orderDescription": "my_first_order",
"merchantOrderParams": [
{
"name": "browser_language_param",
"value": "en"
},
{
"name": "browser_os_param",
"value": "UNKNOWN"
},
{
"name": "user_agent",
"value": "curl/7.75.0"
},
{
"name": "browser_name_param",
"value": "DOWNLOAD"
}
],
"transactionAttributes": [],
"attributes": [
{
"name": "mdOrder",
"value": "016b7747-c4ed-70b3-bc36-fdd400a7d8c0"
}
],
"cardAuthInfo": {
"maskedPan": "555555*5599",
"expiration": "202412",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "123456",
"pan": "555555*5599"
},
"authDateTime": 1618577288377,
"terminalId": "123456",
"authRefNum": "931793605827",
"paymentAmountInfo": {
"paymentState": "DEPOSITED",
"approvedAmount": 2000,
"depositedAmount": 2000,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryCode": "UNKNOWN",
"bankCountryName": "<Unknown>"
}
}
Make use of a signed gateway callback
If you know how to handle digital certificates and signatures, you can use a digitally signed callback with a checksum that the gateway may be configured to send. A checksum is used for verification and security purposes. After the callback signature has been verified on your side, there is no need to send getOrderStatusExtended
because the callback includes the order status.
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=1
Types of notifications
Notifications without checksums
These notifications contain only information about the order, so potentially, the merchant risks accepting a notification sent by an attacker as genuine.
Notifications with checksums
These notifications contain an authentication code in addition to order information. The authentication code is a checksum of order data. This checksum allows to make sure that the callback notification is genuine and was sent by the payment gateway.
There are two methods of implementing callback notifications with checksums:
- using symmetric cryptography — same (symmetric) cryptographic key is used by the payment gateway to create a checksum and by a merchant to validate it;
- using asymmetric cryptography — to create a checksum the payment gateway uses its private key known only to the payment gateway, while for validation of the created checksum the corresponding public key is used, this public key can be distributed openly.
The public key can be downloaded from the payment gate Web console. For more security, it is recommended to use asymmetric cryptography.
To enable notifications with checksums as well as to get the relevant cryptographic key, please, contact our technical support.
Requirements for SSL certificates on the store’s website
If an HTTPS connection is used to access a store that receives callback notifications, the certificate of the site where the store is located must meet the following requirements (see the table below).
Requirement | Description |
---|---|
Signature algorithm. | Not lower than SHA-256.. |
Supported certification authorities. | Below are examples of organizations that register digital certificates:
There are also opportunities to register digital certificates via providers. Self signed certificates are not allowed. The certificate must be signed by a trusted certification authority (see the above list). |
URL format for callback notifications
Notification without a checksum
https://myshop.com/callback/?mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0
Notification with a checksum
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&
orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&
operation=deposited&callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0
The passed parameters are shown in the table below.
The table contains only basic parameters. You can add other parameters you want to receive in your personal cabinet.
Parameter | Description |
---|---|
mdOrder |
Unique order number stored in the payment gateway. |
orderNumber |
Unique order number (identifier) in merchant's system. |
checksum |
Authentication code (checksum) resulting from received parameters. |
operation |
Type of event that triggered notification:
|
status |
Indicates if an operation was successfully processed:
|
Custom headers for callback notifications
In the Admin Panel, in the merchant settings, you can set custom headers for callback notifications. For example:
'http://mybestmerchantreturnurl.com/callback.php', headers={Authorization=token, Content-type=plain
/text}, params={orderNumber=349002, mdOrder=5ffb1899-cd1e-7c1e-8750-e98500093c43, operation=deposited, status=1}
where {Authorization=token, Content-type=plain/text}
is a custom header.
Examples
Example of a notification URL without a checksum
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0
Example of a notification URL with a checksum
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=0
Algorithm for processing callback notifications
Sections below contain notification processing algorithms depending on notification type.
Notification without a checksum
- The payment gateway sends to the merchant's server the following request.
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0
- The merchant's server returns HTTP
200 OK
to the payment gateway.
Notification with a checksum
-
The payment gateway sends the following HTTPS request to the merchant's server - please, note that:
- when using symmetric cryptography, the checksum is generated using a key common for the payment gateway and the merchant;
- when using asymmetric cryptography, the checksum is generated using a private key known only to the payment gateway.
https://mybestmerchantreturnurl.com/path?amount=123456&orderNumber=10747&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&mdOrder=3ff6962a-7dcc-4283-ab50-a6d7dd3386fe&operation=deposited&status=1
The order of the parameters in a notification can be arbitrary.
On the merchant's side
checksum
parameter is removed from the notification parameter string, and the value of this parameter (checksum) is saved for verifying the notification's authenticity.The parameters and their values that are left are used for creating the following string.
parameter_name1;paramenter_value1;parameter_name2;paramenter_value2;…;parameter_nameN;paramenter_valueN;
In this case pairsname_parameter;value_parameter
must be sorted in direct alphabetical order (ascending) by parameter names.
Here is an example of a generated parameter stringamount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;
-
The checksum is calculated on the merchant's side, the method of calculation depends on the method of its formation:
- when using symmetric cryptography - with the help of HMAC-SHA256 algorithm and a private key shared with the payment gateway;
- when using asymmetric cryptography - with the help of a hashing algorithm that depends on how the key pair is created and a public key that is associated with a private key located in the payment gateway.
In the resulting checksum string, all lower-case letters are replaced by upper-case letters.
The resulting value must be compared with the checksum extracted earlier from
checksum
parameter.If the checksums match, the server sends an HTTP code
200 OK
to the payment gateway.
If the checksums match, this notification is authentic and was sent by the payment gateway. Otherwise, it is likely that the attacker is trying to pass off his notification as a payment gateway notification.
Payment status notification
In order to detect whether the payment run successfully or not you need to:
- Сheck the signature;
- Сheck two callback parameters:
operation
andstatus
.
If the operation
value is not approved
or deposited
, then the callback doesn't refer to the payment at all. There must be one of these values.
In addition to the operation
value we should state that in case the status
parameter value is 1
, it means the payment was successfull. Otherwise, it was not.
When notifications fail
If a response other than 200 OK
is returned to the payment gateway, the notification is considered unsuccessful. In this case, the payment gateway repeats the notification at intervals of 30 seconds until one of the following conditions is met:
- the payment gateway receives
200 OK
, OR - there are 3 successive notification failures.
When one of the above conditions is met, attempts to send a callback notification about an event stop.
Code examples
Symmetric cryptography
Java
package net.payrdr.test;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;
public class SymmetricCryptographyExample {
private static final String secretToken = "ooc7slpvc61k7sf7ma7p4hrefr";
private static final Map<String, String> callbackParams = Map.of(
"checksum", "EAF2FB72CAB99FD5067F4BA493DD84F4D79C1589FDE8ED29622F0F07215AA972",
"mdOrder", "06cf5599-3f17-7c86-bdbc-bd7d00a8b38b",
"operation", "approved",
"orderNumber", "2003",
"status", "1"
);
public static void main(String[] args) throws Exception {
String signedString = callbackParams.entrySet().stream()
.filter(entry -> !entry.getKey().equals("checksum"))
.sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
.collect(Collector.of(
StringBuilder::new,
(accumulator, element) -> accumulator
.append(element.getKey()).append(";")
.append(element.getValue()).append(";"),
StringBuilder::append,
StringBuilder::toString
));
byte[] mac = generateHMacSHA256(secretToken.getBytes(), signedString.getBytes());
String signature = callbackParams.get("checksum");
boolean verified = verifyMac(signature, mac);
System.out.println("signature verification result: " + verified);
}
private static boolean verifyMac(String signature, byte[] mac) {
return signature.equals(bytesToHex(mac));
}
public static byte[] generateHMacSHA256(byte[] hmacKeyBytes, byte[] dataBytes) throws Exception {
SecretKeySpec secretKey = new SecretKeySpec(hmacKeyBytes, "HmacSHA256");
Mac hMacSHA256 = Mac.getInstance("HmacSHA256");
hMacSHA256.init(secretKey);
return hMacSHA256.doFinal(dataBytes);
}
private static String bytesToHex(byte[] bytes) {
final byte[] HEX_ARRAY = "0123456789ABCDEF".getBytes(StandardCharsets.US_ASCII);
byte[] hexChars = new byte[bytes.length * 2];
for (int j = 0; j < bytes.length; j++) {
int v = bytes[j] & 0xFF;
hexChars[j * 2] = HEX_ARRAY[v >>> 4];
hexChars[j * 2 + 1] = HEX_ARRAY[v & 0x0F];
}
return new String(hexChars, StandardCharsets.UTF_8);
}
}
Asymmetric cryptography
Java
package net.payrdr.test;
import java.io.ByteArrayInputStream;
import java.io.InputStream;
import java.security.Signature;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;
import java.util.Base64;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;
public class AsymmetricCryptographyExample {
private static final Map<String, String> callbackParams = Map.of(
"amount", "35000099",
"sign_alias", "SHA-256 with RSA",
"checksum", "163BD9FAE437B5DCDAAC4EB5ECEE5E533DAC7BD2C8947B0719F7A8BD17C101EBDBEACDB295C10BF041E903AF3FF1E6101FF7DB9BD024C6272912D86382090D5A7614E174DC034EBBB541435C80869CEED1F1E1710B71D6EE7F52AE354505A83A1E279FBA02572DC4661C1D75ABF5A7130B70306CAFA69DABC2F6200A698198F8",
"mdOrder", "12b59da8-f68f-7c8d-12b5-9da8000826ea",
"operation", "deposited",
"status", "1");
private static final String certificate =
"MIICcTCCAdqgAwIBAgIGAWAnZt3aMA0GCSqGSIb3DQEBCwUAMHwxIDAeBgkqhkiG9w0BCQEWEWt6" +
"bnRlc3RAeWFuZGV4LnJ1MQswCQYDVQQGEwJSVTESMBAGA1UECBMJVGF0YXJzdGFuMQ4wDAYDVQQH" +
"EwVLYXphbjEMMAoGA1UEChMDUkJTMQswCQYDVQQLEwJRQTEMMAoGA1UEAxMDUkJTMB4XDTE3MTIw" +
"NTE2MDEyMFoXDTE4MTIwNTE2MDExOVowfDEgMB4GCSqGSIb3DQEJARYRa3pudGVzdEB5YW5kZXgu" +
"cnUxCzAJBgNVBAYTAlJVMRIwEAYDVQQIEwlUYXRhcnN0YW4xDjAMBgNVBAcTBUthemFuMQwwCgYD" +
"VQQKEwNSQlMxCzAJBgNVBAsTAlFBMQwwCgYDVQQDEwNSQlMwgZ8wDQYJKoZIhvcNAQEBBQADgY0A" +
"MIGJAoGBAJNgxgtWRFe8zhF6FE1C8s1t/dnnC8qzNN+uuUOQ3hBx1CHKQTEtZFTiCbNLMNkgWtJ/" +
"CRBBiFXQbyza0/Ks7FRgSD52qFYUV05zRjLLoEyzG6LAfihJwTEPddNxBNvCxqdBeVdDThG81zC0" +
"DiAhMeSwvcPCtejaDDSEYcQBLLhDAgMBAAEwDQYJKoZIhvcNAQELBQADgYEAfRP54xwuGLW/Cg08" +
"ar6YqhdFNGq5TgXMBvQGQfRvL7W6oH67PcvzgvzN8XCL56dcpB7S8ek6NGYfPQ4K2zhgxhxpFEDH" +
"PcgU4vswnhhWbGVMoVgmTA0hEkwq86CA5ZXJkJm6f3E/J6lYoPQaKatKF24706T6iH2htG4Bkjre" +
"gUA=";
public static void main(String[] args) throws Exception {
String signedString = callbackParams.entrySet().stream()
.filter(entry -> !entry.getKey().equals("checksum") && !entry.getKey().equals("sign_alias"))
.sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
.collect(Collector.of(
StringBuilder::new,
(accumulator, element) -> accumulator
.append(element.getKey()).append(";")
.append(element.getValue()).append(";"),
StringBuilder::append,
StringBuilder::toString
));
InputStream publicCertificate = new ByteArrayInputStream(Base64.getDecoder().decode(certificate));
String signature = callbackParams.get("checksum");
boolean verified = checkSignature(signedString.getBytes(), signature.getBytes(), publicCertificate);
System.out.println("signature verification result: " + verified);
}
private static boolean checkSignature(byte[] signedString, byte[] signature, InputStream publicCertificate) throws Exception {
CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
X509Certificate x509Cert = (X509Certificate) certFactory.generateCertificate(publicCertificate);
Signature signatureAlgorithm = Signature.getInstance("SHA512withRSA");
signatureAlgorithm.initVerify(x509Cert.getPublicKey());
signatureAlgorithm.update(signedString);
return signatureAlgorithm.verify(decodeHex(new String(signature)));
}
private static byte[] decodeHex(String hex) {
int l = hex.length();
byte[] data = new byte[l / 2];
for (int i = 0; i < l; i += 2) {
data[i / 2] = (byte) ((Character.digit(hex.charAt(i), 16) << 4)
+ Character.digit(hex.charAt(i + 1), 16));
}
return data;
}
}
Symmetric cryptography
PHP
<?php
$data = 'amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;';
$key = 'yourSecretToken';
$hmac = hash_hmac ( 'sha256' , $data , $key);
echo "[$hmac]\n";
?>
- Assign the string value to
data
variable. - Assign the private key value to the
key
variable. -
hash_hmac
function ( 'sha256', $data, $key) calculates the checksum of the passed string using the private key and SHA-256 algorithm. - Save the function output in
hmac
variable. - Use
echo
function to create an output. - Compare this value with the one passed in the callback notification.
Asymmetric cryptography
PHP
<?php
// data from response
$data = 'amount;35000099;mdOrder;12b59da8-f68f-7c8d-12b5-9da8000826ea;operation;deposited;status;1;';
$checksum = '9524FD765FB1BABFB1F42E4BC6EF5A4B07BAA3F9C809098ACBB462618A9327539F975FEDB4CF6EC1556FF88BA74774342AF4F5B51BA63903BE9647C670EBD962467282955BD1D57B16935C956864526810870CD32967845EBABE1C6565C03F94FF66907CEDB54669A1C74AC1AD6E39B67FA7EF6D305A007A474F03B80FD6C965656BEAA74E09BB1189F4B32E622C903DC52843C454B7ACF76D6F76324C27767DE2FF6E7217716C19C530CA7551DB58268CC815638C30F3BCA3270E1FD44F63C14974B108E65C20638ECE2F2D752F32742FFC5077415102706FA5235D310D4948A780B08D1B75C8983F22F211DFCBF14435F262ADDA6A97BFEB6D332C3D51010B';
// your public key (e.g. SHA-512 with RSA)
// if you have a CERT, please see openssl_get_publickey()
$publicKey = <<<EOD
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwtuGKbQ4WmfdV1gjWWys
5jyHKTWXnxX3zVa5/Cx5aKwJpOsjrXnHh6l8bOPQ6Sgj3iSeKJ9plZ3i7rPjkfmw
qUOJ1eLU5NvGkVjOgyi11aUKgEKwS5Iq5HZvXmPLzu+U22EUCTQwjBqnE/Wf0hnI
wYABDgc0fJeJJAHYHMBcJXTuxF8DmDf4DpbLrQ2bpGaCPKcX+04POS4zVLVCHF6N
6gYtM7U2QXYcTMTGsAvmIqSj1vddGwvNGeeUVoPbo6enMBbvZgjN5p6j3ItTziMb
Vba3m/u7bU1dOG2/79UpGAGR10qEFHiOqS6WpO7CuIR2tL9EznXRc7D9JZKwGfoY
/QIDAQAB
-----END PUBLIC KEY-----
EOD;
$binarySignature = hex2bin(strtolower($checksum));
$isVerify = openssl_verify($data, $binarySignature, $publicKey, OPENSSL_ALGO_SHA512);
if ($isVerify == 1) {
echo "signature ok\n";
} elseif ($isVerify == 0) {
echo "bad (there's something wrong)\n";
} else {
echo "error checking signature\n";
}
?>