VOID Result Notification

Overview

When a VOID order reaches a terminal state, Botim Money sends the VOID result to the merchant via a data stream. The merchant system must receive, process, and respond to this notification according to the API specifications.

This notification applies exclusively to POS terminal payments, including NFC contactless payments, card swipe payments, and QR code payments, etc.

---

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 Botim Money 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 Botim Money sends a notification, 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 notification was sent by Botim Money and not faked by others.

Http Body

• notify_timestamp Timestamp Required

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

• notify_id String Required

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

• voidOrder Object

  Attributes

  • voidMerchantOrderNo String Required

    The merchant-side VOID request order number.

  • voidOrderNo String Required

    The platform-generated VOID order number. Recommended as one of the idempotency keys.

  • originMerchantOrderNo String Required

    The merchant order number of the original payment order.

  • status String Required

    VOID order status.

    • Enum values: SUCCESS, FAILURE, PLACED

  • amount Object Required

    • amount Number Required

      VOID amount.

    • currency String Required

      Currency code.

      • Example value: AED

  • voidCallbackUrl String Optional

    The merchant-configured callback URL for VOID notifications.

  • failCode String Optional

    Failure code. Empty when the VOID succeeds.

  • failDes String Optional

    Failure description. Empty when the VOID succeeds.

  • feeVoid Object Optional

    • amount Number Required

      VOID fee amount.

    • currency String Required

      VOID fee currency code.

      • Example value: AED

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
{
    "notify_id": "202004170007499051",
    "notify_timestamp": 1587113039189,
    "voidOrder": {
        "voidMerchantOrderNo": "VM202604100001",
        "voidOrderNo": "202604100000000001",
        "originMerchantOrderNo": "M202604090001",
        "status": "SUCCESS",
        "amount": {
            "amount": 100.00,
            "currency": "AED"
        },
        "voidCallbackUrl": "https://merchant.example.com/callback/void",
        "failCode": "",
        "failDes": "",
        "feeVoid": {
            "amount": 0.00,
            "currency": "AED"
        }
    }
}

---

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

---

Event Codes

The following event codes are used for VOID-related notifications:

Event Code	Description
VOID_ORDER_SUCCESS	VOID succeeded
VOID_ORDER_FAILURE	VOID failed
VOID_ORDER_PLACED	VOID accepted / pending