NAV

For any question, we are one click away

Contact us

Getting Started

We offer multiple ways of adding payments to your website.

Simple Integration

First to consider are simple ways of integration that don't require any development effort on your part.

Advanced integration

Consider advanced integration options if you need to create a tailored payment flow. This will require in-house or third-party coding expertise.

Pay by link

You can issue an invoice to the buyer for payment for goods or services by e-mail. For this, use the Invoice to e-mail section ( in the navigation bar to the left). Once the invoice is issued, the buyer receives an e-mail and follows the link in it to the payment page.

To invoice a customer and send them a link to the payment page by email, follow these steps.

  1. Go to Invoice to e-mail section of the Personal Area. The page for entering the invoice parameters will be displayed:

  2. Configure the settings referring to the table below.

    Setting Description
    Payment type Choose from two options.
    • One-phase – after the payment has been made, no additional actions are required on your part.
    • Two-phase – after the client has confirmed the payment, you must complete the payment in your Personal Area. Before you do this, the money will be held (reserved) on the client's account until you confirm the payment or until the confirmation period expires.
      If you confirm the payment, the money will be transferred to your account.
      The reserved funds on client's account will be released if the reservation period expires before confirmation.
    Client name Client's first name, last name, and patronymic. The data entered in this field is displayed in an email containing a link to the payment page.
    E-mail The e-mail address to which the payment link will be sent.
    Due date Indicate the date and time by which the payment can be made. After this date and time it will be impossible to pay the invoice.
    Client ID Client number in your store’s system. If you specify this parameter, the client will see the Save my card check box on the payment page. If the client selects this check box, a credential will be stored after the payment is completed, and the client will not have to enter the card data next time.
    Description Free-form description of the payment.
    Enter the amount Enter the payment amount here. If the order contains a shopping cart, the field value is populated automatically.
  3. Click the Send button.

    Upon successful dispatch, a link to the payment form will be displayed below:

You can view the payment page sent to the client by clicking on the Link to payment page button.

Adding a shopping cart to invoice

When generating an invoice you can add a shopping cart for the order. The Cart section is located under the area for creating a link to payment page:

  1. To add a line item to the shopping cart, click on the Add product button. A row with the parameters of the product being added will be displayed.
  2. Fill in the required fields referring to the table below.

    Field Description
    ID Identifier of a line item in the cart. Filled in automatically.
    Name Product/service name.
    Price Price of one product unit.
    Qty The number of units of the product.
    Measure Units of measurement, for example: L – liters, pcs. – pieces.
    Amount The total amount for specified line item. Calculated automatically when the Price and Qty fields are filled out.
    Article The vendor code of the line item.
  3. Repeat the required steps for each item in the shopping cart. If you need to delete the added row, click on the icon.

Having added all items to the shopping cart, invoice the client.

Making a test transaction

You can test the payment process on behalf of the client. To do so:

  1. Create an invoice for the client.
  2. Go to the payment page by clicking on the Link to payment page button in the invoice-issued-successfully message.
  3. Enter the details of one of the test cards. Leave the Cardholder name field blank.
  4. Select Save my card if you want to store the credential: in this case, you will not have to enter the card data next time.
  5. Click on the Pay button. To confirm the transaction, use the 3-D Secure code specified for the test card.

Final page

After successfull payment, the client can optionally be redirected to the Final page. This page contains data about the payment and a link back to the store.

The table below describes the data displayed on the final page.

Field Description
Merchant Merchant’s login.
Web-site Merchant’s website address.
ID Automatically generated order number in the merchant’s system.
Authorization code International payment system authorization code (6 symbols).
Terminal ID Terminal identifier in the system that processes the payment.
Reference ID (RRN) Reference number of the payment authorization that has been assigned to it upon its registration.
Amount Payment amount.
Description Description of the payment.
Card information Masked number and expiration date of the card used for payment.

For the client to go back to the store, they would click the Return to Merchant link.

You can enable or disable showing the final page using the Show final page check box on the General settings page of your Personal Area. Read more here.

Redirect integration

Redirect integration is a simple and secure process that uses the payment page on the payment gateway side. The main advantage of this integration method is that you don't need to collect and process card data on your website. The API is used minimally in this case, so this method does not require much development expertise.

