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 reference 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. Used for PayBy internal classification.
    • Maximum length: 100

  • status Enum Required

    • Possible values:
      • CREATED: The order has been created.
      • SUCCESS: The transfer completed.
      • FAILURE: The order has been cancelled or expired.

  • paymentInfo Object

    • payerFeeAmount Money Required
      • Fee that the payer needs to pay in this transfer.
    • arrivalTime Timestamp Required
      • Estimated time of fund arrival (not actual arrival time).
      • Example value: 1581493898000

  • beneficiaryIdentityType String Required

    • Method used to identify the beneficiary.
    • Possible values:
      • PHONE_NO: Transfer through mobile phone number
      • MEMBER_ID: Transfer through PayBy member ID
    • Maximum length: 20

  • beneficiaryIdentity String Required

    • Value passed based on the selected identity type.
    • Should be encrypted using SHA-256.
    • Example values:
      • +971-585812345 (for PHONE_NO)
      • 100006514321 (for MEMBER_ID)
    • Maximum length: 20

  • beneficiaryFullName String

    • If provided, PayBy verifies it against the beneficiary's KYC info.
    • If not provided, no verification is performed.
    • Should be encrypted using SHA-256.
    • Maximum length: 100

  • memo String Required

    • Description of the transfer.
    • Maximum length: 128

  • notifyUrl String

    • URL to receive asynchronous notifications of order status updates.
    • Example value: https://www.yoursite.com
    • Maximum length: 200

  • failCode String

    • Code identifying the reason for failure (if status is FAILURE).
    • Example value: 504

  • failDes String

    • Description of the failure reason (if status is FAILURE).
    • 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"
}