Authentication

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

Using login and password of the merchant's API user (account with -api postfix) received on registration. These values are passed in userName and password parameters correspondingly (see the table below).

Mandatory	Name	Type	Description
See description	`userName`	String	Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass `token` parameter.

Using a special token - you can request its value in the technical support service. In requests its value is passed in token parameter (see the table below).

Mandatory	Name	Type	Description
See description	`token`	String	Value that is used for merchant authentication when requests are sent to the payment gateway. If you pass this parameter do not pass `userName` and `password`.

Using REST protocol send requests with application/x-www-form-urlencoded type, not multipart/form-data type.

Errors

HTTP status codes:

200 - in case of the Payment Gateway API calls the JSON payload from the response must be inspected to determine whether processing was successful or not. Success is indicated by either:
- the success parameter value being true
- the errorCode parameter value being 0
If both parameters are present, success overrides errorCode.
400 - an internal error occurred in the system.
404 - error while calling API - URL is incorrect (does not exist).
429 - this code means that the system is overloaded. Most often the main reason is that the limit of requests per second or limit of simultaneous requests is reached. But it may also be due to the fact that the system as a whole is overloaded (regardless of your requests).
500 or 502 - this code means that something went wrong on our side.

If the request, associated with an order payment, is processed successfully, it does not directly mean that the payment itself was successful.

To determine whether the payment was successful or not, you may refer to the description of the request used, where the intepretation of the payment success is thoroughly described, or you may follow the rule of thumb here:

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

In case the orderStatus value is 1, there is still a need to capture money. Otherwise, the money will be returned to a cardholder in a week or so.

API request signature

Facing insecure integration you may be requested to implement an asymmetric request signature. Usually this requirement is applied only if you carry out P2P/AFT/OCT requests.

To have a possibility to sign requests you need first to upload a certificate needed by contacting the technical support service.

Having an appropriate signature key uploaded, you need to generate a hash and a signature using your secret key, in the process of sending a request used in the API interface.

Thus, the correct hash (X-Hash) and the signature value (X-Signature) must be passed in the request header. The header is filled in using SHA256 and RSA algorithms. The request header will look like this:

X-Hash: GDrobAlCcpdOOlVuqra7Oogl/4s3vToGOXGpf3t/wJ0= 
X-Signature: TJrm6jYAf2ssp/iYoDb3B+nuPqQ572oe/3a2RQ4oG2BFbmeRcoiITvR6tybNsbRHvRRlJys/2xFB  W9ilee9GCN9WwYJ9h/MDyUEktj6NLZOztBAWi+7S8LDaiEWd+MUdTqe0hdiqo/lY2uIlEMTtkqTB  7LsbEhrJ6NhJdpSxrstAnpyGIrGfldt0Vz+gz+YQ5XXrwhD6HyGShqV+tXzxcMdezWJJJ8vH5C0s  4jij2PuoauUSHkTrSc4vIJl/TPMliLJNsC5KCXka4/1hSr0exawFBekRldFnv5YvFakWJUN3kEc8  w3uauzTDh+CG0/Vxs/3gNun7e9ik9kCpwdiSMw==

Payment status

The most straightforward way to know the status of the payment is to use a dedicated API call:

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

In case the orderStatus value is 1, there is still a need to capture money. Otherwise, the money will be returned to a cardholder in a week or so.

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.

Response is successful only if http status code = 200 and errorCode = 0

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

1 - order is APPROVED
2 - order is DEPOSITED
5 - redirect to ACS, see acsUrl (order is CREATED, but not paid yet)

Examples

Request example

curl --request POST \
--url  https://dev.bpcbt.com/payment/rest/instantPayment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data amount=100 \
--data currency=978 \
--data description=my_first_order \
--data orderNumber=1218637308 \
--data pan=5000001111111115 \
--data cvc=123 \
--data expiry=203012 \
--data cardHolderName="TEST CARDHOLDER" \
--data language=en \
--data backUrl=https%3A%2F%2Fmybestmerchantreturnurl.com \
--data failUrl=https%3A%2F%2Fmybestmerchantreturnurl.com

