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

Mandatory parameters

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

• Mandatory - the parameter must always be included. If it is not provided, an empty value should be passed, depending on the expected format;
• Optional - the parameter may be included or excluded, and its excessive inclusion will not cause a system error;
• Conditional - the parameter can either be included (be mandatory) or excluded, depending on one or more specified conditions.

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

Authentication

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

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

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

API URLs

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

Errors

HTTP status codes:

• 200 - in case of the Payment Gateway API calls the JSON payload from the response must be inspected to determine whether processing was successful or not. Success is indicated by either:
  - the success parameter value being true
  - the errorCode parameter value being 0
  If both parameters are present, success overrides errorCode.

• 400 - an internal error occurred in the system.

• 404 - error while calling API - URL is incorrect (does not exist).

• 429 - this code means that the system is overloaded. Most often the main reason is that the limit of requests per second or limit of simultaneous requests is reached. But it may also be due to the fact that the system as a whole is overloaded (regardless of your requests).

• 500 or 502 - this code means that something went wrong on our side.

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

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

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.
   

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:

• All the request parameters are included into the request body (not into the URL).

• If the request parameters are in JSON format, then the following header should be used:

  --header 'content-type: application/json'

• If the request parameters are in Query format (like parameterA=valueA&parameterB=valueB), then the following header should be used:

  --header 'content-type: application/x-www-form-urlencoded'

• The request contains correct login and password of the API user.

• The X-Hash header contains SHA256 hash of the request body (calculated at step 1).

• The X-Signature header contains the signature for the calculated SHA256 hash with RSA algorythm using the private key (generated at step 2).

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

To register an order, use https://dev.bpcbt.com/payment/rest/register.do request.

When sending the request, you should use the header: Content-Type: application/x-www-form-urlencoded

Request parameters

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

| features | String | Features of the order. To specify multiple features, use this parameter several times in one request. 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. 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).
• PARTIAL_AUTHORIZATION - partial authorization is available in the order. Read more here.
• FORCE_PAYMENT_WAY - force payment by the payment method specified in jsonParams in the paymentWay parameter. To process these payments merchant must have sufficient permissions in the payment gateway.
  This is currently used for force MOTO payments. To enable this, it is necessary to pass also paymentWay parameter with the value CARD_MOTO in jsonParams.

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

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

| feeInput | Integer [0..8] | Fee amount in minimum currency units. Must be enabled by respective Merchant-level permission in the Gateway. |

| email | String [1..40] |Email to be displayed on the payment page. Customer's email must be passed if client notification is configured for the merchant. Example: client_mail@email.com.
The email will not be validated on registration. It will be later validated on payment. |

| mcc | Integer [4] | Merchant Category Code. Using this parameter requires a special permission. You can use only the values from the predefined list of allowed MCC values. Contact the support team for details. |

| mvv | String [1..10] | Merchant verification value from Mastercard for tokenized transactions. To pass this parameter, a special setting must be enabled (contact technical support). |

| billingAndShippingAddressMatchIndicator | String [1] | 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).

| payerIdNumber | String [1..100] | Number of the payer's identifying document (e.g. passport) provided. |

| payerBirthday | String [1..20] | Payer's birth date in the YYYYMMDD format. |

Description of parameters in shippingPayerData object:

Description of parameters in preOrderPayerData object:

Description of parameters in orderPayerData object:

Description of parameters in marketplace object:

Description of parameters of the object that is an element of the retailers array.

Example of a marketplace object:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Description of parameters in orderBundle object:

Description of parameters in customerDetails object:

Description of parameters in deliveryInfo object.

Description of parameters in cartItems object.

Description of parameters in items object.

Description of parameters in quantity object.

Description of parameters in itemDetails object.

Description of parameters in itemDetailsParams object.

Description of parameters in the paymentFacilitator object:

Parameters of an object in subMerchants array:

Parameters of the address object:

Example of paymentFacilitator object:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Response parameters

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

| 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=123456 \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderNumber=1234567890ABCDEF \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data failUrl=https://mybestmerchantfailurl.com \
  --data email=test@test.com \
  --data clientId=259753456 \
  --data features=FORCE_SSL \
  --data language=en \
  --data 'jsonParams={"param_1_name":"param_1_value","param_2_name":"param_2_value"}'

Response example - success

