Docs
Callback

Transaction Callback (Webhook)

When a transaction is successfully processed through Zipay, Zipay will automatically send a callback to the URL registered by the merchant. This allows the merchant’s system to receive real-time updates on the transaction status, such as when a payment is confirmed as successful.

Callback Flow

  1. A customer makes a payment through Zipay.
  2. Once the payment is confirmed, Zipay sends a callback to the merchant’s registered callback URL.
  3. The merchant’s server receives the callback and processes the payment status accordingly (e.g., updating the order status, notifying the customer).

Callback Payload

Once a transaction is successfully paid, Zipay will send a callback request to the URL you registered. Make sure your server is ready to handle and respond to this callback appropriately. Zipay sends a POST request to the registered callback URL with a payload that includes details about the transaction.

Example Callback Request

{
  "uuid": "b063757a-fdeb-411c-a1a5-2dd1cdb84xxx",
  "type": "STATIC",
  "amount": "10000",
  "invoiceNumber": "13h35dblkH13h35dblkL",
  "mpan": "9360082500812547376",
  "customerName": "AGUNG MAULANA",
  "externalId": "QRST-621713",
  "mdrPercentage": 0.7,
  "mdrAmount": 70,
  "status": "PAID",
  "issuerName": "Zipay",
  "merchantId": "1",
  "merchantName": "TOKO SEPATU",
  "transactionTime": "2025-01-06 20:59:32",
  "paidAt": "2025-01-06"
}

Fields Explanation

FieldDescription
uuidA unique identifier for the transaction.
typeThe type of transaction, e.g., STATIC.
amountThe amount paid for the transaction (in the smallest currency unit, e.g., cents).
invoiceNumberThe invoice number generated for the transaction.
mpanThe Merchant PAN (Primary Account Number) assigned to the merchant.
customerNameThe name of the customer who made the payment.
externalIdAn external identifier associated with the transaction, useful for linking to your internal system.
mdrPercentageMDR expressed as a percentage, based on merchant criteria.
mdrAmountThe fee deducted from the transaction, calculated using the MDR percentage.
statusThe payment status of the transaction (e.g., PAID, FAILED, etc.).
issuerNameThe name of the payment issuer (in this case, Zipay).
merchantIdThe unique identifier of the merchant who received the payment.
merchantNameThe name of the merchant who received the payment.
transactionTimeThe date and time when the transaction was created. This timestamp indicates when the transaction was initiated or recorded in the system. Format: YYYY-MM-DD HH:mm:ss (e.g., 2024-08-15 20:59:32).
paidAtThe date and time when the payment for the transaction was successfully completed. This timestamp represents when the transaction was marked as paid. Format: YYYY-MM-DD HH:mm:ss (e.g., 2024-09-10).

Example Callback Response

Once your system receives and processes the callback request, it should respond with a 200 OK status code to acknowledge receipt of the callback.

Handling the Callback

  1. Verify the Payment Status: Ensure that the status field in the callback payload is PAID before proceeding with any business logic, such as updating the order system or notifying the customer.

  2. Check for Matching Invoice: Compare the invoiceNumber and externalId with your system’s records to ensure that the callback corresponds to the correct transaction.

  3. Acknowledge the Callback: Once you have successfully processed the callback, your server should respond with a 200 OK status code. If any issues occur, respond with an appropriate error message.

LoginRegister Merchant