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 referece 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, which the merchant needs to refund.

  Example value: M965739182419

  Maximum length: 64

  
  

• status String Required

  The status of the refund order. The possible values are:

  CREATED. PayBy's server accepts the refund request.

  REFUNDED_SETTLED. Refund amount have been deducted from the merchant's account.

  SUCCESS. If payment method is balance, the refund has reached the payer's payment account. If payment method is bank card, the bank has started processing this refund and the fund will take some time to reach the payer's bank account.

  FAILURE. Refund order failed

  
  

• amount Money Required

  The amount to refund.

  
  

• feeRefunded Money

  In this refund, the transaction fee PayBy needs to refund.

  
  

• sharingInfoList List

  If a refund occurs before the sharing amount is settled into the receiver's account, the receiver will actually receive less funds than the requested amount in the payment order. In this list PayBy will return the original requested sharing amount and the receiver actually obtained.

  The attributes of each item in the list are:

  • sharingIdentitySeqId Money Required

    You can pass multiple account ids to split the payment amount, in order to distinguish them, the serial number is needed. Please start with 1, then 2, 3, 4, etc.

    Example value: 1

    
    

  • sharingMid String Required

    If the sharingIdentityType and sharingIdentity passed in the request can correspond to a member id that already exists in the PayBy system, in the response PayBy will return the member id.

    
    

  • sharingMemo String Required

    Add some description to this operation.

    
    

  • sharingAmount Money Required

    The amount you plan to split to this id.

    
    

  • sharingSettledAmount Money Required

    The amount of fund the sharing account finally received. If any refund occurs before settlement, the sharingSettledAmount will be different from the original sharingAmount.

    
    

• notifyUrl String

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

  Maximum length: 200

  
  

• reason String

  Reason for refund.

  Maximum length: 64

  
  

• secondaryMerchantId String

  If you are a platform and the transaction was made at a merchant under your platform, you can use this parameter to allocate the funds collected. To learn more about this feature please contact PayBy. The secondary merchant id represents the merchant's member id on your platform.

  Maximum length: 200

  
  

• deviceId String

  If the transaction wad made on a terminal or virtual device, the device id can be passed for transaction data statistics. Note that this parameter must be passed if you are using the secondery merchant function, this parameter must be passed.

  Maximum length: 200

  
  

• failCode String

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

  Example value: 62002

  
  

• failDes String

  If the order status is FAILURE, the failure reason.

  Example value: Failed orders cannot be cancelled or refunded

  
  

• reserved String Required

  The PayBy's unique identify 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"
}