Response example

{
    "errorCode": "0",
    "orderId": "eee72f6e-b980-79c5-92e8-6f4200b1eae0",
    "info": "Your order is proceeded, redirecting...",
    "redirect": "https://www.test.com/payment/merchants/gateway/finish.html?orderId=eee72f6e-b980-79c5-92e8-6f4200b1eae0&lang=en",
    "orderStatus": {
        "expiration": "202412",
        "cardholderName": "TEST CARDHOLDER",
        "depositAmount": 100,
        "currency": "978",
        "approvalCode": "123456",
        "authCode": 2,
        "ErrorCode": "0",
        "ErrorMessage": "Success",
        "OrderStatus": 2,
        "OrderNumber": "2011",
        "Pan": "500000**1115",
        "Amount": 100,
        "Ip": "10.99.50.35"
    }
}

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.

Response is successful only if http status code = 200 and errorCode = 0

Then you should see orderStatus:

1 - order is APPROVED
2 - order is DEPOSITED

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/payment/applepay/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
  "additionalParameters" : {
    "phone" : "9521235847",
    "order-pain" : "111",
    "email" : "apple@pay.com"
  },
  "features" : [ ],
  "language" : "ru",
  "merchant" : "sandbox_merchant",
  "orderNumber" : "281477871",
  "paymentToken" : "eyJkYXRhIjoiYPhK3M1bEtm...YjM2NWMzZWNmYjE5fIkVDX3YxIn0=",
  "preAuth" : false,
  "recurrent" : false,
  "recurrentInitialize" : false
}'

Response in case of a successful payment

{
    "success": true,
    "data": {
        "orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
    },
    "orderStatus": {
        "errorCode": "0",
        "orderNumber": "229",
        "orderStatus": 1,
        "actionCode": 0,
        "actionCodeDescription": "",
        "amount": 960000,
        "currency": "978",
        "date": 1478682458102,
        "ip": "81.18.144.51",
        "merchantOrderParams": [
            {
                "name": "param2",
                "value": "param2"
            },
            {
                "name": "param1",
                "value": "param1"
            }
        ],
        "attributes": [
            {
                "name": "mdOrder",
                "value": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
            }
        ],
        "cardAuthInfo": {
            "expiration": "203012",
            "cardholderName": "TEST CARDHOLDER",
            "approvalCode": "123456",
            "pan": "500000**1115"
        },
        "authDateTime": 1478682459082,
        "terminalId": "12345678",
        "authRefNum": "111111111111",
        "paymentAmountInfo": {
            "paymentState": "APPROVED",
            "approvedAmount": 960000,
            "depositedAmount": 0,
            "refundedAmount": 0
        },
        "bankInfo": {
            "bankCountryName": "<UNKNOWN>"
        }
    }
}

Response in case of a failed payment

{
  "error": {
    "code": 10,
    "description": "Processing Error",
    "message": "Auth is invalid"
  },
  "success": false
}

Apple Pay Direct

The request used to make a direct payment via Apple Pay is apple/paymentDirect.do. This request can be used for integrations that involve payment data decoding on Merchant side.

Request parameters

Mandatory	Name	Type	Description
Yes	`userName`	String	Merchant's API account login.

Possible values of tii (read about the stored credential types supported by the Payment Gateway here):

