Payment Callback

Instead of constantly polling the API to check payment status, Gate will automatically send a real-time HTTP POST notification (webhook) to your server when a payment succeeds.


Webhook Workflow

  1. The customer completes payment via the payment_url obtained during the Create Transaction step.
  2. The payment gateway verifies the funds and sends a server-to-server webhook to the Gate API.
  3. Gate updates the internal database status to SUCCESS.
  4. Gate's asynchronous worker dispatches a simplified webhook payload to the callback_url you provided during the Create Transaction request.

Webhook Endpoint Details

Property Value
HTTP Method POST
Target URL Your configured callback_url
Content-Type application/json

Payload Structure

Fields

Field Type Description
trx_id string The transaction ID returned by create-transaction.
paid_at string (RFC3339) Timestamp when the payment was completed (e.g. 2026-07-01T10:05:43+07:00).
amount string Paid amount as a decimal string (e.g. "10020").
method integer Payment method enum (4 for Credit Card).
status integer Payment status enum code (see table below).
issuer_name string Issuing bank / card network code (e.g. BCA).
customer_name string Customer / Cardholder name.

Status Values

Value Status Meaning
0 Pending Not yet paid (default for new transactions).
1 Reject Rejected by the payment network.
2 Cancel Cancelled at the payment network's request.
3 Expired Time limit reached without payment.
4 Obscure Undefined status from the bank / network.
5 Completed Successfully paid and settled.

Example Webhook Payload

{
  "trx_id": "INV-20260608-0001",
  "paid_at": "2026-07-01T10:05:43+07:00",
  "amount": "10020",
  "method": 4,
  "status": 5,
  "issuer_name": "BCA",
  "customer_name": "Budi Santoso"
}

Expected Response

Your server must accept the webhook and respond with an HTTP 2xx status code (e.g., 200 OK) as quickly as possible.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

If your server returns an error code (4xx or 5xx) or times out, the delivery will be considered failed and subject to retry policies based on the background queue configuration.


Important Notes

[!IMPORTANT] Always verify trx_id: Ensure the trx_id corresponds to a pending order in your database before fulfilling the product or service.

Idempotency: Webhook deliveries can occasionally be retried. Your handler should be idempotent—handling the same trx_id with status 5 multiple times should not result in duplicate order fulfillment.