Asynchronous Notification

Overview

When a merchant payment to a bank card has a result, PayBy sends the related result to the merchant.

The merchant needs to receive and process the notification, then return a response. The actual arrival time depends on the settlement time of each bank and is subject to the actual arrival time.

Notification Handling Guidelines

1. Duplicate Notifications
   PayBy may send the same notification multiple times. The merchant system must be capable of identifying and handling duplicate notifications correctly to avoid processing the same transaction more than once.

2. Notification Retry Mechanism
   If PayBy receives an invalid response or no response (timeout) from the merchant system during backend notification, it will consider the attempt failed and retry the notification.

   • Retry Policy: Up to 7 attempts
   • Retry Intervals: 2, 10, 10, 60, 120, 360, and 900 minutes
     Please note: PayBy does not guarantee final delivery success.

3. Unclear Order Status
   If the payment result is not received or the order status is unclear, merchants are advised to actively query the order status using the transfer query interface.

4. Signature Verification
   All notification requests are signed using PayBy’s RSA private key.

   • The signature algorithm is the same as for ordinary requests.
   • Merchants must verify the signature using PayBy’s public key, which can be downloaded from the merchant portal.

Notification Parameters

The notification request format is the same as ordinary requests, using the HTTP protocol with HTTP headers and a JSON object in the HTTP body.

Bank Card Transfer Order Information

• Variable Name: transferBankCardOrder
• Required: Required
• Type: TransferBankCardOrder
• Example: -
• Description: Contains the details of the bank card transfer order

Attributes

TransferBankCardOrder

• Request Time (requestTime)

  • Required: Yes
  • Type: Timestamp(3)
  • Example: 1581493898000

• Merchant Order Number (merchantOrderNo)

  • Required: Yes
  • Type: String(64)
  • Example: S10000

• PayBy Order Number (orderNo)

  • Required: Yes
  • Type: String(32)
  • Example: O1000

• Product Name (product)

  • Required: Yes
  • Type: String(200)
  • Example: Transfer Bank Card

• Order Status (status)

  • Required: Yes
  • Type: String
  • Example: CREATED, SUCCESS, FAILURE, BANK_FAIL
  • Description: The status of order

• Amount (amount)

  • Required: Yes
  • Type: Money

• Account Holder Type (accountHolderType)

  • Required: Yes
  • Type: String(16)
  • Example: INDIVIDUAL
  • Description: INDIVIDUAL or CORPORATE

• First Name (firstName)

  • Required: Optional
  • Type: String(200)
  • Description: SHA256 of original text, required if INDIVIDUAL

• Last Name (lastName)

  • Required: Optional
  • Type: String(200)
  • Description: SHA256 of original text, required if INDIVIDUAL

• Middle Name (middleName)

  • Required: Optional
  • Type: String(200)
  • Description: SHA256 of original text

• Company Name (companyName)

  • Required: Optional
  • Type: String(200)
  • Description: SHA256 of original text, required if CORPORATE

• Card Number (cardNumber)

  • Required: Yes
  • Type: String(64)
  • Description: SHA256 of original text

• Expiry Month (expiryMonth)

  • Required: Yes
  • Type: String(2)
  • Example: 09
  • Description: The card's expiration month of the expiration year. The number must between 1 and 12, and the year + month should be larger or equal to current month.

• Expiry Year (expiryYear)

  • Required: Yes
  • Type: String(4)
  • Example: 2027
  • Description: The card's expiration year

• Payment Memo (memo)

  • Required: Optional
  • Type: String(128)
  • Example: Bonus

• Notification URL (notifyUrl)

  • Required: Optional
  • Type: String(200)
  • Example: http://yoursite.com/api/notification
  • Description: The URL where the merchant receives notifications

• Failure Description (failDes)

  • Required: Optional
  • Type: String(200)
  • Example: -
  • Description: Cause of order failure

• Bank Reference Number (bankReference)

  • Required: Optional
  • Type: String(128)

• Payer Fee Amount (payerFeeAmount)

  • Required: Yes
  • Type: Money
  • Example: { "amount": 0, "currency": "AED" },
  • Description: The fee paid by the payer

• Fee Payer ID (payerFeeMemberId)

  • Required: Yes
  • Type: String(32)
  • Example: 200000429066
  • Description: ID of the party paying the fee

• Payment Time (paidTime)

  • Required: Yes
  • Type: Date
  • Description: Time of deduction

• Refund Time (refundedTime)

  • Required: Optional
  • Type: Date
  • Description: Time of refund

Notification Sample

{
  "transferBankCardOrder": {
    // Transfer bank card order details will be provided here
  }
}

Response Parameters

After the merchant receives the notification, return "SUCCESS" to indicate successful receipt.

Any other response indicates an exception.

Response Codes

Code	Message	Cause	Workaround
0	SUCCESS	Success	-
400	INVALID_PARAMETER	Parameter error	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too early compared to current time	Adjust request time
400	REQUESTTIME_TOO_LATER	Request time is too late compared to current time	Adjust request time
402	RATE_LIMIT_REJECT	Request too frequent	Reduce request frequency
403	UNAUTHORIZED	API unauthorized	Contact PayBy
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact PayBy
500	SYSTEM_ERROR	System error	Contact PayBy, retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later
601	RISK_FAIL	Risk control verification failed	Please adjust business
62002	ORDER_FAILURE	Failed order initiated cancellation again. Failed order initiated refund.	Adjust merchant order number
62004	MERCHANT_ORDER_NO_NOT_EXIST	Order with merchant order number does not exist	Adjust merchant order number
62016	MERCHANT_ORDER_NO_EXIST	Same order number, different business parameter order creation request	Adjust order number
62026	PRODUCT_IS_NOT_APPLIED	Product not applied	Please apply for product
62028	ORDER_SUCCESS	Order already successful	Adjust merchant order number
62029	ORDER_CREATED	Order already created	Adjust merchant order number