For any question, we are one click away

Contact us

Overview

You can use our Merchant API to create a payment flow you need. For example, you can design your own fully customized payment page and connect it to our Payment Gateway.

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

You can also use our Server Side SDK for running API requests.

Mandatory parameters

The mandatory presence of a parameter in a request/response may have the following values:

The mandatory transmission of a parameter in the request/response description is indicated in the "Required" column.

If you don’t have access to the Dashboard, create your account.

Authentication

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

Required Name Type Description
Conditional

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Required Name Type Description
Conditional

token String [1..256] 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.

API URLs

TEST: https://dev.bpcbt.com/payment/rest/
PROD: https://dev.bpcbt.com/payment/rest/

Errors

HTTP status codes:

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

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

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

API request signature

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

To have a possibility to sign requests, you need to perform the following steps:

  1. Generate and upload a certificate.
  2. Calculate a hash and a signature using your private key and pass the generated hash (X-Hash) and the signature value (X-Signature) in the request header.

These steps are described below in details.

Generating and uploading a certificate

  1. Generate 2048-bit RSA private key. The way of generation depends on privacy policy in your company. For example, you can do it using OpenSSL:

    openssl genrsa -des3 -out private.key 2048

  2. Generate public CSR (Certificate Signing Request) using the generated private key:

    openssl req -key private.key -new -out public.csr

  3. Generate a certificate using the generated private key and CSR. The example of generating a certificate for 5 years:

    openssl x509 -signkey private.key -in public.csr -req -days 1825 -out public.cer

  4. Upload the generated certificate in the Personal Area. To do this, go to Wallet certificates > Merchant API, click Add a certificate and upload the generated public certificate.
    JCC installments final page

Calculating a hash and a signature

  1. Calculate SHA256 hash of the request body as follows:

    1. Use request body as a string (in our example it is amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api).
    2. Calculate SHA256 hash from this string, in raw bytes.
    3. Convert the raw bytes into base64 encoding.
  2. Generate a signature for the calculated SHA256 hash with RSA algorythm using the private key.

In our example we use the following private key with the password 12345:

-----BEGIN RSA PRIVATE KEY-----

Proc-Type: 4,ENCRYPTED

DEK-Info: DES-EDE3-CBC,C502560EDE8F82B7

O4+bY1Q1ZcXFLDGVE8s9G2iVISHR/c/IMZKZEjkBED/TbuOCUGVjcav2ZaZO2dO0 lm771N6JNB01uhJbTHScVQ6R0UnGezHFTcsJlAlBa9RQyOwujs4Pk6riOGnLliIs urnTXD0oskBR1wLRA2kp8+V0UPOAMXQaoLxFGE/o8taDGSrkyIcYTBoh9o7ZBxvO SqUWAt2vPbGVyc6XspyuVtgHgEctaJO+E26QTweqdpN5JITF+fDFPNwUrFHoho4N pxpKRWbiCJSpbvbsvhdizkmfgvRw+qYJvTirF3JTfGr14DttudFwjm7sNrr0JILR XPKDUhRyWjkthZM+oDjF2HwISAGkbxcpn4PU7Tywq0uax+5KCQQn2uz4jLM2P6+9 000cvVLwhMnoUdOxuISRXeOcOWVyTO1mPfKiWnHaoO4yS3Y36OCIOe9RHGP8TTmq acb3LUIF30eQyk3KxH/tUB0ScPDKEKMiww13/Kcfr0JkdIe/BWCvV+hSQm38TLQe bTFy+wnD9kHACCwTSVVSOO+rHgJGVIyLgnpClZKWQyyJ4clH7/cORA7mTmp85Ckx IjV5Egu0bPPUMudOB5BnQ4u85RnqXavasgrLRA3JZM4+Jzl8MNy/fsFXnVBQLJJC Wlz/B7S7W8sabRogFuiqkkPmXE/QcpdKQoY3yh748QqMSl8vkA6WgndyYv1EnDDl jA5j7vSf0wKI8BHgdHBEWuEjn3X/s0S/BiPPI6puboYY90tYVJTWSQCR83QrMF3N BIcMu4+RIYu6GWnPx9npZpt0858c670ZII56np24iMse3qgHCOZxsGOenK2x7ta6 163gvaD8bu8xoeQcGVfd6IMbXWVb0+z1hvWR5HWHSalof4lMzZrDsQDKc2UA0ygh hA1+VAl1MAEHVLNCCmyG1SwRwg1PI7FfftW7YARngCZRWkJ1haj1fgy7rtYolrdv lEz/vjFD6diABx67omGgfiJhWdiKIlzsYlX1SW7yaik/Uxf1j8gTFwY34y8ekVd9 6pQTzV2V/4a48ELZl4LvelLWyt1AB3AR+/fM7YG6LYIqlo+qnLtro7Bqu8RNTNRP wcWCd04r/20ulFWMIH8pVa60C98pSdOXriWEI1KDLc0E/fCdhjW2kL+FTPLC7ORe cuzmfI27+06P/BvLZq/FAVBrDAmkioKwe6XYzTjpK1p5jZ3IrNwjAiasY1MNxCRy 5ufhQwkW//d+VUdU5m8Sm30/kXe9UkxMaetXgzPxbB7+5QFFr0bi7D1MjIrJNtTx 5g5E+UfOhqrp8ztBht9csQeFYSYabyyGX4Lh7ymVWrKCVdHlJib3M36nvOjpV/lA zf35sxFz9kaQqNK7xJdQ9Bx6TBUzLjpYhNry37vKk+SIB6Weo+LJ99mALMeX79CB osRqZqX5yrZhaQ8bbpo981nvLy5xFnpRqCuSWVZrVMBq3LQLaOvaCeyGC0V+ZN0C CU6lHlR6XQqd/IjoEN8+8aiVp6Ubw8FuD28TDaEvCltrX3ARL0xFpABsa42LgV1F 09Vi+ju7SSNDvbezN8q0EILq9xp/zNCVhMpyRCIXBq9fzHkyCZ5qMw==

-----END RSA PRIVATE KEY-----

and get the signature: pJ/gM4PR1/mKGuIxMvTl5pYDDjJslb0BcXFnIxijFn5qKdPd7W+2ueoctziU7omnkYp01/BlracukH1GOPWMSO+9zKuTDdFueFm1utsS0zaPFU+dmc1niGDRWE0CbCXcti/rGSTDPsnR58mwqgVkbCWxKyCDtuo5LxiKPK9mzgWTUuJ8LX6f6u42MURi5tRG6a9dc8l/+J94g0YOk911R6Lqv2jcluEvZ9ZeMMt8hyxowb0eDaCHlussu2CAyqpE9V+EUAc81Jkwv96MMSsA6UnFwEaCV/k+kwYd0jHCx94m2yWX734p9cWsBW7Fr5F0zox9Yck4GOjqe9nJMMB9jQ== 3. Now you should pass the generated hash (X-Hash) and the signature value (X-Signature) in the request header. The request will look like this:

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'X-Hash: eYkMUF+xaYJhsETTIGsctl6DBNZha1ITN8muCcWQtZk=' \
  --header 'X-Signature: pJ/gM4PR1/mKGuIxMvTl5pYDDjJslb0BcXFnIxijFn5qKdPd7W+2ueoctziU7omnkYp01/BlracukH1GOPWMSO+9zKuTDdFueFm1utsS0zaPFU+dmc1niGDRWE0CbCXcti/rGSTDPsnR58mwqgVkbCWxKyCDtuo5LxiKPK9mzgWTUuJ8LX6f6u42MURi5tRG6a9dc8l/+J94g0YOk911R6Lqv2jcluEvZ9ZeMMt8hyxowb0eDaCHlussu2CAyqpE9V+EUAc81Jkwv96MMSsA6UnFwEaCV/k+kwYd0jHCx94m2yWX734p9cWsBW7Fr5F0zox9Yck4GOjqe9nJMMB9jQ==' \
  --data 'amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api'

The request should meet the following requirements:

Java code example

Below is the Java code example that loads a private key, calculates SHA256 hash, signs it using the private key with the password 12345, and then sends a correct register.do request:

import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyStore;
import java.security.MessageDigest;
import java.security.PrivateKey;
import java.security.Signature;
import java.util.Base64;

import static java.net.HttpURLConnection.HTTP_OK;

public class SimpleSignatureExample {

    // This example is not production ready. It just shows how to use signatures in API.
    public static void main(String[] args) throws Exception {
        // load private key from jks
        KeyStore ks = KeyStore.getInstance("JKS");
        char[] pwd = "123456".toCharArray();
        ks.load(Files.newInputStream(Paths.get("/path/to/certificates.jks")), pwd);
        PrivateKey privateKey = (PrivateKey) ks.getKey("111111", pwd);

        // Sign
        String httpBody = "amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api";

        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initSign(privateKey);

        byte[] sha256 = digest.digest(httpBody.getBytes());
        signature.update(sha256);
        byte[] sign = signature.sign();

        // Send
        Base64.Encoder encoder = Base64.getEncoder();
        HttpsURLConnection connection = (HttpsURLConnection) new URL("https://<YOUR_DOMAIN>/payment/rest/register.do").openConnection();
        connection.setDoOutput(true);
        connection.setDoInput(true);
        connection.setRequestMethod("POST");
        connection.addRequestProperty("content-type", "application/x-www-form-urlencoded");
        connection.addRequestProperty("X-Hash", encoder.encodeToString(sha256));
        connection.addRequestProperty("X-Signature", encoder.encodeToString(sign));
        connection.addRequestProperty("Content-Length", String.valueOf(httpBody.getBytes().length));
        try (final DataOutputStream outputStream = new DataOutputStream(connection.getOutputStream())) {
            outputStream.write(httpBody.getBytes());
            outputStream.flush();
        }
        connection.connect();

        InputStream inputStream = connection.getResponseCode() == HTTP_OK ? connection.getInputStream() : connection.getErrorStream();
        BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
        String line;
        while ((line = reader.readLine()) != null) {
            System.out.println(line);
        }
    }
}

Python code example

Below is the Python code example that generates the signature:

import OpenSSL
from OpenSSL import crypto
import base64
from hashlib import sha256
key_file = open("./priv.pem", "r")
key = key_file.read()
key_file.close()

if key.startswith('-----BEGIN '):
    pkey = crypto.load_privatekey(crypto.FILETYPE_PEM, key)
else:
    pkey = crypto.load_pkcs12(key, password).get_privatekey()

data = “amount=2000&currency=978&userName=test_user&password=test_user_password&returnUrl=https%3A%2F%2Fmybestmerchantreturnurl.com&description=my_first_order&language=en”

sha256_hash = sha256(data.encode()).digest()
base64_hash = base64.b64encode(sha256_hash)
print(base64_hash)

sign = OpenSSL.crypto.sign(pkey, sha256_hash, "sha256")

signed_base64 = base64.b64encode(sign)
print(signed_base64)

The private key file for the Python example should have the format:

-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDdpOwhY/p9x0WmBd3HaDfCD+KYung3M8Cxrw0ozF+h//GltRdnkJD7ejsBDB6/YeIVXZeU3AyqWvsi/IfeHwnokGxVg2IMw8OPacY6o1x7W0EQtfRoZa2Cn2PMCpZhEHlIVraXZDDeg4HY26YP0FZxRbpNnpXhGbiop+Bq0wHeE3JIk53cRmwYhxdxMmvFpgNd6C3dYhmnQqLv6WSpVNDFbQxBVU+JDNyR9FQwB1dU2MadgYwFJnEssbhUkM+sXAC4Wv3qhcZek6MWeWsbFIIlyTPa1T3yrWSXIb4qFJEro4pRMmwQ72qG02p8EPx1tlveQo22TojV9WbTPtaVwQtxAgMBAAECggEBANheTGkYOYsZwgMdzPAB7BSU/0bLGdoBuoV6dqUyRdVWjqaOTwe519625uzR0R5RRqxGzlfyLKcM5Aa2cUhEEp8mhatA87G0Va8lue66VOjTH4RZq/tR7v0J7hlc6Ipe05brl5nYo+BEjriNS+I6Jnizcfid7IBvZJW4NFr0G+mWTxl2BhUK/Mk895n8hg9QtgSRoMNO4jK2f0vJrH4hBHehTYpjHx+QhbUyIvsp60bEnNOXzl054TuWBVCYAQHcHTTZowWMY0s1Z0kGNxwsqQm4amW/v+1EqCF4fjRDrU6v/kjDKxGFx9GJUktKZAe2T8e2LySjgGpJO5g4AdxIVpUCgYEA8x9te+i2ijxoS3kIUSwXaPq5EdKGWGl5mW8KZHzmt9LB/CqTKvSOiDkMGoAx/76t5QmKOYojP+Vsc2XdfQfhT6d00MGTdiPBd+8//MmQQ07/D1/PV58Jd1O8bQFU4fZCMpQl/8Azp9ix/NEx0sHDv2KigLfFMBVGeJxwSoU2JzMCgYEA6WJC0BDTA9vx+i+p9i/41f7ozpQuYey5sxdZa2emOSYen6ptxUFLAYXMxVDaBJ89PMUa8GzWoXHhgXzbuRJk74IzUhWgPpneS4HTr5KDStJh2TqWWVLwEIgLwxvtuw0i9uSEU64D/Czzm801lrOhVgmZsWwNpFtP8ujz0v84MssCgYEA1P4YhbB3kx2e5VfwgGSXUcIttr5wMi6deF0+hpCh9DNw/QEzkzNTV2ZbAzCCHSKo5/n2nbg2b3kIDQUWCL6JlqYHAghErwBeMztoHIddmoovjAGM/Z93xJGYhwremWOL1RHTRH7XAlomfG2tL43PdvDrmsbkut44sdujyLVxnt8CgYBirK3tBMADKLJVgmOM+FlwORe7iAFYW9tj8iJXe/pWvVxDS66fsOyCl0ytvHKBc8ZTdE7gilPw7JJYyi6oQDO25EjIkuYusaXALQMQf5TNRMgkLVY2LA/eHXdDpgJMjNBUrOeZ7cA3ldXl8MyQjCBRnTuDPVlDPWw/GulEM65SIwKBgQDIEv8XK2YBkZrr+0fZSFTQAeK4R7Ve3z4hbpHhJi41YanCNaEWoeYAuQd6/b/QLwABllvfJBDYCNnF8heUxqISpyWd+FZ8nhZtxBoKj5l80czTcutIz/M+ETcvl8FqnMBsoCdp1wodqaLkOx6DIldgKLze6AqKXl5lHUsU4mvVqg==
-----END PRIVATE KEY-----

Order registration

Order registration

Start working with the API Sandbox by creating an account or logging in.

 

To register an order, use register.do request.

Request parameters

Required Name Type Description
Conditional

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

token String [1..256] 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.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Mandatory

returnUrl String [1..512] The address to which the user will be redirected if the payment is successful. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

failUrl String [1..512] The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

dynamicCallbackUrl String [1..512] This parameter allows you to use the functionality of sending callback notifications dynamically. Here you can pass the address to which all "payment" callback notifications activated for the merchant will be sent. "Payment" notifications are callback notifications related to the following events: successful hold, payment declined by timeout, cardpresent payment is declined, successful debit, refund, cancellation. At the same time, callback notifications activated for the merchant that are not related to payments (enabling/disabling a stored credential, storing a credential) will be sent to a static address for callbacks. Whether the parameter is mandatory or not depends on the merchant configuration on Payment Gateway side.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

merchantLogin String [1..255] To register an order on behalf of another merchant, specify the merchant's API account login in this parameter.
Can be used only if you have the permission to see the transactions of other merchants or if the specified merchant is your child merchant.
Optional

jsonParams Object 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
  • 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).
Optional

sessionTimeoutSecs Integer [1..9] Order lifetime in seconds. If the parameter is not specified, the value specified in the merchant settings or the default value (1200 seconds = 20 minutes) will be used. If the request contains expirationDate, the value of sessionTimeoutSecs is not taken into account.
Optional

expirationDate String Data and time of the order expiry. Format used: yyyy-MM-ddTHH:mm:ss.
If this parameter is not passed in the request, sessionTimeoutSecs is used to define the expiry of the order.
Optional

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Optional

features String Features of the order. As an example, below are the possible values.
  • VERIFY - If you specify this value in the order registration request, cardholder will be verified however they will not be charged any amount, so in this case amount parameter can be 0. Verification allows to make sure that a payment card is used by its legitimate owner, and further you can charge them without authentication (CVC, 3D-Secure). Even if some amount is passed in the request, the customer will not be charged if VERIFY feature is used. After a successful registration order status is changed to REVERSED. This value can be also used for storing the credential – in this case, the clientId parameter must be passed as well. Read more here.
  • FORCE_TDS - Force 3-D Secure payment. If a payment card does not support 3-D Secure, the transaction will fail.
  • FORCE_SSL - Force SSL payment (without 3-D Secure).
  • FORCE_FULL_TDS - After 3-D Secure authentication, PaRes status must be Y, which guarantees successful user authentication. Otherwise, the transaction will fail.
  • FORCE_CREATE_BINDING - passing this feature in the order registration request forcefully stores the credential. This functionality must be enabled by Merchant level permission in the Gateway. This value cannot be passed in a request with an existing bindingId or bindingNotNeeded = true (will cause validation error). When this feature is passed, the clientId parameter must be passed as well. If you pass both FORCE_CREATE_BINDING and VERIFY features, the order will be created for storing the credential ONLY (without payment).
Optional

postAddress String [1..255] Delivery address.
Optional

orderBundle Object Object containing cart of items. The description of the nested elements is given below.
Optional

feeInput String Fee amount in minimum currency units. Must be enabled by respective Merchant-level permission in the Gateway.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

shippingPayerData Object Object containing customer delivery data. It is used for further 3DS authentication of the client. See nested parameters
Optional

preOrderPayerData Object Object containing pre-order data. It is used for further 3DS authentication of the client. See nested parameters
Optional

orderPayerData Object Object containing data about the order payer. It is used for further 3DS authentication of the client. See nested parameters
Optional

billingAndShippingAddressMatchIndicator A1 Indicator for matching the cardholder's billing address and shipping address. This parameter is used for further 3DS authentication of the customer.
Possible values:
  • Y - the cardholder's billing address and shipping address match;
  • N - cardholder billing address and shipping address do not match

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

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Description of parameters in shippingPayerData object:

Required Name Type Description
Optional shippingCity ANS...50 The customer's city (from the delivery address)
Optional shippingCountry ANS...50 The customer's country
Optional shippingAddressLine1 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine2 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine3 ANS...50 The customer's primary address (from the shipping address)
Optional shippingPostalCode ANS...16 The customer's zip code for delivery
Optional shippingState ANS...50 Customer's state/region (from delivery address)
Optional shippingMethodIndicator N2 Shipping Method Indicator.
Possible values:
  • 01 - delivery to the cardholder's billing address
  • 02 - delivery to another address verified by Merchant
  • 03 - delivery to an address other than the cardholder's primary (settlement) address
  • 04 - shipment to the store/self-collection (the store address should be specified in the relevant delivery parameters)
  • 05 - Digital distribution (includes online services and e-gift cards)
  • 06 - travel and event tickets that are not deliverable
  • 07 - Other (e.g. games, non-deliverable digital goods, digital subscriptions, etc.)
Optional deliveryTimeframe N2 Product delivery timeframe.
Possible values:
  • 01 - digital distribution
  • 02 - same-day delivery
  • 03 - overnight delivery
  • 04 - delivery within 2 days after payment and later
Optional deliveryEmail ANS...254 Target email address for delivery of digital distribution

Description of parameters in preOrderPayerData object:

Required Name Type Description
Optional preOrderDate ANS8 Expected date when delivery will be available (for pre-ordered purchases), in the format YYYYYYMMDD.
Optional preOrderPurchaseInd N2 Indicator of a customer placing an order for available or future delivery.
Possible values:
  • 01 - delivery available;
  • 02 - future delivery
Optional reorderItemsInd N2 An indicator that the customer is rebooking a previously paid delivery as part of a new order.
Possible values:
  • 01 - order placed for the first time;
  • 02 - repeated order

Description of parameters in orderPayerData object:

Required Name Type Description
Optional homePhone ANS...19 The cardholder's home phone number, with the obligatory "+" symbol
Optional workPhone ANS...19 The cardholder's work phone number, with the obligatory "+" symbol
Optional mobilePhone ANS...19 The cardholder's mobile phone number, with the obligatory "+" symbol

Description of parameters in orderBundle object:

Required Name Type Description
Optional

orderCreationDate String Order creation date in the following format: YYYY-MM-DDTHH:MM:SS.
Optional

customerDetails Object Block containing customer attributes. The description of the tag attributes is given below.
Optional

cartItems Object Object containing cart items attributes. The description of nested elements is given below.

Description of parameters in customerDetails object:

Required Name Type Description
Conditional

email String Customer's email address. Multiple emails can be passed as comma-separated values.
Either of email or phone must be passed.
Conditional

phone String Customer's phone number. It is always necessary to specify the country code, but you can specify or omit the + sign. Thus, the following options are valid:
  • +449998887766;
  • 449998887766. 7 to 15 digits long.
Optional

contact String [0..40] Customer's preferred way of communication.
Optional

fullName String [1..100] Payer's full name.
Optional

passport Integer Customer's passport serial number in the following format: 2222888888.
Optional

deliveryInfo Object Object containing delivery address attributes. The description of the nested elements is given below.

Description of parameters in deliveryInfo object.

Required Name Type Description
Optional

deliveryType String [1..20] Delivery method.
Mandatory

country String Two letter code of the country of delivery.
Mandatory

city String [0..40] City of destination.
Mandatory

postAddress String [1..255] Delivery address.

Description of parameters in cartItems object.

Required Name Type Description
Mandatory

items Object An element of the array containing cart item attributes. The description of the nested elements is given below.

Description of parameters in items object.

Required Name Type Description
Mandatory

positionId Integer [1..12] Unique product identifier in the cart.
Mandatory

name String [1..255] Name or the description of an item in any format.
Optional

itemDetails Object Object containing the parameters describing an item. The description of the nested elements is given below.
Mandatory

quantity Object Element describing the total of items of one positionId and its unit of measurement. The description of the nested elements is given below.
Optional

itemAmount Integer [1..12] The total cost of all instances of one positionId specified in minor denomination of the currency. itemAmount must be passed only if the itemPrice parameter has not been passed. Otherwise passing of itemAmount is not required. If both parameters itemPrice and itemAmount are passed in the request, then itemAmount shall be equal itemPrice * quantity, otherwise the request will return an error.
Optional

itemPrice Integer [1..18] Total cost of instance of one positionId specified in minor currency units.
Optional

itemCurrency Integer ISO 4217 currency code. If the parameter is not specified, it is considered to be equal to the Order currency.
Mandatory

itemCode String [1..100] Number (identifier) of an item in the store system.
Optional

discount Object Object containing item discount attributes. The description of the nested elements is given below.
Optional

agentInterest Object Object containing attributes of the description of an agent fee for the sale of goods. The description of the nested elements is given below.

Description of parameters in quantity object.

Required Name Type Description
Mandatory

value String Number of items in one positionId. Use a decimal point as a separator in fractions.
Mandatory

measure String [1..20] The unit of measurement for the quantity of item instances.

Description of parameters in itemDetails object.

Required Name Type Description
Optional

itemDetailsParams Object Parameter describing additional information regarding a line item. The description of the nested elements is given below.

Description of parameters in itemDetailsParams object.

Required Name Type Description
Mandatory

value String Additional item info.
Mandatory

name String [1..255] Name of the parameter describing the details of an item

Description of parameters in discount object.

Required Name Type Description
Mandatory

discountType String [1..20] Type of discount applicable to an item.
Mandatory

discountValue Integer [0..20] Value of the item discount.

Description of parameters in agentInterest object:

Required Name Type Description
Mandatory

interestType String [1..20] Agent fee type.
Mandatory

interestValue Integer [1..20] Agent fee value.

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

formUrl String [1..512] URL of the payment form, to which a customer will be redirected The URL is not returned if the registration of the order fails due to an error specified in errorCode.
Optional

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.

Examples

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderNumber=1218637308 \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data failUrl=https://mybestmerchantfailurl.com \
  --data email=test@test.com \
  --data clientId=259753456 \
  --data language=en

Response example

{
  "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
  "formUrl": "https://dev.bpcbt.com/payment/merchants/pay/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

Required Name Type Description
Conditional

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

token String [1..256] 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.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Mandatory

returnUrl String [1..512] The address to which the user will be redirected if the payment is successful. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

failUrl String [1..512] The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

dynamicCallbackUrl String [1..512] This parameter allows you to use the functionality of sending callback notifications dynamically. Here you can pass the address to which all "payment" callback notifications activated for the merchant will be sent. "Payment" notifications are callback notifications related to the following events: successful hold, payment declined by timeout, cardpresent payment is declined, successful debit, refund, cancellation. At the same time, callback notifications activated for the merchant that are not related to payments (enabling/disabling a stored credential, storing a credential) will be sent to a static address for callbacks. Whether the parameter is mandatory or not depends on the merchant configuration on Payment Gateway side.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

merchantLogin String [1..255] To register an order on behalf of another merchant, specify the merchant's API account login in this parameter.
Can be used only if you have the permission to see the transactions of other merchants or if the specified merchant is your child merchant.
Optional

jsonParams Object 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
  • 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).
Optional

sessionTimeoutSecs Integer [1..9] Order lifetime in seconds. If the parameter is not specified, the value specified in the merchant settings or the default value (1200 seconds = 20 minutes) will be used. If the request contains expirationDate, the value of sessionTimeoutSecs is not taken into account.
Optional

expirationDate String Data and time of the order expiry. Format used: yyyy-MM-ddTHH:mm:ss.
If this parameter is not passed in the request, sessionTimeoutSecs is used to define the expiry of the order.
Optional

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Optional

