Skip to main content

Payments by Uzcard or Humo cards

info

If you have the webhooks disabled, use the session/status method to get information on your transaction.

You can only accept payments by Uzbek cards if you have a PCI DSS certificate.

To make a payment by Uzcard or Humo card, complete the following steps:

  1. Create a payment session (session/create).

    Alternatively, you can create a session along with the payment using the session/init/payment method.

    Example
    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",
             }
         }
     }
     }'

  2. Send a session/start/payment request.

    To get a token for recurring payments, send recurrent=true in the payment_options object.

    Example
    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
     }
     }'

  3. Wait for a ready_to_confirm webhook, which means that the Bank is ready to perform the payment and is waiting for your confirmation.

  4. Confirm the payment (session/confirm) or cancel it (session/cancel).

    Example
    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"
    }'

  5. If you get an action_required webhook, it means that the Bank is expecting an authentication code from you at the address specified in callback_url of the accept_code object.

    Example
    {
     "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. Get the code from the payer (6 digits) and send it in the otp parameter along with the suspend_key parameter (copy its value from the webhook) to the specified address.

    Sending a code
    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" 
    }'

    Retry to send the code (up to 3 attempts) if:

    • you get an unsuccessful response
    • you do not get any webhook, neither ready_to_capture nor payment_finished

    Request a new code using the address from the resend_sms object if:

    • the payer does not get an SMS with a code
    • the code expires
    • you do not have any attempts left and get a payment_finished webhook
    Requesting a new code
    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 '{
    }'
    info

    If the payer enters a wrong code:

    1. The Bank will send a new action_required webhook with the pending status in the acquiring_payments object.
    2. You will get a verification error (provider_internal_error).

    In this case, request a new code.

  7. When you receive a ready_to_capture webhook, send a session/capture request to continue the operation or a session/cancel request to cancel it.

    Example
    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"
    }'

  8. Wait for a payment_finished webhook with the payment results. The succeeded status means that the payment was successful.

    Example
    {
     "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"
         }
     }
     }

Sequence diagram of Uzbek card payments​

Uzbek card payments