Перейти к содержанию

API версия 3

Общее описание

Чтобы предоставлять своим клиентам больше доступной информации о статусе обработки транзакции, сервис bePaid начал внедрение API версии 3 (API v.3). Основным отличием этой версии API системы от предыдущей является формат и параметры ответов на запросы и новые коды ошибок обработки транзакций. Коды ошибок обработки транзакции теперь также будут сопровождаться понятным текстовым описанием, что поможет понимать статус или причину ошибки обработки транзакции.

C 15 сентября 2022 API v.3 применяется для всех https://gateway.bepaid.by/- методов. В запросах к этой версии API следует только добавить заголовок X-API-Version: 3. Описание параметров и их значений приведено ниже на странице.

По всем вопросам, связанным со взаимодействием с bePaid API v.3, вы можете обращаться в Службу технической поддержки на help@bepaid.by.

Формат запросов

Для отправки POST или GET запроса к API v.3 https://gateway.bepaid.by/-методов, добавьте к запросу заголовок X-API-Version: 3 или посылайте его вместо заголовка X-API-Version: 2, если такой требуется.

В теле запроса используйте параметры, описанные для требуемого метода. Дополнительных параметров для API v.3 передавать не требуется.

Формат ответов

Ответы от API v.3 системы содержат следующие параметры:

Параметр Тип Описание
uid string UID обработанной транзакции.
status string Статус обработанной транзакции.
code string Код обработанной транзакции.
friendly_message string Сообщение системы для покупателя.
message string Сообщение системы банка.
amount integer Сумма обработанной транзакции в минимальных денежных единицах. Например, USD 12.00 передается как 1200.
currency string Валюта обработанной транзакции в формате ISO-4217, например USD.
description string Описание обработанной транзакции.
type string Тип обработанной транзакции.
tracking_id string Устанавливается в значении параметра tracking_id из запроса.
test boolean Устанавливается в значении true, если транзакция была обработана как тестовая.
created_at string Дата и время создания транзакции в формате ISO 8601 YYYY-MM-DDThh:mm:ssTZD.
updated_at string Дата и время последнего обновления транзакции в формате ISO 8601 YYYY-MM-DDThh:mm:ssTZD.
paid_at string Дата и время завершения транзакции в формате ISO 8601 YYYY-MM-DDThh:mm:ssTZD. Устанавливается в значении null, если транзакция имеет статус incomplete.
expired_at string Дата и время окончания периода для возможного проведения транзакции в формате ISO 8601 YYYY-MM-DDThh:mm:ssTZD, т.е. срока, до которого клиент может совершить платеж. Устанавливается в значении null, если параметр не применим к транзакции.
closed_at string Дата и время окончания банковского дня в формате ISO 8601 YYYY-MM-DDThh:mm:ssTZD. Устанавливается в значении null, если параметр не применим к транзакции.
settled_at string Дата и время перечисления суммы транзакции на счет торговца в формате ISO 8601 YYYY-MM-DDThh:mm:ssTZD. Устанавливается в значении null, если параметр не применим к транзакции.
manually_corrected_at string Дата и время ручной корректировки транзакции в формате ISO 8601 YYYY-MM-DDThh:mm:ssTZD. Устанавливается в значении null, если параметр не применим к транзакции.
redirect_url string URL страницы для завершения транзакции. Если параметр status имеет значение incomplete, необходимо перенаправить покупателя на этот URL для прохождения проверки 3-D Secure.
parent_uid string UID родительской транзакции, если требуется.
reason string Описание причины оспоренного платежа.
recurring_type string Тип транзакции по сохраненным данным карты. Устанавливается в значении null, если параметр не применим к транзакции.
language string Значение параметра language из запроса, или en по умолчанию.
status_code integer Код статуса проверки 3-D Secure. Устанавливается в значении null, если параметр не применим к транзакции.
errors object Секция данных и парамтеров ошибки обработки транзакции.
customer object Секция информации о покупателе.
ip string IP-адрес клиента.
email string Адрес электронной почты клиента.
device_id string ID устройства клиента.
birth_date string Дата рождения клиента.
first_name string Имя клиента.
last_name string Фамилия клиента.
address string Адрес клиента.
country string Страна клиента в формате ISO 3166-1 alpha-2.
city string Город клиента.
state string Двухбуквенный ккод штата клиента, если страна - US или CA.
zip string Индекс клиента. Если страна - US, то индекс должен быть представлен в формате NNNNN или NNNNN-NNNN.
phone string Номер телефона клиента.
payment_method object Секция параметров способа оплаты, использованного клиентом при проведении транзакции.
payment_method_type string Тип платежного метода.
holder string Имя владельца карты.
stamp string Хэш карты.
brand string Бренд карты.
last_4 string Последние 4 цифры карты.
first_1 string Первая цифра карты.
bin string BIN карты.
issuer_country string Страна банка-эмитента карты.
issuer_name string Название банка-эмитента карты.
product string Тип карточного продукта.
exp_month integer Месяц окончания срока действия карты, представленный двумя цифрами, например 01.
exp_year integer Год окончания срока действия карты, представленный четырьмя цифрами, например, 2026.
token_provider string Провайдер токена карты, если применяется.
token string Токен карты.
recipient object Секция данных получателя средств. Применяется к выплатам и P2P переводам средств от клиента к получателю.
customer object Секция персональных данных и данных адреса получателя средств.
first_name string Имя получателя.
last_name string Фамилия получателя.
address string Адрес получателя.
country string Страна получателя в формате ISO 3166-1 alpha-2.
city string Город получателя.
state string Двухбуквенный код штата получателя, если страна - US или CA.
zip string Индекс получателя. Если страна - US, то индекс должен быть представлен в формате NNNNN или NNNNN-NNNN.
phone string Номер телефона получателя.
payment_method object Секция параметров способа оплаты, использованного для получения выплаты или P2P перевода.
holder string Имя владельца карты-приемника средств.
stamp string Хэш карты-приемника средств.
brand string Бренд карты-приемника средств.
last_4 string Последние 4 цифры карты-приемника средств.
first_1 string Первая цифра карты-приемника средств.
bin string BIN карты-приемника средств.
issuer_country string Страна карты-приемника средств.
issuer_name string Название банка-эмитента карты-приемника средств.
product string Тип карты-приемника средств.
exp_month integer Месяц окончания срока действия карты-приемника средств, представленный двумя цифрами, например 01.
exp_year integer Год окончания срока действия карты-приемника средств, представленный четырьмя цифрами, например, 2026.
token string Токен карты-приемника средств.
token_provider string Провайдер токена карты-приемника средств, если применяется.
payment_method_type string Тип платежного метода, использованного для получения выплаты или P2P перевода.
be_protected_verification object Секция с параметрами проверки beProtected. Применяется, если сервис активирован.
status string Статус проверки сервиса beProtected.
message string Описание ошибки или статуса, если применяется.
white_black_list object Секция проверки по спискам доверительных параметров, если применяется.
email string Устанавливается в значении absent, если адрес электронной почты клиента не в списке.
ip string Устанавливается в значении absent, если IP-адрес клиента не в списке.
card_number string Устанавливается в значении absent, если номер карты клиента не в списке.
rules object Секция правил обработки транзакций. Содержит краткое описание применяемых правил и статусов проверки.
smart_routing_verification object Секция параметров сервиса Smart Routing. Применяется, если сервис активирован.
status string Статус обработки транзакции сервисом.
data object Секция правил с типом результата "Действие" и статуса проверки транзакции по этим правилам.
object string ID объекта сервиса. Относится к ID платежного шлюза, обработавшего транзакцию.
object_defined_via string
object_flows object Секция потоков правил типа "Объект".
three_d_secure_verification object Секция параметров проверки 3-D Secure.
additional_data object Секция дополнительных данных о транзакии.
browser object Секция данных браузера клиента.
contract object Секция параметров выдачи карточных токенов для платежей по сохраненным картам.
max_mind_verification object Секция парамтеров проверки MaxMind. Применяется, если сервис активирован.
status string Статус проверки сервиса.
score integer Оценка риска транзакции сервисом.
avs_cvc_verification object Секция проверки AVS/ CVC параметров.
avs_verification object Секция с результатом проверки AVS параметров.
result_code string Код результата проверки AVS параметров.
cvc_verification object Секция с результатом проверки CVC параметров.
result_code string Код результата проверки CVC параметров.
transaction object Секция данных о транзакции.
ref_id string Идентификационный номер транзакции в системе банка (reference ID).
message string Сообщение об обработке транзакции.
amount integer Сумма обработанной транзакции в минимальных денежных единицах.
currency string Валюта обработанной транзакции в формате ISO-4217, например USD.
billing_descriptor string Описание обработанной транзакции.
gateway_id integer ID платежного шлюза, через который транзакция была обработана в системе bePaid.
status string Статус обработанной транзакции.
auth_code string Код авторизации обработанной транзакции.
rrn string Номер транзакции в системе банка (Retrieval Reference Number).
bank_code string Код обработки транзакции в системе банка.
links object Секция ссылок.
receipt_url string URL на получение чека об обработанной транзакции.
bank_info object Секция параметров запроса баланса.

