Acquiring (payment) for UzCard/HUMO

URL payment gateway

https://paysys.uz/gateway

Attention!

PCI DSS Service Provider Certification required.

The stages of the communication process are shown in the diagram:

User card registration

Method's name: paysys.card_registration
Authorization: requires

Registration a user card in the PaySys system allows you to pay for goods and services in the future without SMS confirmation. After successful registration, the partner system will receive a user card token that can be used in requests for payments by passing them in the request header.

Request contains:

phone_number - Phone number, 12 digits in the format 998907702150
card_number - Card number
card_expire - Card expiration dates. Date format YYMM

Request example

{
  "method": "paysys.card_registration",
  "params": {
    "phone_number": "998907702150",
    "card_number": "8600330410689500",
    "card_expire": "2304"
  },
  "id": "0d61b196-9575-11ec-b909-0242ac120002"
}

Response contains:

id - Card ID in the PaySys system
masked_phone_number - Phone number to which the SMS code was sent to complete the payment
time_out - Lifetime of the SMS code to confirm the operation
mx_id - Request tracker

Response example

{
  "id": "0d61b196-9575-11ec-b909-0242ac120002",
  "error": null,
  "result": {
    "id": "6A0A002A1289688F2CDA1F1C0686359C16",
    "masked_phone_number": "+99890*****50",
    "time_out": 120
  },
  "mx_id": "60b9408332261f741449e42fe6903eac"
}

In case of invalid request parameters, the system will return error.

Card registration confirmation

Method's name: paysys.card_confirm
Authorization: requires

Request contains:

card_id - Card ID in the PaySys system
confirmation_code - Confirmation code received by the user from SMS

Request example

{
  "method": "paysys.card_confirm",
  "params": {
    "card_id": "6A0A002A1289688F2CDA1F1C0686359C16",
    "confirmation_code": "254004"
  },
  "id": "c183b8b2-9576-11ec-b909-0242ac120002"
}

Response contains:

