Skip to main content

Acquiring (payment) for international cards

URL gateway payment

https://paysys.uz/gateway

Preparing for online payment

Method's name: paysys.prepare_payment
Authorization: requires

PaySys payment aggregator provides online payment by card Visa, MasterCard, MIR.

This method prepares the payment and returns a link to the payment confirmation page using 3DS.

Request contains:

  • card_holder_name - Cardholder name, valid characters [0-9a-zA-Z-/ _.]{1,26}
  • card_number - Card number [0-9a-zA-Z-/ _.]{1,26}
  • card_number - Card number
  • card_expire - Card expiration dates. Date formatYYMM
  • card_cvc - Card CVC value, 3 digits
  • amount - Payment amount in dollar/euro cents, ruble kopecks
  • currency - Payment currency. Currencies are available:
    uzs - Uzbek sum - minimum 1000 sum, maximum 75,000,000 sum - currency by default
    usd - US dollar - minimum 1$, maximum 5000$
    eur - Euro - minimum 1€, maximum 5000€
    rub - Russian ruble - minimum 1₽, maximum - unlimited
  • vendor_id - Site ID for the provision of services
  • partner_trans_id - Order identifier (personal account, subscription, user)
  • client_ip_addr - IP of client address
  • description - Brief description of the payment (up to 125 characters)
  • redirect_url - The link URL of the supplier's site where the user will be redirected after the payment is completed (not required)
Request example
{
"method": "paysys.prepare_payment",
"params": {
"card_holder_name": "CARDHOLDER NAME",
"card_number": "4278000000275400",
"card_expire": "2702",
"card_cvc": "067",
"amount": "1139000",
"currency": "uzs",
"vendor_id": "100381",
"partner_trans_id": "167075",
"client_ip_addr": "192.4.59.3",
"description": "Month subscription",
"redirect_url": "https://shop.merchant.com/order/23"
},
"id": "85e0cd56-52c9-4709-b558-81203cb4e6ff"
}

Response contains:

  • transaction_id - Transaction number in the PaySys
  • confirm_url - The URL to enter the 3DS verification code.
  • mx_id - Request tracker
Response example
{
"id": "85e0cd56-52c9-4709-b558-81203cb4e6ff",
"error": null,
"result": {
"transaction_id": "1485295",
"confirm_url": "https://ecomm.kapital24.uz:6443/ecomm2/ClientHandler?trans_id=tYkiAVsnP3SnjBMSiXrWGrIRbeo%3D"
},
"mx_id": "2c2a35dc3682fc7e94df5b2f61a10c6b"
}

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


Checking payment status

Method's name: paysys.check_payment
Authorization: requires

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

Request contains:

  • partner_trans_id - Order identifier (personal account, subscription, user)
Request example
{
"method": "paysys.check_payment",
"params": {
"partner_trans_id": "167075"
},
"id": "f23eb612-9ea6-4ee2-97c3-33f6b5f38c17"
}

