Abby Cardholder Validator

На основании требований нормативных документов Мерчанты, занимающиеся гэмблингом и/или продажей/покупкой криптовалюты, должны верифицировать принадлежность платежных карт физическим лицам.

С целью проведения такой верификации при обработке платежей разработан REST API сервис Abby Cardholder Validator (далее Прокси). Этот сервис обеспечивает интеграцию с Платежным шлюзом и внешними сервисами валидации для проведения транзакций электронной коммерции.

Проверка принадлежности карты физическому лицу выполняется при оплате, вне зависимости от того, делает ли Клиент привязку карты или нет. Если Мерчант прислал определенные параметры в запросе на регистрацию, относящиеся к персональным данным, и в его настройках включена необходимость верификации карт, то такую операцию требуется отправлять на проверку принадлежности карты Клиенту.

На основании настроек сервис:

• Определяет возможность проведения валидации для переданных карточных данных. При необходимости, если сервис не может провалидировать переданные карточные данные, сервис может отклонять либо проводить подобный платеж, в зависимости от пожеланий Мерчанта (для включения такой возможности обратитесь в команду поддержки)
• Проводит по API валидацию во внешнем сервисе
• Анализирует статус валидации для принятия решения о возможности проведения транзакции
• Сохраняет статус валидации в атрибут транзакции externalServiceCardValidation (см. возможные значения ниже)

Сценарий работы

Типовой сценарий работы (когда ПС находится на стороне Платежного шлюза):

1. Клиент оформляет заказ у Мерчанта
2. Мерчант отправляет запрос регистрации заказа в Прокси, передавая персональные данные клиента
3. Прокси валидирует полноту полученных данных Клиента
4. Если валидация успешна, то Прокси вызывает регистрацию заказа в Платежном Шлюзе
5. Платежный Шлюз возвращает Прокси ссылку на платежную страницу
6. Прокси возвращает Мерчанту ссылку на платежную страницу
7. Мерчант отображает клиенту платежную страницу
8. Клиент вводит карточные данные на платежной странице
9. Платежная страница вызывает в Прокси метод оплаты картой, передавая карточные данные
10. Прокси определяет необходимость проверки принадлежности карты
11. Прокси вызывает сервис проверки принадлежности карты
12. Прокси проверяет статус проверки
13. При успешной проверке Прокси вызывает запрос оплаты в Платежном шлюзе
14. Платежный шлюз сохраняет в атрибуты транзакции статус валидации карты
15. Платежный шлюз возвращает Прокси результат оплаты
16. Прокси возвращает на платежную страницу результат оплаты

Методы API

Базовый URL-адрес

Для отправки запросов в Прокси (Abby Cardholder Validator) используется базовый URL-адрес: https://abby.rbsuat.com/abby-cardholder-validator.

Формат данных

• Формат запросов: application/x-www-form-urlencoded
• Формат ответов: application/json (возвращается как byte[])
• Кодировка: UTF-8

Аутентификация

Для аутентификации используются параметры:

• userName - имя пользователя API Мерчанта
• password - пароль Мерчанта

Для тестирования методов API можно использовать тестовые данные.

Регистрация заказа

Для регистрации заказа используется запрос https://abby.rbsuat.com/abby-cardholder-validator/payment/rest/register.do.

Параметры запроса

Ниже приведены параметры блока billingPayerData (персональные данные плательщика). Состав и обязательность параметров зависит от того, является ли плательщик резидентом Республики Беларусь. Резидентство определяется по значению параметра payerIdType:

• payerIdType = IDTP8 - нерезидент
• Любое иное значение или отсутствие - резидент

Для резидентов РБ:

Для нерезидентов РБ:

Параметры ответа

Примеры

Пример запроса для резидента РБ

curl -X POST 'https://abby.rbsuat.com/abby-cardholder-validator/payment/rest/register.do' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'userName=merchant_api_user' \
 -d 'password=merchant_password' \
 -d 'orderNumber=ORDER-12345' \
 -d 'amount=100000' \
 -d 'currency=933' \
 -d 'returnUrl=https://merchant.com/success' \
 -d 'description=Payment for order 12345' \
 -d 'billingPayerData.billingCountry=BY' \
 -d 'billingPayerData.payerBirthday=1990-01-15' \
 -d 'billingPayerData.payerIdNumber=1234567890123'

Пример запроса для нерезидента РБ

curl -X POST 'https://abby.rbsuat.com/abby-cardholder-validator/payment/rest/register.do' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'userName=merchant_api_user' \
 -d 'password=merchant_password' \
 -d 'orderNumber=ORDER-12345' \
 -d 'amount=100000' \
 -d 'currency=933' \
 -d 'returnUrl=https://merchant.com/success' \
 -d 'description=Payment for order 12345' \
 -d 'billingPayerData.billingCountry=RU' \
 -d 'billingPayerData.payerBirthday=1990-01-15' \
 -d 'billingPayerData.payerFirstName=John' \
 -d 'billingPayerData.payerLastName=Doe' \
 -d 'billingPayerData.payerIdType=IDTP8' \ 
 -d 'billingPayerData.payerIdNumber=1234567890123' \
 -d 'billingPayerData.payerDocumentDate=2020-01-15'