features String Features of the order. As an example, below are the possible values.
  • VERIFY - If you specify this value in the order registration request, cardholder will be verified however they will not be charged any amount, so in this case amount parameter can be 0. Verification allows to make sure that a payment card is used by its legitimate owner, and further you can charge them without authentication (CVC, 3D-Secure). Even if some amount is passed in the request, the customer will not be charged if VERIFY feature is used. After a successful registration order status is changed to REVERSED. This value can be also used for storing the credential – in this case, the clientId parameter must be passed as well. Read more here.
  • FORCE_TDS - Force 3-D Secure payment. If a payment card does not support 3-D Secure, the transaction will fail.
  • FORCE_SSL - Force SSL payment (without 3-D Secure).
  • FORCE_FULL_TDS - After 3-D Secure authentication, PaRes status must be Y, which guarantees successful user authentication. Otherwise, the transaction will fail.
  • FORCE_CREATE_BINDING - passing this feature in the order registration request forcefully stores the credential. This functionality must be enabled by Merchant level permission in the Gateway. This value cannot be passed in a request with an existing bindingId or bindingNotNeeded = true (will cause validation error). When this feature is passed, the clientId parameter must be passed as well. If you pass both FORCE_CREATE_BINDING and VERIFY features, the order will be created for storing the credential ONLY (without payment).
Optional

autocompletionDate String The date and time when the two-stage payment was completed automatically in the following format: 2017-12-29T13:02:51. The used timezone is UTC+0. To enable sending this field to the processing system, contact your technical support service.
Optional

autoReverseDate String The date and time when the two-stage payment was reversed automatically in the following format: 2022-06-23T13:02:51. The used timezone is UTC+0. To enable sending this field to the processing system, contact your technical support service.
Optional

postAddress String [1..255] Delivery address.
Optional

orderBundle Object Object containing cart of items. The description of the nested elements is given below.
Optional

feeInput String Fee amount in minimum currency units. Must be enabled by respective Merchant-level permission in the Gateway.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

shippingPayerData Object Object containing customer delivery data. It is used for further 3DS authentication of the client. See nested parameters
Optional

preOrderPayerData Object Object containing pre-order data. It is used for further 3DS authentication of the client. See nested parameters
Optional

orderPayerData Object Object containing data about the order payer. It is used for further 3DS authentication of the client. See nested parameters
Optional

billingAndShippingAddressMatchIndicator A1 Indicator for matching the cardholder's billing address and shipping address. This parameter is used for further 3DS authentication of the customer.
Possible values:
  • Y - the cardholder's billing address and shipping address match;
  • N - cardholder billing address and shipping address do not match

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Description of parameters in shippingPayerData object:

Required Name Type Description
Optional shippingCity ANS...50 The customer's city (from the delivery address)
Optional shippingCountry ANS...50 The customer's country
Optional shippingAddressLine1 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine2 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine3 ANS...50 The customer's primary address (from the shipping address)
Optional shippingPostalCode ANS...16 The customer's zip code for delivery
Optional shippingState ANS...50 Customer's state/region (from delivery address)
Optional shippingMethodIndicator N2 Shipping Method Indicator.
Possible values:
  • 01 - delivery to the cardholder's billing address
  • 02 - delivery to another address verified by Merchant
  • 03 - delivery to an address other than the cardholder's primary (settlement) address
  • 04 - shipment to the store/self-collection (the store address should be specified in the relevant delivery parameters)
  • 05 - Digital distribution (includes online services and e-gift cards)
  • 06 - travel and event tickets that are not deliverable
  • 07 - Other (e.g. games, non-deliverable digital goods, digital subscriptions, etc.)
Optional deliveryTimeframe N2 Product delivery timeframe.
Possible values:
  • 01 - digital distribution
  • 02 - same-day delivery
  • 03 - overnight delivery
  • 04 - delivery within 2 days after payment and later
Optional deliveryEmail ANS...254 Target email address for delivery of digital distribution

Description of parameters in preOrderPayerData object:

Required Name Type Description
Optional preOrderDate ANS8 Expected date when delivery will be available (for pre-ordered purchases), in the format YYYYYYMMDD.
Optional preOrderPurchaseInd N2 Indicator of a customer placing an order for available or future delivery.
Possible values:
  • 01 - delivery available;
  • 02 - future delivery
Optional reorderItemsInd N2 An indicator that the customer is rebooking a previously paid delivery as part of a new order.
Possible values:
  • 01 - order placed for the first time;
  • 02 - repeated order

Description of parameters in orderPayerData object:

Required Name Type Description
Optional homePhone ANS...19 The cardholder's home phone number, with the obligatory "+" symbol
Optional workPhone ANS...19 The cardholder's work phone number, with the obligatory "+" symbol
Optional mobilePhone ANS...19 The cardholder's mobile phone number, with the obligatory "+" symbol

Description of parameters in orderBundle object:

Required Name Type Description
Optional

orderCreationDate String Order creation date in the following format: YYYY-MM-DDTHH:MM:SS.
Optional

customerDetails Object Block containing customer attributes. The description of the tag attributes is given below.
Optional

cartItems Object Object containing cart items attributes. The description of nested elements is given below.

Description of parameters in customerDetails object:

Required Name Type Description
Conditional

email String Customer's email address. Multiple emails can be passed as comma-separated values.
Either of email or phone must be passed.
Conditional

phone String Customer's phone number. It is always necessary to specify the country code, but you can specify or omit the + sign. Thus, the following options are valid:
  • +449998887766;
  • 449998887766. 7 to 15 digits long.
Optional

contact String [0..40] Customer's preferred way of communication.
Optional

fullName String [1..100] Payer's full name.
Optional

passport Integer Customer's passport serial number in the following format: 2222888888.
Optional

deliveryInfo Object Object containing delivery address attributes. The description of the nested elements is given below.

Description of parameters in deliveryInfo object.

Required Name Type Description
Optional

deliveryType String [1..20] Delivery method.
Mandatory

country String Two letter code of the country of delivery.
Mandatory

city String [0..40] City of destination.
Mandatory

postAddress String [1..255] Delivery address.

Description of parameters in cartItems object.

Required Name Type Description
Mandatory

items Object An element of the array containing cart item attributes. The description of the nested elements is given below.

Description of parameters in items object.

Required Name Type Description
Mandatory

positionId Integer [1..12] Unique product identifier in the cart.
Mandatory

name String [1..255] Name or the description of an item in any format.
Optional

itemDetails Object Object containing the parameters describing an item. The description of the nested elements is given below.
Mandatory

quantity Object Element describing the total of items of one positionId and its unit of measurement. The description of the nested elements is given below.
Optional

itemAmount Integer [1..12] The total cost of all instances of one positionId specified in minor denomination of the currency. itemAmount must be passed only if the itemPrice parameter has not been passed. Otherwise passing of itemAmount is not required. If both parameters itemPrice and itemAmount are passed in the request, then itemAmount shall be equal itemPrice * quantity, otherwise the request will return an error.
Optional

itemPrice Integer [1..18] Total cost of instance of one positionId specified in minor currency units.
Optional

itemCurrency Integer ISO 4217 currency code. If the parameter is not specified, it is considered to be equal to the Order currency.
Mandatory

itemCode String [1..100] Number (identifier) of an item in the store system.
Optional

discount Object Object containing item discount attributes. The description of the nested elements is given below.
Optional

agentInterest Object Object containing attributes of the description of an agent fee for the sale of goods. The description of the nested elements is given below.

Description of parameters in quantity object.

Required Name Type Description
Mandatory

value String Number of items in one positionId. Use a decimal point as a separator in fractions.
Mandatory

measure String [1..20] The unit of measurement for the quantity of item instances.

Description of parameters in itemDetails object.

Required Name Type Description
Optional

itemDetailsParams Object Parameter describing additional information regarding a line item. The description of the nested elements is given below.

Description of parameters in itemDetailsParams object.

Required Name Type Description
Mandatory

value String Additional item info.
Mandatory

name String [1..255] Name of the parameter describing the details of an item

Description of parameters in discount object.

Required Name Type Description
Mandatory

discountType String [1..20] Type of discount applicable to an item.
Mandatory

discountValue Integer [0..20] Value of the item discount.

Description of parameters in agentInterest object:

Required Name Type Description
Mandatory

interestType String [1..20] Agent fee type.
Mandatory

interestValue Integer [1..20] Agent fee value.

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Optional

formUrl String [1..512] URL of the payment form, to which a customer will be redirected The URL is not returned if the registration of the order fails due to an error specified in errorCode.

Examples

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/registerPreAuth.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data userName=test_user \
  --data password=test_user_password \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data orderNumber=1255555555555 \
  --data clientId=259753456 \
  --data language=en

Response example

{
  "orderId": "01492437-d2fb-77fa-8db7-9e2900a7d8c0",
  "formUrl": "https://dev.bpcbt.com/payment/merchants/pay/payment_en.html?mdOrder=01492437-d2fb-77fa-8db7-9e2900a7d8c0"
}

Direct payments

Payment for order

The request used to make a payment for order is paymentorder.do.

If you have an agreement/certificate signed with IPS that enables to run 3DS operations, you can use paymentorder.do (external MPI). It means that you can use your own MPI for 3D Secure authorization. Read more about payment with your MPI here.

Otherwise, use paymentorder.do (internal MPI).

Payment for order (external MPI)

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

MDORDER String [1..36] Order number in the payment gateway.
Mandatory

$PAN Integer [1..19] Payment card number. Mandatory, if seToken is not passed.
Mandatory

$CVC Integer CVC/CVV2 code on the back of a payment card. Mandatory, if seToken is not passed.
Mandatory

YYYY Integer Payment card expiry year. If seToken is not passed, it is mandatory to pass either $EXPIRY or YYYY and MM.
Mandatory

MM Integer Payment card expiry month. If seToken is not passed, it is mandatory to pass either $EXPIRY or YYYY and MM.
Conditional

$EXPIRY Integer Card expiration in the following format: YYYYMM. Overrides YYYY and MM parameters. If seToken is not passed, it is mandatory to pass either $EXPIRY or YYYY and MM.
Conditional

seToken String Encrypted card data that replaces $PAN, $CVC, and $EXPIRY (or YYYY,MM) parameters. Must be passed if used instead of the card data.
The mandatory parameters for seToken string are timestamp, UUID, PAN, EXPDATE, MDORDER. Click here for more information about seToken generation.
If seToken contains encrypted data about a stored credential (bindingId), the paymentOrderBinding.do request should be used for payment instead of paymentorder.do.
Mandatory

TEXT String Cardholder name.
Mandatory

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

bindingNotNeeded Boolean Allowed values:
  • true – storing the credential after the payment is disabled (a stored credential is a customer identifier passed in order registration request — after paymentorder.do request it will be deleted from order details);
  • false – if payment is successful the credential can be stored (if the necessary conditions are met). This is the default value.
Optional

jsonParams String Fields for storing additional data, must be passed as follows {"param":"value","param2":"value2"}.
These fields can be passed to the processing bank for further display in the bank registries.
By default orderNumber (order number) and description (order description) are passed. description must not exceed 99 characters, do not use the following characters: %, +, end of line \r and line break \n).
To enable this functionality contact the bank.
If you use your own MPI the payment gateway expects that every paymentOrder request will include the following additional parameters.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

tii String Transaction initiator indicator. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant). Possible values
Optional

threeDSProtocolVersion String 3DS protocol version. Possible values are "2.1.0", "2.2.0" for 3DS2.
If threeDSProtocolVersion is not passed in the request, then the default value will be used for 3D Secure authorization (2.1.0 - for 3DS 2).
Optional

shippingPayerData Object Object containing customer delivery data. It is used for further 3DS authentication of the client. See nested parameters
Optional

preOrderPayerData Object Object containing pre-order data. It is used for further 3DS authentication of the client. See nested parameters
Optional

orderPayerData Object Object containing data about the order payer. It is used for further 3DS authentication of the client. See nested parameters
Optional

billingAndShippingAddressMatchIndicator A1 Indicator for matching the cardholder's billing address and shipping address. This parameter is used for further 3DS authentication of the customer.
Possible values:
  • Y - the cardholder's billing address and shipping address match;
  • N - cardholder billing address and shipping address do not match
Optional

acsInIFrame Boolean Flag indicating that an iFrame version of the finish URL will be returned. Possible values are true or false. To enable this feature please contact support.
Optional

clientBrowserInfo Object A block with the data about the client's browser that is sent to ACS during the 3DS authentication. To pass this block, you should have a special setting (contact the support team). See nested parameters.

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Description of parameters in shippingPayerData object:

Required Name Type Description
Optional shippingCity ANS...50 The customer's city (from the delivery address)
Optional shippingCountry ANS...50 The customer's country
Optional shippingAddressLine1 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine2 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine3 ANS...50 The customer's primary address (from the shipping address)
Optional shippingPostalCode ANS...16 The customer's zip code for delivery
Optional shippingState ANS...50 Customer's state/region (from delivery address)
Optional shippingMethodIndicator N2 Shipping Method Indicator.
Possible values:
  • 01 - delivery to the cardholder's billing address
  • 02 - delivery to another address verified by Merchant
  • 03 - delivery to an address other than the cardholder's primary (settlement) address
  • 04 - shipment to the store/self-collection (the store address should be specified in the relevant delivery parameters)
  • 05 - Digital distribution (includes online services and e-gift cards)
  • 06 - travel and event tickets that are not deliverable
  • 07 - Other (e.g. games, non-deliverable digital goods, digital subscriptions, etc.)
Optional deliveryTimeframe N2 Product delivery timeframe.
Possible values:
  • 01 - digital distribution
  • 02 - same-day delivery
  • 03 - overnight delivery
  • 04 - delivery within 2 days after payment and later
Optional deliveryEmail ANS...254 Target email address for delivery of digital distribution

Description of parameters in preOrderPayerData object:

Required Name Type Description
Optional preOrderDate ANS8 Expected date when delivery will be available (for pre-ordered purchases), in the format YYYYYYMMDD.
Optional preOrderPurchaseInd N2 Indicator of a customer placing an order for available or future delivery.
Possible values:
  • 01 - delivery available;
  • 02 - future delivery
Optional reorderItemsInd N2 An indicator that the customer is rebooking a previously paid delivery as part of a new order.
Possible values:
  • 01 - order placed for the first time;
  • 02 - repeated order

Description of parameters in orderPayerData object:

Required Name Type Description
Optional homePhone ANS...19 The cardholder's home phone number, with the obligatory "+" symbol
Optional workPhone ANS...19 The cardholder's work phone number, with the obligatory "+" symbol
Optional mobilePhone ANS...19 The cardholder's mobile phone number, with the obligatory "+" symbol

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.
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
RI Initial Recurrent CIT Initiating Customer Entered by Customer Yes An e-commerce transaction, credential is stored.
R Recurrent MIT Subsequent Merchant No manual entry, Merchant passes the data No A recurrent transaction that uses a stored credential.
II Initial Installment CIT Initiating Customer Entered by Customer Yes An e-commerce transaction, credential is stored.
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 clientBrowserInfo block (data about the client's browser).

Required Name Type Description
Optional userAgent string Browser agent.
Optional OS string Operation system.
Optional OSVersion string Operation system version.
Optional browserAcceptHeader string The Accept header that tells the server what file formats (or MIME-types) the browser accepts.
Optional browserIpAddress string Browser IP address.
Optional browserLanguage string Browser language.
Optional browserTimeZone string Browser time zone.
Optional browserTimeZoneOffset integer The time zone offset in minutes between the user's local time and UTC.
Optional colorDepth string Screen color depth, in bits.
Optional fingerprint string Browser fingerprint - a unique digital identifier of the browser.
Optional isMobile Boolean Possible values: true or false. Flag showing that a mobile device is used.
Optional javaEnabled Boolean Possible values: true or false. Flag showing that java is enabled in the browser.
Optional javascriptEnabled Boolean Possible values: true or false. Flag showing that javascript is enabled in the browser.
Optional plugins string Comma-separated list of plugins the browser uses.
Optional screenHeight integer Screen height, in pixels.
Optional screenWidth integer Screen width, in pixels.
Optional screenPrint string Data about current screen print including resolution, color depth, display metrics.

Example of clientBrowserInfo block:

"clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"10.99.50.37"
    }

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

info String If response is successful. Result of a payment attempt. Below are the possible values.
  • Your payment has been processed, redirecting...
  • Operation declined. Check the entered data and that there are enough funds on the card and repeat the operation. Redirecting...
  • Sorry, payment cannot be completed. Redirecting...
  • Operation declined. Contact the merchant. Redirecting...
  • Operation declined. Contact the bank that issued the card. Redirecting...
  • Impossible operation. Cardholder authentication completed unsuccessfully. Redirecting...
  • No connection with bank. Try again later. Redirecting...
  • Input time expired. Redirecting...
  • No response from bank received. Try again later. Redirecting...
Optional

acsInIFrame Boolean Flag indicating that an iFrame version of the finish URL will be returned. Possible values are true or false. To enable this feature please contact support.

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=0140dda0-71ed-7706-a61f-36bd00a7d8c0 \\
  --data '$PAN=4000001111111118' \\
  --data '$CVC=123' \\
  --data YYYY=2030 \\
  --data MM=12 \\
  --data 'TEXT=TEST CARDHOLDER' \\
  --data language=en \\
  --data 'jsonParams={"eci": "02", "cavv": "AkZO5XQAA0rhBxoaufa+MAABAAA=", "xid": "5010857f-8d3f-74e1-9c5a-54a000cc4110", "threeDSProtocolVersion": "2.2.0", "authenticationTypeIndicator": "5"}'

Response example

{
  "redirect": "https://dev.bpcbt.com/payment/merchants/temp/finish.html?orderId=01493844-d4d3-703f-9f7e-a73900a7d8c0&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

Payment for order (internal MPI)

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Mandatory

MDORDER String [1..36] Order number in the payment gateway.
Mandatory

$PAN Integer [1..19] Payment card number. Mandatory, if seToken is not passed.
Mandatory

$CVC Integer CVC/CVV2 code on the back of a payment card. Mandatory, if seToken is not passed.
Mandatory

YYYY Integer Payment card expiry year. If seToken is not passed, it is mandatory to pass either $EXPIRY or YYYY and MM.
Mandatory

MM Integer Payment card expiry month. If seToken is not passed, it is mandatory to pass either $EXPIRY or YYYY and MM.
Conditional

$EXPIRY Integer Card expiration in the following format: YYYYMM. Overrides YYYY and MM parameters. If seToken is not passed, it is mandatory to pass either $EXPIRY or YYYY and MM.
Conditional

seToken String Encrypted card data that replaces $PAN, $CVC, and $EXPIRY (or YYYY,MM) parameters. Must be passed if used instead of the card data.
The mandatory parameters for seToken string are timestamp, UUID, PAN, EXPDATE, MDORDER. Click here for more information about seToken generation.
If seToken contains encrypted data about a stored credential (bindingId), the paymentOrderBinding.do request should be used for payment instead of paymentorder.do.
Mandatory

TEXT String Cardholder name.
Mandatory

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

bindingNotNeeded Boolean Allowed values:
  • true – storing the credential after the payment is disabled (a stored credential is a customer identifier passed in order registration request — after paymentorder.do request it will be deleted from order details);
  • false – if payment is successful the credential can be stored (if the necessary conditions are met). This is the default value.
Optional

jsonParams Object 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
  • 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).
Optional

threeDSSDK Boolean Possible values: true or false. Flag showing that payment comes from 3DS SDK.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

tii String Transaction initiator indicator. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant). Possible values
Optional

externalScaExemptionIndicator String The type of SCA (Strong Customer Authentication) excemption. If this parameter is specified, the transaction will be processed depending on your settings in the payment gateway: either forced SSL operation will be done, or the issuer bank will get the information about SCA excemption and decide to perform operation with or without 3DS authentication (for details, contact our support team). Allowed values:
  • LVP – Low Value Payments transaction. You can consider a transaction as low risk based on the transaction amount, the client's transactions per day or the client's total daily amount.
  • TRA – Transaction Risk Analysis transaction, i.e., the transaction that has passed successful anti-fraud check.

To pass this parameter, you must have sufficient permissions in the payment gateway.
Optional

acsInIFrame Boolean Flag indicating that an iFrame version of the finish URL will be returned. Possible values are true or false. To enable this feature please contact support.
Optional

clientBrowserInfo Object A block with the data about the client's browser that is sent to ACS during the 3DS authentication. To pass this block, you should have a special setting (contact the support team). See nested parameters.

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

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.
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
RI Initial Recurrent CIT Initiating Customer Entered by Customer Yes An e-commerce transaction, credential is stored.
R Recurrent MIT Subsequent Merchant No manual entry, Merchant passes the data No A recurrent transaction that uses a stored credential.
II Initial Installment CIT Initiating Customer Entered by Customer Yes An e-commerce transaction, credential is stored.
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 clientBrowserInfo block (data about the client's browser).

Required Name Type Description
Optional userAgent string Browser agent.
Optional OS string Operation system.
Optional OSVersion string Operation system version.
Optional browserAcceptHeader string The Accept header that tells the server what file formats (or MIME-types) the browser accepts.
Optional browserIpAddress string Browser IP address.
Optional browserLanguage string Browser language.
Optional browserTimeZone string Browser time zone.
Optional browserTimeZoneOffset integer The time zone offset in minutes between the user's local time and UTC.
Optional colorDepth string Screen color depth, in bits.
Optional fingerprint string Browser fingerprint - a unique digital identifier of the browser.
Optional isMobile Boolean Possible values: true or false. Flag showing that a mobile device is used.
Optional javaEnabled Boolean Possible values: true or false. Flag showing that java is enabled in the browser.
Optional javascriptEnabled Boolean Possible values: true or false. Flag showing that javascript is enabled in the browser.
Optional plugins string Comma-separated list of plugins the browser uses.
Optional screenHeight integer Screen height, in pixels.
Optional screenWidth integer Screen width, in pixels.
Optional screenPrint string Data about current screen print including resolution, color depth, display metrics.

Example of clientBrowserInfo block:

"clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"10.99.50.37"
    }

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

Required Name Type Description
Optional

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSVer2FinishUrl String URL where Customer should be redirected after authentication on ACS Server.
Optional

threeDSMethodNotificationUrl String URL where notification about authentication on ACS Server should be sent to.

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

info String If response is successful. Result of a payment attempt. Below are the possible values.
  • Your payment has been processed, redirecting...
  • Operation declined. Check the entered data and that there are enough funds on the card and repeat the operation. Redirecting...
  • Sorry, payment cannot be completed. Redirecting...
  • Operation declined. Contact the merchant. Redirecting...
  • Operation declined. Contact the bank that issued the card. Redirecting...
  • Impossible operation. Cardholder authentication completed unsuccessfully. Redirecting...
  • No connection with bank. Try again later. Redirecting...
  • Input time expired. Redirecting...
  • No response from bank received. Try again later. Redirecting...
Optional

redirect String [1..512] This parameter is returned if the payment is successful and that payment did not include check for 3-D Secure involvement. Merchants can use it if they want to redirect the user to the payment gateway page. If they have their own response page then this value can be ignored.
Optional

termUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address to which ACS redirects the cardholder after authentication. For details see Redirect to ACS.
Optional

acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
Optional

paReq String [1..255] In a successful response in case of a 3D-Secure payment. PAReq (Payment Authentication Request) - a message that should be sent to ACS together with redirect. This message contains the Base64-encoded data necessary for the cardholder authentication. For details see Redirect to ACS.
Optional

acsInIFrame Boolean Flag indicating that an iFrame version of the finish URL will be returned. Possible values are true or false. To enable this feature please contact support.

When authenticating via the 3DS 2.0 protocol, the following parameters are returned during the initial request:

Required Name Type Description
Mandatory

is3DSVer2 Boolean Possible values: true or false. Flag showing that payment uses 3DS 2.0.
Mandatory

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSMethodUrl String URL of ACS Server for gathering browser data.
Mandatory

threeDSMethodUrlServer String URL of 3DS Server for gathering browser data to be included in the AReq (Authentication Request) from 3DS Server to ACS Server.
Optional

threeDSMethodDataPacked String Base-64-encoded data of CReq (Challenge Response) to be sent to ACS Server.
Optional

threeDSMethodURLServerDirect String URL of 3dsmethod.do for executing the 3DS method on 3DS Server via Payment Gateway (subject to respective Merchant-level permission).

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:

Required Name Type Description
Conditional*

acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
Conditional*

packedCReq String Packed challenge request data. This value should be used as the ACS link creq parameter (acsUrl) to redirect the client to the ACS.

* Mandatory, if redirect to the ACS is needed.

Examples

Request example

Example of the first request:

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=64d3b8c2-5d87-7d92-bd20-d8db011b4f5b \
  --data '$PAN=4000001111111118' \
  --data '$CVC=123' \
  --data YYYY=2030 \
  --data MM=12 \
  --data 'TEXT=TEST CARDHOLDER' \
  --data language=en

Example of the second request:

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=64d3b8c2-5d87-7d92-bd20-d8db011b4f5b \
  --data '$PAN=4000001111111118' \
  --data '$CVC=123' \
  --data YYYY=2030 \
  --data MM=12 \
  --data 'TEXT=TEST CARDHOLDER' \
  --data language=en \
  --data threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6

Response examples

Example of the response to the first request:

{
  "errorCode": 0,
  "is3DSVer2": true,
  "threeDSServerTransId": "5802746e-3393-40c3-929a-dc966ebf08c6",
  "threeDSMethodURL": "https://example.com/acs2/acs/3dsMethod",
  "threeDSMethodURLServer": "example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6",
  "threeDSMethodDataPacked": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9hY3F1aXJlci5jb20vM2Rzc2VydmVyL2FwaS92MS9hY3Mvbm90aWZpY2F0aW9uP3RocmVlRFNTZXJ2ZXJUcmFuc0lEPTNhZmMxNjhhLTk0YjQtNGViMy04ZTJlLTgwZjZjMTg2NjY5ZCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiM2FmYzE2OGEtOTRiNC00ZWIzLThlMmUtODBmNmMxODY2NjlkIn0="
}

Example of the response to the second request:

{
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0,
  "acsUrl": "https://example.com/acs2/acs/creq",
  "is3DSVer2": true,
  "packedCReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjU4MDI3NDZlLTMzOTMtNDBjMy05MjlhLWRjOTY2ZWJmMDhjNiIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4xLjAiLCJhY3NUcmFuc0lEIjoiODFmZTU1ODUtZmZhOS00Y2NkLTljMjAtY2QzYWFiZDQwNTllIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
}

