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


acquireOrder 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


  • status Enum Required

    The possible values are:

    CREATED. The order has been created.

    PAID_SUCCESS. The order has been successfully paid.

    SETTLED. The order has been paid and the fund has been settled to merchant's account.

    FAILURE. The order has been cancelled or expired.


  • paymentInfo Object

    • paidAmount Money Required

      The amount actually paid by the user. If a discount is used, it will be different from the order amount.


    • paidTime TimeStamp Required

      Payer's successful payment time

      Example value: 1581493898000


    • payerMid String

      If the payer uses a BOTIM or Pay By wallet for payment, payerMid represents the payer's member ID in the wallet.

      Example value: 200001200101


    • payerFeeAmount Money

      If the order transaction fee is set to be charged from the payer, payerFeeAmount represents the actual amount of the transaction fee.


    • payeeFeeAmount Money

      If the order transaction fee is set to be charged from the payee, payeeFeeAmount represents the actual amount of the transaction fee.


    • payChannel String Required

      The payment channel used by the payer. The possible values areBANKCARD, INSTALLMENT, EWALLET, etc.


    • settlementAmount Money Required

      The actual funds the payee can receive after deducting transactions fees and amount for other reasons.


    • cardInfo
      This object may be returned only for `DIRECTPAY` payment scene.The attibutes are:

      brand String Required

      The card issuer. The possible values are:

      MASTERCARD >VISA >AE >DISCOVER >JC


      cardId String

      If the payer's card information was requested to be saved for future use., payby will return the card's ID.

      Example value: 31658300


      last4 String Required

      Last 4 digits of card number.

      Example value: 6345


      cardType String Required

      The possible values are:

      DC. Debit Card

      CC. Credit Card


      expMonth String Required

      Two -digit number, representing the card expiry month.

      Example value: 01


      expYearString Required

      Two -digit number, representing last two digits of the card expiry year.

      Example value: 22


  • product String Required

    The product name related to the payment scene parameter used in the order. This product name is only used for PayBy internal classification.

    Example value: Basic Payment Gateway


  • totalAmount Money Required

    The order amout intended to collect from the payer.


  • payeeMid String Required

    The payee's member ID in PayBy.

    Example value: 200001200101


  • expiredTime TimeStamp Required

    The order expiration time, after which the payment cannot be completed.

    Example value: 1581493898000


  • notifyUrl String Required

    To receive asynchronous notifications of order status updates, the merchant can pass the notify URL in the request to place order.

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


  • sharingParamList List

    With every payment, you can split the funds between your merchant account and other PayBy member IDs. For example, a payment of 10 AED, if you share 1 AED to A and 2 AED to B, you will get 7 AED.

    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.


  • subject String Required

    Description of this order.

    Example value: iPhone.


  • accessoryContent String

    Used for storing additional information about the order.


  • paySceneCode Enum Required

    Payment scene used to create the order. The possible values are PAYPAGE, INAPP, EWALLET, DYNQR, QRPAY, JSAPI, AUTODEBIT, DIRECTPAY, etc.


  • paySceneParams String Required

    Different payment scenarios need to pass different scenario parameters.


  • deviceId String

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


  • 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


  • 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


  • revoked Boolean Required

    If true, it means that the payment has been made but then cancelled.


  • reserved String

    Merchant's notes for the order.

    Example value: June campaign order.

    Maximum length: 200



**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",
"Sign": "NshUvvVM3f/2eYcHyel7w7xDyzX1o7azydZ3ctGVWEghE4MCDcrEfO7LHmuDCQO4tqLwXwIv4pJfPH37X/o4V8q9QaE+gcPPvzO2xlT/Fksocd+gBoBWGz6SaEmD3eKQ7J9SU3+sKLOre9BomzJ5CuzsFAbBrZVw1+0MiwE3NTJvKEL3CW6LhHj2/1bnFMrQeBXP0z2LoqqODORG5Sgy8W9EPlMityjGOtPGMPj6iOK6il1KIeGRBW1wBeP0ZP/n8hwsob/fLygJ8UhB/kOAICXRrA+uo2Z4JJXhuX9P+C0BufPWHIdwq7ZdAvcxmSXFjtwIHuY9JFNWdTBZhxNw3g=="
}

Http Body
{
"_input_charset": "UTF-8",
"acquireOrder": {
"accessoryContent": {
"amountDetail": {
"amount": {
"amount": 1.09,
"currency": "AED"
},
"vatAmount": {
"amount": 20.65,
"currency": "AED"
}
},
"goodsDetail": {
"body": "Gifts",
"categoriesTree": "CT12",
"goodsCategory": "GC10",
"goodsId": "GI1005",
"goodsName": "Candy flower",
"price": {
"amount": 10.87,
"currency": "AED"
},
"quantity": 2.0
},
"terminalDetail": {
"merchantName": "LuLu",
"operatorId": "OP1000000000000001",
"storeId": "SI100000000000002",
"storeName": "LuLu",
"terminalId": "TI100999999999900"
}
},
"expiredTime": 1587120191014,
"merchantOrderNo": "M572007254058",
"notifyUrl": "http://www.yoursite.com",
"orderNo": "131587112991000943",
"paySceneCode": "PAYPAGE",
"payeeMid": "200000000888",
"paymentInfo": {
"paidAmount": {
"amount": 0.1,
"currency": "AED"
},
"paidTime": 1587113039000,
"payChannel": "BALANCE",
"payeeFeeAmount": {
"amount": 0.01,
"currency": "AED"
},
"payerFeeAmount": {
"amount": 0.0,
"currency": "AED"
},
"payerMid": "100000012396"
},
"product": "Basic Payment Gateway",
"requestTime": 1587112991014,
"status": "PAID_SUCCESS",
"subject": "Your subject",
"totalAmount": {
"amount": 0.1,
"currency": "AED"
}
},
"notify_id": "202004170007499051",
"notify_time": "20200417124359",
"notify_timestamp": 1587113039189
}

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"
}