Пример ответа - успех

{
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "formUrl": "https://abby.rbsuat.com/paymentpayment/form?mdOrder=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Пример ответа - ошибка

{
  "errorCode": "118",
  "errorMessage": "Missing required personal data fields"
}

Коды ответов:

• 200 OK - Заказ успешно зарегистрирован (или ошибка в JSON с errorCode)
• 400 Bad Request - Некорректные входные данные
• 500 Internal Server Error - Внутренняя ошибка сервера

Регистрация заказа c предавторизацией

Для регистрации заказа c предавторизацией используется запрос https://abby.rbsuat.com/abby-cardholder-validator/payment/rest/registerPreAuth.do.

Параметры запроса

Ниже приведены параметры блока billingPayerData (персональные данные плательщика). Состав и обязательность параметров зависит от того, является ли плательщик резидентом Республики Беларусь. Резидентство определяется по значению параметра payerIdType:

• payerIdType = IDTP8 - нерезидент
• Любое иное значение или отсутствие - резидент

Для резидентов РБ:

Для нерезидентов РБ:

Параметры ответа

Примеры

Пример запроса для резидента РБ

curl -X POST 'https://abby.rbsuat.com/abby-cardholder-validator/payment/rest/registerPreAuth.do' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'userName=merchant_api_user' \
 -d 'password=merchant_password' \
 -d 'orderNumber=PREAUTH-12345' \
 -d 'amount=50000' \
 -d 'currency=933' \
 -d 'returnUrl=https://merchant.com/success' \
 -d 'billingPayerData.billingCountry=BY' \
 -d 'billingPayerData.payerBirthday=1990-01-15' \
 -d 'billingPayerData.payerIdNumber=1234567890123'

Пример ответа - успех

{
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "formUrl": "https://abby.rbsuat.com/paymentpayment/form?mdOrder=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Пример ответа - ошибка

{
  "errorCode": "118",
  "errorMessage": "Missing required personal data fields"
}

Обработка платежа по заказу

Для обработки платежа с валидацией владения картой для существующего заказа используется запрос https://abby.rbsuat.com/abby-cardholder-validator/payment/rest/paymentorder.do.

Процесс обработки:

• Извлечение данных карты (BIN, маска, срок действия)
• Аутентификация мерчанта
• Извлечение персональных данных из заказа
• Определение необходимости и типа валидации
• Валидация владения картой через внешний сервис
• Обработка платежа через Платежный шлюз (при успешной валидации)
• Сохранение статуса валидации в атрибуты транзакции

Параметры запроса

Параметры ответа

Примеры

Пример запроса

curl -X POST 'https://abby.rbsuat.com/abby-cardholder-validator/payment/rest/paymentorder.do' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'mdOrder=a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
 -d 'pan=4111111111111111' \
 -d 'cvc=123' \
 -d 'expiry=202512' \
 -d 'cardHolderName=JOHN DOE'

Пример ответа - успех

{
 "success": true,
 "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "redirect": "https://payment-gateway.com/success"
}

Пример ответа - ошибка

{
 "errorCode": 116,
 "errorMessage": "Card validation failed"
}

Платеж по связке

Для обработки платежа для существующего заказа с использованием сохраненного привязанного ID карты (связки) используется запрос https://abby.rbsuat.com/abby-cardholder-validator/payment/rest/paymentOrderBinding.do.

Персональные данные извлекаются из существующего заказа.

Параметры запроса

Параметры ответа

Примеры

Пример запроса

curl -X POST 'https://abby.rbsuat.com/abby-cardholder-validator/payment/rest/paymentOrderBinding.do' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'userName=merchant_api_user' \
 -d 'password=merchant_password' \
 -d 'mdOrder=a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
 -d 'bindingId=550e8400-e29b-41d4-a716-446655440000' \
 -d 'ip=192.168.1.1' \
 -d 'language=en'

Пример ответа - успех

{
 "success": true,
 "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Коды ошибок

Статус валидации в атрибутах транзакции

Атрибут транзакции externalServiceCardValidation отображает значение статуса валидации в консоли администратора.

Возможные значения перечислены в таблице ниже.

Сообщения об ошибках на ПС

При отклонении платежа на платежной странице Клиента могут отображаться следующие сообщения:

Тестовые данные БелПЦ

Для тестирования взаимодействия с Прокси можно использовать следующие тестовые данные клиентов:

Резидент РБ

9112500000051990
Срок действия 12/34
CVC 123
Иванов Иван Иванович, 01.01.2000
Паспорт MP3012345, 5010100C001PB5

Нерезидент РБ

9112500000051925
Срок действия 12/34
CVC 123
Jane X Doe, 02.02.2000
Паспорт EC9271036 (латиница), тип документа - 09