Redirect integration

  1. A customer selects a product in the online store, and then clicks Buy.

  2. The online store server receives a purchase request.

  3. The online store server requests an order registration by sending the register.do API call to the payment gateway. This request must contain the amount parameter (the payment amount in minor currency units) and the returnUrl parameter (the address to which the customer will be redirected after successfull payment in step 9).

    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 currency=978 \
    --data userName=test_user \
    --data password=test_user_password \
    --data returnUrl=https://mybestmerchantreturnurl.com \
    --data description=my_first_order \
    --data language=en
    

    Alternatively, you can hold the amount on account before the charge by using the registerPreAuth.do call. For more details about hold and capture, click here.

  4. The payment gateway server registers an order and sends a response to the online store server. The response contains the formUrl parameter (the payment URL to which the online store should redirect the customer in step 5) and the orderId parameter (the unique order number in the payment gateway system, will be used in step 10).

    Response example:

    {
    "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
    "formUrl": "https://dev.bpcbt.com/payment/merchants/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
    }
    
  5. The online store redirects the customer to the URL received in the formUrl parameter. The redirection may be done in the same window or in a new window.

  6. The payment gateway opens the payment URL.

  7. The customer enters his or her card number, expiration date, and CVV/CVC, and clicks Pay.

    Alternatively, it is possible to use tokenized payments via Apple Pay, Samsung Pay, or Google Pay wallets. In this case the customer selects the corresponding option. Read more about using tokenized payments here.

  8. The payment gateway processes the payment request.

  9. The customer is redirected to the online store page defined in the returnUrl parameter (specified in step 3).

  10. The online store sends the getOrderStatusExtended.do request to the payment gateway to check the order status and make sure the order is really paid. The request contains the orderId parameter received in step 4. In response, the payment gateway returns the order status in the orderStatus parameter. Status 2 means a succesfull payment. Additionally, the actionCode parameter is returned - it contains the response code from the processing bank. See the list of response codes here. Find more details in the Getting the order status section.

Direct Payment

Overview

In this scheme, an online store has its own payment page to collect card data natively through its web site.

Direct integration

  1. A customer selects a product in the online store, and then clicks Buy.

  2. The online store server receives a purchase request and opens a payment page.

  3. The customer enters their card details on the online store payment page.

  4. The online store server collects the card data.

  5. The online store server requests an order registration by sending register.do API call. This request must contain the amount parameter (the payment amount in minor currency units) and the returnUrl parameter (the address to which the user will be redirected if the payment is successful in Step 10). In response, the payment gateway sends orderId - the unique order number in the payment gateway system.

    Order registration 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 currency=978 \
    --data userName=test_user \
    --data password=test_user_password \
    --data returnUrl=finish.html \
    --data description=my_first_order \
    --data language=en
    

    Order registration response example:

    {
    "orderId": "0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0",
    "formUrl": "https://dev.bpcbt.com/payment/merchants/pay/payment_en.html?mdOrder=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0"
    }
    

    Alternatively, you can hold the amount on account before the charge by using the registerPreAuth.do call. For more details about hold and capture, click here.

    Then the online store passes card data to pay the order by sending the paymentOrder.do API call to the payment gateway. This request contains the MDORDER parameter - the unique order number in the payment gateway system returned in the register.do response.

    Payment order 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=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0 \
    --data '$PAN=4000001111111118' \
    --data '$CVC=123' \
    --data YYYY=2030 \
    --data MM=12 \
    --data 'TEXT=TEST CARDHOLDER' \
    --data 'ip=185.230.240.201' \
    --data language=en
    

    Order registration response example:

    {
    "info": "Your order is proceeded, redirecting...",
    "errorCode": 0,
    "acsUrl": "https://web.payuat.com/acs/auth/start.do",
    "paReq": "eJxVUtFu4jAQ/BWU92DHcSCpFle946ryAEd7FKl9OZl4gbSNA05ypP36s0NSWsmSd8br3fGO4brJ3wb/0JRZoSdeMKTeAHVaqEzvJt7j6taPvWsBq71BnP7BtDYoYI5lKXc4yNTEG48kj5KN8jfxOPH5NqZ+kiTURxYlSEMaxtvUE7C8ecCjgK6RsH2GDEgPbUWT7qWuBMj0+GO2EJyNR5QC6SDkaGZTEfGQhRzIGYGWOYpSarUpmr95VwJIS0Na1Loy72LEQyA9gNq8iX1VHa4IqbCshmmRA3EkkIuGZe2i0hZpMiUWH/en39NZs3j5xearHZ+vnk6LD7tPnyZAXAYoWaFglAWUB8mAjq/simIgLQ8yd93tefugM4CD63Hz9eQrA3bQxvrQy+8RYHMoNLo7QD5jeHDGCNgaPNZtXgTkAgC1OmdYiZwGNLB3ewpIv19e/fPO+ZBWdsYvxamWr6rcnNaqWMuQrbF+zqLlXbQ7OHfaJKcqs9NlPDjLcgCIK0M640n3Z2z07S/9Bypv08k=",
    "termUrl": "https://dev.bpcbt.com/payment/rest/finish3ds.do?lang=en"
    }
    

    Alternatively, you can use API methods for direct payments via Apple Pay, Samsung Pay, or Google Pay.

    Read more about tokenized payments here.

  6. If 3-D Secure is required (the acsUrl parameter is returned in Step 5), the payment gateway communicates with the Directory Server to reach the ACS. It returns all the data necessary for the ACS redirect to the online store.

    If 3-D Secure is not used, the Steps 7-9 are omitted and the customer is redirected to the payment confirmation page (Step 10). The redirect parameter is ignored in this case as the online store uses its own payment confirmation page.

  7. The online store server requests simplified customer redirect to the ACS by sending the acsRedirect.do API call to the payment gateway. The orderId parameter (received in Step 5) is used in the request.

    Request example:

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

  8. The payment gateway redirects the customer to the ACS.

  9. The cardholder confirms the order and the ACS redirects him or her to the payment gateway.

  10. The customer returns to the online store page (to the URL specified during the order registration in Step 5) or closes the page.

    Redirect URL example:

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

  11. The payment gateway sends an asynchronous callback notification to the online store server.

  12. The online store sends the getOrderStatusExtended.do request to the payment gateway to check the order status and make sure the order is really paid. The request contains the orderId parameter received in Step 5. In response, the payment gateway returns the order status in the orderStatus parameter. Status 2 means a successful payment, status 1 means a successful pre-authorization for two-phase payments (the amount needs to be captured in this case). Additionally, the actionCode parameter is returned - it contains the response code from the processing bank. See the list of response codes here.

    Find more details in the Getting the order status section.