`tii` value	Description	Transaction type	Transaction initiator	Card data for transaction	Card data saved after transaction	Note
Empty		Regular	Customer	Entered by Customer	No	An e-commerce transaction, credential is not stored.
CI	Initial Common CIT	Initiating	Customer	Entered by Customer	Yes	An e-commerce transaction, credential is stored.
II	Initial Installment CIT	Initiating	Customer	Entered by Customer	Yes	An e-commerce transaction, credential is stored.
RI	Initial Recurrent CIT	Initiating	Customer	Entered by Customer	Yes	An e-commerce transaction, credential is stored.
F	Unscheduled CIT	Subsequent	Customer	Customer selects card instead of manual entry	No	An e-commerce transaction that uses a stored credential.
U	Unscheduled MIT	Subsequent	Merchant	No manual entry, Merchant passes the data	No	An e-commerce transaction that uses a stored credential
R	Recurrent MIT	Subsequent	Merchant	No manual entry, Merchant passes the data	No	A recurrent transaction that uses a stored credential.
I	Installment MIT	Subsequent	Merchant	No manual entry, Merchant passes the data	No	An installment transaction that uses a stored credential.

Below are the parameters of the billingPayerData block (data about the client registration address).

Mandatory	Name	Type	Description
No	`billingCity`	String	The city registered on a specific card of the Issuing Bank.

Response parameters

Mandatory	Name	Type	Description
Yes	`success`	String	Main parameter which indicates directly that the request was successful. The following values are available: `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.

Response is successful only if http status code = 200 and errorCode = 0.

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.

It is necessary to add to the request a header with the definition of the type of contents - Content-Type: application/json to ensure that the request is processed correctly.

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:

The online store passes the data of the card to be debited and of the card to be credited to the payment gateway. In this case both blocks of parameters — fromCard and toCard — must be presented in the request.
If the money is transferred to the card by a third-party system, the online store passes only the data of the card to be debited to the payment gateway. In this case the request must include only one block of parameters — fromCard.
If debiting is performed by a third-party system, the online store passes only the data of the card to be credited to the payment gateway. In this case the request must include only one block of parameters – toCard.

Request parameters

Mandatory	Name	Type	Description
Yes	`userName`	String	Merchant's API account login.

The fromCard block (if debiting is done by a third-party system, this block must be absent) includes the following possible parameters:

Mandatory	Name	Type	Description
Yes	`pan`	String	The number of the card to be debited.

The toCard block (if crediting is done by a third-party system, this block must be absent) consists of the following possible parameters:

Mandatory	Name	Type	Description
Yes	`pan`	String	The number of the card to be credited.

Response parameters

Mandatory	Name	Type	Description
Yes	`errorCode`	Integer	Information parameter in case of an error, which may have different code values: `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.

If a fee is to be charged for the money transfer, it is necessary to execute a request (verifyP2P.do) to obtain its amount before executing the transfer.

The structure of the performP2P.do request assumes the presence of the fromCard block to pass the attributes of the card to be debited and the toCard block to pass the attributes of the card to be credited. Depending on the business processes of the bank and the online store, the following options are possible when carrying out a card-to-card money transfer:

The online store passes the data of the card to be debited and of the card to be credited to the payment gateway. In this case both blocks of parameters — fromCard and toCard — must be present in the request.
If the money is transferred to the card by a third-party system, the online store passes only the data of the card to be debited to the payment gateway. In this case the request must include only one block of parameters — fromCard.
If debiting is performed by a third-party system, the online store passes only the data on the card to be credited to the payment gateway. In this case the request must include only one block of parameters — toCard.

Request parameters

Mandatory	Name	Type	Description
Yes	`userName`	String	Merchant's API account login.

Below are the parameters of the billingPayerData block (data about the client registration address).

Mandatory	Name	Type	Description
No	`billingCity`	String	The city registered on a specific card of the Issuing Bank.

The fromCard block (if debiting is done by a third-party system, this block must be absent) includes the following possible parameters:

Mandatory	Name	Type	Description
Yes	`pan`	String	The number of the card to be debited.

The toCard block (if crediting is done by a third-party system, this block must be absent) consists of the following possible parameters:

Mandatory	Name	Type	Description
Yes	`pan`	String	The number of the card to be credited.

The following parameters are also passed during the authentication via the 3DS 2.0 protocol:

