Asynchronous Notification

If the notifyUrl parameter is passed in the order creation request to receive payment notifications, Botim Money 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 Botim Money to the merchant, and the merchant needs to send response to Botim Money.
2. After receiving the notification, please return the success message, otherwise Botim Money 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 Botim Money 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 Botim Money sends response, Botim Money will use its own private key to sign the message, and the merchant uses Botim Money 's public key to verify the signature. If the verification is passed, it proves that the response was sent by Botim Money and not faked by others.

Http Body

• notify_timestamp Timestamp Required

  • The timestamp when Botim Money sent the request.
  • Example value: 1586849271877

• notify_id String Required

  • The unique identification number of this notification within the Botim Money system.
  • Example value: 202004140007474501

• transferOrder 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 Botim Money's unique identification number of the order.
    • Example value: 131658300517875854

  • product String Required

    • The product name of the API method used in the order. Used for Botim Money internal classification.
    • Maximum length: 100

  • status Enum Required

    • Possible values:
      • CREATED: The order has been created.
      • SUCCESS: The transfer completed.
      • FAILURE: The order has been cancelled or expired.

  • paymentInfo Object

    • payerFeeAmount Money Required
      • Fee that the payer needs to pay in this transfer.
    • arrivalTime Timestamp Required
      • Estimated time of fund arrival (not actual arrival time).
      • Example value: 1581493898000

  • beneficiaryIdentityType String Required

    • Method used to identify the beneficiary.
    • Possible values:
      • PHONE_NO: Transfer through mobile phone number
      • MEMBER_ID: Transfer through Botim Money member ID
    • Maximum length: 20

  • beneficiaryIdentity String Required

    • Value passed based on the selected identity type.
    • Should be encrypted using SHA-256.
    • Example values:
      • +971-585812345 (for PHONE_NO)
      • 100006514321 (for MEMBER_ID)
    • Maximum length: 20

  • beneficiaryFullName String

    • If provided, Botim Money verifies it against the beneficiary's KYC info.
    • If not provided, no verification is performed.
    • Should be encrypted using SHA-256.
    • Maximum length: 100

  • memo String Required

    • Description of the transfer.
    • Maximum length: 128

  • notifyUrl String

    • URL to receive asynchronous notifications of order status updates.
    • Example value: https://www.yoursite.com
    • Maximum length: 200

  • failCode String

    • Code identifying the reason for failure (if status is FAILURE).
    • Example value: 504

  • failDes String

    • Description of the failure reason (if status is FAILURE).
    • Example value: SERVICE_TIMEOUT

**notify_time** String

The parameter is deprecated. Please use the notify_timestamp instead.

**_input_charset** String

The parameter is deprecated.

Notification Sample

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

// Http Body
{
    "_input_charset": "UTF-8",
    "notify_id": "202004170007501041",
    "notify_time": "20200417180000",
    "notify_timestamp": 1587132000943,
    "transferOrder": {
        "amount": {
            "amount": 1.21,
            "currency": "AED"
        },
        "beneficiaryFullName": "1fab0a7a62d3528b4a58270b0c29b7494bdb2527a555819159e956b01778d488",
        "beneficiaryIdentity": "ff3f1b1584a619ff725ac1f4606964e18bef257b83257265f65ade62326f7c10",
        "beneficiaryIdentityType": "PHONE_NO",
        "memo": "Your memo",
        "merchantOrderNo": "M046082822070",
        "notifyUrl": "http://www.yoursite.com",
        "orderNo": "911587131999001394",
        "paymentInfo": {
            "arrivalTime": 1587132000000,
            "payerFeeAmount": {
                "amount": 0.01,
                "currency": "AED"
            }
        },
        "product": "Transfer",
        "requestTime": 1587131998413,
        "status": "SUCCESS"
    }
}

Response

Please reply success after receiving the notification, otherwise Botim Money 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"
}