Если параметр не применим к транзакции, он будет установлен в значении null.

Коды обработки транзакций

Ответ по формату API v.3 обязательно содержит параметр code со значением в формате {Буквенный код}.{4 цифры кода ошибки}, где:

  • {Буквенный код} относится к статусу обработки транзакции;
  • {4 цифры кода ошибки} относится к коду ошибки того сервиса системы, который не смог успешно обработать транзакцию.

Буквенный код

Буквенный код API v.3 Статус API v2 Описание статуса
S sucсessful Транзакция была успешно обработана.
F failed Транзакция была отклонена по какой-то причине.
P pending
incomplete
Транзакция все еще находится в обработке, или система ожидает действия клиента для завершения транзакции.
E expired
deleted
Срок возможности проведения транзакции истек, или транзакция была удалена.

4 цифры кода ошибки

Диапазон кодов
API v.3
Описание
0000 Операция успешна.
0001 - 0499 Коды ошибок валидации и обработки параметров карточных платежей.
0501 - 0999 Коды ошибок валидации и обработки параметров платежей альтернативными платежными методами.
1000 - 1999 Коды ошибок сервиса платежного шлюза.
2000 - 3999 Коды ошибок сервиса Smart Routing.
4000 - 4999 Коды ошибок сервиса проверки 3-D Secure.
5000 - 5999 Коды ошибок сервиса проверки MaxMind.
6000 - 6999 Коды ошибок сервиса проверки AVS/ CVC.
7000 - 7999 Коды ошибок сервиса Verify.
8001 Код ошибки сервиса проверки P2P транзакций.
8010 Код ошибки сервиса платежного шлюза при работе в асинхронном режиме.
8011 - 9999 Коды ошибок банка.

Детальное описание всех кодов представлено в приложении Коды ошибок обработки транзакции API v.3.

Пример ответа по формату API v.3 на запрос проведения платежа

В примере транзакция имеет статус incomplete и код P.9998. С учетом того, что только секция three_d_secure_verification имеет статус incomplete, транзакция получила такой статус, т.к. система bePaid ожидает прохождения клиентом проверки 3-D Secure.

{
    "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": 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",
        "data": {
            "action_rules": {
                "Psp_1_DEMO_PSP": {
                    "Notify on payments of 3.000 USD and higher": {
                        "Notify on payments with amounts of 3.000 USD and higher": "skipped"
                    },
                    "Reject payments of 3,000 USD and higher": {
                        "Decline payments if the amount equals or more than 3,000 USD": "passed"
                    }
                }
            },
            "object": "645",
            "object_defined_via": "allowed objects",
            "object_flows": [
                {
                    "name": "[Payout channel][Balance flow] USD payouts through ABC bank, gateway_id: 918",
                    "rules": [
                        {
                            "alias": "[Payout channel][Balance check] USD payouts through ABC bank, gateway_id: 918",
                            "description": "[Payout channel][Balance check] USD payouts through ABC bank, gateway_id: 918",
                            "error": {
                                "code": "rule_inactive",
                                "friendly_message": "Rule is inactive",
                                "message": "The rule is inactive"
                            },
                            "state": "skipped"
                        }
                    ],
                    "skipped": false,
                    "system": true
                }
            ],
            "object_name": "Bogus",
            "status": "passed"
        }
    },    
    "be_protected_verification": {
        "status": "successful",
        "message": null,
        "limit": {
            "volume": false,
            "count": false,
            "max": false,
            "current_volume": 200,
            "current_count": 2
        },
        "white_black_list": {
            "email": "absent",
            "ip": "absent",
            "card_number": "absent"
        },
        "rules": {
            "Demo Shop": {},
            "Demo 123": {},
            "DEMO_PSP": {
                "Channels payouts": {
                    "Total successful payout transactions amount more or equal than 1000.00 ISK in 100000000000 days": "passed"
                }
            }
        }
    },
    "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,
        "maxmindID": "DV28GG8U",
        "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
        }
    }
}