Mandatory	Name	Type	Description
No	`threeDSDsTransID`	String	Unique identifier of transaction witin IPS.

Response parameters

Mandatory	Name	Type	Description
Yes	`errorCode`	Integer	Information parameter in case of an error, which may have different code values: `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:

if authentication succeeds - returnUrl with appended orderId parameter;
if authentication fails - failUrl (or returnUrl if failUrl was not passed) with appended orderID parameter.

To redirect a customer to the ACS, use the following URL:

https://dev.bpcbt.com/payment/acsRedirect.do?orderId=<order number in the system>

Request parameters

Mandatory	Name	Type	Description
Yes	`orderId`	String	Order number in the payment gateway. Unique within the payment gateway.

Example

Request example

https://dev.bpcbt.com/payment/acsRedirect.do?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1

Redirect URL example

https://mybestmerchantreturnurl.com/?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1

Finishing 3DS payment via API

This method is used in a scheme where issuing bank ACS executes authentication of the cardholder and redirects them to the Merchant. PARes from ACS is sent to the merchant. Then the Merchant passes it to the Payment Gateway by the finish3dsPayment.do method.

Request parameters

Mandatory	Name	Type	Description
Yes	`userName`	String	Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass `token` parameter.

Response parameters

Mandatory	Name	Type	Description
No	`errorCode`	Integer	Information parameter in case of an error, which may have different code values: `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:

deposit of funds on Merchant's account
hold of funds on buyer's account
payment reversal
refund

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

saving of a card (i.e., storing a credential)
enabling/disabling an existing stored credential
payments being declined, etc.

The trigger type is passed in the operation parameter of the callback (see details below). For convenience, the callbacks for addional triggers can be directed to another URL by using the dynamicCallbackUrl parameter in order registration requests.

Integration with callback

Instead of the last step of the Redirect integration you may choose to use one of the following approaches.

Make use of `returnUrl`