Secure card data transfer

If you collect card data on your side and don't want it to be present on your server, you should use seToken.

Please note that seToken can be generated via SDK.

Click here to get more information about seToken.

After the payment

Once a payment is made, you can manage it in your Personal Area on Merchant Portal or over the API. Read the sections below to learn more.

Reversal & Refund

If you want to cancel the payment, you can perform one of two operations, depending on the order status: reversal or refund. These operations are described below.

Reversal

Reversal means that the transaction is cancelled and all the funds reserved on the client’s account are released. This operation can be applied to two-phase transactions, when the funds are reserved but not captured yet (Approved status). After the reversal, the transaction gets the Reversed status.

The following ways of reversal are available:

Reversal can be made only before the end of the current bank day.

Refund

Refund means returning already captured funds to the customer. This operation can be applied to one-phase or two-phase transactions when the funds are already captured (Deposited status). You can make refund more than once, but for a total amount not exceeding the initial captured amount.

The following ways of issuing a refund are available:

Both reversal and refund can trigger callback notifications. Read more here.

Getting the order status

You can check the order status at any moment. For example, you may check it after the payment to make sure the order is really paid. The status of the order is available on the Merchant Portal and can also be retrieved over the API.

Looking up the order status on Merchant Portal

You can see the order status in the Transaction details page of the corresponding transaction. In particular, status Deposited means a succesfull payment.

Getting the order status over the API

The online store sends the getOrderStatusExtended.do request to the Payment Gateway to check the order status. The request contains either orderId (the unique order number in the payment gateway) or orderNumber (the unique order number in the online store’s system). If both parameters are passed to the payment gateway, orderId has higher priority.

The payment gateway returns the order status in the orderStatus parameter. Status 2 means a succesfull payment.

Additional functionality

Two-phase payments

Types of payment

A company may use two types of payments, depending on the specifics of its business:

The amount to be debited may differ from the holding amount to a greater or lesser extent.

Two-phase payments should be used if some time elapses between the buyer's decision to pay and delivery of the selected good or service