{
  "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
  "formUrl": "https://dev.bpcbt.com/payment/payment/merchants/ecom/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}

Response example - fail

{
  "errorCode": "1",
  "errorMessage": "Order number is duplicated, order with given order number is processed already"
}

Order pre-authorization

The method used for registration of an order with preauthorization is https://dev.bpcbt.com/payment/rest/registerPreAuth.do.

When sending the request, you should use the header: Content-Type: application/x-www-form-urlencoded

Request parameters

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

| expirationDate | String [19] | Date 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. |

| 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 credential;
• The payer will be redirected to a payment page where only CVC entry is required. |

| features | String | Features of the order. To specify multiple features, use this parameter several times in one request. 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. 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).
• PARTIAL_AUTHORIZATION - partial authorization is available in the order. Read more here.
• FORCE_PAYMENT_WAY - force payment by the payment method specified in jsonParams in the paymentWay parameter. To process these payments merchant must have sufficient permissions in the payment gateway.
  This is currently used for force MOTO payments. To enable this, it is necessary to pass also paymentWay parameter with the value CARD_MOTO in jsonParams.

| autocompletionDate | String [19] | The date and time when the two-phase payment must be completed automatically in the following format: 2025-12-29T13:02:51. The used timezone is UTC+0. To enable sending this field to the processing system, contact your technical support service. |

| autoReverseDate | String [19] | The date and time when the two-phase payment must be reversed automatically in the following format: 2025-06-23T13:02:51. The used timezone is UTC+0. To enable sending this field to the processing system, contact your technical support service. |

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

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

| feeInput | Integer [0..8] | Fee amount in minimum currency units. Must be enabled by respective Merchant-level permission in the Gateway. |

| email | String [1..40] |Email to be displayed on the payment page. Customer's email must be passed if client notification is configured for the merchant. Example: client_mail@email.com.
The email will not be validated on registration. It will be later validated on payment. |

| mcc | Integer [4] | Merchant Category Code. Using this parameter requires a special permission. You can use only the values from the predefined list of allowed MCC values. Contact the support team for details. |

| mvv | String [1..10] | Merchant verification value from Mastercard for tokenized transactions. To pass this parameter, a special setting must be enabled (contact technical support). |

| billingAndShippingAddressMatchIndicator | String [1] | 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).

| payerIdNumber | String [1..100] | Number of the payer's identifying document (e.g. passport) provided. |

| payerBirthday | String [1..20] | Payer's birth date in the YYYYMMDD format. |

Description of parameters in shippingPayerData object:

Description of parameters in preOrderPayerData object:

Description of parameters in orderPayerData object:

Description of parameters in marketplace object:

Description of parameters of the object that is an element of the retailers array.

Example of a marketplace object:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Description of parameters in orderBundle object:

Description of parameters in customerDetails object:

Description of parameters in deliveryInfo object.

Description of parameters in cartItems object.

Description of parameters in items object.

Description of parameters in quantity object.

Description of parameters in itemDetails object.

Description of parameters in itemDetailsParams object.

Description of parameters in the paymentFacilitator object:

Parameters of an object in subMerchants array:

Parameters of the address object:

Example of paymentFacilitator object:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Response parameters

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

| 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

To initiate payment on earlier registered order https://dev.bpcbt.com/payment/rest/paymentorder.do request is used.
Request is used in Internal 3DS Server mode, you don't need any additional permissions and/or certifications.
Request is used in External 3DS Server mode if you have agreement with Payment System or special Certificate, which alows you to perform 3DS authentacation on your own. It means, that you can use your own 3DS Server to authenticate your client using 3D Secure technology. Read more about payment with your own 3DS Server here.

When sending the request, you should use the header: Content-Type: application/x-www-form-urlencoded

Payment for order (internal 3DS Server)

Payment is initiated using payment card data and using 3DS authentication (authentication is regulated by permissions, managed by Support).

Request parameters

| jsonParams | Object | A set of additional free-form attributes, structure: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}.
These fields can be passed to the Processing Center for further processing (additional setup is needed, please contact Support).
If you use your own 3DS Server the payment gateway expects that every paymentOrder request will include the following additional parameters such as eci, cavv, xid etc. Please refer here for more information.
To initiate 3RI authentication in case when there is no stored credentials, you may need to pass a number of additional parameters (see 3RI authentication for details).
Some pre-defined jsonParams attributes:

• 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.
• totalInstallmentAmount - total sum of all installment payments. Is required for creating an installment stored credential.
• recurringFrequency - minimum number of days between authorizations. Is required for creating a recurrent or installment stored credential.
• recurringExpiry - the date after which authorizations are not allowed, in YYYYMMDD format. Recommended for creating a recurrent or installment stored credential (mandatory for 3DS2)

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