Response contains:

  • transaction_id - Transaction number in the PaySys
  • partner_trans_id -Order identifier (personal account, subscription, user)
  • data - System response Visa, MasterCard, MIR by operation (used for debugging)
  • err_obj - If the payment status -1, then parameter err_obj will contain a code [error](api-concepts#example-rpc-request-completed-with mistake) code and the error descriptionmessage , otherwiseerr_obj will be equalnull
{ "code": -32313, "message": "Transaction status is canceled"}
  • status - Payment status
    6 - Refund
    3 - Payment is canceled
    2 - Payment is completed
    1 - Awaiting payment
    0 - Payment has been created
    -1 -Error
  • mx_id - Request tracker
Response example
{
"id": "f23eb612-9ea6-4ee2-97c3-33f6b5f38c17",
"error": null,
"result": {
"transaction_id": "1485295",
"partner_trans_id": "167075",
"status": "2",
"data": {
"RESULT": "OK",
"RESULT_CODE": "000",
"3DSECURE": "AUTHENTICATED",
"RRN": "207011889463",
"APPROVAL_CODE": "155427",
"CARD_NUMBER": "427831******5400"
},
"err_obj": null
},
"mx_id": "8e23e530e81f6b777efa19f4c7e1e007"
}

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


Registration of international card

Method's name: mir.card_registration
Authorization: requires

The PaySys system provides an opportunity to register the international card Visa, MasterCard, MIR.

Request contains:

  • card_number - Card number
  • card_expire - Card expiration dates. Date formatYY/MM
  • card_cvc - Meaning of CVC card
  • card_holder - Cardholder name, valid characters[0-9a-zA-Z-/ _.]{1,26}
  • account - Account
  • id - Request ID
Request example
{
"method": "mir.card_registration",
"params": {
"card_number": "2222222222222222",
"card_expire": "04/27",
"card_cvc": "XXX",
"card_holder": "CARDHOLDER NAME",
"account": "998123456789"
},
"id": 2
}

Response contains:

  • error - Object with error information. If the method was executed without error parameter will be NULL
  • card_id - Card ID in the PaySys system
  • confirm_url -URL for entering 3DS verification code
  • id - Request ID
  • mx_id - Request tracker
Response example
{
"error": null,
"result": {
"card_id": "722c379bbe7646446483813c88f3883c",
"confirm_url": "https://paysys.uz/Security3d/qiwi/caea6ec14e8dee23ca8c68b69565fa9a"
},
"id": 2,
"mx_id": "bd9e122dae9cabfa97b0bb8e468e3b63"
}

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

By this request, the PaySys system notifies you of the card registration status.

The request is sent by the PaySys. If the callback contains the status SUCCESS, then the registration was successful.

Request contains:

  • stat - Status
  • id - Card ID in the PaySys system
  • token - Card token
  • pan - Card number
Request example
{
"id": "34a83544-81f8-4804-b6b7-07044a1600ca",
"method": "partner.notify",
"params": {
"stat": "SUCCESS",
"id": "d553921350e68a6af96d63a544720f9c",
"token": "0b6227c70d365255176cb6c3b9b6cccfd3aa17b0",
"pan": "222222******2222"
}
}

The response must be mandatory to make sure that the request from the PaySys system is received.

Response contains:

  • error -If the method was executed without errors, the parameter will be equal to NULL`
Response example
{
"error": null
}

In case of an error, the request will contain the status ERROR and its description.

Request contains:

{
"id": "34a83544-81f8-4804-b6b7-07044a1600ca",
"method": "partner.notify",
"params": {
"stat": "ERROR",
"id": "d553921350e68a6af96d63a544720f9c",
"code": "-34000",
"message": "Описание ошибки"
}
}
Response example
{
"id": "34a83544-81f8-4804-b6b7-07044a1600ca",
"method": "partner.notify",
"params": {
"stat": "ERROR",
"id": "d553921350e68a6af96d63a544720f9c",
"code": "-34000",
"message": "Описание ошибки"
}
}

The response must be mandatory to make sure that the request from the PaySys system is received.

Response contains:

  • error - If the method was executed without errors, the parameter will be equal to NULL
Response example
{
"error": null
}

Remove card token

Method's name: mir.remove_card_token
Authorization: requires

The PaySys system provides the ability to remove the card token, if necessary.

Request contains:

  • card_id - Идентификатор карты в системе PaySys
  • card_token - Токен карты
  • id - Идентификатор запроса
Request example
{
"method": "mir.remove_card_token",
"params": {
"card_id": "49270cae102c3c3197da8d0086a28c15",
"card_token": "6b7b30a481e66bad08de64f3145cf7ce"
},
"id": "288175fc-6d5b-4179-b598-defec67abbaa"
}

Response contains:

  • error - Если метод выполнился без ошибок праметр будет равен NULL
  • pan - Номер карты
  • id - Идентификатор запроса
Response example
{
"error": null,
"result": {
"pan": "222222******2222"
},
"id": "288175fc-6d5b-4179-b598-defec67abbaa"
}

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


Online payment using card token

Method's name: paysys.pay_by_id
Authorization: requires
Card token: requires

When sending a request, you must add the card token to its header.

Request contains:

  • partner_trans_id - Order identifier (personal account, subscription, user)
  • card_id - Card ID in the PaySys system
  • amount - Payout amount
  • currency - Payment currency
  • client_ip_addr - IP of client address
  • description - Payment Description
  • vendor_id - Vendor ID
  • id - Request ID
Request example
{
"method": "paysys.pay_by_id",
"params": {
"partner_trans_id": "39888c6d-bbb9-4044-97a6-bec2d85dd6c10",
"card_id": "722c379bbe7646446483813c88f3883c",
"amount": "100",
"currency": "RUB",
"client_ip_addr": "1.1.1.1",
"description": "TEST",
"vendor_id": "101478"
},
"id": "f23eb612-9ea6-4ee2-97c3-33f6b5f38c17"
}

Response contains:

  • error - Object with error information. If the method was executed without error, parameter will be NULL
  • id -Bank transaction ID RRN (Reference Retrieval Number)
  • masked_card_number - Card number
  • transaction_id - Payment ID in the PaySys system
  • bank_transaction_id - Transaction number in the PaySys
  • amount - Payout amount
  • merchantId - Service Provider ID
  • terminalId - Terminal ID
  • date - Transaction creation date in seconds
  • payment_id - Payment system identifier in the PaySys system
  • id - Request ID
  • mx_id - Request tracker
Response example
{
"error": null,
"result": {
"details": {
"id": 217909211968,
"masked_card_number": "222222******2222",
"transaction_id": "4457089",
"bank_transaction_id": 100053825,
"amount": "100,00",
"merchantId": null,
"terminalId": null,
"date": 1656407767
},
"payment_id": 27
},
"id": "f23eb612-9ea6-4ee2-97c3-33f6b5f38c17",
"mx_id": "007ed8fddeffb2301b7a0c21d968b9b4"
}

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


Payment cancellation

Method's name: paysys.cancel_payment
Authorization: requires

Cancellation (reversal, adjustements) of payment is possible within 7 days, once, from the moment of operation (preferably before "closing business of the day).
Cancellation scheme: during payment, the payment amount is blocked (block with a minus) for the card and becomes unavailable for the client (waiting for clearing to write off the funds completely).
If the service provider canceled the payment (reversal), then a block with a plus appears on the card that cancels the first blocking (block with a minus). The previously blocked amount on the card becomes available.
If the client does not see a block with a plus and the funds are still not available, then you need to contact the issuing bank, who issued this card and request the reason why the payment was not cancelled.

Request contains:

  • partner_trans_id - Order identifier (personal account, subscription, user)
Request example
{
"method": "paysys.cancel_payment",
"params": {
"partner_trans_id": "167075"
},
"id": "73a32f5c-9dca-446e-afa9-22eb5602954c"
}

Response contains:

  • error - Object with error information. If the method was executed without errors, the parameter will be NULL
  • transaction_id - Transaction number in the PaySys system
  • partner_trans_id -Order identifier (personal account, subscription, user)
  • data - System response Visa, MasterCard, MIR on operation (used for debugging)
  • status - Payment status
    3 - Payment is canceled
  • mx_id - Request tracker
Response example
{
"id": "73a32f5c-9dca-446e-afa9-22eb5602954c",
"error": null,
"result": {
"transaction_id": "1485295",
"partner_trans_id": "167075",
"status": "3",
"data": {}
},
"mx_id": "6c2c9a196ab97334382bf23a7d3430ab"
}

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


Refund

Method's name: paysys.refund_payment
Authorization: requires

Refund on a payment is possible from the moment of the operation (preferably after the “closing of the business day”).
You can make any number of refunds, provided that the amount of all refunds is less than or equal to the amount of the original payment, taking into account the commission withheld. For refunds, the acquirer fee is non-refundable.
The scheme of the return method: after the initialization of the operation of the refund (refund) by the service provider, the amount comes to the client's card along with clearing.
This process usually takes 3 (three) business days. But it depends on the policy of the acquiring bank in which the service provider company and from the issuing bank where the card was issued. Both banks must go through the procedure clearing.
The amount of the refund depends on the costs of the service provider for the refund procedure and is usually less than the amount of the payment.

Request contains:

  • partner_trans_id - Order identifier (personal account, subscription, user)
  • amount - The refund amount in dollar cents. Cannot exceed payment amount
  • currency - Payment currency. Currencies available:
    uzs - Uzbek sum - default currency
    usd - US dollar
    eur - Euro
    rub - Russian ruble
Request example
{
"method": "paysys.refund_payment",
"params": {
"partner_trans_id": "167075",
"amount": "113305",
"currency": "uzs"
},
"id": "69810651-2402-4af7-a245-77e488f21b2b"
}

Response contains:

  • error - Object with error information. If the method was executed without errors, the parameter will be NULL
  • transaction_id - Transaction number in the PaySys system
  • partner_trans_id -Order identifier (personal account, subscription, user)
  • data - System response Visa, MasterCard, MIR on operation (used for debugging)
  • status - Payment status
    6 - Refund
  • mx_id - Request tracker
Response example
  • error - Объект с информацией об ошибке. Если метод выполнился без ошибок праметр будет равен NULL
  • transaction_id - Номер транзакции в системе PaySys
  • partner_trans_id - Идентификатор заказа (лицевого счета, подписки, пользователя)
  • data - Ответ системы Visa, MasterCard, MIR по операции (используется для отладки)
  • status - Payment status
    6 - Возврат средств
  • mx_id - Трекер запроса

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


Transaction Status Notification

HTTP header: "Authorization: Basic " + base64_encode(VENDOR_METHOD + ":" + VENDOR_SECRET_KEY)

With this request, the PaySys system notifies you about the status of the transaction. The request is sent by the PaySys system.

Request contains:

  • id - Transaction ID in the PaySys system
  • account - Payment ID of the partner's system
  • amount - Payout amount
  • card_masked - Card number
  • currency - Currency code
  • currency_name - Name of currency
  • status - Payment status
    6 - Refund
    3 - Payment is canceled
    2 - Payment is completed
    1 - Awaiting payment
    0 - Payment is created
    <0 - Error
  • date - Transaction creation date
Request example
{
"id": "44114543",
"account": "931111111",
"amount": 1000,
"card_masked": "222222******2222",
"currency": 840,
"currency_name": "usd",
"status": -1,
"date": "24.06.2022 07:49:16"
}

The response must be mandatory to make sure that the request from the PaySys system is received.

Response contains:

  • error - If the method was executed without errors, the parameter will be equal to NULL
Response example
{
"error": null
}

Query Testing

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

  1. Download the collection of requests: Visa Payment Gateway API.postman_collection.json
  2. Download the environment file for execution of requests: PaySys-Visa-Gateway.postman_environment.json
  3. Import Collections in Postman Application
  4. Import environment
  5. Go to the imported collection and select environment in the top right corner PaySys Visa Gateway
  6. There is also an icon on the right.</> code, by clicking on which you can see the request in different formats(cURL, HTTP и т.д.)
  7. Below on the left there is a >_Console that displays the executed queries