card_token - Card token (returned NULL if the phone_number parameter was not sent during card registration or the number does not match the number associated with this card)
card_data - Object with detailed map information
- id - Card ID in the PaySys system
- username - User login in the PaySys system
- pan - Card number
- expiry - Card expiration date. Date format YYMM`
- status - Card status.
- phone - User phone number, 12 digits in the format 998907702150
- fullName - User name
- balance - Card balance amount in tiins
- sms - flag, sms notifications
  true – The card is active, SMS notification is connected.
  false – SMS notification is not connected.
mx_id - Request tracker

Response example

{
  "id": "c183b8b2-9576-11ec-b909-0242ac120002",
  "error": null,
  "result": {
    "card_token": "reethaa7ae2jooqee90t2neiloh8wai2jo",
    "card_data": {
      "id": "6A0A002A1289688F2CDA1F1C0686359C16",
      "username": "aloqa",
      "pan": "860033******1501",
      "expiry": "2304",
      "status": 0,
      "phone": "998907702150",
      "fullName": "TEST TEST2",
      "balance": 200000,
      "sms": true
    }
  },
  "mx_id": "27e8b6197f146e0ab14d01fe7ba6f362"
}

In case of invalid request parameters, the system will return error.

Preparing for online payment

Method's name: pam.prepare_payment
Authorization: requires

Online payment can be made by card number and by its identifier in the PaySys.

For paying by card number, you must send its number and expiration date.
For paying by card ID, just send its id.
After requesting a method, the confirmation code will be sent to the user's phone, with which the user will confirm payment.
If a phone number is not linked to the payment card, the method will return an error with the code _ -32311

Request contains:

Card data
- card_id - Card ID in the PaySys system
  or
- card_number - Card number
- card_expire - Card Expiry Date. Date formatYYMM
phone_number -User phone number, 12 digits in the format 998907702150
amount - Amount in tiins
vendor_id - Site ID for the provision of services
product - Order identifier (personal account, subscription, user)
comment - Comment for payment
save - Map save flag
true - Save the payment card in the PaySys system - after confirming the payment, the PaySys system will return the identifier and card token
false - Do not save the payment card (by default)

Request example using card number

{
  "method": "pam.prepare_payment",
  "params": {
    "card_number": "8601312960622192",
    "card_expire": "2302",
    "phone_number": "998907702150",
    "amount": 100000,
    "vendor_id": 100381,
    "product": "11011bd8-955d-11ec-b909-0242ac120002",
    "comment": "Month subscription",
    "hold": true,
    "holding_time": 604800,
    "after_expired": "accept",
    "save": true
  },
  "id": "bb2656ec-955c-11ec-b909-0242ac120002"
}

Request example using card id

{
  "method": "pam.prepare_payment",
  "params": {
    "card_id": "6A0A002A1289688F2CDA1F1C0686359C16",
    "phone_number": "998907702150",
    "amount": 100000,
    "vendor_id": 100381,
    "product": "11011bd8-955d-11ec-b909-0242ac120002",
    "comment": "Month subscription",
    "hold": true,
    "holding_time": 604800,
    "after_expired": "accept",
    "save": true
  },
  "id": "bb2656ec-955c-11ec-b909-0242ac120002"
}

Response contains:

bank_transaction_id - Transaction number in the PaySys
masked_phone_number - Phone number to which the SMS code was sent to complete the payment
time_out - Lifetime of the SMS code to confirm the operation
mx_id - Request tracker

Response example

{
  "id": "bb2656ec-955c-11ec-b909-0242ac120002",
  "error": null,
  "result": {
    "bank_transaction_id": 1485295,
    "masked_phone_number": "+99890*****50",
    "time_out": 120
  },
  "mx_id": "be5bf35a31e58b1d1cf176c4c4574028"
}

In case of invalid request parameters, the system will return error.

Confirmation of online payment

Method's name: pam.confirm_payment
Authorization: requires

If incorrect confirmation code is sent or the code has expired, the method will return error with code -32308.

Request contains:

bank_transaction_id - Transaction number in the PaySys system
confirmation_code - Payment confirmation code received via SMS

Request example

{
  "method": "pam.confirm_payment",
  "params": {
    "bank_transaction_id": 1485295,
    "confirmation_code": "253890"
  },
  "id": "67f922e4-955f-11ec-b909-0242ac120002"
}

Response contains:

details - Object with the details of the made payment
- id - Intermediate Request ID
- masked_card_number - Card number
- transaction_id -Transaction ID in the PaySys system
- bank_transaction_id - Transaction number in the PaySys system
- reference_number - Processing center transaction ID
- merchantId - Service provider identifier in the UZCARD ONLINE/HUMO system
- terminalId - Terminal identifier in the UZCARD ONLINE/HUMO system
- amount - Transaction amount in tiins
- date - Transaction creation date in seconds
card - Object with card data (only present if the save: true flag is specified during the payment)
- id - Payment card ID
- token - Payment card token - in use for payment without confirmation payment by SMS code
mx_id - Request tracker

Response example

{
  "id": "67f922e4-955f-11ec-b909-0242ac120002",
  "error": null,
  "result": {
    "details": {
      "id": "1429072927",
      "masked_card_number": "860053******9500",
      "transaction_id": "167075",
      "bank_transaction_id": "232288",
      "reference_number": "003136441185",
      "amount": 100000,
      "merchantId": "900000000",
      "terminalId": "97000000",
      "date": 1645700612
    },
    "card": {
      "id": "6A0A002A1289688F2CDA1F1C0686359C16",
      "token": "f0bc2c517a194f148b76a965dd6b51be03a32917"
    }
  },
  "mx_id": "a814f53ab2d9c597e8c8391a73e1980e"
}

In case of invalid request parameters, the system will return error.

Confirm and Cancel Hold Transaction

Method's name: hold.confirm
Authorization: requires

Request

bank_transaction_id - Transaction number in the PaySys
status - Payment status
accept - Confirm hold payment
cancel - Cancel transaction. Return payment.

Request

{
  "id": "bb2656ec-955c-11ec-b909-0242ac120002",
  "method":"hold.confirm",
  "params":{
    "bank_transaction_id" : "108137783",
    "status" : "accept"
  }
}

Response:

status - Payment status
2 - complete
1 - awaiting
3 - cancel
6 - return
7 - hold
0 - processing
-1 - error
mx_id - Request tracker

Response

{
  "id": "bb2656ec-955c-11ec-b909-0242ac120002",
  "error": null,
  "result": {
    "status": 2
  },
  "mx_id": "c147dbab49736626fde2c2330a4f7353"
}

In case of invalid request parameters, the system will return error.

Checking payment status

Method's name: pam.check_payment
Authorization: requires

Checking the payment status is necessary to make sure that the payment was successful.

Request contains:

bank_transaction_id - Transaction number in the PaySys system

Request example

{
  "method": "pam.check_payment",
  "params": {
    "bank_transaction_id": "586151"
  },
  "id": "e4db6fae-4e58-4469-b442-092ee2ff3370"
}

Response contains:

bank_transaction_id -Transaction number in the PaySys system
amount -Amount of payment in soums
status - Payment status
2 - Payment has been completed
1 - Awaiting payment
3 - Cancel
6 - Return
0 - Payment is created
-1 -Error
mx_id - Request tracker

Response example

{
  "id": "e4db6fae-4e58-4469-b442-092ee2ff3370",
  "error": null,
  "result": {
    "bank_transaction_id": "232288",
    "status": "2",
    "amount": 100000
  },
  "mx_id": "e47e0bde96dea9c758735889b564e7e6"
}

In case of invalid request parameters, the system will return error.

Online payment using ID and card token

Method's name: pam.payment
Authorization: requires
Card token: requires

This method does not require user confirmation of payment. When sending a request, you must add to its header card token.

Request contains:

card_id - Card ID in the PaySys system
phone_number - User phone number, 12 digits in the format 998907702150
amount - Payment amount in tiins
vendor_id -Site ID for the provision of services
product - Order identifier (personal account, subscription, user)
hold - Hold status (true | false)
holding_time - hold time
after_expired - after hold timeout
accept - Confirm hold payment
cancel - return money

Request example

{
  "method": "pam.payment",
  "params": {
    "card_id": "6A0A002A1289688F2CDA1F1C0686359C16",
    "phone_number": "998907702150",
    "amount": 100000,
    "vendor_id": 100381,
    "product": "5d1a3442-d031-4683-8d77-165c4cfc8a9b"
  },
  "id": "77051b9a-f12f-40b0-8ad6-4805ce6121d6"
}

Response contains:

details - Object with the details of the made payment
- masked_card_number - Card number
- transaction_id - Transaction ID in the PaySys system
- bank_transaction_id - Transaction number in the PaySys system
- reference_number - Processing center transaction ID
- merchantId - Service provider identifier in the UZCARD ONLINE/HUMO system
- terminalId - Terminal identifier in the UZCARD ONLINE/HUMO system
- amount - Transaction amount in tiins
- date - Transaction creation date in seconds
mx_id - Request tracker

Response example

{
  "id": "77051b9a-f12f-40b0-8ad6-4805ce6121d6",
  "error": null,
  "result": {
    "details": {
      "id": "6A0A002A1289688F2CDA1F1C0686359C16",
      "masked_card_number": "860053******9500",
      "transaction_id": "167075",
      "bank_transaction_id": "232288",
      "reference_number": "003136441185",
      "amount": 100000,
      "merchantId": "900000000",
      "terminalId": "97000000",
      "date": 1645769446
    }
  },
  "mx_id": "e679b1177515ddb621d1fedcbfbc8a6a"
}

In case of invalid request parameters, the system will return error.

Cancellation a transaction using its id

Method's number: transaction.reverse
Authorization: requires

Request contains:

transaction_id - Transaction ID in the PaySys system

Request example

{
  "method": "transaction.reverse",
  "params": {
    "transaction_id": 7508737
  },
  "id": "77051b9a-f12f-40b0-8ad6-4805ce6121d6"
}

Response contains:

transaction_id - Transaction ID in the PaySys system
ref_num - Processing center transaction ID
mx_id - Request tracker

Response example

{
  "id": "77051b9a-f12f-40b0-8ad6-4805ce6121d6",
  "error": null,
  "result": {
    "transaction_id": 7508737,
    "ref_num": "014173418653"
  },
  "mx_id": "e679b1177515ddb621d1fedcbfbc8a6a"
}

In case of invalid request parameters, the system will return error.

Query Testing

Test requests API (Mockup server) is also possible via Postman:

Download the collection of requests: [Payment Gateway API.postman_collection](/assets/API шлюза оплаты PaySys.postman_collection.json)
Download runtime environments of requests: PaySys-Gateway.postman_environment.json
Import collections in the application Postman
Import environment
Go to the imported collection and select environment in the top right corner PaySys Gateway
On the right there is also an icon </> code, by clicking on you can see the request in different formats(cURL, HTTP and so on)
Below on the left there is a >_Console, that displays the executed queries

Acquiring (payment) for UzCard/HUMO

The stages of the communication process are shown in the diagram:​

User card registration​

Card registration confirmation​

Preparing for online payment​

Confirmation of online payment​

Confirm and Cancel Hold Transaction​

Checking payment status​

Online payment using ID and card token​

Cancellation a transaction using its id​

Query Testing​

The stages of the communication process are shown in the diagram:

User card registration

Card registration confirmation

Preparing for online payment

Confirmation of online payment

Confirm and Cancel Hold Transaction

Checking payment status

Online payment using ID and card token

Cancellation a transaction using its id

Query Testing