Платеж банковской картой Humo или Uzcard

к сведению

Если вы не получаете вебхуки, пользуйтесь методом session/status для получения информации по транзакции.

Чтобы провести платеж картой Humo или Uzcard, выполните следующие шаги:

1. Создайте платежную сессию (session/create).

   В качестве альтернативы вы можете создать сессию и платеж одновременно при помощи метода session/init/payment.

   Пример

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

   curl -X POST \
   https://proxy.bank131.ru/api/v1/session/create \
   -H 'Content-Type: application/json' \
   -H 'X-PARTNER-PROJECT: your_project_name' \
   -H 'X-PARTNER-SIGN: signature' \
   -d '{
    "amount_details": {
        "amount": 2499900,
        "currency": "UZS"
    },
    "customer": {
        "reference": "1234567890"
    },
    "payment_details": {
        "type": "card",
        "card": {
            "type": "bank_card",
            "bank_card": {
                "number": "8600780422601850",
                "expiration_month": "11",
                "expiration_year": "28",
            }
        }
    }
    }'

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

   {
    "status": "ok",
    "session": {
        "id": "ps_3230",
        "status": "created",
        "created_at": "2024-10-08T11:51:12.213675Z",
        "updated_at": "2024-10-08T11:51:12.213675Z"
    }
   }

2. Отправьте запрос session/start/payment.

   Чтобы получить токен для рекуррентных платежей, передайте recurrent=true в объекте payment_options.

   Пример

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

   curl -X POST \
   https://proxy.bank131.ru/api/v1/session/start/payment \
   -H 'Content-Type: application/json' \
   -H 'X-PARTNER-PROJECT: your_project_name' \
   -H 'X-PARTNER-SIGN: signature' \
   -d '{
    "session_id": "ps_3230",
    "payment_options": {
        "return_url": "return url",
        "recurrent": false
    }
    }'

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

   {
    "status": "ok",
    "session": {
        "id": "ps_3230",
        "status": "in_progress",
        "created_at": "2024-10-08T11:51:12.213675Z",
        "updated_at": "2024-10-08T11:51:12.581086Z",
        "acquiring_payments": [
            {
                "id": "pm_2501",
                "status": "in_progress",
                "created_at": "2024-10-08T11:51:12.626283Z",
                "customer": {
                    "reference": "1234567890"
                },
                "payment_details": {
                    "type": "card",
                    "card": {
                        "brand": "humo",
                        "last4": "1850",
                        "country_iso3": "UZB"
                    }
                },
                "amount_details": {
                    "amount": 2499900,
                    "currency": "UZS"
                }
            }]
    }                   
    }'

3. Дождитесь от Банка 131 вебхука ready_to_confirm — это значит, что Банк готов провести платеж и ждет вашего подтверждения.

4. Подтвердите проведение платежа (session/confirm) или отмените его (session/cancel).

   Пример

   Пример подтверждения

   curl -X POST \
   https://proxy.bank131.ru/api/v1/session/confirm \
   -H 'Content-Type: application/json' \
   -H 'X-PARTNER-PROJECT: your_project_name' \
   -H 'X-PARTNER-SIGN: signature' \
   -d '{
     "session_id": "ps_3230"
   }'

   Пример отмены

   curl -X POST \
   https://proxy.bank131.ru/api/v1/session/cancel \
   -H 'Content-Type: application/json' \
   -H 'X-PARTNER-PROJECT: your_project_name' \
   -H 'X-PARTNER-SIGN: signature' \
   -d '{
     "session_id": "ps_3230"
   }'

5. Если вы получите вебхук action_required от Банка 131, это значит, что нужно отправить код аутентификации по адресу, указанному в callback_url в объекте accept_code.

   Пример

   {
    "type": "action_required",
    "session": {
        "id": "ps_3230",
        "status": "in_progress",
        "created_at": "2024-10-08T11:51:12.213675Z",
        "updated_at": "2024-10-08T11:51:15.526791Z",
        "acquiring_payments": [
            {
                "id": "pm_2501",
                "status": "pending",
                "created_at": "2024-10-08T11:51:12.626283Z",
                "customer": {
                    "reference": "1234567890"
                },
                "payment_details": {
                    "type": "card",
                    "card": {
                        "brand": "humo",
                        "last4": "1850",
                        "country_iso3": "UZB"
                    }
                },
                "amount_details": {
                    "amount": 2499900,
                    "currency": "UZS"
                },
                "customer_interaction": {
                    "type": "redirect",
                    "redirect": {
                        "url": "url address",
                        "base_url": "base url address",
                        "method": "GET",
                        "params": {}
                    }
                },
                "customer_authorization": {
                    "suspend_key": "suspend key value",
                    "accept_code": {
                        "rest_of_attempts": 3,
                        "active_to": "2024-10-08T11:52:14+00:00",
                        "callback_url": "https://proxy.bank131.ru/provider/v1/public/ZPlatProvider/verify/_hash_code"
                    },
                    "resend_sms": {
                        "rest_of_attempts": 2,
                        "allowed_from": "2024-10-08T11:52:14+00:00",
                        "callback_url": "https://proxy.bank131.ru/provider/v1/public/ZPlatProvider/resend/_hash_code"
                    },
                    "type": "sms"
                },
                "payment_options": {
                    "return_url": "return url",
                    "recurrent": false
                }
            }
        ],
        "actions": {
            "confirm": "2024-10-08T11:51:12.697715Z"
        }
    }
   }

