Asynchronous Notification

When a VAM top-up occurs, PayBy will send relevant top-up information to the merchant through a data stream. The merchant needs to receive and process this information, and return a response according to the document specifications.

Note

1. The same notification may be sent to the merchant system multiple times. The merchant system must be able to correctly handle duplicate notifications.
2. During backend notification interactions, if PayBy receives a response from the merchant that does not conform to specifications or times out, PayBy will determine this notification as failed and resend the notification until successful (default retry 7 times with intervals: 2, 10, 10, 60, 120, 360, 900 minutes). However, PayBy does not guarantee that notifications will ultimately succeed.
3. In cases where the order status is unclear or no PayBy payment result notification is received, it is recommended that merchants actively call the order query interface to confirm the order status.

Request

Http Header

Attributes

• 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

• vamDepositOrder Object Required

  Attributes

  • transactionTime Timestamp Required

    • The time the transaction occurred, in milliseconds since epoch¹.
    • Example value: 1581493898000

  • orderNo String Required

    • Unique identifier for the PayBy order.
    • Example value: O1000
    • Maximum length: 32

  • amount Money Required

    • The amount of money deposited.
    • Example value: 100.00

  • status String Required

    • The current status of the deposit.
    • Possible values:
      • SUCCESS: The deposit was successful.
      • FAILED: The deposit failed.
    • Example value: SUCCESS
    • Maximum length: 32

  • referenceNo String

    • External reference number for the transaction.
    • Example value: REF123456
    • Maximum length: 200

  • remitterInfo String

    • Information about the person or entity sending the funds.
    • Example value: John Doe
    • Maximum length: 200

  • senderBankCode String

    • Bank code of the sender’s bank.
    • Example value: HSBC001
    • Maximum length: 200

  • depositDetails String

    • Additional details or notes about the deposit.
    • Example value: Invoice #4567
    • Maximum length: 200

  • collectIBAN String

    • IBAN where the funds are collected.
    • Example value: AE070331234567890123456
    • Maximum length: 200

  ---

  1. Epoch typically refers to a specific point in time, expressed as the number of milliseconds (or seconds) that have elapsed since January 1, 1970, 00:00:00 UTC—commonly known as the Unix epoch.↩

• **notify_time** String

  The parameter is deprecated. Please use the notify_timestamp instead.

• **_input_charset** String

  The parameter is deprecated.

Notification Sample

// HTTP request headers
Http Header
{
  "Content-Type": "application/json; charset=UTF-8"
}

// HTTP request body containing the notification data
Http Body
{
  "notify_time": "20241224061738",  // Notification timestamp in format YYYYMMDDHHMMSS
  "vamDepositOrder": {
    "remitterInfo": "MR HUA JIANG",  // Name of the person sending the funds
    "amount": {
      "amount": 3000,                // Transaction amount (in smallest currency unit)
      "currency": "AED"              // Currency code (ISO 4217 format)
    },
    "orderNo": "131727701521486397", // PayBy internal order number
    "referenceNo": "UFOC0HQ008",     // External reference number
    "senderBankCode": "BBMEAEADXXX", // SWIFT code of the sender's bank
    "depositDetails": "REF AEV260832YLQ4K5D FIS 56057df891a0449584dc5c8d84a6a138", // Additional deposit details/memo
    "transactionTime": 1727701521000, // Transaction timestamp in milliseconds (Unix epoch)
    "status": "SUCCESS"              // Transaction status (SUCCESS/FAILED/PENDING)
  },
  "_input_charset": "UTF-8",         // Character encoding of the request
  "notify_timestamp": 1735006658869, // System notification timestamp in milliseconds
  "notify_id": "202409300013926551"  // Unique notification identifier
}

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

// Http Header
{
 "Content-Type": "application/json; charset=UTF-8" 
}

// Http Body
{
    "response":"SUCCESS"
}