Payment for an Industry Practice transaction order

To pay for an order with Industry Practice transaction characteristics, use the request /industryPractice/paymentOrder.do.

Request parameters

Required Name Type Description
Conditional

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

token String [1..256] 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.
Mandatory

originalMdOrder String [1..36] The number of the original order in the Payment Gateway for which Industry Practice payment is made.
Conditional

amount Integer [0..12] Payment amount in minimum currency units of original payment for Incremental, Delayed Charges, No show operations.
The parameter is required for the Incremental, Delayed Charges, No show operations. The parameter must not be specified for Resubmission and Reauthorization.
Optional

jsonParams Object Object containing the attributes used to pass additional parameters. See below.
The former params parameter is an alias to this parameter (i.e., the requests with params also work).
Mandatory

tii String The initiator ID of the transaction. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant).

Possible values of tii:

tii value Description Transaction type Transaction initiator Card data for transaction Note
IPI Industry Practice Incremental (MIT) Subsequent Merchant Not entered, loaded from the corresponding transaction record stored credential in the payment gateway. A transaction to increase the payment amount within an already paid order.
IPS Industry Practice Resubmission (MIT) Subsequent Merchant Not entered, loaded from the corresponding transaction record stored credential in the payment gateway. A transaction attempting to repay when the original payment failed.
IPD Industry Practice Delayed Charges (MIT) Subsequent Merchant Not entered, loaded from the corresponding transaction record stored credential in the payment gateway. Delayed charges.
IPA Industry Practice Reauthorization (MIT) Subsequent Merchant Not entered, loaded from the corresponding transaction record stored credential in the payment gateway. Retry authorization if completion or execution of original order exceeds Visa/MC authorization validity period.
IPN Industry Practice No Show (MIT) Subsequent Merchant Not entered, loaded from the corresponding transaction record stored credential in the payment gateway. Performed by Merchants to issue fines to the Client for no-show when booking hotels and Car Sharing.

The jsonParams block contains additional information fields for later storage. To pass N parameters, a request must contain N jsonParams tags, where the name attribute contains the parameter name and value attribute contains its value:

Required Name Type Description
Mandatory

name String [1..255] Name of an additional parameter.
Mandatory

value String [1..1024] Value of an additional parameter - up to 1024 characters.

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

mdOrder String [1..36] The number of the order in the payment gateway with the payment completed by Industry Practice.
Optional

actionCode Integer Response code from the processing bank. See the list of action codes here.
Optional

approvalCode String [6] IPS authorization code. This field has a fixed length (six symbols) and can contain digits and Latin letters.
Optional

rrn Integer [1..12] Reference Retrieval Number - transaction ID assigned by Acquiring Bank.

Examples

Request example

curl --request POST \\
  --url https://dev.bpcbt.com/payment/industryPractice/paymentOrder.do \\
  --header 'content-type: application/x-www-form-urlencoded' \\
  --data '{
    "originalMdOrder":"f252eee4-5598-728a-a023-af6e09078dd0",
    "orderNumber":"testOrderNumber1",
    "tii":"IPI",
    "amount":"10",
    "username":"test_user",
    "password":"test_user_password"
}'

Response example

Successful industry practice payment

{
  "errorCode": "0",
  "errorMessage": "Successful",
  "mdOrder": "d88680c4-54e9-7115-80ae-3cc709017350",
  "actionCode": "0",
  "approvalCode": "000000",
  "rrn": "111111111113"
}

Unsuccessful industry practice payment (processing returned a failure)

{
  "errorCode": "5",
  "errorMessage": "Unsuccessful",
  "mdOrder": "d88680c4-54e9-7115-80ae-3cc709017350",
  "actionCode": "116",
  "approvalCode": "000000",
  "rrn": "111111111113"
}

Unsuccessful industry practice payment (for example, validation error)

{
  "errorCode": "5",
  "errorMessage": "Operation is not allowed for original order"
}

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

Required Name Type Description
Conditional

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

token String [1..256] 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.
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

bindingNotNeeded Boolean Allowed values:
  • true – storing the credential after the payment is disabled (a stored credntial is a customer identifier passed in order registration request — after instantPayment.do request it will be deleted from order details);
  • false – if payment is successful the credential can be stored (if the necessary conditions are met). This is the default value.
Optional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Optional

preAuth Boolean Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available:
  • true - two-phase payments enabled;
  • false - one-phase payments enabled (money are charged right away).
If the parameter is missing, one-phase payment is made.
Optional

pan String [1..19] Payment card number (mandatory, unless bindinId is passed). pan overrides bindingId.
Optional

cvc Integer This parameter is mandatory if permission Can process payments without confirmation of CVC is not enabled.
Optional

cardHolderName String [1..26] Cardholder's name in Latin characters. This parameter is passed only after an order is paid.
Optional

merchantLogin String [1..255] To register an order and carry out payment on behalf of another merchant, specify the merchant's API account login in this parameter.
Can be used only if you have the permission to see the transactions of other merchants or if the specified merchant is your child merchant.
Optional

sessionTimeoutSecs Integer [1..9] Order lifetime in seconds. If the parameter is not specified, the value specified in the merchant settings or the default value (1200 seconds = 20 minutes) will be used. If the request contains expirationDate, the value of sessionTimeoutSecs is not taken into account.
Optional

autocompletionDate String The date and time when the two-stage payment was completed automatically in the following format: 2017-12-29T13:02:51. The used timezone is UTC+0. To enable sending this field to the processing system, contact your technical support service.
Optional

autoReverseDate String The date and time when the two-stage payment was reversed automatically in the following format: 2022-06-23T13:02:51. The used timezone is UTC+0. To enable sending this field to the processing system, contact your technical support service.
Optional

expirationDate String Data and time of the order expiry. Format used: yyyy-MM-ddTHH:mm:ss.
If this parameter is not passed in the request, sessionTimeoutSecs is used to define the expiry of the order.
Conditional

seToken String Encrypted card data that replaces $PAN, $CVC, and $EXPIRY (or YYYY,MM) parameters. Must be passed if used instead of the card data.
The mandatory parameters for seToken string are timestamp, UUID, bindingId(or PAN,EXPDATE). Click here for more information about seToken generation.
Mandatory

backUrl String [1..512] URL the user is to be redirected to if payment is successful.
Use full path with protocol included, like this - https://test.com (not test.com).
Otherwise the user will be redirected to a URL composed like this: http://paymentGatewayURL/merchantURL
Optional

failUrl String [1..512] The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

jsonParams Object 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
  • 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).
Optional

features String Features of the order. As an example, below are the possible values.
  • VERIFY - If you specify this value in the order registration request, cardholder will be verified however they will not be charged any amount, so in this case amount parameter can be 0. Verification allows to make sure that a payment card is used by its legitimate owner, and further you can charge them without authentication (CVC, 3D-Secure). Even if some amount is passed in the request, the customer will not be charged if VERIFY feature is used. After a successful registration order status is changed to REVERSED. This value can be also used for storing the credential – in this case, the clientId parameter must be passed as well. Read more here.
  • FORCE_TDS - Force 3-D Secure payment. If a payment card does not support 3-D Secure, the transaction will fail.
  • FORCE_SSL - Force SSL payment (without 3-D Secure).
  • FORCE_FULL_TDS - After 3-D Secure authentication, PaRes status must be Y, which guarantees successful user authentication. Otherwise, the transaction will fail.
  • FORCE_CREATE_BINDING - passing this feature in the order registration request forcefully stores the credential. This functionality must be enabled by Merchant level permission in the Gateway. This value cannot be passed in a request with an existing bindingId or bindingNotNeeded = true (will cause validation error). When this feature is passed, the clientId parameter must be passed as well. If you pass both FORCE_CREATE_BINDING and VERIFY features, the order will be created for storing the credential ONLY (without payment).
Optional

orderBundle Object Object containing cart of items. The description of the nested elements is given below.
Optional

dynamicCallbackUrl String [1..512] This parameter allows you to use the functionality of sending callback notifications dynamically. Here you can pass the address to which all "payment" callback notifications activated for the merchant will be sent. "Payment" notifications are callback notifications related to the following events: successful hold, payment declined by timeout, cardpresent payment is declined, successful debit, refund, cancellation. At the same time, callback notifications activated for the merchant that are not related to payments (enabling/disabling a stored credential, storing a credential) will be sent to a static address for callbacks. Whether the parameter is mandatory or not depends on the merchant configuration on Payment Gateway side.
Optional

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSVer2FinishUrl String URL where Customer should be redirected after authentication on ACS Server.
Optional

threeDSMethodNotificationUrl String URL where notification about authentication on ACS Server should be sent to.
Conditional

threeDSVer2MdOrder String Order number which was registered in the first part of the request within 3DS 2.0 transaction.
If this parameter is present in the request, the mdOrder value passed in it overrides, and in this case the order gets paid right away instead of being registered. For Google Pay transactions, this parameter is mandatory.
Optional

threeDSSDK Boolean Possible values: true or false. Flag showing that payment comes from 3DS SDK.
Optional

threeDSProtocolVersion String 3DS protocol version. Possible values are "2.1.0", "2.2.0" for 3DS2.
If threeDSProtocolVersion is not passed in the request, then the default value will be used for 3D Secure authorization (2.1.0 - for 3DS 2).
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

expiry Integer Card expiration in the following format: YYYYMM. Mandatory, if neither seToken nor bindingId is passed.
Optional

email String Cardholder billing email.
Optional

phone String Customer's phone number. It is always necessary to specify the country code, but you can specify or omit the + sign. Thus, the following options are valid:
  • +449998887766;
  • 449998887766. 7 to 15 digits long.
Optional

tii String Transaction initiator indicator. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant). Possible values
Optional

externalScaExemptionIndicator String The type of SCA (Strong Customer Authentication) excemption. If this parameter is specified, the transaction will be processed depending on your settings in the payment gateway: either forced SSL operation will be done, or the issuer bank will get the information about SCA excemption and decide to perform operation with or without 3DS authentication (for details, contact our support team). Allowed values:
  • LVP – Low Value Payments transaction. You can consider a transaction as low risk based on the transaction amount, the client's transactions per day or the client's total daily amount.
  • TRA – Transaction Risk Analysis transaction, i.e., the transaction that has passed successful anti-fraud check.

To pass this parameter, you must have sufficient permissions in the payment gateway.
Optional

shippingPayerData Object Object containing customer delivery data. It is used for further 3DS authentication of the client. See nested parameters
Optional

preOrderPayerData Object Object containing pre-order data. It is used for further 3DS authentication of the client. See nested parameters
Optional

orderPayerData Object Object containing data about the order payer. It is used for further 3DS authentication of the client. See nested parameters
Optional

billingAndShippingAddressMatchIndicator A1 Indicator for matching the cardholder's billing address and shipping address. This parameter is used for further 3DS authentication of the customer.
Possible values:
  • Y - the cardholder's billing address and shipping address match;
  • N - cardholder billing address and shipping address do not match

Description of parameters in orderBundle object:

Required Name Type Description
Optional

orderCreationDate String Order creation date in the following format: YYYY-MM-DDTHH:MM:SS.
Optional

customerDetails Object Block containing customer attributes. The description of the tag attributes is given below.
Optional

cartItems Object Object containing cart items attributes. The description of nested elements is given below.

Description of parameters in customerDetails object:

Required Name Type Description
Conditional

email String Customer's email address. Multiple emails can be passed as comma-separated values.
Either of email or phone must be passed.
Conditional

phone String Customer's phone number. It is always necessary to specify the country code, but you can specify or omit the + sign. Thus, the following options are valid:
  • +449998887766;
  • 449998887766. 7 to 15 digits long.
Optional

contact String [0..40] Customer's preferred way of communication.
Optional

fullName String [1..100] Payer's full name.
Optional

passport Integer Customer's passport serial number in the following format: 2222888888.
Optional

deliveryInfo Object Object containing delivery address attributes. The description of the nested elements is given below.

Description of parameters in deliveryInfo object.

Required Name Type Description
Optional

deliveryType String [1..20] Delivery method.
Mandatory

country String Two letter code of the country of delivery.
Mandatory

city String [0..40] City of destination.
Mandatory

postAddress String [1..255] Delivery address.

Description of parameters in cartItems object.

Required Name Type Description
Mandatory

items Object An element of the array containing cart item attributes. The description of the nested elements is given below.

Description of parameters in items object.

Required Name Type Description
Mandatory

positionId Integer [1..12] Unique product identifier in the cart.
Mandatory

name String [1..255] Name or the description of an item in any format.
Optional

itemDetails Object Object containing the parameters describing an item. The description of the nested elements is given below.
Mandatory

quantity Object Element describing the total of items of one positionId and its unit of measurement. The description of the nested elements is given below.
Optional

itemAmount Integer [1..12] The total cost of all instances of one positionId specified in minor denomination of the currency. itemAmount must be passed only if the itemPrice parameter has not been passed. Otherwise passing of itemAmount is not required. If both parameters itemPrice and itemAmount are passed in the request, then itemAmount shall be equal itemPrice * quantity, otherwise the request will return an error.
Optional

itemPrice Integer [1..18] Total cost of instance of one positionId specified in minor currency units.
Optional

itemCurrency Integer ISO 4217 currency code. If the parameter is not specified, it is considered to be equal to the Order currency.
Mandatory

itemCode String [1..100] Number (identifier) of an item in the store system.
Optional

discount Object Object containing item discount attributes. The description of the nested elements is given below.
Optional

agentInterest Object Object containing attributes of the description of an agent fee for the sale of goods. The description of the nested elements is given below.

Description of parameters in itemDetails object.

Required Name Type Description
Optional

itemDetailsParams Object Parameter describing additional information regarding a line item. The description of the nested elements is given below.

Description of parameters in itemDetailsParams object.

Required Name Type Description
Mandatory

value String Additional item info.
Mandatory

name String [1..255] Name of the parameter describing the details of an item

Description of parameters in quantity object.

Required Name Type Description
Mandatory

value String Number of items in one positionId. Use a decimal point as a separator in fractions.
Mandatory

measure String [1..20] The unit of measurement for the quantity of item instances.

Description of parameters in discount object.

Required Name Type Description
Mandatory

discountType String [1..20] Type of discount applicable to an item.
Mandatory

discountValue Integer [0..20] Value of the item discount.

Description of parameters in agentInterest object:

Required Name Type Description
Mandatory

interestType String [1..20] Agent fee type.
Mandatory

interestValue Integer [1..20] Agent fee value.

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

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.
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
RI Initial Recurrent CIT Initiating Customer Entered by Customer Yes An e-commerce transaction, credential is stored.
R Recurrent MIT Subsequent Merchant No manual entry, Merchant passes the data No A recurrent transaction that uses a stored credential.
II Initial Installment CIT Initiating Customer Entered by Customer Yes An e-commerce transaction, credential is stored.
I Installment MIT Subsequent Merchant No manual entry, Merchant passes the data No An installment transaction that uses a stored credential.

Description of parameters in shippingPayerData object:

Required Name Type Description
Optional shippingCity ANS...50 The customer's city (from the delivery address)
Optional shippingCountry ANS...50 The customer's country
Optional shippingAddressLine1 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine2 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine3 ANS...50 The customer's primary address (from the shipping address)
Optional shippingPostalCode ANS...16 The customer's zip code for delivery
Optional shippingState ANS...50 Customer's state/region (from delivery address)
Optional shippingMethodIndicator N2 Shipping Method Indicator.
Possible values:
  • 01 - delivery to the cardholder's billing address
  • 02 - delivery to another address verified by Merchant
  • 03 - delivery to an address other than the cardholder's primary (settlement) address
  • 04 - shipment to the store/self-collection (the store address should be specified in the relevant delivery parameters)
  • 05 - Digital distribution (includes online services and e-gift cards)
  • 06 - travel and event tickets that are not deliverable
  • 07 - Other (e.g. games, non-deliverable digital goods, digital subscriptions, etc.)
Optional deliveryTimeframe N2 Product delivery timeframe.
Possible values:
  • 01 - digital distribution
  • 02 - same-day delivery
  • 03 - overnight delivery
  • 04 - delivery within 2 days after payment and later
Optional deliveryEmail ANS...254 Target email address for delivery of digital distribution

Description of parameters in preOrderPayerData object:

Required Name Type Description
Optional preOrderDate ANS8 Expected date when delivery will be available (for pre-ordered purchases), in the format YYYYYYMMDD.
Optional preOrderPurchaseInd N2 Indicator of a customer placing an order for available or future delivery.
Possible values:
  • 01 - delivery available;
  • 02 - future delivery
Optional reorderItemsInd N2 An indicator that the customer is rebooking a previously paid delivery as part of a new order.
Possible values:
  • 01 - order placed for the first time;
  • 02 - repeated order

Description of parameters in orderPayerData object:

Required Name Type Description
Optional homePhone ANS...19 The cardholder's home phone number, with the obligatory "+" symbol
Optional workPhone ANS...19 The cardholder's work phone number, with the obligatory "+" symbol
Optional mobilePhone ANS...19 The cardholder's mobile phone number, with the obligatory "+" symbol

Below are the parameters of the clientBrowserInfo block (data about the client's browser).

Required Name Type Description
Optional userAgent string Browser agent.
Optional OS string Operation system.
Optional OSVersion string Operation system version.
Optional browserAcceptHeader string The Accept header that tells the server what file formats (or MIME-types) the browser accepts.
Optional browserIpAddress string Browser IP address.
Optional browserLanguage string Browser language.
Optional browserTimeZone string Browser time zone.
Optional browserTimeZoneOffset integer The time zone offset in minutes between the user's local time and UTC.
Optional colorDepth string Screen color depth, in bits.
Optional fingerprint string Browser fingerprint - a unique digital identifier of the browser.
Optional isMobile Boolean Possible values: true or false. Flag showing that a mobile device is used.
Optional javaEnabled Boolean Possible values: true or false. Flag showing that java is enabled in the browser.
Optional javascriptEnabled Boolean Possible values: true or false. Flag showing that javascript is enabled in the browser.
Optional plugins string Comma-separated list of plugins the browser uses.
Optional screenHeight integer Screen height, in pixels.
Optional screenWidth integer Screen width, in pixels.
Optional screenPrint string Data about current screen print including resolution, color depth, display metrics.

Example of clientBrowserInfo block:

"clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"10.99.50.37"
    }

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] 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.
Optional

error String Error message (if response returned an error) in the language passed in the request.
Optional

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Optional

info String If response is successful. Result of a payment attempt. Below are the possible values.
  • Your payment has been processed, redirecting...
  • Operation declined. Check the entered data and that there are enough funds on the card and repeat the operation. Redirecting...
  • Sorry, payment cannot be completed. Redirecting...
  • Operation declined. Contact the merchant. Redirecting...
  • Operation declined. Contact the bank that issued the card. Redirecting...
  • Impossible operation. Cardholder authentication completed unsuccessfully. Redirecting...
  • No connection with bank. Try again later. Redirecting...
  • Input time expired. Redirecting...
  • No response from bank received. Try again later. Redirecting...
Optional

redirect String [1..512] This parameter is returned if the payment is successful and that payment did not include check for 3-D Secure involvement. Merchants can use it if they want to redirect the user to the payment gateway page. If they have their own response page then this value can be ignored.
Optional

termUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address to which ACS redirects the cardholder after authentication. For details see Redirect to ACS.
Optional

acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
Optional

paReq String [1..255] In a successful response in case of a 3D-Secure payment. PAReq (Payment Authentication Request) - a message that should be sent to ACS together with redirect. This message contains the Base64-encoded data necessary for the cardholder authentication. For details see Redirect to ACS.
Conditional orderStatus Object Contains order status parameters and is returned only if the payment gateway has recognized all request parameters as correct. See the description below.

When authenticating via the 3DS v2.0 protocol, the following parameters are returned during the initial request:

Required Name Type Description
Mandatory

is3DSVer2 Boolean Possible values: true or false. Flag showing that payment uses 3DS 2.0.
Mandatory

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSMethodUrl String URL of ACS Server for gathering browser data.
Mandatory

threeDSMethodUrlServer String URL of 3DS Server for gathering browser data to be included in the AReq (Authentication Request) from 3DS Server to ACS Server.
Optional

threeDSMethodDataPacked String Base-64-encoded data of CReq (Challenge Response) to be sent to ACS Server.
Optional

threeDSMethodURLServerDirect String URL of 3dsmethod.do for executing the 3DS method on 3DS Server via Payment Gateway (subject to respective Merchant-level permission).

orderStatus block contains the following elements.

Required Name Type Description
Optional

ErrorCode Integer [1..2] 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.
Optional

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

OrderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each merchant.
Optional

OrderStatus Integer The value of this parameter specifies the status of the order in the payment gateway. It is missing if the order has not been found. Below is the list of available values:
  • 0 - order was registered but not paid;
  • 1 - pre-authorized amount is on hold on the buyer's account (for two-phase payments);
  • 2 - order amount is fully authorized;
  • 3 - authorization canceled;
  • 4 - transaction was refunded;
  • 5 - access control server of the issuing bank initiated authorization procedure;
  • 6 - authorization declined.
  • 7 - pending order payment;
  • 8 - intermediate completion for multiple partial completion.
Optional

expiration Integer Card expiration in the following format: YYYYMM. This parameter is to be specified only after the order has been paid.
Optional

cardholderName String [1..26] Cardholder's name (if available).
Optional

depositAmount String [0..12] Absent in REST API - amount is used instead.
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional

approvalCode String [6] IPS authorization code. This field has a fixed length (six symbols) and can contain digits and Latin letters.
Optional

authCode Integer [6] Deprecated parameter (not used). Its value is always 2 regardless the order status and authorization code of the processing system.
Optional

Pan String [1..19] Masked number of the card that has been used for the payment. This parameter is to be specified only after the order has been paid. When paying via Apple Pay, DPAN is used as card number - it is a number linked to customer's mobile device that functions as a payment card number in the Apple Pay system.
Optional

Amount Integer [0..12] Payment amount in minor currency units (e.g., in cents).
Optional

Ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

originalActionCode String Response code received from the processing system. To enable receiving this field, contact the technical support service.
Optional

rrn Integer [1..12] Reference Retrieval Number - transaction ID assigned by Acquiring Bank.

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 email="demo@example.com" \
--data phone="+449998887766" \
--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,
        "originalActionCode": "S1",
        "rrn": "311489272111",
        "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 number of payment card. Luhn validation (if payment card number is real), number of digits in a card number is from 13 to 20

CVC

Integer 3 digits

YYYY, MM

Year, Month Present or future date. If card expiry is current year and month payment is possible only until the end of the current calendar month.

TEXT

Cardholder Not verified.

MOTO payment

The request used to carry out MOTO paymenents is motoPayment.do.

Request parameters

Required Name Type Description
Optional

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Optional

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Optional

token String [1..256] 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.
Optional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Mandatory

returnUrl String [1..512] The address to which the user will be redirected if the payment is successful. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

failUrl String [1..512] The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

merchantLogin String [1..255] To carry out MOTO paymenent on behalf of another merchant, specify the merchant's API account login in this parameter.
Can be used only if you have the permission to see the transactions of other merchants or if the specified merchant is your child merchant.
Optional

postAddress String [1..255] Delivery address.
Optional

jsonParams Object 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
  • 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).
Optional

features String Features of the order. As an example, below are the possible values.
  • VERIFY - If you specify this value in the order registration request, cardholder will be verified however they will not be charged any amount, so in this case amount parameter can be 0. Verification allows to make sure that a payment card is used by its legitimate owner, and further you can charge them without authentication (CVC, 3D-Secure). Even if some amount is passed in the request, the customer will not be charged if VERIFY feature is used. After a successful registration order status is changed to REVERSED. This value can be also used for storing the credential – in this case, the clientId parameter must be passed as well. Read more here.
  • FORCE_TDS - Force 3-D Secure payment. If a payment card does not support 3-D Secure, the transaction will fail.
  • FORCE_SSL - Force SSL payment (without 3-D Secure).
  • FORCE_FULL_TDS - After 3-D Secure authentication, PaRes status must be Y, which guarantees successful user authentication. Otherwise, the transaction will fail.
  • FORCE_CREATE_BINDING - passing this feature in the order registration request forcefully stores the credential. This functionality must be enabled by Merchant level permission in the Gateway. This value cannot be passed in a request with an existing bindingId or bindingNotNeeded = true (will cause validation error). When this feature is passed, the clientId parameter must be passed as well. If you pass both FORCE_CREATE_BINDING and VERIFY features, the order will be created for storing the credential ONLY (without payment).
Optional

dynamicCallbackUrl String [1..512] This parameter allows you to use the functionality of sending callback notifications dynamically. Here you can pass the address to which all "payment" callback notifications activated for the merchant will be sent. "Payment" notifications are callback notifications related to the following events: successful hold, payment declined by timeout, cardpresent payment is declined, successful debit, refund, cancellation. At the same time, callback notifications activated for the merchant that are not related to payments (enabling/disabling a stored credential, storing a credential) will be sent to a static address for callbacks. Whether the parameter is mandatory or not depends on the merchant configuration on Payment Gateway side.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

preAuth Boolean Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available:
  • true - two-phase payments enabled;
  • false - one-phase payments enabled (money are charged right away).
If the parameter is missing, one-phase payment is made.
Mandatory

pan String [1..19] Masked number of the card that has been used for the payment. This parameter is to be specified only after the order has been paid. When paying via Apple Pay, DPAN is used as card number - it is a number linked to customer's mobile device that functions as a payment card number in the Apple Pay system.
Mandatory

expiry Integer Card expiration in the following format: YYYYMM. Mandatory, if neither seToken nor bindingId is passed.
Mandatory

cardholder String [1..26] Cardholder's name in Latin characters. This parameter is passed only after an order is paid.
Optional

cvc Integer This parameter is mandatory if permission Can process payments without confirmation of CVC is not enabled.

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Response parameters

Required Name Type Description
Mandatory

success Boolean 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.
Read here to find out how to get payment status.
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Mandatory

errorMessage String [1..512] 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.
Mandatory

mdOrder String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

userMessage String [1..512] Message to user describing the result code.

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

Redirect to ACS (simplified)