6. Запросите код у плательщика (6 цифр) и отправьте его в поле otp, а также отправьте поле suspend_key (скопируйте его значение из вебхука) на указанный адрес.

   Пример отправки кода

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

   curl -X POST \
   https://proxy.bank131.ru/provider/v1/public/ZPlatProvider/verify/_hash_code \
   -H 'Content-Type: application/json' \
   -H 'X-PARTNER-PROJECT: your_project_name' \
   -H 'X-PARTNER-SIGN: signature' \
   -d '{
   "suspend_key": "suspend key value",
    "otp": "999999"
   }'

   Пример успешного ответа

   {
   }

   Пример неуспешного ответа

   {
    "status": "error",
    "error": {
        "description": "Internal error",
        "code": "internal_error"
    }
   }

   Перешлите код еще раз (всего 3 попытки), если:

   • получили неуспешный ответ,
   • не получили вебхук ready_to_capture или payment_finished.

   Запросите новый код, используя адрес из объекта resend_sms, если:

   • СМС не пришло,
   • срок действия кода истек,
   • закончились попытки отправки кода и пришел вебхук payment_finished.
     
   Пример запроса кода

   curl -X POST \
   https://proxy.bank131.ru/provider/v1/public/ZPlatProvider/resend/_hash_code \
   -H 'Content-Type: application/json' \
   -H 'X-PARTNER-PROJECT: your_project_name' \
   -H 'X-PARTNER-SIGN: signature' \
   -d '{
   }'
   Важно!

   Если плательщик введет неправильный код:

   1. Банк пришлет новый вебхук action_required, в котором статус в объекте acquiring_payments/payment_list будет pending.

   2. Вернется ошибка по транзакции provider_internal_error, означающая, что верификация не пройдена.
      

   В этом случае запросите новый код.

7. При получении от Банка 131 вебхука ready_to_capture отправьте запрос session/capture, чтобы продолжить операцию, или запрос session/cancel, чтобы ее отменить.

   Пример

   Пример подтверждения

   curl -X POST \
   https://proxy.bank131.ru/api/v1/session/capture \
   -H 'Content-Type: application/json' \
   -H 'X-PARTNER-PROJECT: your_project_name' \
   -H 'X-PARTNER-SIGN: signature' \
   -d '{
     "session_id": "ps_3230"
   }'

   Пример отмены

   curl -X POST \
   https://proxy.bank131.ru/api/v1/session/cancel \
   -H 'Content-Type: application/json' \
   -H 'X-PARTNER-PROJECT: your_project_name' \
   -H 'X-PARTNER-SIGN: signature' \
   -d '{
     "session_id": "ps_3230"
   }'

8. Дождитесь от Банка 131 вебхука payment_finished с результатом проведения платежа. Статус succeeded означает, что платеж успешно проведен.

   Пример

   {
    "type": "payment_finished",
    "session": {
        "id": "ps_3230",
        "status": "accepted",
        "created_at": "2024-10-08T11:51:12.213675Z",
        "updated_at": "2024-10-08T11:51:51.344550Z",
        "acquiring_payments": [
            {
                "id": "pm_2501",
                "status": "succeeded",
                "created_at": "2024-10-08T11:51:12.626283Z",
                "finished_at": "2024-10-08T11:51:50.668491Z",
                "customer": {
                    "reference": "1234567890"
                },
                "payment_details": {
                    "type": "card",
                    "card": {
                        "brand": "humo",
                        "last4": "1850",
                        "country_iso3": "UZB"
                    }
                },
                "amount_details": {
                    "amount": 2499900,
                    "currency": "UZS"
                },
                "payment_options": {
                    "return_url": "return url",
                    "recurrent": false
                }
            }
        ],
        "actions": {
            "confirm": "2024-10-08T11:51:12.697715Z",
            "capture": "2024-10-08T11:51:44.460417Z"
        }
    }
    }

Схема платежа картами Humo и Uzcard