NAV

For any question, we are one click away

Contact us

Authentication

For merchant authentication in the payment gateway two methods can be used.

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.
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:

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:

  1. Call getOrderStatusExtended.do;
  2. Check the orderStatus field in the response: the order is considered to be payed only if the orderStatus value is 1 or 2.

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:

  1. Call getOrderStatusExtended.do;
  2. Check the orderStatus field in the response: the order is considered to be payed only if the orderStatus value is 1 or 2.

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.

Download Postman collection

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • email - cardholder email to prefill on checkout page
  • phone - cardholder Billing phone number to prefill on checkout page
  • backToShopUrl - adds checkout page button that will take a cardholder back to the assigned merchant web-site URL
  • backToShopName - customizes default "Back to shop" button text label if used along with backToShopUrl
  • payerPostalCode - cardholder Shipping postal code
  • payerCountry - cardholder Shipping country
  • payerState - cardholder Shipping state
  • payerCity - cardholder Shipping city
  • postAddress - cardholder Shipping address
  • installments - maximum number of allowed authorizations for installment payments. Is required for creating an installment stored credential.
  • recurringFrequency - minimum number of days between authorizations. Is required for creating a recurrent stored credential and recommended for creating an installment stored credential (required if 3DS2 is used).
  • recurringExpiry - the date after which authorizations are not allowed, in YYYYMMDD format. Is required for creating a recurrent stored credential and recommended for creating an installment stored credential (required if 3DS2 is used).
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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.
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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 – no VAT;
  • 1 – 0% VAT;
  • 2 – 10% receipt VAT rate;
  • 4 – 10/110 VAT applicable rate;
  • 6 - 20% receipt VAT rate;
  • 7 - 20/120 applicable VAT rate.

Description of parameters in itemAttributes object:

Mandatory Name Type Description
Yes

paymentMethod Integer Payment type, the available values are:
  • 1 - full prepayment;
  • 2 - partial prepayment;
  • 3 - advance payment;
  • 4 - full payment;
  • 5 - partial payment with further installment payments;
  • 6 - no payment with further installment payments;
  • 7 - paymenty with further installment payments.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which error parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

if acsUrl is not null, then 3DS flow should be initiated. Otherwise see orderStatus:

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"
    }
}

Card data validation

Payment card validation is done as shown in the table below.

Parameter Description Validation

PAN

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:
  • true - request processed successfully;
  • false - request failed.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • true - request processed successfully;
  • false - request failed.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.
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:
  • CREATED - order created (but not paid);
  • APPROVED - order approved (funds are on hold on buyer's account);
  • DEPOSITED - order deposited (buyer is charged);
  • DECLINED - order declined;
  • REVERSED - order canceled;
  • REFUNDED - refund.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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.
  • ECI=1 or ECI=6 - merchant supports 3-D Secure, payment card does not support 3-D Secure, payment is processed based on CVV2/CVC code.
  • ECI=2 or ECI=5 - both merchant and payment card support 3-D Secure;
  • ECI=7 - merchant does not support 3-D Secure, payment is processed based on CVV2/CVC code.

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": "&ltUnknown&gt"
  }
}

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:
  • true - request processed successfully;
  • false - request failed.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.
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:
  • CREATED - order created (but not paid);
  • APPROVED - order approved (funds are on hold on buyer's account);
  • DEPOSITED - order deposited (buyer is charged);
  • DECLINED - order declined;
  • REVERSED - order canceled;
  • REFUNDED - refund.

bankInfo block contains the following elements.

Mandatory Name Type Description
Yes

bankCountryName String Country of the issuing bank.

Then you should see orderStatus:

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:
  • true - request processed successfully;
  • false - request failed.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • CREATED - order created (but not paid);
  • APPROVED - order approved (funds are on hold on buyer's account);
  • DEPOSITED - order deposited (buyer is charged);
  • DECLINED - order declined;
  • REVERSED - order canceled;
  • REFUNDED - refund.

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:
  • true - request processed successfully;
  • false - request failed.

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:
  • true - request processed successfully;
  • false - request failed.

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:
  • true - request processed successfully;
  • false - request failed.

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:
  • true - request processed successfully;
  • false - request failed.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

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:
  • 0 value - indicates success of processing;
  • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
It also can be missing if the result has not caused any error.

Below are possible parameters of the operationList block.

Mandatory Name Type Description
No

operationType String Transaction type. The following values are available:
  • P2P_VERIFY - requests the fee amount;
  • P2P_DEBIT - debits the money;
  • P2P_CREDIT - credits the money;
  • P2P_DEBIT_REVERSAL - debit cancellation;
  • P2P_CREDIT_REVERSAL - credit cancellation;
  • P2P_TRANSFER - card-to-card money transfer;
  • P2P_TRANSFER_REVERSAL - automatic refund if an error occurs during the transfer.

    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:
    • 0 value - indicates success of processing;
    • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
    It also can be missing if the result has not caused any error.

    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:
    • 0 value - indicates success of processing;
    • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
    It also can be missing if the result has not caused any error.

    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:

    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:
    • 0 value - indicates success of processing;
    • another positive number value - indicates an error for more details of which error parameter must be inspected.
    It also can be missing if the result has not caused any error.

    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:
    • 0 value - indicates success of processing;
    • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
    It also can be missing if the result has not caused any error.

    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:
    • 0 value - indicates success of processing;
    • another positive number value - indicates an error for more details of which errorMesage parameter must be inspected.
    It also can be missing if the result has not caused any error.

    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:

    More advanced integrations may make use of additional callback triggers like:

    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.

    getOrderStatusExtended.do

    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": "&ltUnknown&gt"
      }
    }
    

    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:


    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:
    • Thawte Consulting cc – https://www.thawte.com/;
    • VeriSign – https://www.verisign.com/;
    • DigiCert Inc – https://www.digicert.com/;
    • COMODO CA Limited – https://www.comodo.com/;
    • GeoTrust Inc. – https://www.geotrust.com/;
    • GlobalSign – https://www.globalsign.com/;
    • Trustis Limited – http://www.trustis.com/;
    • UniTrust – http://www.unitrust.co.uk/.

    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:
    • approved - funds are put on hold on buyer's account;
    • deposited - order deposited;
    • reversed - payment was reversed;
    • refunded - order was refunded;
    • binding created - payer's card has been saved (a credential was stored);
    • binding_activity_changed - an existing stored credential was disabled/enabled;
    • declined_by_timeout - payment was declined because it timed out;
    • declined_cardpresent - a declined card-present transaction (payment with physical card).
    status Indicates if an operation was successfully processed:
    • 1 - success;
    • 0 - fail.

    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

    1. 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
    2. The merchant's server returns HTTP 200 OK to the payment gateway.

    Notification with a checksum

    1. 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.
    2. 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.

    3. 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 pairs name_parameter;value_parameter must be sorted in direct alphabetical order (ascending) by parameter names.
      Here is an example of a generated parameter string
      amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;

    4. 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.
    5. In the resulting checksum string, all lower-case letters are replaced by upper-case letters.

    6. The resulting value must be compared with the checksum extracted earlier from checksum parameter.

    7. 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:

    1. Сheck the signature;
    2. Сheck two callback parameters: operation and status.

    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:

    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";
    ?>
    
    1. Assign the string value to data variable.
    2. Assign the private key value to the key variable.
    3. hash_hmac function ( 'sha256', $data, $key) calculates the checksum of the passed string using the private key and SHA-256 algorithm.
    4. Save the function output in hmac variable.
    5. Use echo function to create an output.
    6. 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";
    }
    ?>