|
Conditional

| email | String [1..40] | Email to be displayed on the payment page. Customer's email must be passed if client notification is configured for the merchant. Example: client_mail@email.com.
For payment by VISA with 3DS authorization, it is necessary to specify either phone or email of the cardholder. |

| mcc | Integer [4] | Merchant Category Code. Using this parameter requires a special permission. You can use only the values from the predefined list of allowed MCC values. Contact the support team for details. |

| mvv | String [1..10] | Merchant verification value from Mastercard for tokenized transactions. To pass this parameter, a special setting must be enabled (contact technical support). |

| originalSchemeTransactionId | String [1..22] | The identifier of the original successful Mastercard transaction.
Is mandatory when using merchant's stored credentials in stored credential transfers. |

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

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

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

| originalPaymentNetRefNum | String [1..36] | The identifier of the original or previous successful transaction in the payment system in relation to the performed stored-credential transaction - TRN ID. Is passed when tii = R,U, or F.
Is mandatory when using merchant's stored credentials in stored credential transfers.|

| originalPaymentDate | String | Date of initiating transaction. The format is Unix timestamp, in milliseconds. Is passed when tii = R,U, or F. |

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

| payerIdNumber | String [1..100] | Number of the payer's identifying document (e.g. passport) provided. |

| payerBirthday | String [1..20] | Payer's birth date in the YYYYMMDD format. |

Description of parameters in shippingPayerData object:

Description of parameters in preOrderPayerData object:

Description of parameters in orderPayerData object:

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

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

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":"x.x.x.x"
    }

Description of parameters in the paymentFacilitator object:

Parameters of an object in subMerchants array:

Parameters of the address object:

Example of paymentFacilitator object:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Description of parameters in marketplace object:

Description of parameters of the object that is an element of the retailers array.

Example of a marketplace object:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

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

Response parameters

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

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

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

| acsUrl | String [1..512] | The URL address for redirecting to ACS. It is returned in a successful response in case of a 3D-Secure payment, when redirect to the ACS is needed. For details see Redirect to ACS.|

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

payerData element contains the following parameters.

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

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 3DS2 protocol:

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 \
  --data 'jsonParams={"param_1_name":"param_1_value","param_2_name":"param_2_value"}'

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 order (external 3DS Server)

In order to use paymenOrder.do request in external 3DS Server mode, you need to perform 3DS authentication using your own 3DS Server.
Also, you need an additional permission managed by Support.

Request parameters

| jsonParams | Object | A set of additional free-form attributes, structure: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}.
These fields can be passed to the Processing Center for further processing (additional setup is needed, please contact Support).
If you use your own 3DS Server the payment gateway expects that every paymentOrder request will include the following additional parameters such as eci, cavv, xid etc. Please refer here for more information.
To initiate 3RI authentication in case when there is no stored credentials, you may need to pass a number of additional parameters (see 3RI authentication for details).
Some pre-defined jsonParams attributes:

• 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.
• totalInstallmentAmount - total sum of all installment payments. Is required for creating an installment stored credential.
• recurringFrequency - minimum number of days between authorizations. Is required for creating a recurrent or installment stored credential.
• recurringExpiry - the date after which authorizations are not allowed, in YYYYMMDD format. Recommended for creating a recurrent or installment stored credential (mandatory for 3DS2)

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

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

| email | String [1..40] | Email to be displayed on the payment page. Customer's email must be passed if client notification is configured for the merchant. Example: client_mail@email.com.
For payment by VISA with 3DS authorization, it is necessary to specify either phone or email of the cardholder. |

| mcc | Integer [4] | Merchant Category Code. Using this parameter requires a special permission. You can use only the values from the predefined list of allowed MCC values. Contact the support team for details. |

| mvv | String [1..10] | Merchant verification value from Mastercard for tokenized transactions. To pass this parameter, a special setting must be enabled (contact technical support). |

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

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

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

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

| payerIdNumber | String [1..100] | Number of the payer's identifying document (e.g. passport) provided. |

| payerBirthday | String [1..20] | Payer's birth date in the YYYYMMDD format. |

Description of parameters in shippingPayerData object:

Description of parameters in orderPayerData object:

Description of parameters in preOrderPayerData object:

Description of parameters in orderPayerData object:

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

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

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":"x.x.x.x"
    }

Description of parameters in the paymentFacilitator object:

Parameters of an object in subMerchants array:

Parameters of the address object:

Example of paymentFacilitator object:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Description of parameters in marketplace object:

Description of parameters of the object that is an element of the retailers array.

Example of a marketplace object:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Response parameters

| 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/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",
  "threeDsType": "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 an Industry Practice transaction order

To pay for an order with Industry Practice transaction characteristics, use the request https://dev.bpcbt.com/payment/industryPractice/paymentOrder.do.

When sending the request, you should use the header: Content-Type: application/x-www-form-urlencoded

Request parameters

Possible values of tii:

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:

Response parameters

| 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/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 - successfull industry practice payment

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

Response example - 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 https://dev.bpcbt.com/payment/rest/instantPayment.do.

When sending the request, you should use the header: Content-Type: application/x-www-form-urlencoded

Request parameters

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

|
Optional

| description | String [1..598] | Order description in any format.
To enable sending this field to the processing system, contact the technical support service.
It is not allowed to fill this parameter with personal data or payment data (card numbers, etc.). This requirement is due to the fact that the order description is not masked in Merchant Portal and log files.|

| 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,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv. |

| 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 credential;
• The payer will be redirected to a payment page where only CVC entry is required. |

| originalSchemeTransactionId | String [1..22] | The identifier of the original successful Mastercard transaction.
Is mandatory when using merchant's stored credentials in stored credential transfers. |

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

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

| cvc | String [3] | The presence of this parameter is determined by payment type:

• cvc is provided not for all tokenized payments;
• cvc is not provided for MIT payments;
• cvc is mandatory by default for all other payment types; but if permission Can process payments without confirmation of CVC is enabled, cvc becomes optional in that case.

| cardholderName | String [2..45] | Cardholder's name in Latin characters. This parameter is passed only after an order is paid.
Such special characters as space, full stop, hyphen, apostrophe ( . - ') can be used. The use of other characters is prohibited. |

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

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

| autocompletionDate | String [19] | The date and time when the two-phase payment must be completed automatically in the following format: 2025-12-29T13:02:51. The used timezone is UTC+0. To enable sending this field to the processing system, contact your technical support service. |

| autoReverseDate | String [19] | The date and time when the two-phase payment must be reversed automatically in the following format: 2025-06-23T13:02:51. The used timezone is UTC+0. To enable sending this field to the processing system, contact your technical support service. |

| expirationDate | String [19] | Date 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. |

| seToken | String [1..8192] | 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. |

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

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

| jsonParams | Object | A set of additional free-form attributes, structure: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}.
These fields can be passed to the Processing Center for further processing (additional setup is needed, please contact Support).
If you use your own 3DS Server the payment gateway expects that every paymentOrder request will include the following additional parameters such as eci, cavv, xid etc. Please refer here for more information.
To initiate 3RI authentication in case when there is no stored credentials, you may need to pass a number of additional parameters (see 3RI authentication for details).
Some pre-defined jsonParams attributes:

• 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.
• totalInstallmentAmount - total sum of all installment payments. Is required for creating an installment stored credential.
• recurringFrequency - minimum number of days between authorizations. Is required for creating a recurrent or installment stored credential.
• recurringExpiry - the date after which authorizations are not allowed, in YYYYMMDD format. Recommended for creating a recurrent or installment stored credential (mandatory for 3DS2)

| features | String | Features of the order. To specify multiple features, use this parameter several times in one request. 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. 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).
• PARTIAL_AUTHORIZATION - partial authorization is available in the order. Read more here.
• FORCE_PAYMENT_WAY - force payment by the payment method specified in jsonParams in the paymentWay parameter. To process these payments merchant must have sufficient permissions in the payment gateway.
  This is currently used for force MOTO payments. To enable this, it is necessary to pass also paymentWay parameter with the value CARD_MOTO in jsonParams.

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

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

| threeDSServerTransId | String [1..36] | Transaction identifier created on 3DS Server. Mandatory for 3DS authentication. |

| threeDSVer2FinishUrl | String [1..512] | URL where Customer should be redirected after authentication on ACS Server. |

| threeDSMethodNotificationUrl | String [1..512] | URL where notification about performed 3DS-method should be sent to. |

| threeDSVer2MdOrder | String [1..36] | Order number which was registered in the first part of the request within 3DS2 transaction. Mandatory for 3DS2 authentication.
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.
This parameter is used only for instant payments, i.e., when the order is registered and payed via the same request. |

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

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

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

| email | String [1..40] | Email to be displayed on the payment page. Customer's email must be passed if client notification is configured for the merchant. Example: client_mail@email.com.
For payment by VISA with 3DS authorization, it is necessary to specify either phone or email of the cardholder. |