If 3-D Secure is required, then, after receiving payment response, the customer must be redirected to ACS. In this case, the payment response contains the acsUrl parameter that will be used for the redirect.

The acsRedirect.do request allows to redirect a customer to the ACS authentication page in a simplified way - just using orderId parameter received after an order registration.

It is also possible to redirect a customer to ACS with a POST request (regular redirect). The description of this method can be found here.

Without other actions required from customer, the payment gateway redirects them to the ACS page, where customer authenticates.

Then, depending on the authentication result, the customer is redirected to the following URL:

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

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

Request parameters

Required Name Type Description
Mandatory

orderId String [1..36] 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

Wallets

Apple Pay order registration

The /applepay/payment.do request is used to register and pay for the order.

Request parameters

Required Name Type Description
Mandatory

merchant String Merchant login in the payment gateway.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

additionalParameters Object Additional parameters of the order that are stored in the merchant personal area for the subsequent viewing. Each new pair of a parameter name and its value must be separated by a comma. Below is a usage example.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
When storing a credential, this tag can contain parameters that specify the type of the stored credential. See the list of parameters.
Optional

preAuth Boolean Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available:
  • true - two-phase payments enabled;
  • false - one-phase payments enabled (money are charged right away).
If the parameter is missing, one-phase payment is made.
Mandatory

paymentToken String [1..8192] The paymentToken parameter must contain a Base64 encoded value of the paymentData property that was received in PKPaymentToken Object from the Apple Pay system (see https://developer.apple.com/library/content/documentation/PassKit/Reference/PaymentTokenJSON/PaymentTokenJSON.html). Thus, to make a request to the payment gateway, the merchant must:
  1. get PKPaymentToken Object containing paymentData from Apple Pay;
  2. extract paymentData value and encode it in Base64;
  3. include the encoded value of the paymentData property as the value of the paymentToken parameter in the payment request that the merchant sends to the payment gateway.
Optional

tii String Transaction initiator indicator. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant). Possible values.
Mandatory

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

threeDSProtocolVersion String 3DS protocol version. Possible values are "2.1.0", "2.2.0" for 3DS2.
If threeDSProtocolVersion is not passed in the request, then the default value will be used for 3D Secure authorization (2.1.0 - for 3DS 2).
Optional

externalScaExemptionIndicator String The type of SCA (Strong Customer Authentication) excemption. If this parameter is specified, the transaction will be processed depending on your settings in the payment gateway: either forced SSL operation will be done, or the issuer bank will get the information about SCA excemption and decide to perform operation with or without 3DS authentication (for details, contact our support team). Allowed values:
  • LVP – Low Value Payments transaction. You can consider a transaction as low risk based on the transaction amount, the client's transactions per day or the client's total daily amount.
  • TRA – Transaction Risk Analysis transaction, i.e., the transaction that has passed successful anti-fraud check.

To pass this parameter, you must have sufficient permissions in the payment gateway.

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. This value is possible to pass only if the "Vendor pays common bindings creation is allowed" permission is enabled.
RI Initial Recurrent 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.

Additional parameters that specify the type of created stored credential and are passed in additionalParameters:

Required Name Type Description
Conditional

installments Integer [3] Maximum number of allowed authorizations for installment payments.
Should be specified when creating an installment stored credential.
Conditional

recurringFrequency Integer [2] Maximum number of days between authorizations. Positive integer from 1 to 28.
Should be specified when creating a recurring stored credential.
Conditional

recurringExpiry String [8] The date after which further authorizations should not be performed. Format: YYYYMMDD.
Should be specified when creating a recurring stored credential.

Response parameters

Required Name Type Description
Mandatory

success Boolean 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.
Read here to find out how to get payment status.
Conditional data Object This parameter is returned only if the payment is processed successfully. See the description below.
Conditional error Object This parameter is returned only if the payment failed. See the description below.
Conditional orderStatus Object 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.

Required Name Type Description
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.

error block contains the following elements.

Required Name Type Description

code Integer [1..3] Code as an information parameter stating an error occurred.

description String [1..598] A detailed technical explanation of the error - the contents of this parameter should not to be displayed to the customer.

message String [1..512] Information parameter that is an error description to be displayed to the user. The parameter may vary, so it should not be hardcoded.

orderStatus block contains the following elements.

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

orderStatus Integer The value of this parameter specifies the status of the order in the payment gateway. It is missing if the order has not been found. Below is the list of available values:
  • 0 - order was registered but not paid;
  • 1 - order was authorized only and wasn't captured yet (for two-phase payments);
  • 2 - order was authorized and captured;
  • 3 - authorization canceled;
  • 4 - transaction was refunded;
  • 5 - access control server of the issuing bank initiated authorization procedure;
  • 6 - authorization declined;
  • 7 - pending order payment;
  • 8 - intermediate completion for multiple partial completion.
Optional

actionCode Integer Response code from the processing bank. See the list of action codes here.
Optional

actionCodeDescription String [1..512] actionCode description returned from the processing bank.
Optional

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional

date String Order registration date (UNIX time).
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Conditional merchantOrderParams Object Object with attributes in which the merchant's additional parameters are transmitted. See the description below.
Conditional attributes Object Attributes of the order in the payment system (order number). See the description below.
Conditional cardAuthInfo Object Information about the buyer's payment card. See the description below.
Optional

authDateTime String Authorization date and time, shown as the amount of milliseconds since 00:00 January 1, 1970 GMT (UNIX time).
Optional

terminalId String [1..10] Terminal identifier in the system that processes the payment.
Optional

authRefNum String [1..24] Reference number of the payment authorization that has been assigned to it upon its registration.
Conditional paymentAmountInfo Object A parameter containing embedded parameters with information about confirmation, debiting and refund amounts. See the description below.
Conditional bankInfo Object Contains the embedded bankCountryName parameter. See the description below.

merchantOrderParams block contains the following elements.

Required Name Type Description
Mandatory

name String [1..255] Name of the merchant's additional parameter.
Mandatory

value String The value of the merchant's additional parameter - up to 1024 characters.

attributes block contains the following elements.

Required Name Type Description
Mandatory

name String [1..255] Name of an additional parameter.
Mandatory

value Alphanumeric Value of an additional parameter - up to 1024 characters.

cardAuthInfo block contains the following elements.

Required Name Type Description
Mandatory

expiration Integer Card expiration in the following format: YYYYMM. This parameter is to be specified only after the order has been paid.
Mandatory

cardholdername String [1..26] Cardholder's name in Latin characters. This parameter is passed only after an order is paid.
Mandatory

approvalCode String [6] IPS authorization code. This field has a fixed length (six symbols) and can contain digits and Latin letters.
Mandatory

pan String [1..19] Masked DPAN: a number that is linked to the customer's mobile device and functions as a payment card number in the Apple Pay system.

paymentAmountInfo block contains the following elements.

Required Name Type Description
Mandatory

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

approvedAmount Integer [0..12] Amount in minimum currency units (e.g. cents) that was put on hold on buyer's account. Used in two-phase payments only.
Mandatory

depositedAmount Integer [1..12] Charged amount in minimum currency units (e.g., in cents).
Mandatory

refundedAmount Integer [1..12] Refunded amount in minimum currency units.

bankInfo block contains the following elements.

Required Name Type Description
Mandatory

bankCountryName String [1..160] Country of the issuing bank.

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"
  },
  "language" : "en",
  "clientId" : "259753456",
  "orderNumber" : "281477871",
  "paymentToken" : "eyJkYXRhIjoiYPhK3M1bEtm...YjM2NWMzZWNmYjE5fIkVDX3YxIn0=",
  "preAuth" : 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 applepay/paymentDirect.do. It is used to register and pay for the order.

This request can be used for integrations that involve payment data decoding on Merchant side.

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

feeInput String Fee amount in minimum currency units. Must be enabled by respective Merchant-level permission in the Gateway.
Optional

additionalParameters Object Additional parameters of the order that are stored in the merchant personal area for the subsequent viewing. Each new pair of a parameter name and its value must be separated by a comma. Below is a usage example.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
When storing a credential, this tag can contain parameters that specify the type of the stored credential. See the list of parameters.
Optional

preAuth Boolean Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available:
  • true - two-phase payments enabled;
  • false - one-phase payments enabled (money are charged right away).
If the parameter is missing, one-phase payment is made.
Mandatory

paymentToken String [1..8192] Payment data as received from Apple Pay and decrypted by a merchant. Flow:
  1. Receive PKPaymentToken Object from Apple Pay (Payment Token Format Reference) with encrypted payment data;
  2. Decrypt (ECC/RSA) paymentData to get clear-text view of the object: {"applicationPrimaryAccountNumber":"4111111111111111","deviceManufacturerIdentifier":"050110030273","currencyCode":"840"," applicationExpirationDate":"220430","paymentData":{"onlinePaymentCryptogram":"AM32yL0vuOOmAAGG0iQUAoABFA=="}," paymentDataType":"3DSecure","transactionAmount":1010};
  3. BASE64 encode clear-text paymentData object and send it as paymentToken.
Optional

merchant String Merchant login in the payment gateway.
Optional

features String In this parameter you can pass VERIFY — in this case the payment will not be made, instead, a credential will be stored (i.e., Customer's card will be saved).
Note that if you pass features, paymentToken.transactionAmount must be 0. Otherwise, an error will be returned.
Optional

tii String Transaction initiator indicator. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant). Possible values.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

threeDSProtocolVersion String 3DS protocol version. Possible values are "2.1.0", "2.2.0" for 3DS2.
If threeDSProtocolVersion is not passed in the request, then the default value will be used for 3D Secure authorization (2.1.0 - for 3DS 2).
Optional

externalScaExemptionIndicator String The type of SCA (Strong Customer Authentication) excemption. If this parameter is specified, the transaction will be processed depending on your settings in the payment gateway: either forced SSL operation will be done, or the issuer bank will get the information about SCA excemption and decide to perform operation with or without 3DS authentication (for details, contact our support team). Allowed values:
  • LVP – Low Value Payments transaction. You can consider a transaction as low risk based on the transaction amount, the client's transactions per day or the client's total daily amount.
  • TRA – Transaction Risk Analysis transaction, i.e., the transaction that has passed successful anti-fraud check.

To pass this parameter, you must have sufficient permissions in the payment gateway.
Optional

shippingPayerData Object Object containing customer delivery data. It is used for further 3DS authentication of the client. See nested parameters
Optional

preOrderPayerData Object Object containing pre-order data. It is used for further 3DS authentication of the client. See nested parameters
Optional

orderPayerData Object Object containing data about the order payer. It is used for further 3DS authentication of the client. See nested parameters
Optional

billingAndShippingAddressMatchIndicator A1 Indicator for matching the cardholder's billing address and shipping address. This parameter is used for further 3DS authentication of the customer.
Possible values:
  • Y - the cardholder's billing address and shipping address match;
  • N - cardholder billing address and shipping address do not match

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. This value is possible to pass only if the "Vendor pays common bindings creation is allowed" permission is enabled.
RI Initial Recurrent 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.

Additional parameters that specify the type of created stored credential and are passed in additionalParameters:

Required Name Type Description
Conditional

installments Integer [3] Maximum number of allowed authorizations for installment payments.
Should be specified when creating an installment stored credential.
Conditional

recurringFrequency Integer [2] Maximum number of days between authorizations. Positive integer from 1 to 28.
Should be specified when creating a recurring stored credential.
Conditional

recurringExpiry String [8] The date after which further authorizations should not be performed. Format: YYYYMMDD.
Should be specified when creating a recurring stored credential.

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Description of parameters in shippingPayerData object:

Required Name Type Description
Optional shippingCity ANS...50 The customer's city (from the delivery address)
Optional shippingCountry ANS...50 The customer's country
Optional shippingAddressLine1 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine2 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine3 ANS...50 The customer's primary address (from the shipping address)
Optional shippingPostalCode ANS...16 The customer's zip code for delivery
Optional shippingState ANS...50 Customer's state/region (from delivery address)
Optional shippingMethodIndicator N2 Shipping Method Indicator.
Possible values:
  • 01 - delivery to the cardholder's billing address
  • 02 - delivery to another address verified by Merchant
  • 03 - delivery to an address other than the cardholder's primary (settlement) address
  • 04 - shipment to the store/self-collection (the store address should be specified in the relevant delivery parameters)
  • 05 - Digital distribution (includes online services and e-gift cards)
  • 06 - travel and event tickets that are not deliverable
  • 07 - Other (e.g. games, non-deliverable digital goods, digital subscriptions, etc.)
Optional deliveryTimeframe N2 Product delivery timeframe.
Possible values:
  • 01 - digital distribution
  • 02 - same-day delivery
  • 03 - overnight delivery
  • 04 - delivery within 2 days after payment and later
Optional deliveryEmail ANS...254 Target email address for delivery of digital distribution

Description of parameters in preOrderPayerData object:

Required Name Type Description
Optional preOrderDate ANS8 Expected date when delivery will be available (for pre-ordered purchases), in the format YYYYYYMMDD.
Optional preOrderPurchaseInd N2 Indicator of a customer placing an order for available or future delivery.
Possible values:
  • 01 - delivery available;
  • 02 - future delivery
Optional reorderItemsInd N2 An indicator that the customer is rebooking a previously paid delivery as part of a new order.
Possible values:
  • 01 - order placed for the first time;
  • 02 - repeated order

Description of parameters in orderPayerData object:

Required Name Type Description
Optional homePhone ANS...19 The cardholder's home phone number, with the obligatory "+" symbol
Optional workPhone ANS...19 The cardholder's work phone number, with the obligatory "+" symbol
Optional mobilePhone ANS...19 The cardholder's mobile phone number, with the obligatory "+" symbol

Response parameters

Required Name Type Description
Mandatory

success Boolean 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.
Read here to find out how to get payment status.
Mandatory

data Object Returns only if the payment is successful.
Mandatory

error Object This parameter is returned only if the payment failed.
Optional

orderStatus Integer The value of this parameter specifies the status of the order in the payment gateway. It is missing if the order has not been found. Below is the list of available values:
  • 0 - order was registered but not paid;
  • 1 - order was authorized only and wasn't captured yet (for two-phase payments);
  • 2 - order was authorized and captured;
  • 3 - authorization canceled;
  • 4 - transaction was refunded;
  • 5 - access control server of the issuing bank initiated authorization procedure;
  • 6 - authorization declined;
  • 7 - pending order payment;
  • 8 - intermediate completion for multiple partial completion.

Parameters in data block:

Required Name Type Description
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.

Parameters in error block:

Required Name Type Description
Mandatory

code Integer [1..3] Code as an information parameter stating an error occurred.
Mandatory

message String [1..512] Information parameter that is an error description to be displayed to the user. The parameter may vary, so it should not be hardcoded.
Mandatory

description String [1..598] A detailed technical explanation of the error - the contents of this parameter should not to be displayed to the customer.

Parameters in orderStatus block:

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

orderStatus Integer The value of this parameter specifies the status of the order in the payment gateway. It is missing if the order has not been found. Below is the list of available values:
  • 0 - order was registered but not paid;
  • 1 - pre-authorized amount is on hold on the buyer's account (for two-phase payments);
  • 2 - order amount is fully authorized;
  • 3 - authorization canceled;
  • 4 - transaction was refunded;
  • 5 - access control server of the issuing bank initiated authorization procedure;
  • 6 - authorization declined.
Optional

actionCode Integer Response code from the processing bank. See the list of action codes here.
Optional

actionCodeDescription String [1..512] actionCode description returned from the processing bank.
Optional

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional

date String Order registration date (UNIX time).
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

merchantOrderParams Object Section with attributes in which the merchant's additional parameters are passed.
Optional

cardAuthInfo Object Block containing data about the payer's card see nested parameters.
Optional

authDateTime String Authorization date and time, shown as the amount of milliseconds since 00:00 January 1, 1970 GMT (UNIX time).
Optional

terminalId String [1..10] Terminal identifier in the system that processes the payment.
Optional

authRefNum String [1..24] Reference number of the payment authorization that has been assigned to it upon its registration.
Optional

paymentAmountInfo Object Object containing the information on the confirmation amount, debit amount, and refund amount. Below is the list of nested parameters.
Optional

bankInfo Object Object containing a nested parameter bankCountryName in which the name of the country of the issuing bank is passed (if available). The language used is the same as the language passed in the language parameter of the request. If no language is passed, the language of the user calling the method will be used.

Parameters in cardAuthInfo block:

Required Name Type Description
Optional

expiration Integer Year and month of card expiration.
Optional

cardholderName String [1..26] Cardholder's name (if available).
Optional

approvalCode String [6] IPS authorization code. This field has a fixed length (six symbols) and can contain digits and Latin letters.
Optional

pan String [1..19] Masked DPAN: a number that is linked to the customer's mobile device and functions as a payment card number in the Apple Pay system.

Parameters in paymentAmountInfo block:

Required Name Type Description
Optional

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

approvedAmount Integer [0..12] Amount in minimum currency units (e.g. cents) that was put on hold on buyer's account. Used in two-phase payments only.
Optional

depositedAmount Integer [1..12] Charged amount in minimum currency units (e.g., in cents).
Optional

refundedAmount Integer [1..12] Refunded amount in minimum currency units.
Optional

totalAmount Integer [1..12] Order amount plus fee, if any.

Examples

Request example

curl --location --request POST 'https://dev.bpcbt.com/payment/applepay/paymentDirect.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "test_user",
    "password": "test_user_password",
    "orderNumber": "947664b3-4a42-4cdf-9f8c-2e9679bad9e4",
    "description": "description of the order",
    "language": "en",
    "paymentToken": "eyJhcHBsaWNhPT...0ifX0="
}'

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 and pay for the order.

Required Name Type Description
Mandatory

merchant String Merchant login in the payment gateway.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

additionalParameters Object Additional parameters of the order that are stored in the merchant personal area for the subsequent viewing. Each new pair of a parameter name and its value must be separated by a comma. Below is a usage example.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
When storing a credential, this tag can contain parameters that specify the type of the stored credential. See the list of parameters.
Optional

preAuth Boolean Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available:
  • true - two-phase payments enabled;
  • false - one-phase payments enabled (money are charged right away).
If the parameter is missing, one-phase payment is made.
Mandatory

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

tii String Transaction initiator indicator. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant). Possible values.
Mandatory

paymentToken String [1..8192] A token obtained from Google Pay and encoded in Base64.
Mandatory

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currencyCode String [3] Numeric ISO 4217 code of the payment currency. If this parameter is not specified, it is considered to be equal to the default currency code.
Mandatory

returnUrl String [1..512] The address to which the user will be redirected if the payment is successful. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

failUrl String [1..512] The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

dynamicCallbackUrl String [1..512] This parameter allows you to use the functionality of sending callback notifications dynamically. Here you can pass the address to which all "payment" callback notifications activated for the merchant will be sent. "Payment" notifications are callback notifications related to the following events: successful hold, payment declined by timeout, cardpresent payment is declined, successful debit, refund, cancellation. At the same time, callback notifications activated for the merchant that are not related to payments (enabling/disabling a stored credential, storing a credential) will be sent to a static address for callbacks. Whether the parameter is mandatory or not depends on the merchant configuration on Payment Gateway side.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

shippingPayerData Object Object containing customer delivery data. It is used for further 3DS authentication of the client. See nested parameters
Optional

orderPayerData Object Object containing data about the order payer. It is used for further 3DS authentication of the client. See nested parameters
Optional

preOrderPayerData Object Object containing pre-order data. It is used for further 3DS authentication of the client. See nested parameters
Optional

billingAndShippingAddressMatchIndicator A1 Indicator for matching the cardholder's billing address and shipping address. This parameter is used for further 3DS authentication of the customer.
Possible values:
  • Y - the cardholder's billing address and shipping address match;
  • N - cardholder billing address and shipping address do not match
Optional

acsInIFrame Boolean Flag indicating that an iFrame version of the finish URL will be returned. Possible values are true or false. To enable this feature please contact support.

Optional

| clientBrowserInfo | Object | A block with the data about the client's browser that is sent to ACS during the 3DS authentication. To pass this block, you should have a special setting (contact the support team). See nested parameters. |

|

If 3DS 2.0 is used, the following parameters should be passed as well:

Required Name Type Description
Conditional

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSVer2FinishUrl String URL where Customer should be redirected after authentication on ACS Server.
Optional

threeDSMethodNotificationUrl String URL where notification about authentication on ACS Server should be sent to.

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. This value is possible to pass only if the "Vendor pays common bindings creation is allowed" permission is enabled.
RI Initial Recurrent 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.

Additional parameters that specify the type of created stored credential and are passed in additionalParameters:

Required Name Type Description
Conditional

installments Integer [3] Maximum number of allowed authorizations for installment payments.
Should be specified when creating an installment stored credential.
Conditional

recurringFrequency Integer [2] Maximum number of days between authorizations. Positive integer from 1 to 28.
Should be specified when creating a recurring stored credential.
Conditional

recurringExpiry String [8] The date after which further authorizations should not be performed. Format: YYYYMMDD.
Should be specified when creating a recurring stored credential.

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Description of parameters in shippingPayerData object:

Required Name Type Description
Optional shippingCity ANS...50 The customer's city (from the delivery address)
Optional shippingCountry ANS...50 The customer's country
Optional shippingAddressLine1 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine2 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine3 ANS...50 The customer's primary address (from the shipping address)
Optional shippingPostalCode ANS...16 The customer's zip code for delivery
Optional shippingState ANS...50 Customer's state/region (from delivery address)
Optional shippingMethodIndicator N2 Shipping Method Indicator.
Possible values:
  • 01 - delivery to the cardholder's billing address
  • 02 - delivery to another address verified by Merchant
  • 03 - delivery to an address other than the cardholder's primary (settlement) address
  • 04 - shipment to the store/self-collection (the store address should be specified in the relevant delivery parameters)
  • 05 - Digital distribution (includes online services and e-gift cards)
  • 06 - travel and event tickets that are not deliverable
  • 07 - Other (e.g. games, non-deliverable digital goods, digital subscriptions, etc.)
Optional deliveryTimeframe N2 Product delivery timeframe.
Possible values:
  • 01 - digital distribution
  • 02 - same-day delivery
  • 03 - overnight delivery
  • 04 - delivery within 2 days after payment and later
Optional deliveryEmail ANS...254 Target email address for delivery of digital distribution

Description of parameters in orderPayerData object:

Required Name Type Description
Optional homePhone ANS...19 The cardholder's home phone number, with the obligatory "+" symbol
Optional workPhone ANS...19 The cardholder's work phone number, with the obligatory "+" symbol
Optional mobilePhone ANS...19 The cardholder's mobile phone number, with the obligatory "+" symbol

Description of parameters in preOrderPayerData object:

Required Name Type Description
Optional preOrderDate ANS8 Expected date when delivery will be available (for pre-ordered purchases), in the format YYYYYYMMDD.
Optional preOrderPurchaseInd N2 Indicator of a customer placing an order for available or future delivery.
Possible values:
  • 01 - delivery available;
  • 02 - future delivery
Optional reorderItemsInd N2 An indicator that the customer is rebooking a previously paid delivery as part of a new order.
Possible values:
  • 01 - order placed for the first time;
  • 02 - repeated order

Below are the parameters of the clientBrowserInfo block (data about the client's browser).

Required Name Type Description
Optional userAgent string Browser agent.
Optional OS string Operation system.
Optional OSVersion string Operation system version.
Optional browserAcceptHeader string The Accept header that tells the server what file formats (or MIME-types) the browser accepts.
Optional browserIpAddress string Browser IP address.
Optional browserLanguage string Browser language.
Optional browserTimeZone string Browser time zone.
Optional browserTimeZoneOffset integer The time zone offset in minutes between the user's local time and UTC.
Optional colorDepth string Screen color depth, in bits.
Optional fingerprint string Browser fingerprint - a unique digital identifier of the browser.
Optional isMobile Boolean Possible values: true or false. Flag showing that a mobile device is used.
Optional javaEnabled Boolean Possible values: true or false. Flag showing that java is enabled in the browser.
Optional javascriptEnabled Boolean Possible values: true or false. Flag showing that javascript is enabled in the browser.
Optional plugins string Comma-separated list of plugins the browser uses.
Optional screenHeight integer Screen height, in pixels.
Optional screenWidth integer Screen width, in pixels.
Optional screenPrint string Data about current screen print including resolution, color depth, display metrics.

Example of clientBrowserInfo block:

"clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"10.99.50.37"
    }

Response parameters

Required Name Type Description
Mandatory

success Boolean 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.
Read here to find out how to get payment status.
Conditional data Object This parameter is returned only if the payment is processed successfully. See the description below.
Conditional error Object This parameter is returned only if the payment failed. See the description below.
Optional

acsInIFrame Boolean Flag indicating that an iFrame version of the finish URL will be returned. Possible values are true or false. To enable this feature please contact support.

data block contains the following elements.

Required Name Type Description
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Conditional*

termUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address to which ACS redirects the cardholder after authentication. For details see Redirect to ACS.
Conditional*

acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
Conditional*

paReq String [1..255] In a successful response in case of a 3D-Secure payment. PAReq (Payment Authentication Request) - a message that should be sent to ACS together with redirect. This message contains the Base64-encoded data necessary for the cardholder authentication. For details see Redirect to ACS.
Conditional**

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.

* Only if additional authentication is used on the issuing bank's ACS
** The parameter is returned if the bindings are used

If 3DS 2.0 protocol is used, the response to the request also includes the following parameters in the data block:

Required Name Type Description
Mandatory

is3DSVer2 Boolean Possible values: true or false. Flag showing that payment uses 3DS 2.0.
Mandatory

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSMethodUrl String URL of ACS Server for gathering browser data.
Optional

threeDSMethodUrlServer String URL of 3DS Server for gathering browser data to be included in the AReq (Authentication Request) from 3DS Server to ACS Server.
Optional

threeDSMethodDataPacked String Base-64-encoded data of CReq (Challenge Response) to be sent to ACS Server.
Optional

threeDSMethodURLServerDirect String URL of 3dsmethod.do for executing the 3DS method on 3DS Server via Payment Gateway (subject to respective Merchant-level permission).

error block contains the following elements.

Required Name Type Description
Mandatory

