API version 3
Introduction
To make API responses more user-friendly and comprehensive for you, bePaid starts introducing the API version 3 (API v.3). The main changes relate to the response parameters and transaction status codes. The codes now go along with friendly messages for you to get more information about transaction processing.
As of September 15, 2022, the API v.3 is already configured for all https://gateway.bepaid.by/
- endpoints. To submit requests, just add the X-API-Version: 3
header to the request. For response parameters and their description, please use the guide below.
For any other questions related to the bePaid API v.3, you are welcome to contact our Tech Support Team on help@bepaid.by.
Requests
To send POST
or GET
requests to the API v.3 of the https://gateway.bepaid.by/
- endpoints, add the X-API-Version: 3
header to the request, or use the header instead of X-API-Version: 2
, if the latter was required.
As for the request parameters, use the parameters described for the required endpoint. No additional parameters are required.
Responses
The API v.3 responses have the following parameters:
Parameter | Type | Description |
---|---|---|
uid | string | A UID of the processed transaction. |
status | string | A status of the processed transaction. |
code | string | A transaction processing code. |
friendly_message | string | Message for the customer. |
message | string | A message from the bank system. |
amount | integer | An amount of the transaction in minimal currency units. For example, USD 12.00 is transmitted as 1200 . |
currency | string | A currency of the transaction in the ISO-4217 format, for example, USD . |
description | string | A transaction description. |
type | string | A transaction type. |
tracking_id | string | Set to the tracking_id value from the request. |
test | boolean | Set to true if a transaction is a test one. |
created_at | string | A time when the transaction was created at in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD . |
updated_at | string | A time when the transaction was last updated at in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD . |
paid_at | string | A time when the transaction was successfully completed at in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD . Set to null if the transaction is incomplete. |
expired_at | string | A time when the transaction expires in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD , i.e. a time till which the customer can complete the transaction. Set to null if the parameter is not applicable to the transaction. |
closed_at | string | A time when a banking day in the acquiring bank ends in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD . Set to null if the parameter is not applicable to the transaction. |
settled_at | string | A time when the acquiring bank settled the transaction amount to the merchant's current account in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD . Set to null if the parameter is not applicable to the transaction. |
manually_corrected_at | string | A time when the transaction was successfully completed at in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD . Set to null if the parameter is not applicable to the transaction. |
redirect_url | string | A URL of the page to finalize the transaction. If the status parameter is set to incomplete , redirect the customer to this URL. It runs the 3-D Secure verification of the cardholder. |
parent_uid | string | A UID of the parent transactions, if applicable. |
reason | string | A description of the chargeback reason. |
recurring_type | string | A type of the recurring transaction. Set to null if the parameter is not applicable to the transaction. |
language | string | A language parameter value from the request, or en , if the parameter is not sent in the request. |
status_code | integer | A status code of the 3-D Secure verification. Set to null if the parameter is not applicable to the transaction. |
errors | object | A section of error details and parameters. |
customer | object | A section of the customer information. |
ip | string | The customer's IP address. |
string | The customer's email. | |
device_id | string | The customer's device ID. |
birth_date | string | The customer's date of birth. |
first_name | string | The customer's first name. |
last_name | string | The customer's last name. |
address | string | The customer' billing address. |
country | string | The customer's billing country in the ISO 3166-1 alpha-2 format. |
city | string | The customer's billing city. |
state | string | The customer's two-letter billing state, if the billing address country is US or CA . |
zip | string | The customer's billing ZIP or postal code. If country=US , the zip format must be NNNNN or NNNNN-NNNN. |
phone | string | The customer's phone number. |
payment_method | object | A section of details of the payment method used by the customer to make the transaction. |
payment_method_type | string | A payment method type used to make the transaction. |
holder | string | The cardholder name. |
stamp | string | The card stamp. |
brand | string | The card brand. |
last_4 | string | The last 4 digits of the card. |
first_1 | string | The first digit of the card. |
bin | string | The card BIN. |
issuer_country | string | The country of the card issuing bank. |
issuer_name | string | The issuing bank of the card. |
product | string | The card product type. |
exp_month | integer | The card expiration month represented with two digits, for example 01 . |
exp_year | integer | The card expiration year represented with four digits, for example 2021 . |
token_provider | string | The card token provider, if any. |
token | string | The card token. |
recipient | object | A section of the recipient's details. Applicable for payouts and P2P transactions initiated by the customer to the recipient. |
customer | object | A section of the recipient's personal and address details. |
first_name | string | The recipient's first name. |
last_name | string | The recipient's last name. |
address | string | The recipient's billing address. |
country | string | The recipient's billing country in the ISO 3166-1 alpha-2 format. |
city | string | The recipient's billing city. |
state | string | The recipient's two-letter billing state, if the billing address country is US or CA . |
zip | string | The recipient's billing ZIP or postal code. If country=US , the zip format must be NNNNN or NNNNN-NNNN. |
phone | string | The recipient's phone number. |
payment_method | object | A section of details of the payment method used to receive a payout or P2P transfer. |
holder | string | The recipient cardholder name. |
stamp | string | The recipient card stamp. |
brand | string | The recipient card brand. |
last_4 | string | The last 4 digits of the recipient card. |
first_1 | string | The first digit of the recipient card. |
bin | string | The recipient card BIN. |
issuer_country | string | The recipient card country. |
issuer_name | string | The issuing bank of the recipient card. |
product | string | The recipient card product type. |
exp_month | integer | The recipient card expiration month represented with two digits, for example 01 . |
exp_year | integer | The recipient card expiration year represented with four digits, for example 2021 . |
token | string | The recipient card token. |
token_provider | string | The source card token provider, if any. |
payment_method_type | string | A payment method type used to receive a payout or P2P transfer. |
smart_routing_verification | object | A section of the Smart Routing service parameters. Applicable if the Smart Routing service is activated. |
status | string | A status of the Smart Routing service processing. |
three_d_secure_verification | object | A section of the 3-D Secure verification parameters. |
additional_data | object | A section of additional details about the transaction. |
browser | object | A section of the customer's browser data. |
contract | object | A section of the parameters related to card tokens issued for payments by saved cards. |
avs_cvc_verification | object | A section of the AVS/ CVC verification check. |
avs_verification | object | A section with the result of the AVS verification check. |
result_code | string | A code of the AVS verification check result. |
cvc_verification | object | A section with the result of the CVC verification check. |
result_code | string | A code of the CVC verification check result. |
transaction | object | A section of the transaction details. |
ref_id | string | A transaction reference ID assigned by the bank. |
message | string | A transaction processing message. |
amount | integer | A transaction amount in minimal currency units. |
currency | string | A currency of the transaction in the ISO-4217 format, for example, USD . |
billing_descriptor | string | A transaction billing descriptor. |
gateway_id | integer | An ID of the payment gateway through which the transaction was processed in the bePaid system. |
status | string | A transaction status. |
auth_code | string | A transaction authorization code. |
rrn | string | A Retrieval Reference Number of the transaction assigned by the bank. |
bank_code | string | A transaction processing code assigned by the bank. |
links | object | A section of links. |
receipt_url | string | A URL of the transaction receipt. |
bank_info | object | A section of parameters of the balance request. |
If the parameter is not applicable to the transaction, response parameter values are set to null
.
Processing codes
An API v.3 response mandatory contains a code
parameter value in the {Letter code}.{4 code digits}
format, where:
{Letter code}
stands for a transaction processing status;{4 error code digits}
relate to an error code of a system service that can not process a transaction.
Letter codes
API v.3 letter code | API v2 status | Status description |
---|---|---|
S | successful |
The transaction is successfully processed. |
F | failed |
The transaction is failed due to some reason in the system of the bank / integration provider. |
P | pending incomplete |
The transaction is still being processed, or the system waits for the customer's action to complete the transaction. |
E | error |
There was an error while processing the transaction by bePaid internal services. |
4 error code digits
API v.3 4 digit range | Description |
---|---|
0000 | The operation is successful. |
0001 - 0499 | Error codes of the system validation and processing service for card transactions. |
0501 - 0999 | Error codes of the system validation and processing service for transactions that are initiated with alternative payment methods. |
1000 - 1999 | Error codes of the payment gateway service. |
2000 - 3999 | Error codes of the Smart Routing service. |
4000 - 4999 | Error codes of the 3-D Secure verification service. |
6000 - 6999 | Error codes of the AVS/ CVC verification check. |
7000 - 7999 | Error codes of the Verify service. |
8001 | Error code of the P2P verification service. |
8010 | Error code of the payment gateway service for requests in asynchronous mode. |
8005 - 9999 | Bank error codes. |
You can find detailed description of all the codes in the API v.3 processing error codes appendix.
Example of the API v.3 response to the payment transaction request
The sample transaction has the incomplete
status and the P.9998
code. Provided that the three_d_secure_verification
is the only section with the incomplete
status, the transaction could not be processed as the bePaid system waits for the customer to take the 3-D Secure verification check.
{
"uid": "46154-aba1cf5e57",
"code": "P.9998",
"friendly_message": "Incomplete transaction",
"status": "incomplete",
"amount": 100,
"currency": "USD",
"description": "Test transaction ütf",
"type": "payment",
"payment_method": {
"payment_method_type": "credit_card",
"holder": "John Doe",
"stamp": "5f854c844e3007f2ecff2aa614f6a4cc6b8a2c241aab3e5776fe7912dc7b9d92",
"brand": "mir",
"last_4": "0013",
"first_1": "2",
"bin": "220138",
"issuer_country": "RU",
"issuer_name": "MIR",
"product": "MIR",
"exp_month": 10,
"exp_year": 1,
"exp_year": 2026,
"token_provider": null,
"token": "2efef4c9-d4de-4603-bc84-7a9bc5456939"
},
"tracking_id": "tracking_id_000",
"message": null,
"test": true,
"created_at": "2022-09-15T08:43:56.521Z",
"updated_at": "2022-09-15T08:43:57.943Z",
"paid_at": null,
"expired_at": null,
"recurring_type": "initial",
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"redirect_url": "https://gateway.bepaid.by/process/46154-aba1cf5e57",
"status_code": 21,
"links": {
"receipt_url": "https://merchant.bepaid.by/customer/transactions/46154-aba1cf5e57/bbe9f4090e43351ca1ee724a202376cb24da3ffbfa86df30c80e95fb4fdee386?language=en"
},
"additional_data": {
"browser": {
"screen_width": 1920,
"screen_height": 1080,
"screen_color_depth": 24,
"language": "en",
"java_enabled": false,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
"time_zone": -180,
"time_zone_name": "Europe/Minsk",
"accept_header": "*/*",
"window_height": 667,
"window_width": 600
},
"contract": [
"recurring"
]
},
"customer": {
"ip": "127.0.0.1",
"email": "john@example.com",
"device_id": "12312312321fff67",
"birth_date": "1980-01-31",
"first_name": "John",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": null
},
"smart_routing_verification": {
"status": "successful"
},
"max_mind_verification": {
"score": 45,
"status": "successful",
"distance": null,
"countryMatch": "No",
"countryCode": null,
"freeMail": "No",
"anonymousProxy": "No",
"binMatch": "No",
"binCountry": "RU",
"err": "IP_NOT_FOUND",
"proxyScore": "0.00",
"ip_region": null,
"ip_city": null,
"ip_latitude": null,
"ip_longitude": null,
"binName": null,
"ip_isp": null,
"ip_org": null,
"binNameMatch": "NA",
"binPhoneMatch": "NA",
"binPhone": null,
"custPhoneInBillingLoc": "NotFound",
"highRiskCountry": "No",
"queriesRemaining": "14286",
"cityPostalMatch": "No",
"shipCityPostalMatch": null,
"carderEmail": "No"
},
"three_d_secure_verification": {
"status": "incomplete",
"message": "Authentication Available",
"ve_status": "Y",
"acs_url": null,
"pa_req": null,
"md": null,
"pa_res_url": "https://gateway.bepaid.by/process/46154-aba1cf5e57",
"eci": null,
"pa_status": null,
"xid": null,
"cavv": null,
"cavv_algorithm": null,
"fail_reason": null,
"method_process_url": "https://gateway.bepaid.by/api/v1/transactions/bd79f747-a42f-4ee3-b993-069310ca8238/method-process",
"creq": null
},
"transaction": {
"auth_code": null,
"bank_code": null,
"rrn": null,
"ref_id": null,
"message": null,
"amount": 100,
"currency": "USD",
"billing_descriptor": null,
"gateway_id": 645,
"status": "incomplete"
},
"avs_cvc_verification": {
"avs_verification": {
"result_code": null
},
"cvc_verification": {
"result_code": null
}
}
}