| mcc | Integer [4] | Merchant Category Code. Using this parameter requires a special permission. You can use only the values from the predefined list of allowed MCC values. Contact the support team for details. |

| mvv | String [1..10] | Merchant verification value from Mastercard for tokenized transactions. To pass this parameter, a special setting must be enabled (contact technical support). |

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

| originalPaymentNetRefNum | String [1..36] | The identifier of the original or previous successful transaction in the payment system in relation to the performed stored-credential transaction - TRN ID. Is passed when tii = R,U, or F.
Is mandatory when using merchant's stored credentials in stored credential transfers.|

| originalPaymentDate | String | Date of initiating transaction. The format is Unix timestamp, in milliseconds. Is passed when tii = R,U, or F. |

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

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

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

| billingAndShippingAddressMatchIndicator | String [1] | 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:

Description of parameters in customerDetails object:

Description of parameters in deliveryInfo object.

Description of parameters in cartItems object.

Description of parameters in items object.

Description of parameters in itemDetails object.

Description of parameters in itemDetailsParams object.

Description of parameters in quantity object.

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

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

| payerIdNumber | String [1..100] | Number of the payer's identifying document (e.g. passport) provided. |

Description of parameters in shippingPayerData object:

Description of parameters in preOrderPayerData object:

Description of parameters in orderPayerData object:

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

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":"x.x.x.x"
    }

Description of parameters in the paymentFacilitator object:

Parameters of an object in subMerchants array:

Parameters of the address object:

Example of paymentFacilitator object:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Description of parameters in marketplace object:

Description of parameters of the object that is an element of the retailers array.

Example of a marketplace object:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Response parameters

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

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

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

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

| acsUrl | String [1..512] | The URL address for redirecting to ACS. It is returned in a successful response in case of a 3D-Secure payment, when redirect to the ACS is needed. For details see Redirect to ACS.|

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

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

payerData element contains the following parameters.

orderStatus block contains the following elements.

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

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

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

| expiration | Integer [6] | Card expiration date in the following format: YYYYMM. |

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

| 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.
In case of partial authorization, this amount may be less than the order registration amount. |

| depositAmount | Integer [1..12] | Charged amount in minimum currency units (e.g., in cents).
In case of partial authorization, this amount may be less than the order registration amount. |

| currency | String [3] | ISO 4217 encoded currency key. If not specified, the default value is used. Only digits are allowed. |

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

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

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

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

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

| originalActionCode | String [1..15] | Response code received from the processing system. To enable receiving this field, contact the technical support service. |

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

| paymentNetRefNum | String [1..512] | Original Network Reference Number - a unique identifier assigned by the card network (e.g., Mastercard, Visa) to the original transaction (such as a purchase or authorization). When a follow-up transaction is initiated (e.g., refund, recurring payment), this number must be included to:

• Link the new transaction to the original one
• Ensure proper tracking and reconciliation
• Meet network compliance requirements

Below are the parameters of the tokenizationInfo block (data about card tokenization).

Example of tokenizationInfo block:

"tokenizationInfo": {
      "tokenId": "8d577a01-55f7-45d4-add5-bfe0e8e6c571",
      "tokenizationProvider": "vts",
      "panReference": "f441492a-5b0a-453d-af97-e897e1148dc5",
      "dpan": "5435982500356335",
      "tokenExpiry": "202912"
    }

• If errorCode <> 0 a transaction should be rejected.
• If errorCode = 0 and OrderStatus is not in (1,2) a transaction should be rejected.
• If errorCode = 0 and OrderStatus = 1 or 2 and acsUrl is null a transaction is approved.
• If errorCode = 0 and OrderStatus = 0 and acsUrl is null a transaction should be rejected.
• If errorCode =0 and OrderStatus = 0 and acsUrl is not null a 3DS flow should be initiated.

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=4000001111111118 \
--data cvc=123 \
--data expiry=203012 \
--data cardholderName="TEST CARDHOLDER" \
--data email="demo@example.com" \
--data phone="+449998887766" \
--data language=en \
--data returnUrl=https://mybestmerchantreturnurl.com \
--data failUrl=https://mybestmerchantreturnurl.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": "x.x.x.x"
    }
}

MOTO payment

The request used to carry out MOTO payments is https://dev.bpcbt.com/payment/rest/motoPayment.do.

When sending the request, you should use the header: Content-Type: application/x-www-form-urlencoded

Request parameters