Acquiring (payment) for international cards
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 format
YYMM
- 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 defaultusd
- 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
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
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
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 parametererr_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
- Refund3
- Payment is canceled2
- Payment is completed1
- Awaiting payment0
- Payment has been created-1
-Error - mx_id - Request tracker
Response example
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 format
YY/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
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
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
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
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
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
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
Response contains:
- error - Если метод выполнился без ошибок праметр будет равен
NULL
- pan - Номер карты
- id - Идентификатор запроса
Response example
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
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
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
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
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 currencyusd
- US dollareur
- Eurorub
- Russian ruble
Request example
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
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
- Refund3
- Payment is canceled2
- Payment is completed1
- Awaiting payment0
- Payment is created<0
- Error - date - Transaction creation date
Request example
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
Query Testing
Test Requests of API (Mockup server) is also possible via Postman:
- Download the collection of requests: Visa Payment Gateway API.postman_collection.json
- Download the environment file for execution of requests: PaySys-Visa-Gateway.postman_environment.json
- Import Collections in Postman Application
- Import environment
- Go to the imported collection and select environment in the top right corner PaySys Visa Gateway
- There is also an icon on the right.
</> code
, by clicking on which you can see the request in different formats(cURL, HTTP и т.д.) - Below on the left there is a
>_Console
that displays the executed queries