code Integer [1..3] Code as an information parameter stating an error occurred.
Mandatory

message String [1..512] Information parameter that is an error description to be displayed to the user. The parameter may vary, so it should not be hardcoded.
Mandatory

description String [1..598] A detailed technical explanation of the error - the contents of this parameter should not to be displayed to the customer.

You should request getOrderStatusExtended.do and check the status of transaction.

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/payment/google/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
  "merchant": "OurBestMerchantLogin",
  "orderNumber": "UAF-203974-DE",
  "language": "EN",
  "preAuth": true,
  "description" : "Test description",
  "additionalParameters":
  {
      "firstParamName": "firstParamValue",
        "secondParamName": "secondParamValue"
  },
  "paymentToken": "eyJtZXJjaGFudCI6ICJ...FnXCJ9In0=",
  "amount" : "230000",
  "failUrl" : "https://mybestmerchantfailurl.com"
  "returnUrl" : "https://mybestmerchantreturnurl.com"
}'

Response example

{
"success":true,
"data": {
 "orderId": "12312312123"
 "is3DSVer2": true,
 "threeDSServerTransId": "f44d6d21-1874-45a5-aeb0-1c710dd6e134",
 "threeDSMethodURLServer": "https://test.com/3dsserver/gatherClientInfo?threeDSServerTransID=f44d6d21-1874-45a5-aeb0-1c710dd6e134"
 }
}

Google Pay Direct

The request used to make a direct payment via Google Pay is google/paymentDirect.do. It is used to register and pay for the order.

This request can be used for integrations that involve payment data decoding on Merchant side.

Request parameters

Required Name Type Description
Mandatory

username String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

additionalParameters Object Additional parameters of the order that are stored in the merchant personal area for the subsequent viewing. Each new pair of a parameter name and its value must be separated by a comma. Below is a usage example.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
When storing a credential, this tag can contain parameters that specify the type of the stored credential. See the list of parameters.
Optional

preAuth Boolean Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available:
  • true - two-phase payments enabled;
  • false - one-phase payments enabled (money are charged right away).
If the parameter is missing, one-phase payment is made.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

protocolVersion String Protocol version as defined by Google for a paymentToken: ECv1 (by default) or ECv2
Mandatory

paymentToken String [1..8192] Payment data as received from Google Pay and decrypted by a merchant. Flow:
  1. Receive PKPaymentToken Object from Google Pay (Payment Token Format Reference) with encrypted payment data;
  2. Decrypt (ECC/RSA) paymentData to get clear-text view of the object: {"paymentMethod": "CARD","paymentMethodDetails": {"pan": "5555555555555599","expirationMonth": 12,"expirationYear": 2024},"gatewayMerchantId": "GPay-decrypted","messageId": "AH2EjtcHYs1Ye9Baqr4FAM735VNThPiP","messageExpiration": "1577862000000"};
  3. BASE64 encode clear-text paymentData object and send it as paymentToken.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currencyCode String [3] Numeric ISO 4217 code of the payment currency. If this parameter is not specified, it is considered to be equal to the default currency code.
Mandatory

returnUrl String [1..512] The address to which the user will be redirected if the payment is successful. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

failUrl String [1..512] The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

merchant String Merchant login in the payment gateway.
Optional

features String Features of the order. As an example, below are the possible values.
  • VERIFY - If you specify this value in the order registration request, cardholder will be verified however they will not be charged any amount, so in this case amount parameter can be 0. Verification allows to make sure that a payment card is used by its legitimate owner, and further you can charge them without authentication (CVC, 3D-Secure). Even if some amount is passed in the request, the customer will not be charged if VERIFY feature is used. After a successful registration order status is changed to REVERSED. This value can be also used for storing the credential – in this case, the clientId parameter must be passed as well. Read more here.
  • FORCE_TDS - Force 3-D Secure payment. If a payment card does not support 3-D Secure, the transaction will fail.
  • FORCE_SSL - Force SSL payment (without 3-D Secure).
  • FORCE_FULL_TDS - After 3-D Secure authentication, PaRes status must be Y, which guarantees successful user authentication. Otherwise, the transaction will fail.
  • FORCE_CREATE_BINDING - passing this feature in the order registration request forcefully stores the credential. This functionality must be enabled by Merchant level permission in the Gateway. This value cannot be passed in a request with an existing bindingId or bindingNotNeeded = true (will cause validation error). When this feature is passed, the clientId parameter must be passed as well. If you pass both FORCE_CREATE_BINDING and VERIFY features, the order will be created for storing the credential ONLY (without payment).
Optional

tii String Transaction initiator indicator. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant). Possible values.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

threeDSProtocolVersion String 3DS protocol version. Possible values are "2.1.0", "2.2.0" for 3DS2.
If threeDSProtocolVersion is not passed in the request, then the default value will be used for 3D Secure authorization (2.1.0 - for 3DS 2).
Optional

externalScaExemptionIndicator String The type of SCA (Strong Customer Authentication) excemption. If this parameter is specified, the transaction will be processed depending on your settings in the payment gateway: either forced SSL operation will be done, or the issuer bank will get the information about SCA excemption and decide to perform operation with or without 3DS authentication (for details, contact our support team). Allowed values:
  • LVP – Low Value Payments transaction. You can consider a transaction as low risk based on the transaction amount, the client's transactions per day or the client's total daily amount.
  • TRA – Transaction Risk Analysis transaction, i.e., the transaction that has passed successful anti-fraud check.

To pass this parameter, you must have sufficient permissions in the payment gateway.
Optional

shippingPayerData Object Object containing customer delivery data. It is used for further 3DS authentication of the client. See nested parameters
Optional

preOrderPayerData Object Object containing pre-order data. It is used for further 3DS authentication of the client. See nested parameters
Optional

orderPayerData Object Object containing data about the order payer. It is used for further 3DS authentication of the client. See nested parameters
Optional

billingAndShippingAddressMatchIndicator A1 Indicator for matching the cardholder's billing address and shipping address. This parameter is used for further 3DS authentication of the customer.
Possible values:
  • Y - the cardholder's billing address and shipping address match;
  • N - cardholder billing address and shipping address do not match
Optional

clientBrowserInfo Object A block with the data about the client's browser that is sent to ACS during the 3DS authentication. To pass this block, you should have a special setting (contact the support team). See nested parameters.

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Description of parameters in shippingPayerData object:

Required Name Type Description
Optional shippingCity ANS...50 The customer's city (from the delivery address)
Optional shippingCountry ANS...50 The customer's country
Optional shippingAddressLine1 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine2 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine3 ANS...50 The customer's primary address (from the shipping address)
Optional shippingPostalCode ANS...16 The customer's zip code for delivery
Optional shippingState ANS...50 Customer's state/region (from delivery address)
Optional shippingMethodIndicator N2 Shipping Method Indicator.
Possible values:
  • 01 - delivery to the cardholder's billing address
  • 02 - delivery to another address verified by Merchant
  • 03 - delivery to an address other than the cardholder's primary (settlement) address
  • 04 - shipment to the store/self-collection (the store address should be specified in the relevant delivery parameters)
  • 05 - Digital distribution (includes online services and e-gift cards)
  • 06 - travel and event tickets that are not deliverable
  • 07 - Other (e.g. games, non-deliverable digital goods, digital subscriptions, etc.)
Optional deliveryTimeframe N2 Product delivery timeframe.
Possible values:
  • 01 - digital distribution
  • 02 - same-day delivery
  • 03 - overnight delivery
  • 04 - delivery within 2 days after payment and later
Optional deliveryEmail ANS...254 Target email address for delivery of digital distribution

Description of parameters in preOrderPayerData object:

Required Name Type Description
Optional preOrderDate ANS8 Expected date when delivery will be available (for pre-ordered purchases), in the format YYYYYYMMDD.
Optional preOrderPurchaseInd N2 Indicator of a customer placing an order for available or future delivery.
Possible values:
  • 01 - delivery available;
  • 02 - future delivery
Optional reorderItemsInd N2 An indicator that the customer is rebooking a previously paid delivery as part of a new order.
Possible values:
  • 01 - order placed for the first time;
  • 02 - repeated order

Description of parameters in orderPayerData object:

Required Name Type Description
Optional homePhone ANS...19 The cardholder's home phone number, with the obligatory "+" symbol
Optional workPhone ANS...19 The cardholder's work phone number, with the obligatory "+" symbol
Optional mobilePhone ANS...19 The cardholder's mobile phone number, with the obligatory "+" symbol

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. This value is possible to pass only if the "Vendor pays common bindings creation is allowed" permission is enabled.
RI Initial Recurrent 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.

Additional parameters that specify the type of created stored credential and are passed in additionalParameters:

Required Name Type Description
Conditional

installments Integer [3] Maximum number of allowed authorizations for installment payments.
Should be specified when creating an installment stored credential.
Conditional

recurringFrequency Integer [2] Maximum number of days between authorizations. Positive integer from 1 to 28.
Should be specified when creating a recurring stored credential.
Conditional

recurringExpiry String [8] The date after which further authorizations should not be performed. Format: YYYYMMDD.
Should be specified when creating a recurring stored credential.

Below are the parameters of the clientBrowserInfo block (data about the client's browser).

Required Name Type Description
Optional userAgent string Browser agent.
Optional OS string Operation system.
Optional OSVersion string Operation system version.
Optional browserAcceptHeader string The Accept header that tells the server what file formats (or MIME-types) the browser accepts.
Optional browserIpAddress string Browser IP address.
Optional browserLanguage string Browser language.
Optional browserTimeZone string Browser time zone.
Optional browserTimeZoneOffset integer The time zone offset in minutes between the user's local time and UTC.
Optional colorDepth string Screen color depth, in bits.
Optional fingerprint string Browser fingerprint - a unique digital identifier of the browser.
Optional isMobile Boolean Possible values: true or false. Flag showing that a mobile device is used.
Optional javaEnabled Boolean Possible values: true or false. Flag showing that java is enabled in the browser.
Optional javascriptEnabled Boolean Possible values: true or false. Flag showing that javascript is enabled in the browser.
Optional plugins string Comma-separated list of plugins the browser uses.
Optional screenHeight integer Screen height, in pixels.
Optional screenWidth integer Screen width, in pixels.
Optional screenPrint string Data about current screen print including resolution, color depth, display metrics.

Example of clientBrowserInfo block:

"clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"10.99.50.37"
    }

If 3DS 2.0 is used, the following parameters should be passed as well:

Required Name Type Description
Conditional

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSVer2FinishUrl String URL where Customer should be redirected after authentication on ACS Server.
Optional

threeDSSDK Boolean Possible values: true or false. Flag showing that payment comes from 3DS SDK.
Optional

threeDSMethodNotificationUrl String URL where notification about authentication on ACS Server should be sent to.

Response parameters

Required Name Type Description
Mandatory

success Boolean 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.
Read here to find out how to get payment status.
Mandatory*

data Object Returns only if the payment is successful.
Mandatory*

error Object This parameter is returned only if the payment failed.

data block contains the following elements.

Required Name Type Description
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Only if additional authentication is used on the issuing bank's ACS

termUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address to which ACS redirects the cardholder after authentication. For details see Redirect to ACS.
Only if additional authentication is used on the issuing bank's ACS

acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
Only if additional authentication is used on the issuing bank's ACS

paReq String [1..255] In a successful response in case of a 3D-Secure payment. PAReq (Payment Authentication Request) - a message that should be sent to ACS together with redirect. This message contains the Base64-encoded data necessary for the cardholder authentication. For details see Redirect to ACS.
The parameter is returned if bindings are used

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.

If 3DS 2.0 protocol is used, the response to the request also includes the following parameters in the data block:

Required Name Type Description
Mandatory

is3DSVer2 Boolean Possible values: true or false. Flag showing that payment uses 3DS 2.0.
Mandatory

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSMethodUrl String URL of ACS Server for gathering browser data.
Optional

threeDSMethodUrlServer String URL of 3DS Server for gathering browser data to be included in the AReq (Authentication Request) from 3DS Server to ACS Server.
Optional

threeDSMethodDataPacked String Base-64-encoded data of CReq (Challenge Response) to be sent to ACS Server.
Optional

threeDSMethodURLServerDirect String URL of 3dsmethod.do for executing the 3DS method on 3DS Server via Payment Gateway (subject to respective Merchant-level permission).

Parameters in error block:

Required Name Type Description
Mandatory

code Integer [1..3] Code as an information parameter stating an error occurred.
Mandatory

message String [1..512] Information parameter that is an error description to be displayed to the user. The parameter may vary, so it should not be hardcoded.
Mandatory

description String [1..598] A detailed technical explanation of the error - the contents of this parameter should not to be displayed to the customer.

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/payment/google/paymentDirect.do \
--header 'Content-Type: application/json' \
--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"
}'

Response examples

{
  "success": true,
  "data": {
    "orderId": "12312312123"
  }
}

Samsung Pay order registration

The /samsung/payment.do request is used to register and pay for the order in Samsung Pay. See Connection coordinates. This request is only used when paying from the mobile application.

Below an example of a request for a payment through Samsung Pay is given.

Request parameters

Required Name Type Description
Mandatory

merchant String Merchant login in the payment gateway.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

additionalParameters Object Additional parameters of the order that are stored in the merchant personal area for the subsequent viewing. Each new pair of a parameter name and its value must be separated by a comma. Below is a usage example.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
When storing a credential, this tag can contain parameters that specify the type of the stored credential. See the list of parameters.
Optional

preAuth Boolean Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available:
  • true - two-phase payments enabled;
  • false - one-phase payments enabled (money are charged right away).
If the parameter is missing, one-phase payment is made.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

tii String Transaction initiator indicator. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant). Possible values.
Mandatory

paymentToken String [1..8192] The contents of the 3ds.data parameter from the response received from Samsung Pay.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

currencyCode String [3] Numeric ISO 4217 code of the payment currency. If this parameter is not specified, it is considered to be equal to the default currency code.
Optional

threeDSProtocolVersion String 3DS protocol version. Possible values are "2.1.0", "2.2.0" for 3DS2.
If threeDSProtocolVersion is not passed in the request, then the default value will be used for 3D Secure authorization (2.1.0 - for 3DS 2).

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. This value is possible to pass only if the "Vendor pays common bindings creation is allowed" permission is enabled.
RI Initial Recurrent 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.

Additional parameters that specify the type of created stored credential and are passed in additionalParameters:

Required Name Type Description
Conditional

installments Integer [3] Maximum number of allowed authorizations for installment payments.
Should be specified when creating an installment stored credential.
Conditional

recurringFrequency Integer [2] Maximum number of days between authorizations. Positive integer from 1 to 28.
Should be specified when creating a recurring stored credential.
Conditional

recurringExpiry String [8] The date after which further authorizations should not be performed. Format: YYYYMMDD.
Should be specified when creating a recurring stored credential.

Response parameters

Required Name Type Description
Mandatory

success Boolean 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.
Read here to find out how to get payment status.
Conditional data Object This parameter is returned only if the payment is processed successfully. See the description below.
Conditional error Object This parameter is returned only if the payment failed. See the description below.

data block contains the following elements.

Required Name Type Description
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.

error block contains the following elements.

Required Name Type Description
Mandatory

code Integer [1..3] Code as an information parameter stating an error occurred.
Mandatory

message String [1..512] Information parameter that is an error description to be displayed to the user. The parameter may vary, so it should not be hardcoded.
Mandatory

description String [1..598] A detailed technical explanation of the error - the contents of this parameter should not to be displayed to the customer.

Examples

Request example

curl --location --request POST 'https://dev.bpcbt.com/payment/samsung/paymentDirect.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchant": "sandbox_merchant_test",
    "orderNumber": "1218637308",
    "language": "en",
    "preAuth": true,
    "description": "Test description",
    "additionalParameters": {
        "firstParamName": "firstParamValue",
        "secondParamName": "secondParamValue"
    },
    "paymentToken": "ew0KICB7DQoJICA...0KICB9DQp9",
    "ip": "127.0.0.1"
}'

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. It is used to register and pay for the order.

This request can be used for integrations that involve payment data decoding on Merchant side.

Request parameters

Required Name Type Description
Mandatory

merchant String Merchant login in the payment gateway.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

feeInput String Fee amount in minimum currency units. Must be enabled by respective Merchant-level permission in the Gateway.
Optional

additionalParameters Object Additional parameters of the order that are stored in the merchant personal area for the subsequent viewing. Each new pair of a parameter name and its value must be separated by a comma. Below is a usage example.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
When storing a credential, this tag can contain parameters that specify the type of the stored credential. See the list of parameters.
Optional

preAuth Boolean Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available:
  • true - two-phase payments enabled;
  • false - one-phase payments enabled (money are charged right away).
If the parameter is missing, one-phase payment is made.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Mandatory

paymentToken String [1..8192] A token obtained from Samsung Pay and encoded in Base64. Example:
{"amount": "100", "currency_code": "USD", "utc": "1490687350988", "eci_indicator": "07", "tokenPAN": "5599014702854883", "tokenPanExpiration": "0420", "cryptogram": "ACF9prZs2wsTAAGysReaAoACFA=="}
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

tii String Transaction initiator indicator. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant). Possible values.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

threeDSProtocolVersion String 3DS protocol version. Possible values are "2.1.0", "2.2.0" for 3DS2.
If threeDSProtocolVersion is not passed in the request, then the default value will be used for 3D Secure authorization (2.1.0 - for 3DS 2).
Optional

externalScaExemptionIndicator String The type of SCA (Strong Customer Authentication) excemption. If this parameter is specified, the transaction will be processed depending on your settings in the payment gateway: either forced SSL operation will be done, or the issuer bank will get the information about SCA excemption and decide to perform operation with or without 3DS authentication (for details, contact our support team). Allowed values:
  • LVP – Low Value Payments transaction. You can consider a transaction as low risk based on the transaction amount, the client's transactions per day or the client's total daily amount.
  • TRA – Transaction Risk Analysis transaction, i.e., the transaction that has passed successful anti-fraud check.

To pass this parameter, you must have sufficient permissions in the payment gateway.
Optional

shippingPayerData Object Object containing customer delivery data. It is used for further 3DS authentication of the client. See nested parameters
Optional

preOrderPayerData Object Object containing pre-order data. It is used for further 3DS authentication of the client. See nested parameters
Optional

orderPayerData Object Object containing data about the order payer. It is used for further 3DS authentication of the client. See nested parameters
Optional

billingAndShippingAddressMatchIndicator A1 Indicator for matching the cardholder's billing address and shipping address. This parameter is used for further 3DS authentication of the customer.
Possible values:
  • Y - the cardholder's billing address and shipping address match;
  • N - cardholder billing address and shipping address do not match

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Description of parameters in shippingPayerData object:

Required Name Type Description
Optional shippingCity ANS...50 The customer's city (from the delivery address)
Optional shippingCountry ANS...50 The customer's country
Optional shippingAddressLine1 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine2 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine3 ANS...50 The customer's primary address (from the shipping address)
Optional shippingPostalCode ANS...16 The customer's zip code for delivery
Optional shippingState ANS...50 Customer's state/region (from delivery address)
Optional shippingMethodIndicator N2 Shipping Method Indicator.
Possible values:
  • 01 - delivery to the cardholder's billing address
  • 02 - delivery to another address verified by Merchant
  • 03 - delivery to an address other than the cardholder's primary (settlement) address
  • 04 - shipment to the store/self-collection (the store address should be specified in the relevant delivery parameters)
  • 05 - Digital distribution (includes online services and e-gift cards)
  • 06 - travel and event tickets that are not deliverable
  • 07 - Other (e.g. games, non-deliverable digital goods, digital subscriptions, etc.)
Optional deliveryTimeframe N2 Product delivery timeframe.
Possible values:
  • 01 - digital distribution
  • 02 - same-day delivery
  • 03 - overnight delivery
  • 04 - delivery within 2 days after payment and later
Optional deliveryEmail ANS...254 Target email address for delivery of digital distribution

Description of parameters in preOrderPayerData object:

Required Name Type Description
Optional preOrderDate ANS8 Expected date when delivery will be available (for pre-ordered purchases), in the format YYYYYYMMDD.
Optional preOrderPurchaseInd N2 Indicator of a customer placing an order for available or future delivery.
Possible values:
  • 01 - delivery available;
  • 02 - future delivery
Optional reorderItemsInd N2 An indicator that the customer is rebooking a previously paid delivery as part of a new order.
Possible values:
  • 01 - order placed for the first time;
  • 02 - repeated order

Description of parameters in orderPayerData object:

Required Name Type Description
Optional homePhone ANS...19 The cardholder's home phone number, with the obligatory "+" symbol
Optional workPhone ANS...19 The cardholder's work phone number, with the obligatory "+" symbol
Optional mobilePhone ANS...19 The cardholder's mobile phone number, with the obligatory "+" symbol

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. This value is possible to pass only if the "Vendor pays common bindings creation is allowed" permission is enabled.
RI Initial Recurrent 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.

Additional parameters that specify the type of created stored credential and are passed in additionalParameters:

Required Name Type Description
Conditional

installments Integer [3] Maximum number of allowed authorizations for installment payments.
Should be specified when creating an installment stored credential.
Conditional

recurringFrequency Integer [2] Maximum number of days between authorizations. Positive integer from 1 to 28.
Should be specified when creating a recurring stored credential.
Conditional

recurringExpiry String [8] The date after which further authorizations should not be performed. Format: YYYYMMDD.
Should be specified when creating a recurring stored credential.

Response parameters

Required Name Type Description
Mandatory

success Boolean 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.
Read here to find out how to get payment status.
Mandatory*

data Object Returns only if the payment is successful.
Mandatory*

error Object This parameter is returned only if the payment failed.

data block contains the following elements.

Required Name Type Description
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
The parameter is returned if stored credentials are used

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.

Parameters in error block:

Required Name Type Description
Mandatory

code Integer [1..3] Code as an information parameter stating an error occurred.
Mandatory

message String [1..512] Information parameter that is an error description to be displayed to the user. The parameter may vary, so it should not be hardcoded.
Mandatory

description String [1..598] A detailed technical explanation of the error - the contents of this parameter should not to be displayed to the customer.

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/payment/samsung/paymentDirect.do \
--header 'Content-Type: application/json' \
--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
}

Payment status

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

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

Another way to check whether the payment was successful or not is to refer to the callback notification.

Order status

The request used to get the order status is getOrderStatusExtended.do.
Learn more about Refusal reasons.

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Mandatory

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Optional

token String [1..256] 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.
Mandatory

orderId String Order number in the payment gateway. Unique within the payment gateway.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each merchant.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

merchantLogin String [1..255] To get the order status of a specific merchant instead of the current user, specify the merchant's API account login.
Can be used only if you have the permission to see the transactions of other merchants or if the specified merchant is your child merchant.

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 Required Name Type Description
All Optional

errorCode String [1..2] 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.
All Optional

errorMessage String [1..512] 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.
All Conditional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each merchant registered in the payment gateway . If the Order number is generated on the Payment Gateway side, this parameter is not mandatory.
All Optional

orderStatus Integer The value of this parameter specifies the status of the order in the payment gateway. It is missing if the order has not been found. Below is the list of available values:
  • 0 - order was registered but not paid;
  • 1 - order was authorized only and wasn't captured yet (for two-phase payments);
  • 2 - order was authorized and captured;
  • 3 - authorization canceled;
  • 4 - transaction was refunded;
  • 5 - access control server of the issuing bank initiated authorization procedure;
  • 6 - authorization declined;
  • 7 - pending order payment;
  • 8 - intermediate completion for multiple partial completion.
All Mandatory

actionCode Integer Response code from the processing bank. See the list of action codes here.
All Mandatory

actionCodeDescription String [1..512] actionCode description returned from the processing bank.
All Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
All Optional

currency String [3] ISO 4217 encoded currency key. If not specified, the default value is used.
All Mandatory

date String Order registration date (UNIX time).
All Optional

depositeddate String Order payment date (UNIX time).
All Optional

orderDescription String [1..600] Order description passed to the payment gateway during the registration.
All Mandatory

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
09+ Optional

authRefNum String [1..24] Reference number of the payment authorization that has been assigned to it upon its registration.
01+ From 27 mandatory. Optional

refundedDate Integer Refunded date and time.
12+ Optional

reverseddate Integer Reversed date and time.
12+ Mandatory

paymentWay String Payment method (a payment with entering card data, a stored-credential transaction, etc.). Find more possible values of the parameter.
19+ Optional

avsCode String A code of the AVS verification response (checking the address and postal code of the cardholder). Possible values:
  • A – postal code and address are the same.
  • B – address matches, postal code doesn't match.
  • C - postal code matches, address doesn't match.
  • D - postal code and address don't match.
  • E - data validation is requested, but the result is unsuccessful.
  • F - invalid format of the AVS/AVV verification request.
19+ Optional

refund Boolean Whether the funds was forcibly returned to the buyer by the bank. The possible values are:
  • true - funds were reversed;
  • false - funds were not reversed.
06+ Optional

authDateTime String Authorization date and time, shown as the amount of milliseconds since 00:00 January 1, 1970 GMT (UNIX time).
01+ Optional

terminalId String [1..10] Terminal identifier in the system that processes the payment.

Values of paymentWay:

refunds block contains information on refunds. Used for version 05 and later. Present only if there are refunds in the order.

Version Required Name Type Description
05+ Optional

date String Order refund date
21+ Optional

externalRefundId String [1..30] The identifier of the refund. When attempting a refund, externalRefundId is checked: if it exists, a successful response with refund data is returned, if not, a refund is held.
From 05 to 25 for NOT card payments. 26+ for all payment methods. Optional

approvalCode String [6] IPS authorization code. This field has a fixed length (six symbols) and can contain digits and Latin letters.
05+ Optional

actionCode Integer Response code from the processing bank. See the list of action codes here.
05+ Optional

referenceNumber String [12] Unique identification number that is assigned to the operation on its completion.
05+ Optional

amount String [0..12] Refund amount in minor currency units. If two-phase payment is used, the refund amount must be less or equal to the total deposited amount. If you specify amount=0 in the request, the entire amount of the order will be refunded.

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 Required Name Type Description
All Optional

name String [1..255] Name of an additional parameter.
All Optional

