Callbacks

The Terminal API uses webhooks to notify your application about payment session and payment object events. This allows you to receive real-time updates about transaction status changes.

Webhook Configuration

Webhooks are configured through the Xendit Dashboard. You’ll need to provide a webhook URL where notifications will be sent.

Make sure your webhook endpoint is publicly accessible and can handle POST requests with JSON payloads.

Authentication

All webhook requests include authentication headers to verify the source:

string

required

Webhook verification token - can get from dashboard

string

required

Unique identifier for the webhook request

Payment Session Callbacks

These callbacks are triggered by payment session events.

Endpoint

POST <Webhook URL provided by Partner via Xendit dashboard>

Events

terminal_session.completed

Payment session has been completed successfully

terminal_session.voided

Payment session has been voided

terminal_session.canceled

Payment session has been canceled

Payload Structure

string

The event enum: terminal_session.completed, terminal_session.voided, terminal_session.canceled

string

Xendit business ID

DateTime

Timestamp for webhook notification creation

object

Payment session data

string

Xendit-generated identifier for business that owns the transaction

string

Merchant’s reference ID

string

Payment Session ID

string

Country where the payment happened

string

ISO 4217 Alpha-3 code

number

Amount of session

object

Payment details

string

Terminal’s id

string

Merchant’s Order ID

string

Payment status

object

A set of key-value pairs that can be used to store custom, unstructured information about the object

DateTime

The timestamp indicates when the resource was created

DateTime

The timestamp indicates when the resource was last modified

Example Payment Session Callback

{
  "event": "terminal_session.completed",
  "business_id": "biz_1234567890",
  "created_at": "2025-01-27T10:45:00Z",
  "data": {
    "business_id": "biz_1234567890",
    "reference_id": "order-123",
    "payment_session_id": "ps_1234567890abcdef",
    "country": "ID",
    "currency": "IDR",
    "amount": 100000,
    "payment_details": {
      "terminal_id": "TERM001",
      "order_id": "ORDER123"
    },
    "status": "COMPLETED",
    "metadata": {
      "store_id": "store_001"
    },
    "created": "2025-01-27T10:30:00Z",
    "updated": "2025-01-27T10:45:00Z"
  }
}

Payment Object Callbacks

These callbacks are triggered by payment object events.

Endpoint

POST <Webhook URL provided by Partner via Xendit dashboard>

Events

terminal_payment.succeeded

Payment has been successfully processed

terminal_payment.voided

Payment has been voided

Payload Structure

string

The event enum: terminal_payment.succeeded, terminal_payment.voided

string

Xendit business ID

DateTime

Timestamp for webhook notification creation

object

Payment object data

string

Xendit-generated identifier for business that owns the transaction

string

Merchant’s reference ID

string

Payment ID

string

Country where the payment happened

string

ISO 4217 Alpha-3 code

number

Amount of payment

object

Payment details

string

Terminal’s id

string

Merchant’s Order ID

string

Payment status

object

A set of key-value pairs that can be used to store custom, unstructured information about the object

DateTime

The timestamp indicates when the resource was created

DateTime

The timestamp indicates when the resource was last modified

Example Payment Object Callback

{
  "event": "terminal_payment.succeeded",
  "business_id": "biz_1234567890",
  "created_at": "2025-01-27T10:45:00Z",
  "data": {
    "business_id": "biz_1234567890",
    "reference_id": "order-123",
    "payment_id": "pay_1234567890abcdef",
    "country": "ID",
    "currency": "IDR",
    "request_amount": 100000,
    "payment_details": {
      "terminal_id": "TERM001",
      "order_id": "ORDER123"
    },
    "status": "SUCCEEDED",
    "metadata": {
      "store_id": "store_001"
    },
    "created": "2025-01-27T10:35:00Z",
    "updated": "2025-01-27T10:45:00Z"
  }
}

Response Handling

Your webhook endpoint should respond with appropriate HTTP status codes:

Success

HTTP status code = 200Indicates successful processing of the webhook

Error

HTTP status code != 200Indicates an error in processing the webhook

Error Response Format

If you need to return an error, include the following fields in your response:

string

Error code

string

Providing additional information about the response

Example Error Response

{
  "error_code": "PROCESSING_ERROR",
  "message": "Unable to process webhook due to database connection issue"
}

Best Practices

Idempotency

Implement idempotency to handle duplicate webhook deliveries

Retry Logic

Xendit will retry failed webhooks, so ensure your endpoint can handle retries

Security

Always verify the webhook signature using the x-callback-token

Logging

Log all webhook events for debugging and audit purposes

Overview

Terminal API (H2H)

Terminal API (C2C)

Callbacks

Callbacks

Webhook Configuration

Authentication

Payment Session Callbacks

Endpoint

Events

terminal_session.completed

terminal_session.voided

terminal_session.canceled

Payload Structure

Example Payment Session Callback

Payment Object Callbacks

Endpoint

Events

terminal_payment.succeeded

terminal_payment.voided

Payload Structure

Example Payment Object Callback

Response Handling

Success

Error

Error Response Format

Example Error Response

Best Practices

Idempotency

Retry Logic

Security

Logging

​Callbacks

​Webhook Configuration

​Authentication

​Payment Session Callbacks

​Endpoint

​Events

terminal_session.completed

terminal_session.voided

terminal_session.canceled

​Payload Structure

​Example Payment Session Callback

​Payment Object Callbacks

​Endpoint

​Events

terminal_payment.succeeded

terminal_payment.voided

​Payload Structure

​Example Payment Object Callback

​Response Handling

Success

Error

​Error Response Format

​Example Error Response

​Best Practices

Idempotency

Retry Logic

Security

Logging

Callbacks

Webhook Configuration

Authentication

Payment Session Callbacks

Endpoint

Events

Payload Structure

Example Payment Session Callback

Payment Object Callbacks

Endpoint

Events

Payload Structure

Example Payment Object Callback

Response Handling

Error Response Format

Example Error Response

Best Practices