Skip to main content

Asynchronous notification

If the notifyUrl parameter is passed in the order creation request to receive payment notifications, PayBy will send a message to the address when the order status changes from CREATED to SUCCESS or FAILURE.


Notice

  1. In this scenario, the request is sent by PayBy to the merchant, and the merchant needs to send response to PayBy.
  2. After receiving the notification, please return the success message, otherwise PayBy will try to send multiple times. The maximum number of attempts is 7. The interval time between each attempt is as follows: 2 minutes, 10 minutes, 10 minutes, 1 hour, 2 hours, 6 hours, and 15 hours.
  3. The notification request is signed by payBy side. The merchant must verify the notification signature before processing the content.

Request

Http Header


Content-Type String Required

The media type. Required for operations with a request body. The value is application/<format>, where format is json.

Example value: application/json


sign String Required

When PayBy sends response, PayBy will use its own private key to sign the message, and the merchant uses PayBy 's public key to verify the signature. If the verification is passed, it proves that the response was sent by PayBy and not faked by others.


Http Body


notify_timestamp Timestamp Required

The timestamp when PayBy sent the request.

Example value: 1586849271877


notify_id String Required

The unique identification number of this notification within the PayBy system.

Example value: 202004140007474501


transferOrder Object

Attributes
  • requestTime Timestamp Required

    Request time passed by the merchant when placing the order.

    Example value: 1581493898000


  • merchantOrderNo String Required

    The merchant's referece number of the request. Used to track every request.

    Example value: M965739182419

    Maximum length: 64


  • orderNo String Required

    The PayBy's unique identification number of the order.

    Example value: 131658300517875854


  • product String Required

    The product name of the API method used in the order. This product name is only used for PayBy internal classification.

    Maximum length: 100


  • status Enum Required

    The possible values are:

    CREATED. The order has been created.

    SUCCESS. The transfer completed.

    FAILURE. The order has been cancelled or expired.


  • paymentInfo Object

    • payerFeeAmount Money Required

      In this transfer, the fee that the payer needs to pay.


    • arrivalTime TimeStamp Required

      Estimated time of fund arrival. Note that this is not the actual arrival time.

      Example value: 1581493898000


  • beneficiaryIdentityType String Required

    The fund can be transfered to the beneficiary through mobile phone number, PayBy member id or BOTIM member id.

    The possible values are:

    PHONE_NO. Transfer through mobile phone number.

    MEMBER_ID. Transfer through PayBy member id.

    TOTOK_UID. Transfer through Totok member id.

    Maximum length: 20


  • beneficiaryIdentity String Required

    After selecting the beneficiary identity type, what value should be passed.

    The parameter needs to be encrypted when passed, and SHA-256 algorithm is recommended.

    For PHONE_NO, example value: +971-585812345

    For MEMBER_ID, example value: 100006514321

    Maximum length: 20


  • beneficiaryFullName String

    If the parameter is passed, PayBy will verify whether the parameter is consistent with the beneficiary's KYC information. If not, the transfer will fail. If the parameter is not passed, PayBy will not perform verification.

    The parameter needs to be encrypted when passed, and SHA-256 algorithm is recommended.

    Maximum length: 100


  • memo String Required

    The description of this transfer.

    Maximum length: 128


  • notifyUrl String

    To receive asynchronous notifications of order status updates, you can pass the notify URL.

    Example value: https://www.yoursite.com

    Maximum length: 200


  • failCode String

    If the order status is FAILURE, the code to identify the exact reason.

    Example value: 504


  • failDes String

    If the order status is FAILURE, the failure reason.

    Example value: SERVICE_TIMEOUT



**notify_time** String

The parameter is deprecated. Please use the notify_timestamp instead.


**_input_charset** String

The parameter is deprecated.


Notification sample

Http Header
{
"Content-Type": "application/json; charset=UTF-8"
}

Http Body
{
"_input_charset": "UTF-8",
"notify_id": "202004170007501041",
"notify_time": "20200417180000",
"notify_timestamp": 1587132000943,
"transferOrder": {
"amount": {
"amount": 1.21,
"currency": "AED"
},
"beneficiaryFullName": "1fab0a7a62d3528b4a58270b0c29b7494bdb2527a555819159e956b01778d488",
"beneficiaryIdentity": "ff3f1b1584a619ff725ac1f4606964e18bef257b83257265f65ade62326f7c10",
"beneficiaryIdentityType": "PHONE_NO",
"memo": "Your memo",
"merchantOrderNo": "M046082822070",
"notifyUrl": "http://www.yoursite.com",
"orderNo": "911587131999001394",
"paymentInfo": {
"arrivalTime": 1587132000000,
"payerFeeAmount": {
"amount": 0.01,
"currency": "AED"
}
},
"product": "Transfer",
"requestTime": 1587131998413,
"status": "SUCCESS"
}
}

Response

Please reply success after receiving the notification, otherwise PayBy will send the notification repeatedly for the same order.


Http Header


Content-Type String Required

The media type. Required for operations with a request body. The value is application/<format>, where format is json.

Example value: application/json


Http Body


response String Required

Example value: Success


Response sample

Http Header
{
"Content-Type": "application/json; charset=UTF-8"
}

Http Body
{
"response":"SUCCESS"
}