value String [1..1024] Value of an additional parameter - up to 1024 characters.

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 Required Name Type Description
All Optional

name String [1..255] Name of an additional parameter.
All Optional

value String [1..1024] Value of an additional parameter - up to 1024 characters.

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 Required Name Type Description
All Optional

name String [1..255] Name of an additional parameter.
All Optional

value String [1..1024] Value of an additional parameter - up to 1024 characters.

cardAuthInfo element contains a structure consisting of secureAuthInfo element list and the following parameters.

Version Required Name Type Description
01+ Optional

maskedPan String [1..19] Masked number of the card used for the payment. This parameter is to be specified only after the order has been paid.
01+ Optional

expiration Integer Card expiration in the following format: YYYYMM. This parameter is to be specified only after the order has been paid.
01+ Optional

cardholdername String [1..26] Cardholder's name in Latin characters. This parameter is passed only after an order is paid.
01+ Optional

approvalCode String [6] IPS authorization code. This field has a fixed length (six symbols) and can contain digits and Latin letters.
08+ Mandatory

paymentSystem String Payment system name. The following variants are possible:
  • VISA;
  • MASTERCARD;
  • AMEX;
  • JCB;
  • CUP;
08+ Mandatory

product String [1..255] Additional details on corporate cards. These details are filled in by the technical support service. If such details are missing, an empty value is returned.
17+ Mandatory

productCategory String Additional details on category of corporate cards. These details are filled in by the technical support service. If such details are missing, an empty value is returned. Possible values: DEBIT, CREDIT, PREPAID, NON_MASTERCARD, CHARGE, DIFFERED_DEBIT.
01+ Optional

corporateCard A..5 Indication of whether the card is a corporate card. Possible values: false - is not a corporate card, true - is a corporate card. May return an empty value, which means that the value was not found.

secureAuthInfo element consists of the following elements (cavv and xid parameters are included into the threeDSInfo element).

Version Required Name Type Description
01+ Optional

eci Integer [1..4] 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.
01+ Optional

authTypeIndicator String 3DS authentication type. depending on ECI value.
Allowed values:
  • 0 - SSL (SSL authentication)
  • 1 - THREE_DS1_FULL (3DS 1 authentication)
  • 2 - THREE_DS1_ATTEMPT (3DS 1 authentication attempt)
  • 3 - THREE_DS2_FULL (Strong customer authentication (SCA))
  • 4 - THREE_DS2_FRICTIONLESS (Risk based authentication(RBA))
  • 5 - THREE_DS2_ATTEMPT (3DS 2 authentication attempt)
01+ Optional

cavv String [0..200] Cardholder authentication value. The indicator is specified only after an order is paid and if the corresponding permission is enabled.
01+ Optional

xid String [1..80] Electronic commerce indicator of the transaction. The indicator is specified only after an order has been paid and in case the corresponding permission is present.
30+ Optional

threeDSProtocolVersion String 3DS protocol version. Possible values are "2.1.0", "2.2.0" for 3DS2.
If threeDSProtocolVersion is not passed in the request, then the default value will be used for 3D Secure authorization (2.1.0 - for 3DS 2).
30+ Optional

rreqTransStatus String [1] Transaction status from the request for passing user authentication results from ACS (RReq). Passed when 3DS 2.0 is used.
30+ Optional

aresTransStatus String Transaction status from the ACS response to the authentication request (ARes). Passed when 3DS 2.0 is used.

bindingInfo element contains the following parameters.

Version Mandatory Name Type Description
All Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
All Optional

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
02+ Optional

authDateTime String Authorization date and time, shown as the amount of milliseconds since 00:00 January 1, 1970 GMT (UNIX time).
02+ Optional

authRefNum String [1..24] Reference number of the payment authorization that has been assigned to it upon its registration.
02+ Optional

terminalId String [1..10] Terminal identifier in the system that processes the payment.

paymentAmountInfo element contains the following parameters.

Version Mandatory Name Type Description
03+ Optional

approvedAmount Integer [0..12] Amount in minimum currency units (e.g. cents) that was put on hold on buyer's account. Used in two-phase payments only.
03+ Optional

depositedAmount Integer [1..12] Charged amount in minimum currency units (e.g., in cents).
03+ Optional

refundedAmount Integer [1..12] Refunded amount in minimum currency units.
03+ Optional

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 element contains the following parameters.

Version Required Name Type Description
03+ Optional

bankName String [1..50] Issuing bank name.
03+ Optional

bankCountryCode String Country code of the issuing bank.
03+ Optional

bankCountryName String [1..160] Country of the issuing bank.

payerData element contains the following parameters.

Version Required Name Type Description
13+ Optional

email String The payer's email address.
13+ Optional

phone String Customer's phone number. It is always necessary to specify the country code, but you can specify or omit the + sign. Thus, the following options are valid:
  • +449998887766;
  • 449998887766. 7 to 15 digits long.
13+ Optional

postAddress String [1..255] Delivery address.

pluginInfo element (which is JSON object) is present in response if payment was made through payment plugin (payment plugin). Contains the following parameters.

Version Required Name Type Description
28+ Optional

name String Unique name of the payment plugin.
28+ Optional

params Object Parameters for a specific payment method, must be passed as follows {"param":"value","param2":"value2"}.

Description of parameters in orderBundle object:

Required Name Type Description
Optional

orderCreationDate String Order creation date in the following format: YYYY-MM-DDTHH:MM:SS.
Optional

customerDetails Object Block containing customer attributes. The description of the tag attributes is given below.
Optional

cartItems Object Object containing cart items attributes. The description of nested elements is given below.

Description of parameters in customerDetails object:

Required Name Type Description
Conditional

email String Customer's email address. Multiple emails can be passed as comma-separated values.
Either of email or phone must be passed.
Conditional

phone String Customer's phone number. It is always necessary to specify the country code, but you can specify or omit the + sign. Thus, the following options are valid:
  • +449998887766;
  • 449998887766. 7 to 15 digits long.
Optional

contact String [0..40] Customer's preferred way of communication.
Optional

fullName String [1..100] Payer's full name.
Optional

passport Integer Customer's passport serial number in the following format: 2222888888.
Optional

deliveryInfo Object Object containing delivery address attributes. The description of the nested elements is given below.

Description of parameters in deliveryInfo object.

Required Name Type Description
Optional

deliveryType String [1..20] Delivery method.
Mandatory

country String Two letter code of the country of delivery.
Mandatory

city String [0..40] City of destination.
Mandatory

postAddress String [1..255] Delivery address.

Description of parameters in cartItems object.

Required Name Type Description
Mandatory

items Object An element of the array containing cart item attributes. The description of the nested elements is given below.

Description of parameters in quantity object.

Required Name Type Description
Mandatory

value String Number of items in one positionId. Use a decimal point as a separator in fractions.
Mandatory

measure String [1..20] The unit of measurement for the quantity of item instances.

Description of parameters in itemDetails object.

Required Name Type Description
Optional

itemDetailsParams Object Parameter describing additional information regarding a line item. The description of the nested elements is given below.

Description of parameters in discount object.

Required Name Type Description
Mandatory

discountType String [1..20] Type of discount applicable to an item.
Mandatory

discountValue Integer [0..20] Value of the item discount.

Description of parameters in agentInterest object:

Required Name Type Description
Mandatory

interestType String [1..20] Agent fee type.
Mandatory

interestValue Integer [1..20] Agent fee value.

Examples

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/getOrderStatusExtended.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --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"
  }
}

Order management

Deposit order

To complete a pre-authorized order use deposit.do request.

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Mandatory

amount String [0..12] Payment amount in minor currency units. The deposit amount must match the total of amounts of all deposited items. If you specify amount=0 in the request, the entire amount of the order will be deposited.
Optional

depositItems Object Object containing cart items attributes. Below is the description of the contained attributes.
Optional

orderBundle Object Object containing cart of items. The description of the nested elements is given below.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.

Description of parameters in deposititems object.

Required Name Type Description
Mandatory

items Object An element of the array containing cart item attributes. The description of the nested elements is given below.

Description of parameters in items object.

Required Name Type Description
Mandatory

positionId Integer [1..12] Unique product identifier in the cart.
Mandatory

name String [1..255] Name or the description of an item in any format.
Optional

itemDetails Object Object containing the parameters describing an item. The description of the nested elements is given below.
Mandatory

quantity Object Element describing the total of items of one positionId and its unit of measurement. The description of the nested elements is given below.
Optional

itemAmount Integer [1..12] The total cost of all instances of one positionId specified in minor denomination of the currency. itemAmount must be passed only if the itemPrice parameter has not been passed. Otherwise passing of itemAmount is not required. If both parameters itemPrice and itemAmount are passed in the request, then itemAmount shall be equal itemPrice * quantity, otherwise the request will return an error.
Optional

itemPrice Integer [1..18] Total cost of instance of one positionId specified in minor currency units.
Optional

itemCurrency Integer ISO 4217 currency code. If the parameter is not specified, it is considered to be equal to the Order currency.
Mandatory

itemCode String [1..100] Number (identifier) of an item in the store system.
Optional

discount Object Object containing item discount attributes. The description of the nested elements is given below.
Optional

agentInterest Object Object containing attributes of the description of an agent fee for the sale of goods. The description of the nested elements is given below.

Description of parameters in itemDetails object.

Required Name Type Description
Optional

itemDetailsParams Object Parameter describing additional information regarding a line item. The description of the nested elements is given below.

Description of parameters in quantity object.

Required Name Type Description
Mandatory

value String Number of items in one positionId. Use a decimal point as a separator in fractions.
Mandatory

measure String [1..20] The unit of measurement for the quantity of item instances.

Description of parameters in discount object.

Required Name Type Description
Mandatory

discountType String [1..20] Type of discount applicable to an item.
Mandatory

discountValue Integer [0..20] Value of the item discount.

Description of parameters in agentInterest object:

Required Name Type Description
Mandatory

interestType String [1..20] Agent fee type.
Mandatory

interestValue Integer [1..20] Agent fee value.

Description of parameters in orderBundle object:

Required Name Type Description
Optional

orderCreationDate String Order creation date in the following format: YYYY-MM-DDTHH:MM:SS.
Optional

customerDetails Object Block containing customer attributes. The description of the tag attributes is given below.
Optional

cartItems Object Object containing cart items attributes. The description of nested elements is given below.

Description of parameters in cartItems object.

Required Name Type Description
Mandatory

items Object An element of the array containing cart item attributes. The description of the nested elements is given below.

Description of parameters in items object.

Required Name Type Description
Mandatory

positionId Integer [1..12] Unique product identifier in the cart.
Mandatory

name String [1..255] Name or the description of an item in any format.
Optional

itemDetails Object Object containing the parameters describing an item. The description of the nested elements is given below.
Mandatory

quantity Object Element describing the total of items of one positionId and its unit of measurement. The description of the nested elements is given below.
Optional

itemAmount Integer [1..12] The total cost of all instances of one positionId specified in minor denomination of the currency. itemAmount must be passed only if the itemPrice parameter has not been passed. Otherwise passing of itemAmount is not required. If both parameters itemPrice and itemAmount are passed in the request, then itemAmount shall be equal itemPrice * quantity, otherwise the request will return an error.
Optional

itemPrice Integer [1..18] Total cost of instance of one positionId specified in minor currency units.
Optional

itemCurrency Integer ISO 4217 currency code. If the parameter is not specified, it is considered to be equal to the Order currency.
Mandatory

itemCode String [1..100] Number (identifier) of an item in the store system.
Optional

discount Object Object containing item discount attributes. The description of the nested elements is given below.
Optional

agentInterest Object Object containing attributes of the description of an agent fee for the sale of goods. The description of the nested elements is given below.

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/deposit.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data currency=978\
  --data amount=2000 \
  --data orderId=01492437-d2fb-77fa-8db7-9e2900a7d8c0 \
  --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

Required Name Type Description
Mandatory

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

jsonParams String Fields for storing additional data, must be passed as follows {"param":"value","param2":"value2"}.
Optional

merchantLogin String [1..255] To reverse an order paymenent on behalf of another merchant, specify the merchant's API account login in this parameter.
Can be used only if you have the permission to see the transactions of other merchants or if the specified merchant is your child merchant.
Optional

amount String [0..12] Reversal amount in minor currency units. If two-phase payment is used, the reversal amount must be less or equal to the total preauthorized amount.
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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 \
  --url https://dev.bpcbt.com/payment/rest/reverse.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data currency=978\
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --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

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Mandatory

amount String [0..12] Refund amount in minor currency units. If two-phase payment is used, the refund amount must be less or equal to the total deposited amount. If you specify amount=0 in the request, the entire amount of the order will be refunded.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

jsonParams String Fields for storing additional data, must be passed as follows {"param":"value","param2":"value2"}.
Optional

expectedDepositedAmount Integer [1..12] The parameter serves as a determination that the request is repeated. If the parameter is passed, its value is compared to the current depositedAmount value in the order. The operation will be performed only if the values match. If two returns arrive with the same expectedDepositedAmount, only one return will be executed. This return will change the depositedAmount value and then the second return will be rejected.
Optional

externalRefundId String [1..30] The identifier of the refund. When attempting a refund, externalRefundId is checked: if it exists, a successful response with refund data is returned, if not, a refund is held.
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/refund.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data currency=978\
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data amount=2000 \
  --data language=en

Response example

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Instant Refund

Use instantRefund.do request to make a refund for an order. Upon this request, the funds for the order are to be returned to the payer.

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
If you specify amount=0, the refund will be made for the total order amount.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Conditional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each merchant registered in the Payment Gateway.
If the order number is generated on the merchant's side, this parameter is not mandatory.
Optional

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Conditional

seToken String Encrypted card data entered by the client on the merchant's side. Must be passed if used instead of the card data: pan, cvc, expiry, and cardHolderName.
Valid combinations of seToken:
  • timestamp/uuid/PAN/CVV/EXPDATE
  • timestamp/uuid/PAN//EXPDATE
  • timestamp/uuid//CVV///bindingId
  • timestamp/uuid/////bindingId

MdOrder should not be present in seToken. If bindingId is specified, then empty value //bindingId is specified instead of mdOrder.
Click here more information about seToken generation.
Conditional

pan String [1..19] Masked number of the card. Mandatory, if neither seToken nor bindingId is passed.
Conditional

cvc Integer CVC/CVV2 code on the back of a payment card. Mandatory if the merchant does not have a permission to pay without CVC. It is also mandatory if neither seToken nor bindingId is passed.
Conditional

expiry Integer Card expiration in the following format: YYYYMM. Mandatory, if neither seToken nor bindingId is passed.
Conditional

cardHolderName String [1..26] Cardholder's name in Latin characters. Mandatory, if neither seToken nor bindingId is passed.
Optional

jsonParams String Fields for storing additional data, must be passed as follows {"param":"value","param2":"value2"}.

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Optional

orderStatus Object A block with the information about the order status. See nested parameters.

Below are the parameters of the orderStatus block.

Required Name Type Description
Optional

approvalCode String [6] IPS authorization code. This field has a fixed length (six symbols) and can contain digits and Latin letters.
Optional

rrn Integer [1..12] Reference Retrieval Number - transaction ID assigned by Acquiring Bank.
Optional

ErrorCode Integer [1..2] 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.
Optional

ErrorMessage String [1..512] 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

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/instantRefund.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderNumber=1218637308 \
  --data pan=4000001111111118 \
  --data cvc=123 \
  --data expiry=203012 \
  --data cardHolderName=TEST CARDHOLDER \
  --data language=en

Response examples

Successful instant refund and successful receipt of order status

{
  "errorCode": "0",
  "errorMessage": "Success",
  "orderId": "04899a8a-3bfd-7ceb-ac10-9e6909017350",
  "orderStatus": {
    "ErrorCode": "7",
    "ErrorMessage": "System error",
  }
}

Successful instant refund and unsuccessful receipt of order status

{
  "errorCode": "0",
  "errorMessage": "Success",
  "orderId": "04899a8a-3bfd-7ceb-ac10-9e6909017350",
  "orderStatus": {
    "ErrorCode": "7",
    "ErrorMessage": "System error",
  }
}

Unsuccessful instant refund (for example, validation error)

{
  "errorCode": "5",
  "errorMessage": "Access denied"
}

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

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Optional

merchantLogin String [1..255] To cancel an order on behalf of another merchant, specify the merchant's API account login in this parameter.
Can be used only if you have the permission to see the transactions of other merchants or if the specified merchant is your child merchant.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Mandatory

errorMessage String [1..512] 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

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/decline.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=8cf0409e-857e-7f95-8ab1-b6810009d884 \
  --data orderNumber=12345678 \
  --data merchantLogin=merch_test418 \
  --data language=en

Response example

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Stored credential

The below API requests allow managing stored credential transactions. Such transactions are used when a cardholder authorizes a merchant to store the payment credentials for further payments. Learn more about storing a credential here.

Stored-credential payment

The request used to make a stored-credential payment is paymentOrderBinding.do.

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

mdOrder String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Mandatory

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

cvc Integer This parameter is mandatory if permission Can process payments without confirmation of CVC is not enabled.
Optional

threeDSSDK Boolean Possible values: true or false. Flag showing that payment comes from 3DS SDK.
Mandatory

tii String Transaction initiator indicator. A parameter indicating what type of operation will be carried out by the initiator (Customer or Merchant). Possible values
Optional

jsonParams Object 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
  • 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).
Optional

threeDSProtocolVersion String 3DS protocol version. Possible values are "2.1.0", "2.2.0" for 3DS2.
If threeDSProtocolVersion is not passed in the request, then the default value will be used for 3D Secure authorization (2.1.0 - for 3DS 2).
Optional

externalScaExemptionIndicator String The type of SCA (Strong Customer Authentication) excemption. If this parameter is specified, the transaction will be processed depending on your settings in the payment gateway: either forced SSL operation will be done, or the issuer bank will get the information about SCA excemption and decide to perform operation with or without 3DS authentication (for details, contact our support team). Allowed values:
  • LVP – Low Value Payments transaction. You can consider a transaction as low risk based on the transaction amount, the client's transactions per day or the client's total daily amount.
  • TRA – Transaction Risk Analysis transaction, i.e., the transaction that has passed successful anti-fraud check.

To pass this parameter, you must have sufficient permissions in the payment gateway.
Conditional

seToken String Encrypted card data that replaces $PAN, $CVC, and $EXPIRY (or YYYY,MM) parameters. Must be passed if used instead of the card data.
The mandatory parameters for seToken string are timestamp, UUID, bindingId, MDORDER. Click here for more information about seToken generation.
Optional

acsInIFrame Boolean Flag indicating that an iFrame version of the finish URL will be returned. Possible values are true or false. To enable this feature please contact support.
Optional

clientBrowserInfo Object A block with the data about the client's browser that is sent to ACS during the 3DS authentication. To pass this block, you should have a special setting (contact the support team). See nested parameters.

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.
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
RI Initial Recurrent CIT Initiating Customer Entered by Customer Yes An e-commerce transaction, credential is stored.
R Recurrent MIT Subsequent Merchant No manual entry, Merchant passes the data No A recurrent transaction that uses a stored credential.
II Initial Installment CIT Initiating Customer Entered by Customer Yes An e-commerce transaction, credential is stored.
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 clientBrowserInfo block (data about the client's browser).

Required Name Type Description
Optional userAgent string Browser agent.
Optional OS string Operation system.
Optional OSVersion string Operation system version.
Optional browserAcceptHeader string The Accept header that tells the server what file formats (or MIME-types) the browser accepts.
Optional browserIpAddress string Browser IP address.
Optional browserLanguage string Browser language.
Optional browserTimeZone string Browser time zone.
Optional browserTimeZoneOffset integer The time zone offset in minutes between the user's local time and UTC.
Optional colorDepth string Screen color depth, in bits.
Optional fingerprint string Browser fingerprint - a unique digital identifier of the browser.
Optional isMobile Boolean Possible values: true or false. Flag showing that a mobile device is used.
Optional javaEnabled Boolean Possible values: true or false. Flag showing that java is enabled in the browser.
Optional javascriptEnabled Boolean Possible values: true or false. Flag showing that javascript is enabled in the browser.
Optional plugins string Comma-separated list of plugins the browser uses.
Optional screenHeight integer Screen height, in pixels.
Optional screenWidth integer Screen width, in pixels.
Optional screenPrint string Data about current screen print including resolution, color depth, display metrics.

Example of clientBrowserInfo block:

"clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"10.99.50.37"
    }

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

redirect String [1..512] This parameter is returned if the payment is successful and that payment did not include check for 3-D Secure involvement. Merchants can use it if they want to redirect the user to the payment gateway page. If they have their own response page then this value can be ignored.
Optional

info String If response is successful. Result of a payment attempt. Below are the possible values.
  • Your payment has been processed, redirecting...
  • Operation declined. Check the entered data and that there are enough funds on the card and repeat the operation. Redirecting...
  • Sorry, payment cannot be completed. Redirecting...
  • Operation declined. Contact the merchant. Redirecting...
  • Operation declined. Contact the bank that issued the card. Redirecting...
  • Impossible operation. Cardholder authentication completed unsuccessfully. Redirecting...
  • No connection with bank. Try again later. Redirecting...
  • Input time expired. Redirecting...
  • No response from bank received. Try again later. Redirecting...
Optional

error String Error message (if response returned an error) in the language passed in the request.
Optional

processingErrorType String Type of processing error. Passed if error occurs on the processing end, and not in the Payment Gateway, while payments attemtps are not exceeded and there's been no redirect to finish page yet.
Optional

displayErrorMessage String Displayed error message.
Optional *

errorTypeName String Parameter needed by the front-end page to define the error type. Mandatory for unsuccessful payments.
Optional

acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
Optional

paReq String [1..255] In a successful response in case of a 3D-Secure payment. PAReq (Payment Authentication Request) - a message that should be sent to ACS together with redirect. This message contains the Base64-encoded data necessary for the cardholder authentication. For details see Redirect to ACS.
Optional

termUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address to which ACS redirects the cardholder after authentication. For details see Redirect to ACS.
Optional

acsInIFrame Boolean Flag indicating that an iFrame version of the finish URL will be returned. Possible values are true or false. To enable this feature please contact support.

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 cvc=123 \
  --data tii=F \
  --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

Required Name Type Description
Mandatory

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Mandatory

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Mandatory

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Optional

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Optional

bindingType String The type of stored credential that is expected in reponse (if not specified, all types are returned). Possible values:
  • C – common stored credential.
  • R – recurrent stored credential.
  • I - installment stored credential.
Optional

showExpired Boolean true/false parameter defining whether to show stored credentials with expired cards. Default is false.
Optional

merchantLogin String [1..255] To get the list of client's stored credentials of another merchant, specify the merchant's API account login in this parameter.
Can be used only if you have the permission to see the transactions of other merchants or if the specified merchant is your child merchant. Both you and the specified merchant should have the permission to work with stored credentials.

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

bindings Object Element with blocks that contain parameters of the stored credentials. See the description below.

bindings element contains blocks with the following parameters.

Required Name Type Description
Optional

maskedPan String [1..19] Masked number of the card used for the payment. This parameter is to be specified only after the order has been paid.
Optional

paymentWay String Payment method (a payment with entering card data, a stored-credential transaction, etc.). Find more possible values of the parameter.
Mandatory

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Mandatory

expiryDate Integer Card expiration in the following format: YYYYMM. This parameter is to be specified only after the order has been paid.
Optional

bindingCategory String The purpose of the of stored credential that is expected in reponse. Possible values: COMMON, INSTALLMENT, RECURRENT.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

displayLabel Integer [1..16] The last 4 digits of the original PAN before tokenization .
Optional

paymentSystem String Payment system name. The following variants are possible:
  • VISA;
  • MASTERCARD;
  • AMEX;
  • JCB;
  • CUP;

Examples

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/getBindings.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data clientId=dos-clientos \
  --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

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Conditional

pan String [1..19] Payment card number (mandatory, unless bindinId is passed). pan overrides bindingId.
Conditional

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Optional

showExpired Boolean true/false parameter defining whether to show stored credentials with expired cards. Default is false.

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

bindings Object Element with blocks that contain parameters of the stored credential: bindingId, maskedPan, expiryDate, clientId
Optional

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Optional

maskedPan String [1..19] Masked number of the card used for the payment. This parameter is to be specified only after the order has been paid.
Optional

expiryDate Integer Card expiration in the following format: YYYYMM. This parameter is to be specified only after the order has been paid.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.

Examples

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/getBindingsByCardOrId.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data pan=4000001111111118

Example of a success response

