Gateway API
The Developers section of the
Dashboard provides you with useful information
about of integration. You can view Gateway APIs.
Authorization
First, get your unique merchant secret key from
Applications
page, and include the merchant secret key in
Header as value for the
Authorization variable
Header example
Authorization: [SECRET_KEY]
Base URL - Gateway API V2
https://api.payriff.com/api/v2/{method_name}
Base URL - Gateway API V3
https://api.payriff.com/api/v3/{method_name}
To process a test transaction, you need to use this test credit card all Gateway API versions
4169741330151778
11/26
822
Gateway API V2
createOrder
POST
{
"body": {
"amount": 0,
"approveURL": "string",
"cancelURL": "string",
"cardUuid": "string",
"currencyType": "AZN",
"declineURL": "string",
"description": "string",
"directPay": true,
"installmentPeriod": 0,
"installmentProductType": "BIRKART",
"language": "AZ",
"senderCardUID": "string"
},
"merchant": "string"
}
{
"code": "string",
"internalMessage": "string",
"message": "string",
"payload": {
"orderId": "string",
"paymentUrl": "string",
"sessionId": "string"
}
}
| Parameter |
Description |
amount |
Payment amount |
approveURL |
After successful payment, the
forwarding address
|
cancelURL |
After canceled payment, the
forwarding address
|
declineURL |
After declined payment, the
forwarding address
|
currencyType |
Currency of payment (AZN, USD, EUR)
|
description |
Payment description for customer
|
language |
Payment page language (AZ, EN, RU)
|
merchant |
Your unique merchant number |
directPay |
Must be true always. (This parameter
is using to get out of money out of
card directly )
|
installmentPeriod |
Indicates the number of installments
in installment payments
|
*If the parameters aprroveUrl,
cancelUrl,
declineUrl are left blank, then we
will automatically redirect to
Success,
Cancel,
Decline
After a successful request, you will receive
paymentUrl, and you need to
redirect the client to paymentUrl.
This page will be for payment. If the
transaction was successful, we return a
POST request for
approveURL, all transaction
parameters:
{
"payload": {
"version": "1.0",
"orderID": 548779,
"sessionId": "61A6275XXXXXXXXXXXXXXXXXXX36100",
"transactionType": "Purchase",
"RRN": "14915908",
"PAN": "416974XXXXXX7777",
"purchaseAmount": 3000,
"currency": "944",
"tranDateTime": "09/06/2023 16:58:55",
"responseCode": "001",
"responseDescription": "Approved, no balances available",
"brand": "VISA",
"orderStatus": "APPROVED",
"approvalCode": "331169 A",
"orderDescription": "null",
"approvalCodeScr": "331169",
"purchaseAmountScr": 30,
"currencyScr": "AZN",
"orderStatusScr": "TƏSDİQLƏNİB",
"cardRegistration": {
"MaskedPAN": "416974****1778",
"CardUID": "D91E8A1XXXXXXXXXXXXXXXXXXBCC",
"Brand": "VISA"
},
"invoiceUuid": "a31b658e0b754a4fa63aba44b487bb77"
},
"code": "00000",
"message": "Operation performed successfully",
"route": "dashboard/main"
}
POST
{
"body": {
"languageType": "AZ",
"orderId": 0,
"sessionId": "string"
},
"merchant": "string"
}
{
"code": "string",
"internalMessage": "string",
"message": "string",
"payload": {
"row": {
"amount": "string",
"approveURL": "string",
"cancelURL": "string",
"createDate": "string",
"currency": "string",
"declineURL": "string",
"description": "string",
"extSystemProcess": "string",
"fee": "string",
"id": "string",
"lastUpdateDate": "string",
"merchantID": "string",
"orderLanguage": "string",
"orderOperations": {
"subRow": {}
},
"orderType": "string",
"orderstatus": "string",
"payDate": "string",
"receipt": "string",
"refundAmount": "string",
"refundCurrency": "string",
"refundDate": "string",
"sessionID": "string",
"twoId": "string",
"twodate": "string"
}
}
}
| Parameter |
Description |
languageType |
Payment page language (AZ, EN, RU)
|
orderId |
After a successful createOrder
request, in response you will
receive an orderId
|
sessionId |
After a successful createOrder
request, in response you will
receive an sessionId
|
merchant |
Your unique merchant number |
If you successfully send a request to the
createOrder method,
you will receive orderId and
sessionId. After that, you can use
this method, and get all the payment details.
getStatusOrder
POST
{
"body": {
"language": "string",
"orderId": "string",
"sessionId": "string"
},
"merchant": "string"
}
{
"code": "string",
"internalMessage": "string",
"message": "string",
"payload": {
"orderId": "string",
"orderStatus": "string"
}
}
| Parameter |
Description |
language |
Payment page language (AZ, EN, RU)
|
orderId |
After a successful createOrder
request, in response you will
receive an orderId
|
sessionId |
After a successful createOrder
request, in response you will
receive an sessionId
|
merchant |
Your unique merchant number |
If you successfully send a request to the
createOrder method,
you will receive orderId and
sessionId. After that, you can use
this method, and get the payment status in the
parameter orderStatus.
refund
POST
{
"body": {
"refundAmount": 0,
"orderId": "string",
"sessionId": "string"
},
"merchant": "string"
}
{
"code": "string",
"internalMessage": "string",
"message": "string"
}
| Parameter |
Description |
refundAmount |
Refund amount or part of the amount
|
orderId |
After a successful createOrder
request, in response you will
receive an orderId
|
sessionId |
After a successful createOrder
request, in response you will
receive an sessionId
|
merchant |
Your unique merchant number |
If you successfully send a request to the
createOrder method,
you will receive orderId and
sessionId. After that, you can use
this method, and you will receive a success
message and the amount will be refunded.
preAuth
POST
{
"body": {
"amount": 1,
"approveURL": "string",
"cancelURL": "string",
"cardUuid": "string",
"currencyType": "AZN",
"declineURL": "string",
"description": "test",
"directPay": false,
"installmentPeriod": 0,
"installmentProductType": "BIRKART",
"language": "AZ",
"senderCardUID": "string"
},
"merchant": "string"
}
{
"code": "string",
"internalMessage": "string",
"message": "string",
"payload": {
"orderId": "string",
"paymentUrl": "string",
"sessionId": "string"
}
}
| Parameter |
Description |
amount |
Payment amount to block |
approveURL |
After successful payment, the
forwarding address
|
cancelURL |
After canceled payment, the
forwarding address
|
declineURL |
After declined payment, the
forwarding address
|
currencyType |
Currency of payment (AZN, USD, EUR)
|
description |
Payment description for customer
|
language |
Payment page language (AZ, EN, RU)
|
merchant |
Your unique merchant number |
installmentPeriod |
Indicates the number of installments
in installment payments
|
directPay |
Must be false (To block payment
amount)
|
senderCardUID |
A request to block money on a saved
card
|
*If the parameters aprroveUrl,
cancelUrl,
declineUrl are left blank, then we
will automatically redirect to
Success,
Cancel,
Decline
This method is for locking the amount, and after
payment, you must call the
completeOrder
method to unlock and receive the full and part
of the amount. After a successful request, you
will receive paymentUrl, and you
need to redirect the client to paymentUrl. This
page will be for payment. If the transaction was
successful, we return a
POST request for
approveURL, all transaction
parameters
reverse
POST
{
"body": {
"amount": 0,
"description": "string",
"language": "AZ"
"orderId": "string",
"sessionId": "string"
},
"merchant": "string"
}
{
"code": "string",
"internalMessage": "string",
"message": "string"
}
| Parameter |
Description |
amount |
Payment amount to reverse |
description |
Payment description for customer
|
language |
Payment page language (AZ, EN, RU)
|
orderId |
After a successful createOrder
request, in response you will
receive an orderId
|
sessionId |
After a successful createOrder
request, in response you will
receive an sessionId
|
merchant |
Your unique merchant number |
This method can be used to check the amount on
the credit card and then return to the credit
card.
To check the amount you need to use the
createOrder method,
and then to return the amount back, you need to
use the reverse method.
completeOrder
POST
{
"body": {
"amount": 0,
"description": "string",
"language": "AZ"
"orderId": "string",
"sessionId": "string"
},
"merchant": "string"
}
{
"code": "string",
"internalMessage": "string",
"message": "string"
}
| Parameter |
Description |
amount |
Payment amount or part of the amount
to complete the payment.
|
description |
Payment description for customer
|
language |
Payment page language (AZ, EN, RU)
|
orderId |
After a successful createOrder
request, in response you will
receive an orderId
|
sessionId |
After a successful createOrder
request, in response you will
receive an sessionId
|
merchant |
Your unique merchant number |
Using this method, you can complete the payment
with the final amount, that is, you can return
part of the amount to the client and the final
amount will be sent to the seller.
To use this method, you first need to block the
amount using the
preAuth method, and then
complete it using the
completeOrder
method
autoPay
POST
{
"body": {
"amount": 0,
"cardUuid": "string",
"description": "test",
"orderId": "string",
"sessionId": "string"
},
"merchant": "string"
}
{
"code": "string",
"internalMessage": "string",
"message": "string"
}
| Parameter |
Description |
amount |
Payment amount |
cardUuid |
Unique id credit card payment
for automatic payment. If you
want to save card payment
details. You can get it using
the
cardSave
method.
|
merchant |
Your unique merchant number |
orderID / sessionId - Normally no change is
made. If a request is sent and preAuth /
createOrder request is received by this
method, in addition, if we want to complete
the payment without going to the payment
page, the sent orderID / sessionID is
recorded.
Post / Get request ----> After successful
payment the Post request is sent covering
all data about payment, Following this, GET
request will open the corresponding page
(success, cancel, decline)
Using this method, you can make an automatic
payment using a
cardUuid.
To use this method, you first need to make
some payment using the
cardSave method, and
get a cardUuid parameter.
invoices
POST
{
"body": {
"amount": 0,
"approveURL": "string",
"cancelURL": "string",
"currencyType": "AZN",
"customMessage": "string",
"declineURL": "string",
"description": "string",
"email": "string",
"expireDate": "2021-12-14T11:30:17.600Z",
"fullName": "string",
"installmentPeriod": 0,
"installmentProductType": "BIRKART",
"languageType": "AZ",
"phoneNumber": "string",
"sendSms": true
},
"merchant": "string"
}
{
"code": "00000",
"message": "Operation performed successfully",
"route": "dashboard/main",
"internalMessage": null,
"payload": {
"id": 12,
"merchantId": "ES109000",
"amount": 10,
"payriffAmount": null,
"payriffFixedFeeAmount": null,
"payriffFee": null,
"totalAmount": null,
"fullName": "string string",
"email": "string@string.com",
"phoneNumber": "+994123456789",
"customMessage": null,
"expireDate": "2022-12-14T11:30:17.6",
"currencyType": "AZN",
"languageType": "AZ",
"paymentType": "ONETIME",
"active": true,
"description": "string",
"approveURL": "string.com",
"cancelURL": "string.com",
"declineURL": "string.com",
"uuid": "2d0be10a98da45c68c61966844e2c941",
"invoiceUuid": "fcaa53aedca14b3a9c6039f4459d8fs3",
"invoiceCode": "1042729",
"invoiceStatus": "PENDING",
"createdDate": "2022-11-24T18:17:46.129",
"paymentUrl": "https://pay.payriff.com/y/RS8u",
"sendSms": true
}
}
Using this method, you can create an invoice and
send SMS to your customer for payment.
get-invoice
POST
{
"merchant": "ES1010101",
"body": {
"uuid": "c1123472cf7945f9876076fcb9af8a05"
}
}
{
"code": "00000",
"message": "Operation performed successfully",
"route": "dashboard/main",
"internalMessage": null,
"payload": {
"id": 15645,
"merchantId": "ES1090510",
"amount": 0.1,
"fullName": "string",
"email": "string",
"phoneNumber": "string",
"personalCode": null,
"expireDate": "2022-09-24T06:46:55.731",
"currencyType": "AZN",
"languageType": "AZ",
"paymentType": "ONETIME",
"subscriptionState": null,
"paymentDay": null,
"expireDay": null,
"active": true,
"description": "string",
"approveURL": "string",
"cancelURL": "string",
"declineURL": "string",
"uuid": "a5fc417ea335487fafced51b5f3e2b34",
"invoiceUuid": "93f5721782f84074b6c5a383bf9f8358",
"baseUrl": null,
"invoiceCode": "1015645",
"invoiceStatus": "PENDING",
"installmentProductType": "BIRKART",
"installmentPeriod": 0,
"source": "DASHBOARD",
"directPay": false,
"createdDate": "2022-08-24T11:15:22.305"
}
}
Using this method you can get invoice
information. Consider
invoiceUuid as uuid in
this api request.
transfer
POST
{
"merchant": "ES1000010",
"body": {
"toMerchant": "ES192837",
"amount": 0,
"description": "transfer"
}
}
{
"code": "00000",
"message": "Operation performed successfully",
"route": "dashboard/main",
"internalMessage": null,
"payload": "APPROVED"
}
Using this method you can transfer money from
wallet to wallet in Payriff
| Parameter |
Description |
toMerchant |
Merchant ID receiver |
amount |
Transfer amount |
description |
Transfer reason |
merchant |
Your unique merchant number |
topup
POST
{
"merchant": "ES1000010",
"body": {
"phoneNumber": "994501234567",
"amount": 0,
"description": "transfer"
}
}
{
"code": "00000",
"message": "Operation performed successfully",
"route": "dashboard/main",
"internalMessage": null
}
Using this method you can transfer money from
Payriff wallet to
MPAY wallet
| Parameter |
Description |
phoneNumber |
Mpay wallet phone number receiver
|
amount |
Transfer amount |
description |
Transfer reason |
merchant |
Your unique merchant number |
wallets
GET
https://api.payriff.com/api/v2/wallet
{
"code": "string",
"message": "string",
"route": "string",
"internalMessage": "null",
"payload": {
"historyResponse": [
{
"id": "number",
"active": "boolean",
"balance": "number",
"amount": "number",
"operation": "string"
},
],
"totalBalance": "number"
}
}
walletById
GET
https://api.payriff.com/api/v2/wallet/:ID
{
"id": "number",
"active": "boolean",
"balance": "number",
"appId": "number",
"userId": "number",
"applicationStatus": "string"
}
