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

• refundOrder Object Required

  Attributes

  • refundMerchantOrderNo String Required

    • The merchant's reference number of the request. Used to track every request.
    • Example value: 1581493898000
    • Maximum length: 64

  • orderNo String Required

    • The PayBy's unique identification number of the refund order.
    • Example value: M965739182419
    • Maximum length: 64

  • originMerchantOrderNo String Required

    • The merchant order number of the payment order to be refunded.
    • Example value: M965739182419
    • Maximum length: 64

  • status String Required

    • Status of the refund order. Possible values:
      • CREATED: PayBy's server accepts the refund request.
      • REFUNDED_SETTLED: Refund amount has been deducted from the merchant's account.
      • SUCCESS: Refund has reached the payer's account or is being processed by the bank.
      • FAILURE: Refund order failed.

  • amount Money Required

    • The amount to refund.

  • feeRefunded Money

    • Transaction fee refunded by PayBy.

  • sharingInfoList List

    • Details of refund impact on sharing accounts.
    • Each item includes:
      • sharingIdentitySeqId Money Required
        • Serial number for multiple account IDs.
        • Example value: 1
      • sharingMid String Required
        • Member ID returned if identity matches an existing PayBy member.
      • sharingMemo String Required
        • Description of the refund operation.
      • sharingAmount Money Required
        • Original requested sharing amount.
      • sharingSettledAmount Money Required
        • Actual amount received by the sharing account.

  • notifyUrl String

    • URL for receiving asynchronous notifications.
    • Maximum length: 200

  • reason String

    • Reason for refund.
    • Maximum length: 64

  • secondaryMerchantId String

    • Merchant's member ID under your platform.
    • Maximum length: 200

  • deviceId String

    • Device ID used for transaction data statistics.
    • Note: Required if using the secondary merchant function.
    • Maximum length: 200

  • failCode String

    • Code identifying the reason for failure.
    • Example value: 62002

  • failDes String

    • Description of the failure reason.
    • Example value: Failed orders cannot be cancelled or refunded

  • reserved String Required

    • PayBy's unique identification number of the order.
    • Example value: 131658300517875854

**notify_time** String

The parameter is deprecated. Please use the notify_timestamp instead.

**_input_charset** String

The parameter is deprecated.

Request Sample

Http Header
{
    "Content-Type": "application/json; charset=UTF-8",
    "Sign": "NshUvvVM3f/2eYcHyel7w7xDyzX1o7azydZ3ctGVWEghE4MCDcrEfO7LHmuDCQO4tqLwXwIv4pJfPH37X/o4V8q9QaE+gcPPvzO2xlT/Fksocd+gBoBWGz6SaEmD3eKQ7J9SU3+sKLOre9BomzJ5CuzsFAbBrZVw1+0MiwE3NTJvKEL3CW6LhHj2/1bnFMrQeBXP0z2LoqqODORG5Sgy8W9EPlMityjGOtPGMPj6iOK6il1KIeGRBW1wBeP0ZP/n8hwsob/fLygJ8UhB/kOAICXRrA+uo2Z4JJXhuX9P+C0BufPWHIdwq7ZdAvcxmSXFjtwIHuY9JFNWdTBZhxNw3g=="
}

Http Body
{
    "_input_charset": "UTF-8",
    "notify_id": "202004170007499141",
    "notify_time": "20200417130228",
    "notify_timestamp": 1587114148892,
    "refundOrder": {
        "amount": {
            "amount": 0.01,
            "currency": "AED"
        },
        "notifyUrl": "http://www.yoursite.com",
        "orderNo": "191587114148046289",
        "originMerchantOrderNo": "M572007254058",
        "reason": "refund",
        "refundMerchantOrderNo": "M029348361456",
        "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"
}