{
"errorCode":"0",
"errorMessage":"Success",
"bindings": [
    {
        "bindingId":"69d6a793-afb5-79be-8ce7-63ff00a8656a",
        "maskedPan":"400000**1118",
        "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

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/unBindCard.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --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

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/bindCard.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --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

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Mandatory

newExpiry Integer New expiration date (year and month) in the following format: YYYYMM.
Mandatory

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/extendBinding.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --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 /payment/recurrentPayment.do. It is used to register and pay for the order.

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

feeInput String Fee amount in minimum currency units. Must be enabled by respective Merchant-level permission in the Gateway.
Mandatory

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

additionalParameters Object Additional parameters of the order that are stored in the merchant personal area for the subsequent viewing. Each new pair of a parameter name and its value must be separated by a comma. Below is a usage example.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
Conditional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

shippingPayerData Object Object containing customer delivery data. It is used for further 3DS authentication of the client. See nested parameters
Optional

preOrderPayerData Object Object containing pre-order data. It is used for further 3DS authentication of the client. See nested parameters
Optional

orderPayerData Object Object containing data about the order payer. It is used for further 3DS authentication of the client. See nested parameters
Optional

billingAndShippingAddressMatchIndicator A1 Indicator for matching the cardholder's billing address and shipping address. This parameter is used for further 3DS authentication of the customer.
Possible values:
  • Y - the cardholder's billing address and shipping address match;
  • N - cardholder billing address and shipping address do not match

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Description of parameters in shippingPayerData object:

Required Name Type Description
Optional shippingCity ANS...50 The customer's city (from the delivery address)
Optional shippingCountry ANS...50 The customer's country
Optional shippingAddressLine1 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine2 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine3 ANS...50 The customer's primary address (from the shipping address)
Optional shippingPostalCode ANS...16 The customer's zip code for delivery
Optional shippingState ANS...50 Customer's state/region (from delivery address)
Optional shippingMethodIndicator N2 Shipping Method Indicator.
Possible values:
  • 01 - delivery to the cardholder's billing address
  • 02 - delivery to another address verified by Merchant
  • 03 - delivery to an address other than the cardholder's primary (settlement) address
  • 04 - shipment to the store/self-collection (the store address should be specified in the relevant delivery parameters)
  • 05 - Digital distribution (includes online services and e-gift cards)
  • 06 - travel and event tickets that are not deliverable
  • 07 - Other (e.g. games, non-deliverable digital goods, digital subscriptions, etc.)
Optional deliveryTimeframe N2 Product delivery timeframe.
Possible values:
  • 01 - digital distribution
  • 02 - same-day delivery
  • 03 - overnight delivery
  • 04 - delivery within 2 days after payment and later
Optional deliveryEmail ANS...254 Target email address for delivery of digital distribution

Description of parameters in preOrderPayerData object:

Required Name Type Description
Optional preOrderDate ANS8 Expected date when delivery will be available (for pre-ordered purchases), in the format YYYYYYMMDD.
Optional preOrderPurchaseInd N2 Indicator of a customer placing an order for available or future delivery.
Possible values:
  • 01 - delivery available;
  • 02 - future delivery
Optional reorderItemsInd N2 An indicator that the customer is rebooking a previously paid delivery as part of a new order.
Possible values:
  • 01 - order placed for the first time;
  • 02 - repeated order

Description of parameters in orderPayerData object:

Required Name Type Description
Optional homePhone ANS...19 The cardholder's home phone number, with the obligatory "+" symbol
Optional workPhone ANS...19 The cardholder's work phone number, with the obligatory "+" symbol
Optional mobilePhone ANS...19 The cardholder's mobile phone number, with the obligatory "+" symbol

Response parameters

Required Name Type Description
Mandatory

success Boolean 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.
Read here to find out how to get payment status.
Conditional data N/A This parameter is returned only if the payment is processed successfully. See the description below.
Conditional error N/A This parameter is returned only if the payment failed. See the description below.

data block contains the following elements.

Required Name Type Description
Mandatory

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.

error block contains the following elements.

Required Name Type Description
Mandatory

code Integer [1..3] Code as an information parameter stating an error occurred.
Mandatory

description String [1..598] A detailed technical explanation of the error - the contents of this parameter should not to be displayed to the customer.
Mandatory

message String [1..512] Information parameter that is an error description to be displayed to the user. The parameter may vary, so it should not be hardcoded.

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/payment/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 /payment/installmentPayment.do

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Mandatory

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Mandatory

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Mandatory

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

additionalParameters Object Additional parameters of the order that are stored in the merchant personal area for the subsequent viewing. Each new pair of a parameter name and its value must be separated by a comma. Below is a usage example.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
Mandatory

preAuth Boolean Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available:
  • true - two-phase payments enabled;
  • false - one-phase payments enabled (money are charged right away).
If the parameter is missing, one-phase payment is made.
Mandatory

token String [1..256] 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.

Response parameters

Required Name Type Description
Optional

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Mandatory

errorMessage String [1..512] 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.
Conditional orderStatus Object Contains order status parameters and is returned only if the payment gateway has recognized all request parameters as correct. See the description below.

orderStatus block contains the following elements.

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

orderStatus Integer The value of this parameter specifies the status of the order in the payment gateway. It is missing if the order has not been found. Below is the list of available values:
  • 0 - order was registered but not paid;
  • 1 - order was authorized only and wasn't captured yet (for two-phase payments);
  • 2 - order was authorized and captured;
  • 3 - authorization canceled;
  • 4 - transaction was refunded;
  • 5 - access control server of the issuing bank initiated authorization procedure;
  • 6 - authorization declined;
  • 7 - pending order payment;
  • 8 - intermediate completion for multiple partial completion.
Optional

actionCode Integer Response code from the processing bank. See the list of action codes here.
Optional

actionCodeDescription String [1..512] actionCode description returned from the processing bank.
Optional

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional

date String Order registration date (UNIX time).
Optional

ip String [1..39] Buyer's IP address. IPv6 is supported in all requests. (up to 39 characters).
Optional

chargeback Boolean Whether the funds was forcibly returned to the buyer by the bank. The possible values are:true, false.
Optional merchantOrderParams N/A Section with attributes in which the merchant's additional parameters are transmitted. See the description below.
Optional attributes Object Attributes of the order in the payment system (order number). See the description below.
Optional cardAuthInfo Object Information about the buyer's payment card. See the description below.
Optional

authDateTime String Authorization date and time, shown as the amount of milliseconds since 00:00 January 1, 1970 GMT (UNIX time).
Optional

terminalId String [1..10] Terminal identifier in the system that processes the payment.
Optional

authRefNum String [1..24] Reference number of the payment authorization that has been assigned to it upon its registration.
Optional paymentAmountInfo Object A parameter containing embedded parameters with information about confirmation, debiting and refund amounts. See the description below.
Optional bankInfo Object Contains the embedded bankCountryName parameter. See the description below.
Optional bindingInfo Object Object containing information on the binding with which the payment is performed. See the description below.
Optional operations Object Object containing the operations information. See the description below.

merchantOrderParams block contains the following elements.

Required Name Type Description
Mandatory

name String [1..255] Name of the merchant's additional parameter.
Mandatory

value String The value of the merchant's additional parameter - up to 1024 characters.

attributes block contains the following elements.

Required Name Type Description
Mandatory

name String [1..255] Name of an additional parameter.
Mandatory

value Alphanumeric Value of an additional parameter - up to 1024 characters.

cardAuthInfo block contains the following elements.

Required Name Type Description
Mandatory

expiration Integer Card expiration in the following format: YYYYMM. This parameter is to be specified only after the order has been paid.
Mandatory

cardholdername String [1..26] Cardholder's name in Latin characters. This parameter is passed only after an order is paid.
Mandatory

approvalCode String [6] IPS authorization code. This field has a fixed length (six symbols) and can contain digits and Latin letters.
Mandatory

pan String [1..19] Masked DPAN: a number that is linked to the customer's mobile device and functions as a payment card number in the Apple Pay system.
Mandatory

maskedPan String [1..19] Masked number of the card used for the payment. This parameter is to be specified only after the order has been paid.
Mandatory

paymentSystem String Payment system name. The following variants are possible:
  • VISA;
  • MASTERCARD;
  • AMEX;
  • JCB;
  • CUP;

paymentAmountInfo block contains the following elements.

Required Name Type Description
Mandatory

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

approvedAmount Integer [0..12] Amount in minimum currency units (e.g. cents) that was put on hold on buyer's account. Used in two-phase payments only.
Mandatory

depositedAmount Integer [1..12] Charged amount in minimum currency units (e.g., in cents).
Mandatory

refundedAmount Integer [1..12] Refunded amount in minimum currency units.
Mandatory

totalAmount Integer [1..12] Order amount plus fee, if any.

bankInfo block contains the following elements.

Required Name Type Description
Mandatory

bankCountryName String [1..160] Country of the issuing bank.

bindingInfo element contains the following parameters.

Name Type Mandatory Description
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional

bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials. If this parameter is passed in this request, it means that:
  • This order can only be paid with a stored crediential;
  • The payer will be redirected to a payment page where only CVC entry is required.

operations element contains the following parameters.

Name Type Mandatory Description
Optional

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

cardHolder String [1..26] Cardholder's name in Latin characters. This parameter is passed only after an order is paid.
Optional

authCode Integer [6] Deprecated parameter (not used). Its value is always 2 regardless the order status and authorization code of the processing system.

Examples

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/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
}

3DS utilities

Finishing a 3DS2 payment via API

The method used for finishing a 3DS2 order via API is finish3dsVer2Payment.do

Request parameters

Required Name Type Description
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory

threeDSServerTransId String Transaction identifier created on 3DS Server.

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Mandatory

errorMessage String [1..512] 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.
Optional

redirect String [1..512] This parameter is returned if the payment is successful and that payment did not include check for 3-D Secure involvement. Merchants can use it if they want to redirect the user to the payment gateway page. If they have their own response page then this value can be ignored.
Optional

is3DSVer2 Boolean Possible values: true or false. Flag showing that payment uses 3DS 2.0.

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
}

Continue payment for 3DS2

To continue payment with 3DS2 authorization, use continue.do request.

Request parameters

Required Name Type Description
Conditional

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Conditional

token String [1..256] 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.
Mandatory

mdOrder String [1..36] Order number in the payment gateway. Unique within the payment gateway.

Response parameters

Required Name Type Description
Mandatory

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

info String If response is successful. Result of a payment attempt. Below are the possible values.
  • Your payment has been processed, redirecting...
  • Operation declined. Check the entered data and that there are enough funds on the card and repeat the operation. Redirecting...
  • Sorry, payment cannot be completed. Redirecting...
  • Operation declined. Contact the merchant. Redirecting...
  • Operation declined. Contact the bank that issued the card. Redirecting...
  • Impossible operation. Cardholder authentication completed unsuccessfully. Redirecting...
  • No connection with bank. Try again later. Redirecting...
  • Input time expired. Redirecting...
  • No response from bank received. Try again later. Redirecting...
Optional

redirect String [1..512] This parameter is returned if the payment is successful and that payment did not include check for 3-D Secure involvement. Merchants can use it if they want to redirect the user to the payment gateway page. If they have their own response page then this value can be ignored.
Conditional*

acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
Conditional*

packedCReq String Packed challenge request data. This value should be used as the ACS link creq parameter (acsUrl) to redirect the client to the ACS.

* Mandatory, if redirect to the ACS is needed (full 3DS2 is used).

Examples

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/3ds/continue.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data mdOrder=eb708f0a-2683-7437-b458-f80400b40dc0 \
  --data userName=test-user \
  --data password=test-password

Response example (full 3DS2, success):

{
    "info": "Your order is proceeded, redirecting...",
    "errorCode": 0,
    "acsUrl": "https://bestbank.com/acs2/acs/creq",
    "is3DSVer2": true,
    "packedCReq": "eyJ0aHJlZURTU...6IjA1In0"
}

Response example (frictionless 3DS2, success):

{
    "redirect": "https://merchant.com/returnUrl?orderId=9666296c-e4f1-7285-a57c-20eb00b40dc1&lang=en",
    "info": "Your order is proceeded, redirecting...",
    "errorCode": 0,
    "is3DSVer2": true
}

Response example (failure - unknown status in ARes):

{
    "redirect": "https://merchant.com/failUrl?orderId=b69ac21f-6cd3-7e06-931d-d90100b40dc1&lang=en",
    "error": "Error 3-D Secure authorization.",
    "errorCode": 0,
    "is3DSVer2": true,
    "errorTypeName": "TDS_UNKNOWN_ARES_STATUS",
    "processingErrorType": "MANDATORY_3DSECURE",
    "errorMessage": "Error 3-D Secure authorization."
}

Response example (failure - authorization failed):

{
    "redirect": "https://merchant.com/failUrl?orderId=de056d10-f91d-7c91-a3de-559800b40dc1&lang=en",
    "error": "Operation declined. Please check the data and available balance of the account.",
    "errorCode": 0,
    "is3DSVer2": true,
    "errorTypeName": "DATA_INPUT_ERROR",
    "processingErrorType": "CLIENT_ERROR",
    "errorMessage": "Operation declined. Please check the data and available balance of the account."
}

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

Required Name Type Description
Optional

userName String [1..100] Merchant 's API account login. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Optional

password String [1..200] Merchant's API account password. If you pass your login and password to authenticate in the payment gateway, do not pass token parameter.
Optional

token String [1..256] 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.
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional

pan String [1..19] Masked number of the card that has been used for the payment. This parameter is to be specified only after the order has been paid. When paying via Apple Pay, DPAN is used as card number - it is a number linked to customer's mobile device that functions as a payment card number in the Apple Pay system.
Optional

cvc Integer This parameter is mandatory if permission Can process payments without confirmation of CVC is not enabled.
Optional

expiry Integer Card expiration in the following format: YYYYMM. Mandatory, if neither seToken nor bindingId is passed.
Optional

cardholdername String [1..26] Cardholder's name in Latin characters. This parameter is passed only after an order is paid.
Optional

backUrl String [1..512] URL the user is to be redirected to if payment is successful.
Use full path with protocol included, like this - https://test.com (not test.com).
Otherwise the user will be redirected to a URL composed like this: http://paymentGatewayURL/merchantURL
Optional

failUrl String [1..512] The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

description String [1..598] Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
Optional

language String [2] ISO 639-1 encoded language key. If the language is not specified, the default language specified in the store settings is used.
Supported languages: en,bg,de,fr,gr,hu,it,pl,ro,sp.
Optional

returnUrl String [1..512] The address to which the user will be redirected if the payment is successful. The address must be specified in full including the protocol used (for example, https://mybestmerchantreturnurl.com instead of mybestmerchantreturnurl.com). Otherwise, the user will be redirected to the address of the following type https://dev.bpcbt.com/payment/<merchant_address>.
Optional

threeDSServerTransId String Transaction identifier created on 3DS Server.
Optional

threeDSVer2FinishUrl String URL where Customer should be redirected after authentication on ACS Server.
Conditional

threeDSVer2MdOrder String Order number which was registered in the first part of the request within 3DS 2.0 transaction.
If this parameter is present in the request, the mdOrder value passed in it overrides, and in this case the order gets paid right away instead of being registered. For Google Pay transactions, this parameter is mandatory.
Optional

threeDSSDK Boolean Possible values: true or false. Flag showing that payment comes from 3DS SDK.
Optional

billingPayerData Object A block with the client's registration data (address, postal code) necessary for passing the address verification within the AVS/AVV services. Mandatory if the feature is enabled for the merchant on Payment Gateway side. See nested parameters.
Optional

shippingPayerData Object Object containing customer delivery data. It is used for further 3DS authentication of the client. See nested parameters
Optional

preOrderPayerData Object Object containing pre-order data. It is used for further 3DS authentication of the client. See nested parameters
Optional

orderPayerData Object Object containing data about the order payer. It is used for further 3DS authentication of the client. See nested parameters
Optional

billingAndShippingAddressMatchIndicator A1 Indicator for matching the cardholder's billing address and shipping address. This parameter is used for further 3DS authentication of the customer.
Possible values:
  • Y - the cardholder's billing address and shipping address match;
  • N - cardholder billing address and shipping address do not match

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

Required Name Type Description
Optional

billingCity String [0..50] The city registered on a specific card of the Issuing Bank.
Optional

billingCountry String [0..50] The country registered on a specific card of the Issuing Bank ( ISO 3166-1, numeric).
Optional

billingAddressLine1 String [0..50] The address registered on a specific card of the Issuing Bank. Line 1. Mandatory to be passed in order AVS verification works.
Optional

billingAddressLine2 String [0..50] The address registered on a specific card of the Issuing Bank. Line 2.
Optional

billingAddressLine3 String [0..50] The address registered on a specific card of the Issuing Bank. Line 3.
Optional

billingPostalCode String [0..9] Postal code registered on a specific card of the Issuing Bank. Mandatory to be passed in order AVS verification works.
Optional

billingState String [0..50] The state registered on a specific card of the Issuing Bank (ISO 3166-2).

Description of parameters in shippingPayerData object:

Required Name Type Description
Optional shippingCity ANS...50 The customer's city (from the delivery address)
Optional shippingCountry ANS...50 The customer's country
Optional shippingAddressLine1 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine2 ANS...50 The customer's primary address (from the shipping address)
Optional shippingAddressLine3 ANS...50 The customer's primary address (from the shipping address)
Optional shippingPostalCode ANS...16 The customer's zip code for delivery
Optional shippingState ANS...50 Customer's state/region (from delivery address)
Optional shippingMethodIndicator N2 Shipping Method Indicator.
Possible values:
  • 01 - delivery to the cardholder's billing address
  • 02 - delivery to another address verified by Merchant
  • 03 - delivery to an address other than the cardholder's primary (settlement) address
  • 04 - shipment to the store/self-collection (the store address should be specified in the relevant delivery parameters)
  • 05 - Digital distribution (includes online services and e-gift cards)
  • 06 - travel and event tickets that are not deliverable
  • 07 - Other (e.g. games, non-deliverable digital goods, digital subscriptions, etc.)
Optional deliveryTimeframe N2 Product delivery timeframe.
Possible values:
  • 01 - digital distribution
  • 02 - same-day delivery
  • 03 - overnight delivery
  • 04 - delivery within 2 days after payment and later
Optional deliveryEmail ANS...254 Target email address for delivery of digital distribution

Description of parameters in preOrderPayerData object:

Required Name Type Description
Optional preOrderDate ANS8 Expected date when delivery will be available (for pre-ordered purchases), in the format YYYYYYMMDD.
Optional preOrderPurchaseInd N2 Indicator of a customer placing an order for available or future delivery.
Possible values:
  • 01 - delivery available;
  • 02 - future delivery
Optional reorderItemsInd N2 An indicator that the customer is rebooking a previously paid delivery as part of a new order.
Possible values:
  • 01 - order placed for the first time;
  • 02 - repeated order

Description of parameters in orderPayerData object:

Required Name Type Description
Optional homePhone ANS...19 The cardholder's home phone number, with the obligatory "+" symbol
Optional workPhone ANS...19 The cardholder's work phone number, with the obligatory "+" symbol
Optional mobilePhone ANS...19 The cardholder's mobile phone number, with the obligatory "+" symbol

Response parameters

Required Name Type Description
Optional

errorCode Integer [1..2] Information parameter in case of an error, which may have different code values:
  • 0 value - indicates success of the request 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.
Optional

errorMessage String [1..512] 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.
Optional

orderId String [1..36] Order number in the payment gateway. Unique within the payment gateway.
Optional

orderNumber String [1..32] Order number (ID) in the merchant's system, must be unique for each order.
Optional

authCode Integer [6] Deprecated parameter (not used). Its value is always 2 regardless the order status and authorization code of the processing system.
Optional

actionCode Integer Response code from the processing bank. See the list of action codes here.
Optional

actionCodeDescription String [1..512] actionCode description returned from the processing bank.
Optional

time String Time when transaction took place.
Optional

eci Integer [1..4] 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.
Optional

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional

rrn Integer [1..12] Reference Retrieval Number - transaction ID assigned by Acquiring Bank.
Optional

acsUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address for redirecting to ACS. For details see Redirect to ACS.
Optional

termUrl String [1..512] In a successful response in case of a 3D-Secure payment. The URL address to which ACS redirects the cardholder after authentication. For details see Redirect to ACS.
Optional

paReq String [1..255] In a successful response in case of a 3D-Secure payment. PAReq (Payment Authentication Request) - a message that should be sent to ACS together with redirect. This message contains the Base64-encoded data necessary for the cardholder authentication. For details see Redirect to ACS.

Examples

Request example

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/verifyCard.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data pan=4000001111111118 \
  --data cvc=123 \
  --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"
}

Recurring tasks API

The below API allows you to configure tasks for recurring payments. The configured payments are futher automatically executed according to the predefined schedule.

Create task

The request used to create a recurrent task is /v1/task/create.

Request parameters

Required Name Type Description
Optional locale String [2] Language in ISO 639-1. If not specified, the default language will be used.
Optional merchantLogin String [1..30] To create a task on behalf of another merchant, specify the merchant's API account login in this parameter.
Can be used only if you have the permission to see the transactions of other merchants or if the specified merchant is your child merchant.
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory task Object Information about the recurring task being created. See nested parameters.

Below are the parameters of the task block (data about the recurrent task being created).

Required Name Type Description
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials.
Optional cardHolder String [1..26] The name of the holder of the card in Latin characters.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Mandatory

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional expiry Integer Card expiration in the following format: YYYYMM.
Mandatory merchantTaskUuid String The unique identifier of the task being created within the merchant.
Optional pan String [1..19] Masked number of the card that has been used for the payment.
Optional attributes Object A set of task attributes, structure:
{name1:value1,…,nameN:valueN}. The exact list of attributes should be coordinated with the bank.
Optional params Object A set of additional free-form parameters, structure:
{name1:value1,…,nameN:valueN}
Mandatory scheduleData Object A set of task frequency shedule data. See nested parameters.

Below are the parameters of the scheduleData block (data about the task frequency shedule).

Required Name Type Description
Mandatory scheduledSince String Date/time from which the task should start. Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
Mandatory scheduledTill String Date/time before which the task should be completed. Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
Mandatory timeUnit String Time unit. Allowed values: Nanos, Micros, Millis, Seconds, Minutes, Hours, HalfDays, Days, Weeks, Months, Years, Decades, Centuries, Millennia, Eras, Forever
Mandatory value integer Frequency value

Response parameters

Required Name Type Description
Mandatory status Object Response status. Allowed values: SUCCESS, FAIL.
Mandatory task Object Information about the created recurring task. See nested parameters.

Below are the parameters of the task block (data about the created recurrent task).

Required Name Type Description
Mandatory created String Date/time the task was created.
Mandatory merchantLogin String Merchant login.
Mandatory merchantTaskUuid String The unique identifier of the task being created within the merchant.
Mandatory nextPaymentDate String Next payment date.
Mandatory state String Task state. Allowed values:
  • CREATED - created, no payments yet
  • ACTIVE - created and at least one payment has been already proceeded
  • FAILED - exceeded max payment attempts and deactivated
  • COMPLETED - reached EOL date, all payments completed
  • TERMINATED - terminated by either client via processing or merchant
  • EXPIRED - card expired
Mandatory taskUuid String The unique identifier of the task within the recurring payments service.

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/recurrent/v1/task/create \
--header 'Content-Type: application/json' \
--data '{
    "username":"test_user",
    "password":"test_user_password",
    "locale":"en",
    "task":{
        "merchantTaskUuid":"c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82",
        "clientId":"TestClient",
        "bindingId": "5eb094e1-4a96-7b33-af5f-a29407a73a93",
        "scheduleData": {
            "value":"1",
            "timeUnit":"DAYS",
            "scheduledSince":"2024-01-24T00:00:00.000+0300",
            "scheduledTill":"2024-02-24T00:00:00.000+0300"
        },
        "amount":100,
        "currency":170,
        "params":{
            "description":"desc",
            "phone":"576015555556"
        }
    }
}'

Example of a success response

{
  "status": "SUCCESS",
  "task": {
    "created": "2024-01-24T10:23:35.434591+03:00",
    "merchantLogin": "testMerch",
    "taskUuid": "8a6a5350-1be3-456e-8e81-e5c7eafbd699",
    "nextPaymentDate": "2024-01-24T00:00:00+03:00",
    "state": "CREATED",
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82"
  }
}

Modify task

The request used to modify an existing recurrent task is /v1/task/modify.

Request parameters

Required Name Type Description
Optional locale String [2] Language in ISO 639-1. If not specified, the default language will be used.
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory task Object Information about the recurring task being modified. See nested parameters.

Below are the parameters of the task block (data about the recurrent task being modified).

Required Name Type Description
Optional bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials.
Optional

cardholder String Cardholder's name in Latin characters. This parameter is passed only after an order is paid.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Optional expiry String Card expiration in the following format: YYYYMM.
Optional pan String [1..19] Masked number of the card that has been used for the payment.
Optional attributes Object A set of task attributes, structure:
{name1:value1,…,nameN:valueN}. The exact list of attributes should be coordinated with the bank.
Optional params Object A set of additional free-form parameters, structure:
{name1:value1,…,nameN:valueN}
Mandatory taskIdentifier Object The unique identifier or set of identifiers of the task. See nested parameters.

Below are the parameters of the taskIdentifier block (set of identifiers for a recurrent task).

Required Name Type Description
Optional merchantLogin String Merchant login. Should be present for searching by merchantTaskUuid.
Optional merchantTaskUuid String The unique identifier of the task being created within the merchant. Required if taskUuid is not present.
Optional taskUuid String The unique identifier of the task within the recurring payments service. Required if merchantTaskUuid is not present.

Response parameters

Required Name Type Description
Mandatory status Object Response status. Allowed values: SUCCESS, FAIL.
Mandatory task Object Information about the created recurring task. See nested parameters.

Below are the parameters of the task block (data about the modified recurrent task).

Required Name Type Description
Mandatory updated String Date/time of the last update of the task.
Mandatory merchantLogin String Merchant login.
Mandatory merchantTaskUuid String The unique identifier of the task within the merchant.
Mandatory taskUuid String The unique identifier of the task within the recurring payments service.

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/recurrent/v1/task/modify \
--header 'Content-Type: application/json' \
--data '{
    "username":"test_user",
    "password":"test_user_password",
    "task":{
        "taskIdentifier": {
           "taskUuid":"9ae9f36d-0ba3-4686-87c4-a5ec77c562a4"
       },
        "bindingId":"5eb094e1-4a96-7b33-af5f-a29407a73a93",
        "clientId":"TestClient",
        "params":{
            "description":"new description",
            "phone":"+576015555558"
        }
}'

Example of a success response

{
  "status": "SUCCESS",
  "task": {
    "updated": "2024-01-23T14:10:03.730644+03:00",
    "merchantLogin": "testMerch",
    "taskUuid": "9ae9f36d-0ba3-4686-87c4-a5ec77c562a4",
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c80"
  }
}

Get task information

The request used to get information about a recurrent task is /v1/task/get.

Request parameters

Required Name Type Description
Optional locale String [2] Language in ISO 639-1. If not specified, the default language will be used.
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory taskIdentifier Object The unique identifier or set of identifiers of the task. See nested parameters.

Below are the parameters of the taskIdentifier block (set of identifiers for a recurrent task).

Required Name Type Description
Optional merchantLogin String Merchant login. Should be present for searching by merchantTaskUuid.
Optional merchantTaskUuid String The unique identifier of the task being created within the merchant. Required if taskUuid is not present.
Optional taskUuid String The unique identifier of the task within the recurring payments service. Required if merchantTaskUuid is not present.

Response parameters

Required Name Type Description
Mandatory status Object Response status. Allowed values: SUCCESS, FAIL.
Mandatory task Object Information about the recurrent task. See nested parameters.