When your web-site code located at returnUrl (for example, https://mybestmerchantreturnurl.com/?back&orderId=61c33664-85a0-7d6b-af26-09ee009c4000&lang=en) identifies a cardholder being redirected back from the gateway after a payment attempt, you can check the order status using the API request getOrderStatusExtended.
This option is the easiest one but it is not completely reliable because the cardholder redirect may fail (for example, as a result of a broken connection or the cardholder closing the browser) and returnUrl may not get the "trigger" to proceed with getOrderStatusExtended.

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:

using symmetric cryptography — same (symmetric) cryptographic key is used by the payment gateway to create a checksum and by a merchant to validate it;
using asymmetric cryptography — to create a checksum the payment gateway uses its private key known only to the payment gateway, while for validation of the created checksum the corresponding public key is used, this public key can be distributed openly.

The public key can be downloaded from the payment gate Web console. For more security, it is recommended to use asymmetric cryptography.
To enable notifications with checksums as well as to get the relevant cryptographic key, please, contact our technical support.

Requirements for SSL certificates on the store’s website

If an HTTPS connection is used to access a store that receives callback notifications, the certificate of the site where the store is located must meet the following requirements (see the table below).

Requirement

Description

Signature algorithm.

Not lower than SHA-256..

Supported certification authorities.

Below are examples of organizations that register digital certificates:

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

The payment gateway sends to the merchant's server the following request.
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0
The merchant's server returns HTTP 200 OK to the payment gateway.

Notification with a checksum

The payment gateway sends the following HTTPS request to the merchant's server - please, note that:
- when using symmetric cryptography, the checksum is generated using a key common for the payment gateway and the merchant;
- when using asymmetric cryptography, the checksum is generated using a private key known only to the payment gateway.
  https://mybestmerchantreturnurl.com/path?amount=123456&orderNumber=10747&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&mdOrder=3ff6962a-7dcc-4283-ab50-a6d7dd3386fe&operation=deposited&status=1
  The order of the parameters in a notification can be arbitrary.
Note that callback notifications are sent only via port 443 (HTTPS).
On the merchant's side checksum parameter is removed from the notification parameter string, and the value of this parameter (checksum) is saved for verifying the notification's authenticity.
The parameters and their values that are left are used for creating the following string.
parameter_name1;paramenter_value1;parameter_name2;paramenter_value2;…;parameter_nameN;paramenter_valueN;
In this case 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;
Note that the string ends with a semicolon (";").
The checksum is calculated on the merchant's side, the method of calculation depends on the method of its formation:
- when using symmetric cryptography - with the help of HMAC-SHA256 algorithm and a private key shared with the payment gateway;
- when using asymmetric cryptography - with the help of a hashing algorithm that depends on how the key pair is created and a public key that is associated with a private key located in the payment gateway.
In the resulting checksum string, all lower-case letters are replaced by upper-case letters.
The resulting value must be compared with the checksum extracted earlier from checksum parameter.
If the checksums match, the server sends an HTTP code 200 OK to the payment gateway.

If the checksums match, this notification is authentic and was sent by the payment gateway. Otherwise, it is likely that the attacker is trying to pass off his notification as a payment gateway notification.

Payment status notification

In order to detect whether the payment run successfully or not you need to:

Сheck the signature;
Сheck two callback parameters: operation 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:

the payment gateway receives 200 OK, OR
there are 3 successive notification failures.

When one of the above conditions is met, attempts to send a callback notification about an event stop.

Code examples

Symmetric cryptography

Java

package net.payrdr.test;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;

public class SymmetricCryptographyExample {

    private static final String secretToken = "ooc7slpvc61k7sf7ma7p4hrefr";
    private static final Map<String, String> callbackParams = Map.of(
            "checksum", "EAF2FB72CAB99FD5067F4BA493DD84F4D79C1589FDE8ED29622F0F07215AA972",
            "mdOrder", "06cf5599-3f17-7c86-bdbc-bd7d00a8b38b",
            "operation", "approved",
            "orderNumber", "2003",
            "status", "1"
    );

    public static void main(String[] args) throws Exception {
        String signedString = callbackParams.entrySet().stream()
                .filter(entry -> !entry.getKey().equals("checksum"))
                .sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
                .collect(Collector.of(
                        StringBuilder::new,
                        (accumulator, element) -> accumulator
                                .append(element.getKey()).append(";")
                                .append(element.getValue()).append(";"),
                        StringBuilder::append,
                        StringBuilder::toString
                ));

        byte[] mac = generateHMacSHA256(secretToken.getBytes(), signedString.getBytes());
        String signature = callbackParams.get("checksum");

        boolean verified = verifyMac(signature, mac);
        System.out.println("signature verification result: " + verified);
    }

    private static boolean verifyMac(String signature, byte[] mac) {
        return signature.equals(bytesToHex(mac));
    }

    public static byte[] generateHMacSHA256(byte[] hmacKeyBytes, byte[] dataBytes) throws Exception {
        SecretKeySpec secretKey = new SecretKeySpec(hmacKeyBytes, "HmacSHA256");

        Mac hMacSHA256 = Mac.getInstance("HmacSHA256");
        hMacSHA256.init(secretKey);

        return hMacSHA256.doFinal(dataBytes);
    }

    private static String bytesToHex(byte[] bytes) {
        final byte[] HEX_ARRAY = "0123456789ABCDEF".getBytes(StandardCharsets.US_ASCII);
        byte[] hexChars = new byte[bytes.length * 2];
        for (int j = 0; j < bytes.length; j++) {
            int v = bytes[j] & 0xFF;
            hexChars[j * 2] = HEX_ARRAY[v >>> 4];
            hexChars[j * 2 + 1] = HEX_ARRAY[v & 0x0F];
        }
        return new String(hexChars, StandardCharsets.UTF_8);
    }
}

Asymmetric cryptography

Java

package net.payrdr.test;

import java.io.ByteArrayInputStream;
import java.io.InputStream;
import java.security.Signature;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;
import java.util.Base64;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;

public class AsymmetricCryptographyExample {

    private static final Map<String, String> callbackParams = Map.of(
            "amount", "35000099",
            "sign_alias", "SHA-256 with RSA",
            "checksum", "163BD9FAE437B5DCDAAC4EB5ECEE5E533DAC7BD2C8947B0719F7A8BD17C101EBDBEACDB295C10BF041E903AF3FF1E6101FF7DB9BD024C6272912D86382090D5A7614E174DC034EBBB541435C80869CEED1F1E1710B71D6EE7F52AE354505A83A1E279FBA02572DC4661C1D75ABF5A7130B70306CAFA69DABC2F6200A698198F8",
            "mdOrder", "12b59da8-f68f-7c8d-12b5-9da8000826ea",
            "operation", "deposited",
            "status", "1");

    private static final String certificate =
            "MIICcTCCAdqgAwIBAgIGAWAnZt3aMA0GCSqGSIb3DQEBCwUAMHwxIDAeBgkqhkiG9w0BCQEWEWt6" +
                    "bnRlc3RAeWFuZGV4LnJ1MQswCQYDVQQGEwJSVTESMBAGA1UECBMJVGF0YXJzdGFuMQ4wDAYDVQQH" +
                    "EwVLYXphbjEMMAoGA1UEChMDUkJTMQswCQYDVQQLEwJRQTEMMAoGA1UEAxMDUkJTMB4XDTE3MTIw" +
                    "NTE2MDEyMFoXDTE4MTIwNTE2MDExOVowfDEgMB4GCSqGSIb3DQEJARYRa3pudGVzdEB5YW5kZXgu" +
                    "cnUxCzAJBgNVBAYTAlJVMRIwEAYDVQQIEwlUYXRhcnN0YW4xDjAMBgNVBAcTBUthemFuMQwwCgYD" +
                    "VQQKEwNSQlMxCzAJBgNVBAsTAlFBMQwwCgYDVQQDEwNSQlMwgZ8wDQYJKoZIhvcNAQEBBQADgY0A" +
                    "MIGJAoGBAJNgxgtWRFe8zhF6FE1C8s1t/dnnC8qzNN+uuUOQ3hBx1CHKQTEtZFTiCbNLMNkgWtJ/" +
                    "CRBBiFXQbyza0/Ks7FRgSD52qFYUV05zRjLLoEyzG6LAfihJwTEPddNxBNvCxqdBeVdDThG81zC0" +
                    "DiAhMeSwvcPCtejaDDSEYcQBLLhDAgMBAAEwDQYJKoZIhvcNAQELBQADgYEAfRP54xwuGLW/Cg08" +
                    "ar6YqhdFNGq5TgXMBvQGQfRvL7W6oH67PcvzgvzN8XCL56dcpB7S8ek6NGYfPQ4K2zhgxhxpFEDH" +
                    "PcgU4vswnhhWbGVMoVgmTA0hEkwq86CA5ZXJkJm6f3E/J6lYoPQaKatKF24706T6iH2htG4Bkjre" +
                    "gUA=";

    public static void main(String[] args) throws Exception {

        String signedString = callbackParams.entrySet().stream()
                .filter(entry -> !entry.getKey().equals("checksum") && !entry.getKey().equals("sign_alias"))
                .sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
                .collect(Collector.of(
                        StringBuilder::new,
                        (accumulator, element) -> accumulator
                                .append(element.getKey()).append(";")
                                .append(element.getValue()).append(";"),
                        StringBuilder::append,
                        StringBuilder::toString
                ));

        InputStream publicCertificate = new ByteArrayInputStream(Base64.getDecoder().decode(certificate));
        String signature = callbackParams.get("checksum");

        boolean verified = checkSignature(signedString.getBytes(), signature.getBytes(), publicCertificate);
        System.out.println("signature verification result: " + verified);
    }

    private static boolean checkSignature(byte[] signedString, byte[] signature, InputStream publicCertificate) throws Exception {
        CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
        X509Certificate x509Cert = (X509Certificate) certFactory.generateCertificate(publicCertificate);

        Signature signatureAlgorithm = Signature.getInstance("SHA512withRSA");
        signatureAlgorithm.initVerify(x509Cert.getPublicKey());
        signatureAlgorithm.update(signedString);

        return signatureAlgorithm.verify(decodeHex(new String(signature)));
    }

    private static byte[] decodeHex(String hex) {
        int l = hex.length();
        byte[] data = new byte[l / 2];
        for (int i = 0; i < l; i += 2) {
            data[i / 2] = (byte) ((Character.digit(hex.charAt(i), 16) << 4)
                    + Character.digit(hex.charAt(i + 1), 16));
        }
        return data;
    }
}

Symmetric cryptography

PHP

<?php

$data = 'amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;';
$key = 'yourSecretToken';
$hmac = hash_hmac ( 'sha256' , $data , $key);

echo "[$hmac]\n";
?>

Assign the string value to data variable.
Assign the private key value to the key variable.
hash_hmac function ( 'sha256', $data, $key) calculates the checksum of the passed string using the private key and SHA-256 algorithm.
Save the function output in hmac variable.
Use echo function to create an output.
Compare this value with the one passed in the callback notification.

Asymmetric cryptography

PHP

<?php
// data from response
$data = 'amount;35000099;mdOrder;12b59da8-f68f-7c8d-12b5-9da8000826ea;operation;deposited;status;1;';
$checksum = '9524FD765FB1BABFB1F42E4BC6EF5A4B07BAA3F9C809098ACBB462618A9327539F975FEDB4CF6EC1556FF88BA74774342AF4F5B51BA63903BE9647C670EBD962467282955BD1D57B16935C956864526810870CD32967845EBABE1C6565C03F94FF66907CEDB54669A1C74AC1AD6E39B67FA7EF6D305A007A474F03B80FD6C965656BEAA74E09BB1189F4B32E622C903DC52843C454B7ACF76D6F76324C27767DE2FF6E7217716C19C530CA7551DB58268CC815638C30F3BCA3270E1FD44F63C14974B108E65C20638ECE2F2D752F32742FFC5077415102706FA5235D310D4948A780B08D1B75C8983F22F211DFCBF14435F262ADDA6A97BFEB6D332C3D51010B';

// your public key (e.g. SHA-512 with RSA)
// if you have a CERT, please see openssl_get_publickey()
$publicKey = <<<EOD
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwtuGKbQ4WmfdV1gjWWys
5jyHKTWXnxX3zVa5/Cx5aKwJpOsjrXnHh6l8bOPQ6Sgj3iSeKJ9plZ3i7rPjkfmw
qUOJ1eLU5NvGkVjOgyi11aUKgEKwS5Iq5HZvXmPLzu+U22EUCTQwjBqnE/Wf0hnI
wYABDgc0fJeJJAHYHMBcJXTuxF8DmDf4DpbLrQ2bpGaCPKcX+04POS4zVLVCHF6N
6gYtM7U2QXYcTMTGsAvmIqSj1vddGwvNGeeUVoPbo6enMBbvZgjN5p6j3ItTziMb
Vba3m/u7bU1dOG2/79UpGAGR10qEFHiOqS6WpO7CuIR2tL9EznXRc7D9JZKwGfoY
/QIDAQAB
-----END PUBLIC KEY-----
EOD;

$binarySignature = hex2bin(strtolower($checksum));
$isVerify = openssl_verify($data, $binarySignature, $publicKey, OPENSSL_ALGO_SHA512);
if ($isVerify == 1) {
    echo "signature ok\n";
} elseif ($isVerify == 0) {
    echo "bad (there's something wrong)\n";
} else {
    echo "error checking signature\n";
}
?>