Asynchronous Notification

Overview

After a successful payment, PayBy sends the payment result and user information to the merchant via a data stream. The merchant system must receive, process, and respond to this notification according to the API specifications.

Note

Duplicate Notifications: The same notification may be sent multiple times. The merchant system must be able to handle duplicate messages correctly and idempotently.
Retry Mechanism: If PayBy does not receive a valid or timely response from the merchant, it will consider the notification failed and retry delivery. The default retry schedule is up to 7 attempts at the following intervals (in minutes): 2, 10, 10, 60, 120, 360, 900. However, successful delivery is not guaranteed.
Order Status Uncertainty: If the order status is unclear or no notification is received, merchants are advised to actively query the order status using the appropriate API.

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 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
- 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
  Detailed payment information including fees and timestamps.
  paidAmount Money Required
  The amount actually paid by the user. If a discount is used, it will differ from the order amount.
  paidTime Timestamp Required
  Payer's successful payment time.
  Example value: 1581493898000
  payerMid String
  Payer's member ID in the wallet (BOTIM or PayBy).
  Example value: 200001200101
  payerFeeAmount Money
  Transaction fee charged to the payer.
  payeeFeeAmount Money
  Transaction fee charged to the payee.
  payChannel String Required
  Payment channel used by the payer.
  Possible values: BANKCARD, INSTALLMENT, EWALLET, etc.
  settlementAmount Money Required
  Actual funds received by the payee after deductions.
  cardInfo
  This object may be returned only for `DIRECTPAY` payment scene. The attributes 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
  Product name related to the payment scene. Used for internal classification.
  Example value: Basic Payment Gateway
- totalAmount Money Required
  The order amount intended to collect from the payer.
- payeeMid String Required
  Payee's member ID in PayBy.
  Example value: 200001200101
- expiredTime Timestamp Required
  Order expiration time.
  Example value: 1581493898000
- notifyUrl String Required
  URL to receive asynchronous notifications of order status updates.
  Example value: https://www.yoursite.com
- sharingInfoList List
  Sharing information for split payments.
  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 sharing operation.
  sharingAmount Money Required
  Amount planned to be split to this ID.
  sharingSettledFeeAmount Money Required
  Transaction fee charged to this sharing account if applicable.
  sharingSettledAmount Money Required
  Actual amount received by this ID.
  withholdAndRemitFee Boolean
  Indicates whether this sharing account pays the transaction fee.
  Only one account can have true in this field per request.
- 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.
  Possible values: 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 was made on a terminal or virtual device, the device ID can be passed for transaction data statistics.
  Note: 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.
  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 String 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"
}

Asynchronous Notification

Overview​

Request​

Http Header​

Http Body​

Request Sample​

Response​

Http Header​

Http Body​

Response Sample​

Overview

Request

Http Header

Http Body

Request Sample

Response

Http Header

Http Body

Response Sample