Подключение
Чтобы использовать сервис Masterpass, необходимо:
-
Стать партнером программы Masterpass. Это можно сделать напрямую или с помощью вашего аккаунт-менеджера.
-
Обратиться к аккаунт-менеджеру для настройки параметров доступа в Masterpass.
-
Реализовать дополнительные методы интеграции для сервиса Masterpass:
-
Добавить на всех страницах логотип Masterpass. Ваш аккант-менеджер подскажет требования к размещению логотипа.
Открытие сессии пользователя в системе Masterpass
Метод используется для авторизации пользователя в Masterpass. Например, в случаях:
- Первый и последующие входы в приложение
- Истечения срока жизни пользовательской сессии (от Masterpass была получена ошибка с
Error_Code=8
илиError_Code=16
). Необходимо выполнить повторный запрос на открытие сессии пользователя и получение списка карт.
Запрос
Для открытия сессии пользователя отправьте POST
запрос на https://gateway.bepaid.by/masterpass/login
со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
phone * обязательный |
string | Номер телефона пользователя. |
fingerprint * обязательный |
string base64 | Цифровой отпечаток устройства - набор уникальных параметров, преобразованных в формат Base64. Руководство по созданию значения параметра опубликовано в личном кабинете Masterpass (запросить у аккаунт-менеджера) |
phone_check_date | string | Последняя успешная дата подтверждения телефона на стороне Мерчанта в формате Date(1612341218000) , где 1612341218000 время в миллисекундах в формате Epoch |
channel | integer | 0 = Recurring 1 = WEB2 = APP iOS3 = APP Android4 = TVE5 = SmartTV6 = Smart devices7 = USSD8 = IVR9 = Offline10 = Other |
test | boolean | true или false . Операция будет тестовой, если значение true |
Пример запроса
{
"fingerprint": "SGVpZ2h0PTg5NjtXaWR0aD00MTQ7T1NWZXJzaW9uPVZlcnNpb24gMTIuMS40IChCdWlsZCAxNkQ1Nyk7RGV2aWNlSWQ9Njk5NkI3QTYtMjREOS00Rj\nVBLUJFMDktOTlBRDQyMEFBRkZGO1RpbWVab25lPUV1cm9wZS9Nb3Njb3c7TW9kZWw9aVBob25lIFhSO09TPWlPUztQaG9uZUlkPTRDNDQzQzI2LUNE\nQTItNDYxQS05QUVGLTNEQkNFMTJCMkVFNztWZXJzaW9uUmVsZWFzZT0xMi4xLjQ7IFJlbW90ZUlwPTkxLjIzOC4xMjAuMTcxO1Bhc3N3b3JkPWNhMz\ndiMzEzMmFhNTE2YzQ1MzdiYWYyOGJiYzI1OTk5OWU0ZDA5ZTZlZTE1NWFkYjNkOGRiMDMzODJlYWI5ODk7WEZvcndhcmRlZEZvcj05MS4yMzguMTIw\nLjE3MSwyMTYuMTE5LjIwOS42NDtPVFA9MDNBQzY3NDIxNkYzRTE1Qzc2MUVFMUE1RTI1NUYwNjc5NTM2MjNDOEIzODhCNDQ1OUUxM0Y5NzhEN0M4ND\nZGNDtBQT1VMA==",
"phone": "77707811122",
"phone_check_date": "Date(1612341218000)",
"channel": 2,
"test": true
}
Ответ
При обработке запроса на открытие сессии система вернет ответ со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
status | string | Статус запроса. |
error_code | integer | Код ошибки. |
error | string | Сообщение об ошибке. |
is_otp_required | boolean | Требуется проверка OTP |
session | string | Идентификатор сессии пользователя в Masterpass |
user_status | integer | Статус пользователя в Masterpass. Если статус не равен 1 , то делать запрос на получение списка карт не нужно. |
Пример успешного ответа
{
"session": "c96fe83d-366c-420c-9038-da0fae844f0c",
"is_otp_required": false,
"user_status": 1
}
Коды ошибок
В случае возникновения ошибки при открытии сессии пользователя в системе Masterpass, чтобы понять причину ошибки, воспользуйтесь пояснением кодов для параметра error_code
.
Код ошибки | Описание | Пояснение описания |
---|---|---|
0 | None | Успешное завершение вызова. |
1 | The service is not available for this card/user | Текущий пользователь находится в черном списке. |
2 | Api not allowed | Вызов метода запрещен после превышения допустимого количества запросов. |
8 | No user was found by the passed session | Передана не существующая сессия или срок действия сессии истек. Необходимо заново активировать сессию. |
10 | Wrong phone format | Неверный формат телефонного номера. |
11 | Empty DeviceId | Обязательный параметр DeviceId не передан в Fingerprint , передано пустое поле или состоящее из пробелов. |
13 | Internal error while encrypting the response | Внутренняя системная ошибка, требуется дополнительная проверка командой Masterpass |
15 | Merchant with such a name and password not found | Обязательное поле Merchant не передано в запросе или мерчант с таким названием не найден. |
19 | The service is not available for this card/user or Wrong params | Пользователь находится в черном списке. Превышено максимальное количество попыток отправки OTP. Ограничение считается одновременно для всех мерчантов. Запрос был отправлен с неверным или неполным набором параметров. |
20 | Internal error | Внутренняя системная ошибка, требуется дополнительная проверка командой Masterpass |
23 | RequestTokenNotFound | Переданное значение RequestToken не существует. |
35 | Wrong params | В Fingerprint не переданы обязательные параметры |
44 | API_NOT_ALLOWED | Сертификат не найден или истек срок действия сертификата, или ошибка подписи. |
Сохранение новой карты в Masterpass
Прежде чем начать
Откройте сессию пользователя перед сохранением новой карты в Masterpass.
Запрос
Для сохранения карты в Masterpass используйте запросы оплаты или авторизации со следующими дополнительными параметрами:
Параметр | Тип | Описание |
---|---|---|
additional_data | object | Секция, содержащая дополнительную информацию о платеже. |
contract * обязательный |
array | Массив с элементом:recurring - bePaid вернет токен карты для осуществления последующих платежей без повторного ввода реквизитов карты. Пользователь, соглашаясь с условиями регулярного списания, единожды производит оплату, вводя реквизиты карты, включая проверочный код карты CVC/CVV и проходя авторизацию по протоколу 3-D Secure. |
masterpass | object | Секция для работы с сервисом Masterpass. |
params | object | Секция для параметров Masterpass. |
session * обязательный |
string | ID пользовательской сессии. |
Пример запроса для операции оплаты
{
"request": {
"amount": 100,
"currency": "USD",
"description": "www",
"tracking_id": "save_card_test_masterpass_success_2",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"country": "US",
"city": "Denver",
"state": "CO",
"zip": "96002",
"address": "1st Street"
},
"credit_card": {
"number": "4200000000000000",
"verification_value": "123",
"holder": "John Doe",
"exp_month": "05",
"exp_year": "2026"
},
"additional_data": {
"contract": [
"recurring"
],
"masterpass": {
"params": {
"session": "a6fd8624-8060-46b3-b343-7a93126fd57f"
}
}
},
"customer": {
"ip": "127.0.0.1",
"email": "email@example.com",
"birth_date": "1998-01-31"
},
"test": true
}
}
Ответ
Если магазин участвует в программе Masterpass, то после проведения платежа, bePaid направит запрос на сохранение карты в Masterpass. В ответе будет получен токен Masterpass и результат сохранения карты в Masterpass.
Info
Если проводится платеж только для сохранения карты, то после получения результатов сохранения, необходимо сделать возврат по этой транзакции.
Пример ответа для типа операции оплаты при успешном сохранении карты
{
"transaction": {
"uid": "10134-ca74085dff",
"status": "successful",
"amount": 100,
"currency": "USD",
"description": "www",
"type": "payment",
"payment_method_type": "credit_card",
"tracking_id": null,
"message": "Successfully processed",
"test": true,
"created_at": "2021-03-15T07:47:27.904Z",
"updated_at": "2021-03-15T07:47:31.095Z",
"paid_at": "2021-03-15T07:47:31.055Z",
"expired_at": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"redirect_url": "https://gateway.bepaid.by/process/10134-ca74085dff",
"credit_card": {
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 5,
"exp_year": 2026,
"token_provider": null,
"token": "495f97d6-862a-4445-b537-06d4b3fa392f"
},
"receipt_url": "https://merchant.bepaid.by/customer/transactions/10134-ca74085dff/f3dcf8284bbe70f87d1714095eb8101053ec4de77dd04e5c74aa280e54276b3d",
"id": "10134-ca74085dff",
"additional_data": {
"contract": [
"recurring"
],
"masterpass": {
"params": {
"session": "35b55f8e-36d4-467a-b41f-28468a031898"
},
"result": {
"status": "successful",
"message": "Postback successfully finished.",
"token": "31b1e418-6a56-490d-bb5b-15f11a2040d8"
}
}
},
"payment": {
"auth_code": "654321",
"bank_code": "05",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was approved",
"amount": 100,
"currency": "USD",
"billing_descriptor": "test descriptor",
"gateway_id": 288,
"status": "successful"
},
"avs_cvc_verification": {
"avs_verification": {
"result_code": "1"
},
"cvc_verification": {
"result_code": "1"
}
},
"customer": {
"ip": "127.0.0.1",
"email": "email@example.com",
"device_id": null,
"birth_date": "1998-01-31"
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": null
}
}
}
Коды ошибок
В случае возникновения ошибок при сохранении новой карты в Masterpass воспользуйтесь пояснением кодов для параметра error_code
.
Код ошибки | Описание | Пояснение описания |
---|---|---|
0 | Успешное завершение вызова. | |
1 | The service is not available for this card/user | Карта находится в черном списке. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту. |
2 | Card is not activated | Реквизиты карты в этом статусе не могут быть получены в GetCard. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту |
3 | The card was not found by the token | Карта с таким токеном не найдена. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту |
5 | Customer with this phone number not found | Пользователь с таким телефоном не найден. |
12 | This transaction is marked as fraud | Операция отклонена системой фрод-мониторинга. |
15 | Merchant with such a name and password not found | Обязательное поле Merchant не передано в запросе или мерчант с таким названием не найден. |
16 | Session for the card not found and it is not recurrent | Передана не существующая сессия или срок действия сессии истек. |
17 | Amount <= 0 | Значение параметра Amount должно быть строго больше 0 |
19 | Wrong params | Обязательный параметр Amount не передан в запросе, пустое поле или содержит что-либо кроме цифр. Запрос был отправлен с неверным или неполным набором параметров. Не переданы обязательные параметры или Amount= 0 |
44 | API_NOT_ALLOWED | Сертификат не найден или истек срок действия сертификата или ошибка подписи. |
Пример ответа в случае ошибки при сохранении карты в Masterpass
{
"transaction": {
"uid": "9706-fde9808c80",
"status": "successful",
"amount": 100,
"currency": "USD",
"description": "www",
"type": "payment",
"payment_method_type": "credit_card",
"tracking_id": "save_card_test_masterpass_success_2",
"message": "Successfully processed",
"test": true,
"created_at": "2021-02-12T12:13:43.314Z",
"updated_at": "2021-02-12T12:13:49.492Z",
"paid_at": "2021-02-12T12:13:49.439Z",
"expired_at": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"redirect_url": "https://gateway.bepaid.by/process/9706-fde9808c80",
"credit_card": {
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 5,
"exp_year": 2026,
"token_provider": null,
"token": "330e7e46-2958-41f1-8272-42ea3e05ec4a"
},
"receipt_url": "https://merchant.bepaid.by/customer/transactions/9706-fde9808c80/c13d59bea3867441f360af4d4a7a75d6398d7d2eed34dd48185ee2e6df0522b4",
"id": "9706-fde9808c80",
"additional_data": {
"contract": [
"recurring"
],
"masterpass": {
"params": {
"session": "session"
},
"result": {
"status": "failed",
"message": "SaveCard failed.",
"error": "Masterpass error response",
"error_message": null,
"error_code": 8
}
}
},
"payment": {
"auth_code": "654321",
"bank_code": "05",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was approved",
"amount": 100,
"currency": "USD",
"billing_descriptor": "test descriptor",
"gateway_id": 288,
"status": "successful"
},
"avs_cvc_verification": {
"avs_verification": {
"result_code": "1"
},
"cvc_verification": {
"result_code": "1"
}
},
"customer": {
"ip": "127.0.0.1",
"email": "email@example.com",
"device_id": null,
"birth_date": "1998-01-31"
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": null
}
}
}
Получение списка карт из Masterpass
Прежде чем начать
Откройте сессию пользователя перед получением списка карт из Masterpass.
Info
bePaid убирает из списка карт бренды, по которым bePaid не сможет провести оплату (шлюз магазина может не поддерживать карточный бренд пользователя, который он ранее привязал в Masterpass).
Запрос
Для получения списка карт из Masterpass отправьте POST
запрос на https://gateway.bepaid.by/masterpass/get_cards
со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
session * обязательный |
string | ID пользовательской сессии. |
test | boolean | true или false . Операция будет тестовой, если значение true |
Пример запроса
{
"session": "c96fe83d-366c-420c-9038-da0fae844f0c",
"test": true
}
Ответ
Прежде, чем направить ответ, bePaid проводит его трансформацию:
- Убирает карты с истекшим сроком действия (
CardStatus=5
) из списка карт - Убирает карты, по которым не сможет провести транзакцию, из списка карт.
При успешной обработке запроса система вернет ответ со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
card_list | array | Список карт с их параметрами. |
card_holder * обязательный |
string | Имя владельца карты: только латинские буквы, цифры, пробелы, тире. |
token * обязательный |
string | Токен карты в Masterpass |
date * обязательный |
string | Дата добавления карты. Время в миллисекундах в формате Epoch |
expiry_date * обязательный |
string | Дата окончания срока действия |
pan_mask * обязательный |
string | Первые 6 цифр и последние 4 цифры номера карты |
card_status * обязательный |
integer | Статус карты. Возможные значения: 0 - Inactive. Карта неактивна 1 - Active. Карта активна 2 - CVC2Always. Необходима проверка CVC2 5 - Expired. Срок действия карты истек. |
is_recurring * обязательный |
boolean | Рекуррентная карта. |
card_name * обязательный |
string | Имя карты: буквы должны быть русскими / латинскими, пробелы, тире, * _- +, символы валюты |
comment1 | string | Поле для комментариев 1 |
comment2 | string | Поле для комментариев 2 |
comment3 | string | Поле для комментариев 3 |
Пример ответа при наличии у пользователя карт в Masterpass
{
"card_list": [
{
"card_holder": "Masterpass",
"token": "8358d402-1111-1111-1111-9dc9811debe",
"expiry_date": "02/21",
"pan_mask": "511111xxxxxx8278",
"card_status": 2,
"is_recurring": false,
"card_name": "My card"
}
]
}
Пример ответа, если у пользователя нет карт в Masterpass
{
"card_list": []
}
При ошибке система вернет ответ со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
status * обязательный |
string | Статус запроса. |
error_code * обязательный |
integer | Код ошибки. |
error * обязательный |
string | Сообщение об ошибке. |
Коды ошибок
В случае возникновения ошибок при получении списка карт из Masterpass воспользуйтесь пояснением кодов для параметра error_code
.
Код ошибки | Описание | Пояснение описания |
---|---|---|
0 | None | Успешное завершение вызова. |
2 | Api not allowed | Вызов метода запрещен после превышения допустимого количества запросов. |
8 | No user was found by the passed session | Передана не существующая сессия или срок действия сессии истек. Необходимо заново активировать сессию |
35 | Wrong params | Запрос был отправлен с неверным или неполным набором параметров. |
Пример ответа в случае ошибки
{
"status": "failed",
"error": "Masterpass error response",
"error_code": 8
}
Получение карты из Masterpass
Прежде чем начать
Получите список карт до запроса карты из Masterpass.
Метод используется для каждой транзакции с участием пользователя, чтобы получить актуальные сведения по карте.
Для рекуррентных платежей по токену, метод вызывается автоматически bePaid.
Запрос
Для получения карты из Masterpass отправьте POST
запрос на https://gateway.bepaid.by/masterpass/get_card
со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
token * обязательный |
string | Токен Masterpass (из запроса на получение списка карт) |
amount * обязательный |
integer | Cумма в минимальных денежных единицах. Например, $32.45 должна быть отправлена как 3245 (равна или больше 0) |
session * условно обязательный |
string | Идентификатор сессии пользователя в Masterpass. Обязательный для нерекуррентных карт. |
currency * обязательный |
string | Валюта в ISO-4217 формате, например USD |
test | boolean | true или false . Операция будет тестовой, если значение true |
Пример запроса
{
"session": "a6fd8624-8060-46b3-b343-7a93126fd57f",
"token": "2887f05c-ff7e-4e67-90e6-7d5e75abc036",
"amount": 10000,
"currency ": "USD",
"test": true
}
Ответ
При успешной обработке запроса система вернет ответ со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
credit_card | object | Информация о карте. |
stamp * обязательный |
string | Хэш карты |
brand * обязательный |
string | Название бренда карты |
last_4 * обязательный |
integer | Последние 4 цифры номера карты |
first_1 * обязательный |
integer | Первая цифра номера карты |
bin * обязательный |
integer | BIN-номер карты |
issuer_country * обязательный |
string | Страна выпуска карты |
issuer_name * обязательный |
string | Название эмитента карты |
product * обязательный |
string | Название карточного продукта. |
exp_month * обязательный |
integer | Месяц окончания срока действия карты. 2 цифры |
exp_year * обязательный |
integer | Год окончания срока действия карты. Последние 2 цифры |
token_provider * обязательный |
string | Провайдер токена. Возможные значения или null . |
token * обязательный |
string | Токен карты в системе bePaid |
holder * обязательный |
string | Имя владельца карты: только латинские буквы, цифры, пробелы, тире. |
recommendation * обязательный |
integer | Рекомендация Masterpass (выполнение не обязательно):0 - Рекомендации отсутствуют;1 - Выполнить проверку CVC2;2 - Выполнить проверку 3DS;3 - Выполнить проверку 3DS и CVC2 или CVC2;4 - Выполнить проверку 3DS и CVC2. |
required * обязательный |
integer | Требования Masterpass (выполнение обязательно):0 - Требования отсутствуют;1 - Выполнить проверку CVC2;2 - Выполнить проверку 3DS;3 - Выполнить проверку 3DS и CVC2 или CVC2;4 - Выполнить проверку 3DS и CVC2. |
Пример успешного ответа
{
"credit_card": {
"holder": "JOHN DOE",
"stamp": "80b274398e413d7bddd4d7df8c9b8aa1f9b0a9233bfb7b9cb6de16d06ea31144",
"brand": "visa",
"last_4": "0019",
"first_1": "4",
"bin": "400555",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 10,
"exp_year": 2026,
"token_provider": null,
"token": "4d9e681b-498f-4f68-a4cd-89018a381c70"
},
"recommendation": 0,
"required": 0
}
При ошибке система вернет ответ со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
status * обязательный |
string | Статус запроса. |
error_code * обязательный |
integer | Код ошибки. |
error * обязательный |
string | Сообщение об ошибке. |
Коды ошибок
В случае возникновения ошибок при получении карты из Masterpass воспользуйтесь пояснением кодов для параметра error_code
.
Код ошибки | Описание | Пояснение описания |
---|---|---|
0 | Успешное завершение вызова. | |
1 | The service is not available for this card/user | Карта находится в черном списке. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту |
2 | Card is not activated | Реквизиты карты в этом статусе не могут быть получены в GetCard. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту |
3 | The card was not found by the token | Карта с таким токеном не найдена. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту |
5 | Customer with this phone number not found | Пользователь с таким телефоном не найден. |
12 | This transaction is marked as fraud | Операция отклонена системой фрод-мониторинга. |
15 | Merchant with such a name and password not found | Обязательное поле Merchant не передано в запросе или мерчант с таким названием не найден. |
16 | Session for the card not found and it is not recurrent | Передана не существующая сессия или срок действия сессии истек. |
17 | Amount <= 0 | Значение параметра Amount должно быть строго больше 0 |
19 | Wrong params | Обязательный параметр Amount не передан в запросе, пустое поле или содержит что-либо кроме цифр. |
44 | API_NOT_ALLOWED | Сертификат не найден или истек срок действия сертификата или ошибка подписи. |
Пример неуспешного ответа
{
"status":"failed",
"error":"Masterpass error response",
"error_code":16
}
Получение карты из Masterpass по токену bePaid
Прежде чем начать
Перед получением информации о карте из Masterpass должна быть открыта сессия пользователя.
Метод используется для каждой транзакции с участием пользователя, чтобы получить актуальные сведения по карте, которая была ранее токенизирована в bePaid.
Для рекуррентных платежей по токену метод вызывается автоматически bePaid.
Запрос
Отправьте POST
запрос на https://gateway.bepaid.by/masterpass/get_saved_card
со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
session * условно опциональный |
string | Идентификатор сессии пользователя в Masterpass. Обязательный для нерекуррентных карт. |
credit_card_token * обязательный |
string | Токен bePaid (из ответа на запрос токенизации карты) |
amount * обязательный |
integer | Cумма в минимальных денежных единицах. Например, $32.45 должна быть отправлена как 3245. |
currency * обязательный |
string | Валюта в ISO-4217 формате, например USD. |
test | boolean | Операция будет тестовой, если значение true . Иначе, false . |
Пример запроса
{
"session": "5cb1ed91-8755-4a9c-89a0-c69899b36f6f",
"credit_card_token": "639c0b58-118e-44f6-ad8c-623592710ba",
"amount": 100,
"currency": "USD",
"test": true
}
Ответ
Параметр | Тип | Описание |
---|---|---|
credit_card | object | Информация о карте. |
stamp * обязательный |
string | Хеш карты. |
brand * обязательный |
string | Название бренда карты. |
last_4 * обязательный |
integer | Последние 4 цифры номера карты. |
first_1 * обязательный |
integer | Первая цифра номера карты. |
bin * обязательный |
integer | BIN-номер карты. |
issuer_country * обязательный |
string | Страна выпуска карты. |
issuer_name * обязательный |
string | Название эмитента карты. |
product * обязательный |
string | Название карточного продукта. |
exp_month * обязательный |
integer | Месяц окончания срока действия карты. 2 цифры. |
exp_year * обязательный |
integer | Год окончания срока действия карты. Последние 2 цифры. |
token_provider * обязательный |
string | Провайдер токена. |
token * обязательный |
string | Токен карты в системе bePaid. |
holder * обязательный |
string | Имя владельца карты: только латинские буквы, цифры, пробелы, тире. |
recommendation * обязательный |
integer | Рекомендация Masterpass (выполнение не обязательно). Возможные значения:0 - Рекомендации отсутствуют;1 - Выполнить проверку CVC2;2 - Выполнить проверку 3DS;3 - Выполнить проверку 3DS и CVC2 или CVC2;4 - Выполнить проверку 3DS и CVC2. |
required * обязательный |
integer | Требования Masterpass (выполнение обязательно). Возможные значения:0 - Требования отсутствуют;1 - Выполнить проверку CVC2;2 - Выполнить проверку 3DS;3 - Выполнить проверку 3DS и CVC2 или CVC2;4 - Выполнить проверку 3DS и CVC2. |
Пример успешного ответа
{
"credit_card": {
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 5,
"exp_year": 2026,
"token_provider": null,
"token": "639c0b58-118e-44f6-ad8c-623592710ba5"
},
"recommendation": 0,
"required": 0
}
Пример неуспешного ответа
{
"status": "failed",
"error": "Params validation error",
"message": "No credit card found"
}
Совершение платежа картой из Masterpass
Прежде чем начать
Чтобы совершить платеж по карте, привязанной к Masterpass, необходимо предварительно запросить данные карты из Masterpass и с полученным токеном bePaid провести оплату.
Если платеж рекуррентный, то открывать пользовательскую сессию не надо.
В текущий запрос на оплату добавляется секция Masterpass с указанием значения session
.
Запрос
Для совершения платежа картой из Masterpass отправьте POST
запрос на https://gateway.bepaid.by/transactions/payments
со следующими дополнительными параметрами в секции request.additional_data
:
Параметр | Тип | Описание |
---|---|---|
additional_data | object | Секция, содержащая дополнительную информацию о платеже. |
masterpass | object | Секция для работы с сервисом Masterpass. |
params | object | Секция для параметров Masterpass. |
session * обязательный |
string | ID пользовательской сессии. |
Пример запроса
{
"request": {
"amount": 100,
"currency": "USD",
"description": "www",
"tracking_id": "masterpass_test_by_token",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"country": "US",
"city": "Denver",
"state": "CO",
"zip": "96002",
"address": "1st Street"
},
"credit_card": {
"token": "03d65020-07c4-4987-b96a-72ec9727ac1f",
"verification_value": 123
},
"additional_data": {
"masterpass": {
"params": {
"session": "037ead94-b11c-4dff-ad73-9e8a414ceb80"
}
}
},
"customer": {
"ip": "127.0.0.1",
"email": "email@example.com",
"birth_date": "1998-01-31"
},
"test": true
}
}
Ответ
Пример ответа
{
"transaction": {
"uid": "9707-af6046bd28",
"status": "failed",
"amount": 100,
"currency": "USD",
"description": "www",
"type": "payment",
"payment_method_type": "credit_card",
"tracking_id": "masterpass_test_by_token",
"message": "Payment was declined",
"test": true,
"created_at": "2021-02-12T12:19:15.314Z",
"updated_at": "2021-02-12T12:19:20.541Z",
"paid_at": "2021-02-12T12:19:20.520Z",
"expired_at": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"redirect_url": "https://gateway.bepaid.by/process/9707-af6046bd28",
"credit_card": {
"holder": "JOHN DOE",
"stamp": "80b274398e413d7bddd4d7df8c9b8aa1f9b0a9233bfb7b9cb6de16d06ea31144",
"brand": "visa",
"last_4": "0019",
"first_1": "4",
"bin": "400555",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 10,
"exp_year": 2026,
"token_provider": null,
"token": "03d65020-07c4-4987-b96a-72ec9727ac1f"
},
"receipt_url": "https://merchant.bepaid.by/customer/transactions/9707-af6046bd28/86e2642265417ab4f4d9102f3092b29dd7ace5a0a925727f9920f0b165e40111",
"id": "9707-af6046bd28",
"additional_data": {
"masterpass": {
"params": {
"session": "037ead94-b11c-4dff-ad73-9e8a414ceb80"
},
"result": {
"status": "successful",
"message": "Postback successfully finished."
}
}
},
"payment": {
"auth_code": "654321",
"bank_code": "10",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was declined",
"amount": 100,
"currency": "USD",
"billing_descriptor": "test descriptor",
"gateway_id": 288,
"status": "failed"
},
"avs_cvc_verification": {
"avs_verification": {
"result_code": null
},
"cvc_verification": {
"result_code": null
}
},
"customer": {
"ip": "127.0.0.1",
"email": "email@example.com",
"device_id": null,
"birth_date": "1998-01-31"
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": null
}
}
}
Коды ошибок
В случае возникновения ошибки при совершении платежа картой из Masterpass, чтобы понять причину ошибки, воспользуйтесь пояснением кодов для параметра error_code
.
Код ошибки | Описание | Пояснение описания |
---|---|---|
0 | Успешное завершение вызова. | |
1 | The service is not available for this card/user | Карта находится в черном списке. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту. |
2 | Card is not activated | Реквизиты карты в этом статусе не могут быть получены в GetCard. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту |
3 | The card was not found by the token | Карта с таким токеном не найдена. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту |
5 | Customer with this phone number not found | Пользователь с таким телефоном не найден. |
12 | This transaction is marked as fraud | Операция отклонена системой фрод-мониторинга. |
15 | Merchant with such a name and password not found | Обязательное поле Merchant не передано в запросе или мерчант с таким названием не найден. |
16 | Session for the card not found and it is not recurrent | Передана не существующая сессия или срок действия сессии истек. |
17 | Amount <= 0 | Значение параметра Amount должно быть строго больше 0 |
19 | Wrong params | Обязательный параметр Amount не передан в запросе, пустое поле или содержит что-либо кроме цифр. Запрос был отправлен с неверным или неполным набором параметров. Не переданы обязательные параметры или Amount= 0 |
44 | API_NOT_ALLOWED | Сертификат не найден или истек срок действия сертификата или ошибка подписи. |
Удаление карты из Masterpass
Info
Перед удалением карты из Masterpass должен быть получен список карт из Masterpass.
Запрос
Для удаления карты из Masterpass отправьте POST
запрос на https://gateway.bepaid.by/masterpass/delete_card
со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
token * обязательный |
string | Токен Masterpass (из запроса на получение списка карт) |
session * обязательный |
string | Идентификатор сессии пользователя в Masterpass |
test | boolean | true или false . Операция будет тестовой, если значение true |
Пример запроса
{
"session": "d1d88fb8-1bf1-4c82-9c8b-00c9d887d821",
"token": "07be2846-aa35-480c-b1f8-a01d8674fadb",
"test": true
}
Ответ
Параметр | Тип | Описание |
---|---|---|
status | string | Результат удаления карты в Masterpass. Возможные значения:successful , failed |
error_code | integer | Код ошибки. |
error | string | Текст ошибки из Masterpass. |
Коды ошибок
В случае возникновения ошибки при удалении карты из системы Masterpass, чтобы понять причину ошибки, воспользуйтесь пояснением кодов для параметра error_code
.
Код ошибки | Описание | Пояснение описания |
---|---|---|
0 | Успешное завершение вызова. | |
1 | Access denied | У мерчанта нет права вызова этого метода. |
5 | Card not found | Карта с таким токеном не найдена. Например, она была удалена из Masterpass. Рекомендуется обновить список карт вызовом GetCards или позволить пользователю сохранить новую карту |
8 | No user was found by the passed session | Передана не существующая сессия или срок действия сессии истек. Необходимо заново активировать сессию |
20 | Internal error | Внутренняя системная ошибка, требуется дополнительная проверка командой Masterpass |
30 | Invalid Token card for this request | Обязательный параметр Token не передан, передано пустое поле или состоящее из пробелов. |
35 | Wrong params | Запрос был отправлен с неверным или неполным набором параметров. |
Пример успешного ответа
{
"status": "successful"
}
Пример неуспешного ответа
{
"status": "failed",
"error": "Masterpass error response",
"error_code": 8
}