For the payment to be a two-phase payment, the order must be registered via registerPreAuth.do request, not register.do.

Two-phase payment is suitable for any method of integration:

For Redirect, Direct, CMS, SDK integration options, it is possible to register and complete an order via API.

Captures

A capture of a pre-authorized amount happens in the second phase of the two-phase payment, when the funds are debited from card holder's account. Once the capture occurs, the order becomes completed and goes in the DEPOSITED status. The amount captured can be greater or less than the pre-authorization amount, and partial capture in increments is available as well. If you do not pass the amount, then the full amount will be executed.

There are three ways to make a capture:

It is available to do a partial capture. It will be less than the order amount and immediately final. This is the default if you do not pass depositType. Also, you can make multiple captures on the Merchant Portal and over the API.

Multiple captures on Merchant Portal

An order can be completed in parts, rather than the full amount. This is incremental completion of the same order, not batch completion of multiple orders at once.

Firstly, go to the Pay by Link block and create a two-phase payment:

As the invoice is successfully issued, send a link to client:

A client enters card details and confirms payment:

Then go to the Transaction details block and click Complete button to deposit the payment:

In newly opened window enter the amount:

As a final result you see a new Deposited status of payment:

Multiple captures over the API

To perform a payment completion, you must pass the depositType and multipleCompletionOrderDescription parameters in the request deposit.do:

depositType - type of the deposit. Possible values:

multipleCompletionOrderDescription - Description of the multiple completion transaction. The parameter is allowed only if the "Multiple Completions Allowed" permissions are enabled and depositType = 1 or 2

Autocompletion and Autoreversal

You can set up your payment integration so that orders would be completed and/or reversed automatically after a specific time period by making use of autocompletion and autoreversal. This means that you don't have to process each order manually in the Merchant Portal (and in case of API integration, there's no need to call deposit.do and/or reverese.do methods).

Stored-credential transactions

A stored-credential transaction is used when a cardholder authorizes a merchant to store the payment credentials for further payments. For example, a payer may opt to save their card at checkout. In this case a unique token is generated by the Payment Gateway that links the payer's card number (PAN) to their ID in the store system (for example, to payer's login).

Read about the types of stored credentials supported by the Payment Gateway here.

Storing a credential

Storing a credintial on file

You can store a payer's credential on file via API or via the Merchant Portal UI for any type of integration. The main requirement is passing the client ID in the store system to the Payment Gateway. See the details below.

Storing a credential upon payment via API

To store a credential upon payment via API, it is enough to pass the clientId parameter in any payment request. The credential will be stored when the payment is completed.

To store a credential upon payment via UI

To store a credential upon payment via UI, go to the Personal Area, issue the invoice via the e-mail and make sure to specify the Client ID parameter. As a result, the client will see the Save my card checkbox on the payment page. If the client checks this checkbox, their credential will be stored: the card data will be saved for this client and the client will not have to enter the card data next time. Read more here.

Storing a credential with no charge

If you have this feature enabled for you by our support team, you can store a credential via API with no charge.

To do this, pass the value VERIFY in the features block of any payment request together with the clientId parameter. In this case, the cardholder will not be charged any amount. The response will contain the identifier of the stored credential in the bindingId parameter. This binding ID can be used in subsequent requests instead of the saved card details.

Read more about the VERIFY feature here.

Forcing a credential storage

If you pass the value FORCE_CREATE_BINDING in the features block of the payment request, the credential will be stored forcefully – even if the client has chosen not to save card data on the payment page.

TheFORCE_CREATE_BINDING value cannot be passed in a request with an existing bindingId or bindingNotNeeded = true (will cause validation error). Passing this value also requires passing the clientId parameter.

If both the FORCE_CREATE_BINDING and the VERIFY values are passed in the features block, the order will be created for the purposes of credential storage ONLY (without payment).

Making a stored-credential payment

Stored-credential payments API

Once a credential is stored, you can handle it over the stored-credential payments API (subject to Merchant-level permission). The following methods are available:

Using stored credentials in recurrent payments

You can use stored credentials for recurring payments. In this case, the bindingId parameter is used in regular order registration request. Read more here.

Using stored credentials in wallet payments

You can also store credentials upon payments via Apple Pay, Google Pay, and Samsung Pay wallets. To do this, pass the clientId parameter in a payment request or in an order registration request (see the description of API requests for wallets).

