🔙Postback

Communication takes place with the help of postback requests (postbacks). After each Client request for input or output, a postback is sent to the Client with the result of the operation.

Funds should only be credited to your users based on the amount specified in the postback. Similarly, funds should only be debited from your users according to the amount indicated in the postback.

Receiving the postback

To accept postbacks, you need to implement a separate path that you can use to receive postbacks. They are sent via a POST request in JSON format.

The A-pay server is waiting for a response in json

{ 
"status": "OK" 
}

Response code 200, otherwise, when receiving a different response, A-pay will forward the postback with a certain frequency.

Deposit

Client-side signature generation

When sending webhooks, A-Pay also sends a signature: a specifically generated hash string that is created using a private key.

The signature itself is calculated as follows:

$signature = sha1($access_key . $private_key . md5($transactions->toJson(JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)));

a string of three parameters is passed to the sha1 function:

Parameter

Description

$access_key

The public key is specified in the settings of the A-Pay technical support personal account

$private_key

The private key is specified in the settings of the A-Pay technical support personal account

md5(...)

Hash from the MD5 function of the entire array of transactions in JSON format

As a result of executing this code, a string is obtained that cannot be faked without having a private key that is not passed in webhooks.

The client can compare the generated signature with the received signature from the webhook and thereby make sure that the data that came was actually sent and not faked by a scammer.

The webhook will include the status of the transactions:

If the status is “Success”, the client should proceed with depositing the funds into the user account.
If the status is “Failed” or “Rejected,” no funds should be deposited, or the deposit should be canceled.

Postback of transactions for deposit

Request body schema:

Name

Type

Description

access_key

string

The access key is specified in the settings of the A-Pay technical support personal account

signature

string

The signature was used to verify the validity of the postback. Concept of generation in the description of the deposit webhook

transactions

Array of objects below

Information about the deposits made (one or more) is passed

List of transactions:

order_id

string

Deposit ID in the A-Pay system

status

string

Enum: "Success" "Failed" "Rejected"

Deposit status, if the deposit was successful, the status will be Success

amount

number >= 0

Deposit amount

currency

string [ 3 .. 3 ]

Currency name

payment_system

string

Enum: "upi_fast", "upi_fast_v", "upi_p2p", "upi_a", "upi_fast_qr", "bankalfalah", "bkash_a", "apaybdt", "upay", "mpesa", "phonepe", "nagad_api_v", "payme", "paytm", "easypaisa"

The payment system from which the deposit was made

custom_transaction_id

string

Transaction ID in the client's system

custom_user_id

string

User ID in the client's system

created_at

integer

Deposit creation time, in timestamp UTC format

activated_at

integer

Deposit activation date, in timestamp UTC format

Example of a postback sent by a POST request in JSON format:

{
  "access_key": "mrOYReXJphqo7lkL",
  "signature": "dfsfrwe3344d",
  "transactions": [
    {
      "order_id": "7fa13dbc3b79e05e",
      "status": "Success",
      "amount": 6008.39,
      "currency": "INR",
      "payment_system": "mpesa",
      "custom_transaction_id": "string",
      "custom_user_id": "string",
      "created_at": 1665731710,
      "activated_at": 1665731710
    }
  ]
}

Responses:

If {"status":"OK"} was passed, we consider the webhook successfully delivered.

Example of a response:

{
    "status": "OK"
}

Withdrawal

Client-side signature generation

When sending webhooks, A-Pay also sends a signature: a specifically generated hash string that is created using a private key.

The signature itself is calculated as follows:

$signature = sha1($access_key . $private_key . md5($transactions->toJson(JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)));

a string of three parameters is passed to the sha1 function:

Parameter

Description

$access_key

The public key is specified in the settings of the A-Pay technical support personal account

$private_key

The private key is specified in the settings of the A-Pay technical support personal account

md5(...)

Hash from the MD5 function of the entire array of transactions in JSON format

As a result of executing this code, a string is obtained that cannot be faked without having a private key that is not passed in webhooks.

The client can compare the generated signature with the received signature from the webhook and thereby make sure that the data that came was actually sent, and not faked by a scammer.

The webhook will include the status of the transactions:

If the status is “Success”, the client should proceed with withdrawal the funds from the user account.
If the status is “Failed” or “Rejected,” no funds should be withdrawal, or the withdraw should be canceled.

Postback of transactions for deposit

Request body schema:

Name

Type

Description

access_key

string

The access key is specified in the settings of the A-Pay technical support personal account

signature

string

The signature was used to verify the validity of the postback. Concept of generation in the description of the deposit webhook

transactions

Array of objects below

Information about the deposits made (one or more) is passed

List of transactions:

order_id

string

Withdrawal ID in the A-Pay system

status

string

Enum: "Success" "Failed" "Rejected"

Withdrawal status, if the deposit was successful, the status will be Success

amount

number >= 0

Withdrawal amount

currency

string [ 3 .. 3 ]

Currency name

payment_system

string

Enum: "upi_fast", "upi_fast_v", "upi_p2p", "upi_a", "upi_fast_qr", "imps", "bankalfalah", "bkash_a", "apaybdt", "upay", "mpesa", "phonepe", "nagad_api_v", "payme", "paytm", "easypaisa"

The payment system from which the deposit was made

custom_transaction_id

string

Transaction ID in the client's system

custom_user_id

string

User ID in the client's system

created_at

integer

Deposit creation time, in timestamp UTC format

activated_at

integer

Deposit activation date, in timestamp UTC format

Example of a postback sent by a POST request in JSON format:

{
  "access_key": "mrOYReXJphqo7lkL",
  "signature": "dfsfrwe3344d",
  "transactions": [
    {
      "order_id": "7fa13dbc3b79e05e",
      "status": "Success",
      "amount": 6008.39,
      "currency": "INR",
      "payment_system": "mpesa",
      "custom_transaction_id": "string",
      "custom_user_id": "string",
      "created_at": 1665731710,
      "activated_at": 1665731710
    }
  ]
}

Responses:

If {"status":"OK"} was passed, we consider the webhook successfully delivered.

Example of a response:

{
    "status": "OK"
}

Expected responses to postbacks from a client:

Сode

Message

200

400

error receiving

401

error validation

404

not found http exception

500

not enough fields

501

empty postback

502

incorrect signature

503

data integrity error

If successful, expect the client to have http status - 2XX.
All 200th codes should be accompanied by "status" = "ok"
In case of failure, expect from the client http status other than 2XX (depending on the error) and an error message. For example, "error validation" or "not enough fields".

PreviousExample NextSettlement

Last updated 1 month ago