Below are the parameters of the task block (data about a recurrent task).

Required Name Type Description
Mandatory

amount Integer [0..12] Payment amount in minor currency units (e.g. in cents etc.).
Optional attemptsHistory Array of objects All payment attempts in chronological order. Each payment attempt is an attemptsHistory object. See nested parameters.
Optional bindingId String [1..255] Identifier of an already existing stored credential. This is the card ID tokenized by the Gateway. Can be used only if the merchant has the permission to work with stored credentials.
Optional cardHolder String [1..26] The name of the holder of the card in Latin characters.
Optional

clientId String [0..255] Customer number (ID) in the merchant's system — up to 255 characters. Used to implement the functionality of stored-credential transactions. Can be returned in the response if the merchant is allowed to store credentials.
Specifying this parameter in stored-credential transactions is mandatory. Otherwise, a payment will be unsuccessful.
Mandatory created String Date/time the task was created.
Mandatory

currency Integer [3] ISO 4217 encoded currency key. If not specified, the default value is used.
Optional expiry Integer Card expiration in the following format: YYYYMM.
Mandatory lastPaymentDate String Last payment date.
Optional maskedPan String Masked pan of the card.
Mandatory merchantLogin String [1..30] The login of the merchant.
Mandatory merchantTaskUuid String The unique identifier of the task within the merchant.
Mandatory nextPaymentDate String Next payment date.
Optional params Object A set of additional free-form parameters, structure:
{name1:value1,…,nameN:valueN}
Mandatory scheduleData Object A set of task frequency shedule data. See nested parameters.
Mandatory state String Task state. Allowed values:
  • CREATED - created, no payments yet
  • ACTIVE - created and at least one payment has been already proceeded
  • FAILED - exceeded max payment attempts and deactivated
  • COMPLETED - reached EOL date, all payments completed
  • TERMINATED - terminated by either client via processing or merchant
  • EXPIRED - card expired
Mandatory taskUuid String The unique identifier of the task within the recurring payments service.
Mandatory updated String Date/time of the last update of the task.

Below are the parameters of the scheduleData block (data about the task frequency shedule).

Required Name Type Description
Mandatory scheduledSince String Date/time from which the task should start. Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
Mandatory scheduledTill String Date/time before which the task should be completed. Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
Mandatory timeUnit String Time unit. Allowed values: Nanos, Micros, Millis, Seconds, Minutes, Hours, HalfDays, Days, Weeks, Months, Years, Decades, Centuries, Millennia, Eras, Forever
Mandatory value integer Frequency value

Below are the parameters of the attemptsHistory block (data about the task frequency shedule).

Required Name Type Description
Mandatory executed String Date/time of the payment attempt. Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
Optional orderId String Unique identifier of the transaction in the payment gateway
Optional orderNumber String Order number in the payment gateway
Mandatory paymentAttemptUuid String Unique identifier of the payment attempt
Mandatory paymentUuid String Unique identifier of the payment
Mandatory state String Task state. Allowed values:
  • CREATED - created, no payments yet
  • ACTIVE - created and at least one payment has been already proceeded
  • FAILED - exceeded max payment attempts and deactivated
  • COMPLETED - reached EOL date, all payments completed
  • TERMINATED - terminated by either client via processing or merchant
  • EXPIRED - card expired
Mandatory technicalAttempt Boolean Flag indicating whether the attempt was technical

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/recurrent/v1/task/get \
--header 'Content-Type: application/json' \
--data '{
    "username":"test_user",
    "password":"test_user_password",
    "taskIdentifier": {
           "taskUuid":"8a6a5350-1be3-456e-8e81-e5c7eafbd699"
     }
}'

Example of a success response

{
  "status": "SUCCESS",
  "task": {
    "taskUuid": "8a6a5350-1be3-456e-8e81-e5c7eafbd699",
    "state": "ACTIVE",
    "merchantLogin": "testMerch",
    "bindingId": "5eb094e1-4a96-7b33-af5f-a29407a73a93",
    "clientId": "TestClient",
    "created": "2024-01-24T10:23:35.434591+03:00",
    "updated": "2024-01-24T10:23:35.434591+03:00",
    "lastPaymentDate": "2024-01-24T00:00:00+03:00",
    "nextPaymentDate": "2024-01-25T00:00:00+03:00",
    "scheduleData": {
      "scheduledSince": "2024-01-24T00:00:00.000+0300",
      "scheduledTill": "2024-02-24T00:00:00.000+0300",
      "value": 1,
      "timeUnit": "DAYS"
    },
    "amount": 100,
    "currency": 170,
    "params": {
      "phone": "576015555556",
      "description": "description"
    },
    "attemptsHistory": [
      {
        "paymentAttemptUuid": "6873d7dc-4366-45c5-9de6-bc6e0aa05b3d",
        "paymentUuid": "1a450005-ad46-4474-8940-eb154822296c",
        "state": "SUCCEEDED",
        "executed": "2024-01-24T10:23:41.788436+03:00",
        "technicalAttempt": false,
        "orderId": "d2d56b04-124b-77ab-9034-9f2307a73a93",
        "orderNumber": "E5DFEDE990694FCFB5246AEC2612A355"
      }
    ],
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82"
  }
}

Terminate task

The request used to terminate a recurrent task is /v1/task/terminate.

Request parameters

Required Name Type Description
Optional locale String [2] Language in ISO 639-1. If not specified, the default language will be used.
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory taskIdentifier Object The unique identifier or set of identifiers of the task. See nested parameters.

Below are the parameters of the taskIdentifier block (set of identifiers for a recurrent task).

Required Name Type Description
Optional merchantLogin String Merchant login. Should be present for searching by merchantTaskUuid.
Optional merchantTaskUuid String The unique identifier of the task being created within the merchant. Required if taskUuid is not present.
Optional taskUuid String The unique identifier of the task within the recurring payments service. Required if merchantTaskUuid is not present.

Response parameters

Required Name Type Description
Mandatory status Object Response status. Allowed values: SUCCESS, FAIL.
Mandatory task Object Information about the recurrent task. See nested parameters.

Below are the parameters of the task block (data about the terminated recurrent task).

Required Name Type Description
Mandatory updated String Date/time of the last update of the task.
Mandatory merchantLogin String Merchant login.
Mandatory merchantTaskUuid String The unique identifier of the task within the merchant.
Mandatory taskUuid String The unique identifier of the task within the recurring payments service.
Mandatory state String Task state. Allowed values:
  • CREATED - created, no payments yet
  • ACTIVE - created and at least one payment has been already proceeded
  • FAILED - exceeded max payment attempts and deactivated
  • COMPLETED - reached EOL date, all payments completed
  • TERMINATED - terminated by either client via processing or merchant
  • EXPIRED - card expired

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/recurrent/v1/task/terminate \
--header 'Content-Type: application/json' \
--data '{
    "username":"test_user",
    "password":"test_user_password",
    "taskIdentifier": {
        "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82",
        "merchantLogin": "testMerch"
    }
}'

Example of a success response

{
  "status": "SUCCESS",
  "task": {
    "updated": "2024-01-24T10:23:35.434591+03:00",
    "merchantLogin": "testMerch",
    "taskUuid": "8a6a5350-1be3-456e-8e81-e5c7eafbd699",
    "state": "TERMINATED",
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82"
  }

Activate task

The request used to activate a recurrent task is /v1/task/activate.

Request parameters

Required Name Type Description
Optional locale String [2] Language in ISO 639-1. If not specified, the default language will be used.
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory taskIdentifier Object The unique identifier or set of identifiers of the task. See nested parameters.

Below are the parameters of the taskIdentifier block (set of identifiers for a recurrent task).

Required Name Type Description
Optional merchantLogin String Merchant login. Should be present for searching by merchantTaskUuid.
Optional merchantTaskUuid String The unique identifier of the task being created within the merchant. Required if taskUuid is not present.
Optional taskUuid String The unique identifier of the task within the recurring payments service. Required if merchantTaskUuid is not present.

Response parameters

Required Name Type Description
Mandatory status Object Response status. Allowed values: SUCCESS, FAIL.
Mandatory task Object Information about the recurrent task. See nested parameters.

Below are the parameters of the task block (data about the activated recurrent task).

Required Name Type Description
Mandatory updated String Date/time of the last update of the task.
Mandatory merchantLogin String Merchant login.
Mandatory merchantTaskUuid String The unique identifier of the task within the merchant.
Mandatory nextPaymentDate String Next payment date.
Mandatory taskUuid String The unique identifier of the task within the recurring payments service.
Mandatory state String Task state. Allowed values:
  • CREATED - created, no payments yet
  • ACTIVE - created and at least one payment has been already proceeded
  • FAILED - exceeded max payment attempts and deactivated
  • COMPLETED - reached EOL date, all payments completed
  • TERMINATED - terminated by either client via processing or merchant
  • EXPIRED - card expired

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/recurrent/v1/task/activate \
--header 'Content-Type: application/json' \
--data '{
    "username":"test_user",
    "password":"test_user_password",
    "taskIdentifier": {
        "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82",
        "merchantLogin": "testMerch"
    }
}'

Example of a success response

{
  "status": "SUCCESS",
  "task": {
    "updated": "2024-01-24T10:23:35.434591+03:00",
    "merchantLogin": "testMerch",
    "taskUuid": "8a6a5350-1be3-456e-8e81-e5c7eafbd699",
    "state": "ACTIVE",
    "nextPaymentDate": "2024-01-25T00:00:00+03:00",
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82"
  }
}

Terminate tasks

The request used to terminate multiple recurrent tasks is /v1/task/batchTerminate.

Request parameters

Required Name Type Description
Optional locale String [2] Language in ISO 639-1. If not specified, the default language will be used.
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory taskIdentifiers Array of Objects Identifiers of tasks to be terminated. Each task is a taskIdentifier object. See nested parameters.

Below are the parameters of the taskIdentifier block (set of identifiers for a recurrent task).

Required Name Type Description
Optional merchantLogin String Merchant login. Should be present for searching by merchantTaskUuid.
Optional merchantTaskUuid String The unique identifier of the task being created within the merchant. Required if taskUuid is not present.
Optional taskUuid String The unique identifier of the task within the recurring payments service. Required if merchantTaskUuid is not present.

Response parameters

Required Name Type Description
Mandatory status Object Response status. Allowed values: SUCCESS, FAIL.

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/recurrent/v1/task/batchTerminate \
--header 'Content-Type: application/json' \
--data '{
    "locale":"EN",
    "username":"testUser",
    "password":"testPwd",
    "tasksIdentifiers":[
        {
            "taskUuid":"0ba73819-65f8-43c4-9dc4-3870cb10416b"
        },
        {
            "taskUuid":"0ba73820-65f8-43c4-9dc4-3870cb10416b"            
        }
    ]
}'

Example of a success response

{   
  "status": "SUCCESS" 
}

Skip payment

The request used to skip a particular payment of a recurrent task is /v1/payment/skip.

Request parameters

Required Name Type Description
Optional locale String [2] Language in ISO 639-1. If not specified, the default language will be used.
Mandatory

userName String [1..100] Merchant's API account login.
Mandatory

password String [1..200] Merchant's API account password.
Mandatory taskIdentifier Object The unique identifier or set of identifiers of the task. See nested parameters.
Mandatory paymentNumber Integer Number of the recurring payment to be skipped.

Below are the parameters of the taskIdentifier block (set of identifiers for a recurrent task).

Required Name Type Description
Optional merchantLogin String Merchant login. Should be present for searching by merchantTaskUuid.
Optional merchantTaskUuid String The unique identifier of the task being created within the merchant. Required if taskUuid is not present.
Optional taskUuid String The unique identifier of the task within the recurring payments service. Required if merchantTaskUuid is not present.

Response parameters

Required Name Type Description
Mandatory status Object Response status. Allowed values: SUCCESS, FAIL.
Mandatory task Object Information about the recurrent task. See nested parameters.

Below are the parameters of the task block (data about the activated recurrent task).

Required Name Type Description
Mandatory updated String Date/time of the last update of the task.
Mandatory merchantLogin String Merchant login.
Mandatory merchantTaskUuid String The unique identifier of the task within the merchant.
Mandatory nextPaymentDate String Next payment date.
Mandatory taskUuid String The unique identifier of the task within the recurring payments service.
Mandatory state String Task state. Allowed values:
  • CREATED - created, no payments yet
  • ACTIVE - created and at least one payment has been already proceeded
  • FAILED - exceeded max payment attempts and deactivated
  • COMPLETED - reached EOL date, all payments completed
  • TERMINATED - terminated by either client via processing or merchant
  • EXPIRED - card expired

Examples

Request example

curl --request POST \
--url https://dev.bpcbt.com/recurrent/v1/payment/skip \
--header 'Content-Type: application/json' \
--data '{
    "locale":"EN",
    "username":"test_user",
    "password":"test_user_password",
    "taskIdentifier": {
           "taskUuid":"7ae881fb-aee0-4446-883c-8087512bd26a"
     },
    "paymentNumber": 2
}'

Example of a success response

{
  "status": "SUCCESS",
  "task": {
    "updated": "2024-01-24T10:23:35.434591+03:00",
    "merchantLogin": "testMerch",
    "taskUuid": "8a6a5350-1be3-456e-8e81-e5c7eafbd699",
    "state": "ACTIVE",
    "nextPaymentDate": "2024-01-25T00:00:00+03:00",
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82"
  }
}

Callback notifications

The payment gateway API allows you to receive callback notifications on changes of payment statuses.

General information

Events that can trigger notifications

You can receive notifications about changes in order payment status and other events in the Payment Gateway.

The most common notifications describe changes in order status, such as:

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

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

Integration with callback

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

Make use of returnUrl

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

getOrderStatusExtended.do

curl --request POST \
  --url https://dev.bpcbt.com/payment/rest/getOrderStatusExtended.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=016b6f47-4628-7ea2-80f5-6c6e00a7d8c0 \
  --data language=en
{
  "errorCode": "0",
  "errorMessage": "Success",
  "orderNumber": "11008",
  "orderStatus": 2,
  "actionCode": 0,
  "actionCodeDescription": "",
  "amount": 2000,
  "currency": "978",
  "date": 1618577250840,
  "orderDescription": "my_first_order",
  "merchantOrderParams": [
    {
      "name": "browser_language_param",
      "value": "en"
    },
    {
      "name": "browser_os_param",
      "value": "UNKNOWN"
    },
    {
      "name": "user_agent",
      "value": "curl/7.75.0"
    },
    {
      "name": "browser_name_param",
      "value": "DOWNLOAD"
    }
  ],
  "transactionAttributes": [],
  "attributes": [
    {
      "name": "mdOrder",
      "value": "016b7747-c4ed-70b3-bc36-fdd400a7d8c0"
    }
  ],
  "cardAuthInfo": {
    "maskedPan": "555555**5599",
    "expiration": "202412",
    "cardholderName": "TEST CARDHOLDER",
    "approvalCode": "123456",
    "pan": "555555**5599"
  },
  "authDateTime": 1618577288377,
  "terminalId": "123456",
  "authRefNum": "931793605827",
  "paymentAmountInfo": {
    "paymentState": "DEPOSITED",
    "approvedAmount": 2000,
    "depositedAmount": 2000,
    "refundedAmount": 0
  },
  "bankInfo": {
    "bankCountryCode": "UNKNOWN",
    "bankCountryName": "&ltUnknown&gt"
  }
}

Make use of a signed gateway callback

If you know how to handle digital certificates and signatures, you can use a digitally signed callback with a checksum that the gateway may be configured to send. A checksum is used for verification and security purposes. After the callback signature has been verified on your side, there is no need to send getOrderStatusExtended because the callback includes the order status.

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=1

Types of notifications

Notifications without checksums

These notifications contain only information about the order, so potentially, the merchant risks accepting a notification sent by an attacker as genuine.

Notifications with checksums

These notifications contain an authentication code in addition to order information. The authentication code is a checksum of order data. This checksum allows to make sure that the callback notification is genuine and was sent by the payment gateway.
There are two methods of implementing callback notifications with checksums:


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

Requirements for SSL certificates on the store’s website

If a callback is delivered over HTTPS connection, the identity of the merchant's website must be verified with an SSL certificate issued and signed by a trusted certificate authority (check the table below). Self-signed certificates are not allowed.

Requirement Description
Signature algorithm. Not lower than SHA-256.
Supported certification authorities. Below are examples of organizations that register digital certificates:

URL format for callback notifications

POST and GET requests can be sent.

Below is an example for a GET request. The parameters are received in the query.

Notification without a checksum (GET)

https://mybestmerchantreturnurl.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 (GET)

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

For POST callbacks, you will receive the same parameters in HTTP body (instead of query parameters).

Notification without a checksum (POST)

https://mybestmerchantreturnurl.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 (POST)

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 also use additional parameters if they are configured in Payment Gateway.

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;
  • bindingCreated - payer's card has been saved (a credential was stored);
  • bindingActivityChanged - an existing stored credential was disabled/enabled;
  • declinedByTimeout - payment was declined because it timed out;
  • declinedCardPresent - 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

You can request the technical support service to set custom headers for callback notifications. For example:

'http://mybestmerchantreturnurl.com/callback.php', headers={Authorization=token, Content-type=plain
/text}, params={orderNumber=349002, mdOrder=5ffb1899-cd1e-7c1e-8750-e98500093c43, operation=deposited, status=1}

where {Authorization=token, Content-type=plain/text} is a custom header.

Examples

Example of a notification URL without a checksum

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0

Example of a notification URL with a checksum

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=0

Algorithm for processing callback notifications

Sections below contain notification processing algorithms depending on notification type.

Notification without a checksum

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

Notification with a checksum

  1. The payment gateway sends the following HTTPS request to the merchant's server - please, note that:

    • when using symmetric cryptography, the checksum is generated using a key common for the payment gateway and the merchant;
    • when using asymmetric cryptography, the checksum is generated using a private key known only to the payment gateway.
      https://mybestmerchantreturnurl.com/path?amount=123456&orderNumber=10747&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&mdOrder=3ff6962a-7dcc-4283-ab50-a6d7dd3386fe&operation=deposited&status=1
      The order of the parameters in a notification can be arbitrary.
  2. On the merchant's side checksum and sign_alias parameters are removed from the notification parameters string, and the value of checksum parameter is saved for verification of the notification's authenticity.

  3. The parameters and their values that are left are used for creating the following string.
    parameter_name1;paramenter_value1;parameter_name2;paramenter_value2;…;parameter_nameN;paramenter_valueN;
    In this case pairs name_parameter;value_parameter must be sorted in direct alphabetical order (ascending) by parameter names.
    Here is an example of a generated parameter string
    amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;

  4. The checksum is calculated on the merchant's side, the method of calculation depends on the method of its formation:

    • when using symmetric cryptography - with the help of HMAC-SHA256 algorithm and a private key shared with the payment gateway;
    • when using asymmetric cryptography - with the help of a hashing algorithm that depends on how the key pair is created and a public key that is associated with a private key located in the payment gateway.
  5. In the resulting checksum string, all lower-case letters are replaced by upper-case letters.

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

  7. If the checksums match, the server sends an HTTP code 200 OK to the payment gateway.

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

Payment status notification

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

  1. Check the signature (checksum parameter in callback);
  2. Check two callback parameters: operation and status.

If the operation value is approved or deposited, then the callback refers to the payment.

When notifications fail

If a response other than 200 OK is returned to the payment gateway, the notification is considered unsuccessful. In this case, the payment gateway repeats the notification at intervals of 30 seconds until one of the following conditions is met:

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

Additional callback parameters

In callback notifications, you can use the following additional parameters if they are configured in the Payment Gateway. If you need them, contact our support team.

Parameter Description Type of event
bindingId UUIID of created/updated stored credential. BINDING_CREATED, BINDING_ACTIVITY_CHANGED
email Client's email. BINDING_CREATED
phone Client's phone number. BINDING_CREATED
panMasked Masked PAN of the client's card. BINDING_CREATED
panCountryCode Client's country code. BINDING_CREATED
enabled Whether a store credential is active (true/false). BINDING_ACTIVITY_CHANGED
currentReverseAmountFormatted Formatted amount of the reversal operation. REVERSED
currentRefundAmountFormatted Formatted amount of the refund operation. REFUNDED
operationRefundedAmountFormatted Formatted amount of the refund operation. REFUNDED
operationRefundedAmount Refund amount in minor currency units (e.g. in cents etc.). REFUNDED
externalRefundId External identifier of the refund operation. REFUNDED
callbackCreationDate Callback notification creation date. Special merchant setting is required. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
status Operation status: 1 - success, 0 - failure DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
operation Callback type. Possible values: deposited, approved, reversed, refunded, bindingCreated, bindingActivityChanged, declinedByTimeout, declinedCardpresent DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
finishCheckUrl URL for receipt generation DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
sign_alias Name of the key used for signature. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
checksum Callback shecksum (used for callbacks with checksum). DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
cardholderName Cardholder name. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
amount Registered order amount in minor currency units. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentAmount Registered order amount in minor currency units. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
amountFormatted Formatted registered order amount. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
feeAmount Fee amount in minor currency units. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
approvedAmount Preauthorized amount in minor currency units. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
depositedAmount Deposited amount in minor currency units. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
refundedAmount Refund amount in minor currency units. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
approvedAmountFormatted Formatted preauthorized amount. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
depositedAmountFormatted Formatted deposited amount. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
refundedAmountFormatted Formatted refunded amount. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
totalAmountFormatted Formatted total order amount (registered amount + fee). DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
depositedTotalAmountFormatted Formatted total deposited amount (all deposited amounts + all refunded amounts + fee). DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
approvalCode Payment authorization code received from processing. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
authCode Authorization code. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
bankName Name of the bank that issued the client's card. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
currency Order currency. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
depositFlag The flag that specifies the type of the operation.
  • 1 - purchase
  • 2 - preauthorization
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
eci Electronic commerce indicator. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
ip Client's IP address. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
ipCountryCode Country code of the client's IP address. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
maskedPan Masked number of the client's card. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
mdOrder Order number in the payment gateway. Unique within the payment gateway. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
mdorder Order number in the payment gateway. Unique within the payment gateway. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
merchantFullName Merchant's full name. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
merchantLogin Merchant's login. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
orderDescription Order description. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
orderNumber Order number (ID) in the merchant's system. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
threeDSType Type of transaction in terms of 3 DS. Possible values: SSL, THREE_DS1_FULL, THREE_DS1_ATTEMPT, THREE_DS2_FULL, THREE_DS2_FRICTIONLESS, THREE_DS2_ATTEMPT DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
date Date of the order creation. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
clientId Customer number (ID) in the merchant's system. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT,BINDING_CREATED, BINDING_ACTIVITY_CHANGED
actionCode Code of the operation execution result. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
actionCodeDescription Description of the code of the operation execution result. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentRefNum Reference Retrieval Number - transaction ID assigned by Acquiring Bank. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentState Order status. Possible values: started, payment_approved, payment_declined, payment_void, payment_deposited, refunded, pending, partly_deposited DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentWay Order payment way. Find more possible values of the parameter here. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
processingId Identifier of the customer in processing. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
refNum Reference Retrieval Number - transaction ID assigned by Acquiring Bank. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
refnum Reference Retrieval Number - transaction ID assigned by Acquiring Bank. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
terminalId Terminal identifier in the system that processes the payment. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentSystem Payment system name. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
currencyName ISO 3-Letter Currency Code. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
transactionAttributes Order attributes. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
paymentDate Order payment date. DEPOSITED, APPROVED, REVERSED, REFUNDED
depositedDate Date of order deposit operation. DEPOSITED, APPROVED, REVERSED, REFUNDED
refundedDate Date of order refund operation. REFUNDED
reversedDate Date of order reversal operation. DEPOSITED, REVERSED, REFUNDED
declineDate Date of order cancellation. DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
xid Electronic commerce indicator of the transaction defined by the merchant. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
cavv Cardholder authentication value. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
authValue Cardholder authentication value. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
sessionExpiredDate Date and time of the order expiration. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
tokenizeCryptogram Tokenized cryptogram. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
creditBankName Name of the bank that issued the card to be credited (in P2P). DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
creditPanCountryCode Country code of recipient card (in P2P). DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
isInternationalP2P Whether P2P transfer is international. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
recipientData Information about P2P recipient. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
transactionTypeIndicator Information about P2P recipient. Possible values:
  • A – Account-to-Account Transfer.
  • P – Person-to-Person Transfer.
  • O - Loan-Prepayment Transfer.
  • D - Funds Disbursement.
  • L - Card Bill Payment.
  • G - Online Gambling Payout.
  • W - Transfer to Own Staged Digital Wallet Account.
  • F - Transfer to Own Stored Digital Wallet Account.
DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
operationType Type of P2P operation: AFT/OCT. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
debitBankName Name of the bank that issued the card to be debited (in P2P). DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
debitPanCountryCode Country code of the card tp be debited (in P2P). DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
p2pDebitRrn RRN (Reference Retrieval Number) of P2P debit operation. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
avsCode A code of the AVS verification response (checking the address and postal code of the cardholder). Possible values:
  • -1 – postal code and address are the same.
  • 1 – address matches, postal code doesn't match.
  • 2 - postal code matches, address doesn't match.
  • 3 - postal code and address don't match.
  • 50 - data validation is requested, but the result is unsuccessful.
  • 51 - invalid format of the AVS/AVV verification request.
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT

Code examples

Symmetric cryptography

Java
package net.payrdr.test;

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

public class SymmetricCryptographyExample {

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

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

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

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

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

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

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

        return hMacSHA256.doFinal(dataBytes);
    }

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

Asymmetric cryptography

Java
package net.payrdr.test;

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

public class AsymmetricCryptographyExample {

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

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

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

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

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

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

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

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

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

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

Symmetric cryptography

PHP
<?php

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

echo "[$hmac]\n";
?>
  1. Assign the string value to data variable.
  2. Assign the private key value to the key variable.
  3. hash_hmac function ( 'sha256', $data, $key) calculates the checksum of the passed string using the private key and SHA-256 algorithm.
  4. Save the function output in hmac variable.
  5. Use echo function to create an output.
  6. Compare this value with the one passed in the callback notification.

Asymmetric cryptography

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

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

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