In this case, a stored credential will link the payer's tokenized card number (DPAN) to their ID in the store system (for example, to payer's login). A credential stored this way cannot be used for displaying a card number on a payment page (because the card number is tokenized). However, this sored credential can be used in recurring payments.

Cardholder verification

You can verify a cardholder without charging any amount. To do this, pass theVERIFY value in the features block of an order registration or payment request.

When theVERIFY feature is used, the payment card will be verified to make sure it is used by its legitimate owner. If 3-D Secure is available for the card, then 3-D Secure verification will be performed. The amount parameter of the verification request can be 0. Even if some amount is passed in the request, no charge will be made. After a successful registration, order status is changed to REVERSED.

If the VERIFY feature is passed together with the clientId parameter, it can be used to store a credential without payment. Read more in the Stored-credential transactions section.

Open ID token

You can generate an Open ID token for a merchant. This token can be used instead of credentials for identifying a merchant in the Payment Gateway.

Open ID token is not private, it can be published or embedded into a web page. For example, it can be used when an order is registered directly from browser. In this case, there is no risk of personal data disclosure, because the token can be interpreted by the Payment Gateway only.

You can use Open ID token for merchant authentication when sending API requests to the Payment Gateway. To do it, pass the Open ID token in the token parameter instead of passing userName and password. You can use the token parameter in the following requests:

To generate an Open ID token, go to the Personal Area, select Settings on the side menu, and then select General Settings in the Merchant block. Click Generate next to the Open Id token field. If you alredy know your token, you may enter in manually. Read more here.

Redirect to ACS

If 3-D Secure is required, then, after receiving a paymentOrder.do response, the customer must be redirected to ACS. There are two ways to do that: regular and simplified.

Regular redirect

If a payment is made with 3-D Secure, merchants must redirect their customers to ACS using the address specified in the acsUrl parameter received from the paymentOrder.do response. The request body must be MD=mdorder&PaReq=paReq&TermUrl=termUrl, where:

It must be a POST request (not GET).

Depending on the configuration agreed with your bank, the customer after ACS authentication will be redirected either to the store or to the payment gateway.

Example of a POST request for regular redirect:

<html>
<head><title>ACS Redirect</title></head>
<body onload="document.forms['acs'].submit()">
ACS Redirect
<form id="acs" method="post" action="[result.acsUrl]">
    <input type="hidden" id="MD" name="MD" value="[MD]"/>
    <input type="hidden" id="PaReq" name="PaReq" value="[result.PaReq]"/>
    <input type="hidden" id="TermUrl" name="TermUrl" value="[result.TermUrl]"/>
</form>
</body>
</html>

Simplified redirect

Alternatively, the online store can use the gateway acsRedirect method, which will perform the same cardholder redirect to the issuer ACS.

Payment with your own MPI

Merchant Plugin Interface (MPI) is a component of 3D Secure technologies that may be implemented in the payment gateway or on your side. If you have your own MPI, you can use it for 3D Secure authorization in API requests. To enable this feature, contact our support team.

If you use your own MPI, the payment gateway expects that every paymentOrder request will include the eci parameter - Electronic commerce indicator (ECI) received from your 3-D Secure Server. Below is the explanation of ECI codes:

If ECI value differs from the ones used for SSL authorizationst, it is also necessary to pass the following parameters:

If you use your own MPI, the paymentOrder response does not contain 3D Secure-related parameters, such as redirect, termUrl, acsUrl, and paReq.

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 'xid=MDAwMDAwMDEzMzkyMjg5ODExNTc=' \\
  --data 'cavv=AAABCpEChRM5IomAKFAAAAAAAAA=' \\
  --data eci=05
{
  "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
}

P2P

To learn more about P2P (peer-to-peer/person-to-person) transactions click here.

Testing

Test cards

For testing purposes you can use the following test cards.

Card number (SSL) 4000 0011 1111 1118
Expiry 12/30
CVC 123
Card number (3DS1) 6777 7700 0000 0006
Expiry 12/30
CVC 123
3-D Secure verification code 12345678
Card number (3DS2) 5000 0011 1111 1115
Expiry 12/30
CVC 123

Test scenarios

You can test the following scenarios:

Glossary

Refer to our glossary to learn about general terms and concepts that you meet in the documentation.

Categories
Search results