Quick Start - Xendit Documentation

Device-Only Setup

For merchants without a POS integration, payments can be accepted directly on the terminal by manually entering amounts. No API or SDK setup is required. Transactions are visible in your Xendit Dashboard.

📖

Device-Only Setup Guide

Learn how to use the terminal without any integration

Integration type

2Integration path

3Get started

Choose your integration path

Select the integration approach that best fits your technical requirements.

Host-to-Host (H2H) — Terminal API Recommended for most merchants	Client-to-Client (C2C) Terminal C2C API or Terminal C2C SDK
Your backend calls Xendit’s cloud HTTP API. Managed orchestration with minimal custom code.	Your POS talks to terminals over the local network via HTTP REST commands or native SDK methods.
Uses Terminal API sessions for payments, callbacks, and reconciliation.	Sends PAY / CANCEL / SETTLEMENT commands directly — via Terminal C2C API (HTTP) or Terminal C2C SDK (native).
Xendit manages device orchestration and infrastructure.	Your team owns device connectivity, error handling, and security.

Not sure? H2H fits most deployments for its simplicity and speed. Explore the Terminal API (H2H) docs or C2C docs for deeper details.

Integration type

Integration path

3Get started

Select your payment provider(s)

Choose the terminal providers you plan to integrate. You can select more than one.

🇮🇩 Indonesia

BRI

Bank Rakyat Indonesia terminals

CashupComing soon

Multi-brand payment terminals

🇹🇭 Thailand

NTT

NTT DATA payment terminals

🇲🇾 Malaysia

Share Commerce

Retail payment terminals

🇻🇳 Vietnam

Atom

Payment terminals for Vietnam

Prerequisites

Terminal API key from the Xendit In-Person Payment team
Node.js or your preferred development environment

For Physical Terminal Testing

Physical terminal device connected and showing “Ready” status
Terminal registered with Xendit for test mode (contact support if needed)
Valid terminal_id from your registered device

For Simulation Testing (No Terminal Required)

Any terminal_id value (e.g., SIM001) — no registration needed
Special test amounts to trigger different payment scenarios
Use 4040404 as terminal_id to test invalid terminal error handling

Don’t have a physical terminal yet? No problem! You can start integration immediately using simulation. Use special test amounts and terminal IDs to simulate different payment scenarios without physical hardware.

Use sandbox/test devices and small amounts while testing. Do not use production keys in development.

1. Configure your environment

Set up your local development environment with the necessary credentials and base URLs.

1

Create environment file

Create a .env file in your project root:

.env

TERMINAL_API_KEY=your_dev_terminal_api_key
TERMINAL_BASE_URL=https://terminal-dev.xendit.co
CALLBACK_URL=http://localhost:3000/terminal/callbacks
TERMINAL_ID=TERM001

Never commit secrets to version control. Add .env to your .gitignore file.

2

Install dependencies

Install required packages for your development environment:

npm install node-fetch express dotenv

3

Set up webhook server

Create a local Express server to receive callbacks:

webhook.js

import express from 'express';
import dotenv from 'dotenv';

dotenv.config();
const app = express();
app.use(express.json());

app.post('/terminal/callbacks', (req, res) => {
console.log('Event:', req.body?.event, req.body?.data?.status);
console.log('Full payload:', JSON.stringify(req.body, null, 2));
res.sendStatus(200);
});

app.listen(3000, () => {
  console.log('Webhook server running on http://localhost:3000');
  console.log('Use ngrok to expose this server for testing');
});

Use ngrok (npm install -g ngrok && ngrok http 3000) to expose your local server publicly for webhook testing.

2. Choose your testing approach

Simulation Testing (Recommended for getting started)
Physical Terminal Testing

Perfect for merchants waiting on terminal delivery or initial integrationTest payment flows without physical hardware using special test amounts and scenarios.

1

Use any terminal ID

For simulation testing, you can use any terminal_id value. The system will automatically simulate payment responses.

.env

TERMINAL_ID=SIM001  # Any value works for simulation

2

Test different scenarios

Use these special amounts to simulate various payment outcomes:

Amount	Scenario	Expected Result
`400508`	Payment declined	Session created, transaction fails
`400509`	Channel unavailable	Session creation fails
`400711`	User cancellation	Session created, then canceled
`4040404` (as terminal_id)	Invalid terminal	Session creation fails
Any other amount	Success flow	Payment completes successfully

Start with a normal amount like 10000 to test the success flow, then try the special amounts to test error handling.

3

Run simulation test

test-simulation.js

import fetch from 'node-fetch';
import dotenv from 'dotenv';

dotenv.config();

async function testSimulation() {
  const auth = 'Basic ' + Buffer.from(`${process.env.TERMINAL_API_KEY}:`).toString('base64');
  
  // Test successful payment simulation
  const successTest = await fetch(`${process.env.TERMINAL_BASE_URL}/v1/terminal/sessions`, {
    method: 'POST',
    headers: {
      'Authorization': auth,
      'Content-Type': 'application/json',
      'Idempotency-key': `sim-success-${Date.now()}`,
    },
    body: JSON.stringify({
      session_type: 'PAY',
      mode: 'TERMINAL',
      currency: 'IDR',
      amount: 10000, // Normal amount = success
      country: 'ID',
      channel_properties: { terminal_id: 'SIM001' },
    }),
  });
  
  const successData = await successTest.json();
  console.log('✅ Success simulation:', successData.status);
  
  // Test payment decline simulation
  const declineTest = await fetch(`${process.env.TERMINAL_BASE_URL}/v1/terminal/sessions`, {
    method: 'POST',
    headers: {
      'Authorization': auth,
      'Content-Type': 'application/json',
      'Idempotency-key': `sim-decline-${Date.now()}`,
    },
    body: JSON.stringify({
      session_type: 'PAY',
      mode: 'TERMINAL',
      currency: 'IDR',
      amount: 400508, // Special amount = decline
      country: 'ID',
      channel_properties: { terminal_id: 'SIM001' },
    }),
  });
  
  const declineData = await declineTest.json();
  console.log('⚠️ Decline simulation:', declineData.status);
}

testSimulation();

You receive different responses based on the test amounts, simulating real payment scenarios without physical hardware.

Simulation Benefits: Start integration immediately, test error handling, validate webhook flows, and prepare for production - all without waiting for terminal delivery.

For merchants with connected terminal devicesTest with actual hardware for the most realistic payment experience.

1

Verify terminal registration

Ensure your terminal is registered for test mode:

Check that your Terminal H2H shows “Connected” or “Ready” status
Confirm terminal is registered with Xendit (contact support if unsure)
Verify you’re using test mode in Terminal H2H settings

Unregistered terminals will automatically fall back to simulation mode, even if physically connected.

2

Test API connectivity

Make a test request to validate your API key and terminal setup:

test-terminal.js

import fetch from 'node-fetch';
import dotenv from 'dotenv';

dotenv.config();

async function testTerminal() {
  const auth = 'Basic ' + Buffer.from(`${process.env.TERMINAL_API_KEY}:`).toString('base64');
  
  const res = await fetch(`${process.env.TERMINAL_BASE_URL}/v1/terminal/sessions`, {
    method: 'POST',
    headers: {
      'Authorization': auth,
      'Content-Type': 'application/json',
      'Idempotency-key': `test-${Date.now()}`,
    },
    body: JSON.stringify({
      session_type: 'PAY',
      mode: 'TERMINAL',
      currency: 'IDR',
      amount: 1000, // Small test amount
      country: 'ID',
      channel_properties: { terminal_id: process.env.TERMINAL_ID },
    }),
  });
  
  const data = await res.json();
  
  if (res.ok) {
    console.log('✅ Terminal connection successful');
    console.log('Session ID:', data.payment_session_id);
    console.log('Status:', data.status);
  } else {
    console.log('❌ Error:', data.error_code, data.message);
  }
}

testTerminal();

You receive a 200 response with a session ID and the physical terminal prompts for payment.

If you get a TERMINAL_NOT_FOUND error, your terminal may not be registered. Contact Xendit support to register it for test mode.

3

Validate physical interaction

Confirm the terminal responds to the API call:

Terminal display shows payment amount
Card reader is active and ready
Payment can be completed with test card
Webhook callbacks are received

Physical terminal displays payment prompt and accepts card interactions.

3. Create your first payment session

Now create a payment session and process it. Choose the approach that matches your setup:

Simulation Payment
Physical Terminal Payment

Perfect for testing without physical terminals

curl -X POST 'https://terminal-dev.xendit.co/v1/terminal/sessions' \
  -u 'YOUR_TERMINAL_API_KEY:' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-key: sim-success-'"$(date +%s)" \
  -d '{
    "session_type": "PAY",
    "mode": "TERMINAL",
    "currency": "IDR",
    "amount": 10000,
    "country": "ID",
    "channel_properties": { "terminal_id": "SIM001" }
  }'

Success: Session created with ACTIVE status, then automatically transitions to COMPLETED
Decline: Session created with ACTIVE status, then transitions to FAILED

For merchants with connected terminals

curl -X POST 'https://terminal-dev.xendit.co/v1/terminal/sessions' \
  -u 'YOUR_TERMINAL_API_KEY:' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-key: payment-'"$(date +%s)" \
  -d '{
    "session_type": "PAY",
    "mode": "TERMINAL",
    "currency": "IDR",
    "amount": 10000,
    "country": "ID",
    "channel_properties": { "terminal_id": "TERM001" }
  }'

The terminal device prompts for payment. Ask the customer to tap/insert/swipe their card.

If the device doesn’t prompt, verify the terminal is connected in Gateway and the terminal_id matches your device configuration.

4. Monitor callbacks

Your webhook server (started in step 1) will receive real-time payment updates. Monitor the console output to see callback events.

Callback events include terminal_session.completed, terminal_session.canceled, terminal_payment.succeeded, and others. See the Callbacks documentation for complete event types.

5. Verify payment details

Query payment details after receiving a success callback.

curl -X GET 'https://terminal-dev.xendit.co/v1/terminal/payments/PAYMENT_ID' \
  -u 'YOUR_TERMINAL_API_KEY:'

Confirm status is SUCCEEDED and amounts match your session.

6. Optional: Void a payment

If needed, you can void a payment transaction:

curl -X POST 'https://terminal-dev.xendit.co/v1/terminal/payments/PAYMENT_ID/void' \
  -u 'YOUR_TERMINAL_API_KEY:'

Troubleshooting

401 Unauthorized

Ensure you include a trailing colon in the Basic Auth username encoding
Verify the key is a Terminal API key (not Dashboard API key)
Check that you’re using the development base URL for testing

Simulation not working as expected

Verify you’re using the correct special amounts: 400508 (decline), 400509 (channel unavailable), 400711 (cancellation)
Check that you’re in test mode (using development base URL)
Any terminal_id works for simulation - you don’t need a real terminal registered
Normal amounts (not special test amounts) will always succeed in simulation mode

Terminal not prompting (Physical terminals only)

Confirm Terminal H2H shows device as Connected/Ready
Verify terminal_id matches your device configuration exactly
Check network connectivity on the device
Ensure device has correct time settings
For simulation testing: You don’t need a physical terminal - any terminal_id will work

Webhook not receiving callbacks

Use ngrok to expose your local server publicly
Ensure your webhook endpoint returns HTTP 200
Check server logs and firewall settings
Verify the webhook URL is configured correctly
For simulation: Callbacks work the same way as physical terminals

Environment variables not loading

Verify .env file is in the correct location
Check that you’re calling dotenv.config() before using environment variables
Ensure .env file is not committed to version control

Ready to transition from simulation to physical terminal

Install and configure Terminal Gateway app or SDK
Register your physical terminal devices with actual Terminal IDs and IP addresses
Update your environment variables to use real terminal IDs
Test with small amounts on the physical device
All your existing integration code will work without changes!

Next steps

Now that you have a working integration, explore these advanced features:

Terminal API (H2H) Introduction

Complete Terminal API (H2H) documentation and reference

Terminal H2H

Learn about Terminal H2H SDKs for Android and iOS

Payment Callbacks

Handle real-time payment notifications and status updates

Gateway App Configuration

Configure Terminal Gateway app for your devices

Production deployment

When ready for production:

Switch to live API keys - Use production Terminal API key and base URL https://terminal.xendit.co
Update webhook URLs - Configure production webhook endpoints that are publicly accessible
Test thoroughly - Start with small amounts and verify all payment flows work correctly
Monitor and log - Set up proper logging and monitoring for payment events

Always test thoroughly with small amounts in production before processing real customer payments.

Integration type

Integration path

3Get started

Terminal C2C API HTTP REST commands	Terminal C2C SDK Native SDK method calls
Send REST commands (PAY, CANCEL, SETTLEMENT) to the Gateway App over the local network.	Call native Android/iOS SDK methods to talk to terminals directly from your app.
Best for multi-store fleets, web POS, or thick-client systems that call backend services.	Ideal for kiosks, custom POS apps, or deployments that need offline resilience and custom UX.
Works from any language or platform that can make HTTP requests.	Requires mobile engineers but unlocks granular device telemetry and fallback logic.

You’ve chosen the Terminal C2C API — HTTP REST commands sent over the local network.

📖

Terminal C2C API Reference

Complete C2C API documentation and endpoints

Prerequisites

Gateway App installed and configured
Access to C2C API credentials and endpoints
Terminal device details: Terminal ID (TID) and IP address

In C2C API mode, your system communicates with terminals via the Gateway App and REST endpoints. Set up the Gateway App first, then follow the API guide.

Steps

1

Install and configure the Gateway App

Follow the Gateway App setup guide:

Gateway App Setup

2

Confirm terminal device information

Collect the Terminal ID (TID) and IP address for each device you’ll use.

3

Integrate using the C2C API

Implement the REST API integration:

C2C API Reference

Create a payment request

curl -X POST "http://{GATEWAY_IP}:8189/commands/pay" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: CLIENT_API_KEY" \
  -H "provider: BRI" \
  -H "simulation: true" \
  -d '{
    "terminal_id": "10362517",
    "order_id": "ORDER123",
    "request_amount": 10000,
    "payment_method": "QRIS"
  }'

Using simulation: true returns mock responses so you can test without a physical device. Remove the header when exercising real hardware; the value defaults to false.

Successful response

{
  "order_id": "ORDER123",
  "terminal_id": "10362517",
  "terminal_reference": "1750407594445|1750407594",
  "payment_method": "QRIS",
  "amount": 10000,
  "currency": "IDR",
  "transaction_date": "2025-06-20T15:19:54+07:00",
  "status": "SUCCESS"
}

You’re ready to send API requests through the Gateway App to the terminal devices you configured.

Troubleshooting

Gateway App not responding

Confirm the Gateway App is running on the same network segment as your POS.
Check that the device IP and port are reachable (default 8189).
Restart the Gateway App after changing provider credentials or API keys.

401 or 403 errors from C2C API

Verify you are using the Gateway App API key rather than your Dashboard key.
Include the correct provider header (BRI, NTT, CASHUP, or SHC) with each request.
Regenerate the Gateway App credentials if the key rotation recently occurred.

Terminal does not prompt for payment

Ensure the terminal is registered in the Gateway App with the exact terminal ID (TID).
Confirm the device shows Connected/Ready status in the Gateway App UI.
Recheck network connectivity and firewall rules that might block terminal traffic.

Next steps

Terminal C2C API Reference

Dive deeper into payload formats, error codes, and advanced operations.

Gateway App Operations

Learn how to monitor device fleets and rotate credentials safely.

Terminal API (H2H)

Compare with the managed H2H flow if you later need centralized orchestration.

Production deployment

Switch the Gateway App to production mode and provision production API keys.
Whitelist production terminal IPs and ensure secure TLS termination on your POS.
Run end-to-end tests with small live amounts before opening to staff.
Set up monitoring for Gateway App health, API latency, and payment callbacks.

You’ve chosen the Terminal C2C SDK — native Android/iOS method calls for direct terminal communication.

🤖

Android C2C SDK

Complete Android C2C SDK integration guide

🍎

iOS C2C SDK

Complete iOS C2C SDK integration guide

Prerequisites

Terminal C2C SDK added to your app (Android or iOS)
Network connectivity to the terminal devices
Terminal device details: Terminal ID (TID) and IP address

In C2C SDK mode, your app talks directly to the terminal devices using platform SDKs (no Gateway App required).

Steps

1

Add provider dependencies

Include the provider-specific artifacts before initializing the SDK. Select the providers above to populate the correct entries.

Android (Gradle)
iOS (Frameworks)

dependencies {
  // Terminal C2C SDK
  implementation("co.xendit.terminal:c2c-android:<latest_version>")

  // Core Terminal SDK (required)
  implementation("co.xendit.terminal:core-android:<latest_version>")

  implementation("co.xendit.terminal:id-bri-android:<latest_version>")
}

# Add these provider frameworks using Xcode (General > Frameworks, Libraries, and Embedded Content).
# See /sdk/c2c/ios-sdk#installation for installation steps.

- Add TerminalBRI.xcframework via Xcode (General > Frameworks, Libraries, and Embedded Content). Follow /sdk/c2c/ios-sdk#installation.

2

Install and set up the C2C SDK

Android (Kotlin)
iOS (Swift)

import co.xendit.terminal.c2c.TerminalC2C
import co.xendit.terminal.core.TerminalApp

class App : Application() {
  override fun onCreate() {
    super.onCreate()

    TerminalApp.initialize(
      context = this,
      clientKey = CLIENT_KEY,
      mode = TerminalMode.LIVE // or TerminalMode.INTEGRATION
    )
    TerminalC2C.addProvider(TerminalBRI)
  }
}

import TerminalC2C

func application(
  _ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
  TerminalApp.shared.initialize(
    clientKey: CLIENT_KEY,
    mode: TerminalMode.live // or TerminalMode.integration
  )
  TerminalC2C.shared.addProvider(provider: TerminalBRI.shared)
  return true
}

3

Configure the terminal device in your app

Configure each device using its Terminal ID (TID) and IP address.

Android (Kotlin)
iOS (Swift)

val terminalDevice = TerminalDevice.create(
  id = "TID001",
  ipAddress = "192.168.1.100",
  provider = "BRI"
)

TerminalC2C.setTerminalDevice(terminalDevice)

let terminalDevice = TerminalDevice.companion.create(
  id: "TID001",
  ipAddress: "192.168.1.100",
  provider: "BRI"
)

TerminalC2C.shared.setTerminalDevice(terminalDevice)

4

Run a test transaction

Use the SDK “Getting Started” steps for your platform to trigger a basic flow and confirm the device responds correctly.

Android (Kotlin)
iOS (Swift)

import co.xendit.terminal.c2c.TerminalC2C
import co.xendit.terminal.c2c.data.Payment
import co.xendit.terminal.c2c.data.TerminalException
import co.xendit.terminal.id.bri.BRIPaymentMethod // Provided by the BRI provider dependency

// Create payment data
val payment = Payment(
  orderID = "ORDER_123",
  amount = 10000.0,
  paymentMethod = BRIPaymentMethod.contactless
)

// Execute payment (suspend function)
try {
  val result = TerminalC2C.createPayment(
    payment = payment,
    isSimulation = true // Remove or set to false when using a physical terminal
  )
  println("Payment successful: ${'$'}{result.status}")
} catch (e: TerminalException) {
  println("Payment failed: ${'$'}{e.message}")
} catch (e: Exception) {
  println("Error: ${'$'}{e.message}")
}

import TerminalC2C

// Create payment data
let payment = Payment(
  orderID: "ORDER_123",
  amount: 10000.0,
  paymentMethod: BRIPaymentMethod.contactless
)

// Execute payment
Task {
  do {
    let result = try await TerminalC2C.shared.createPayment(
      payment: payment,
      isSimulation: true // Remove or set to false when using a physical terminal
    )
    print("Payment successful: \(result.status)")
  } catch let error as TerminalException {
    print("Payment failed: \(error.message)")
  } catch {
    print("Error: \(error.localizedDescription)")
  }
}

For SDK testing without hardware, either set TerminalC2C.isSimulation = true globally before issuing requests or pass isSimulation = true to individual calls as shown above. Remove these simulation flags for real terminal runs.

If your test succeeds, your app is ready to communicate with the terminal using the C2C SDK.

Troubleshooting

SDK initialization fails

Confirm the Client Key matches the environment (sandbox vs production).
Initialize the SDK during application start before invoking any payment calls.
Add required permissions (BLE, network) to your AndroidManifest or Info.plist.

Terminal remains offline

Check that the terminal device IP is reachable from the mobile device.
Verify the provider SDK (BRI, NTT, Cashup, SHC) is registered before setting the device.
Recreate the terminal pairing if the device was rebooted or network changed.

Payment command returns errors

Inspect the SDK error object for provider-specific codes and retry guidance.
Ensure amount, currency, and payment method align with the provider’s supported values.
For persistent failures, fall back to the Terminal C2C API mode and compare payloads.

Next steps

Android SDK Deep Dive

Explore lifecycle hooks, receipt printing, and advanced device management.

iOS SDK Deep Dive

Review concurrency patterns, error domains, and background execution rules.

Migration Guidance

Plan future transitions between C2C and H2H solutions.

Production deployment

Embed secure storage for client keys and rotate them on schedule.
Enable crash and telemetry reporting for SDK interactions and payment outcomes.
Run pilot stores with real terminals before rolling out widely.
Document recovery flows so field teams can re-pair or reset devices quickly.

Getting started

Migration

​Choose how you want to accept payments

​Device-Only Setup

​Choose your integration path

​Host-to-Host (H2H) — Terminal API

​Client-to-Client (C2C)

​Select your payment provider(s)

​🇮🇩 Indonesia

​🇹🇭 Thailand

​🇲🇾 Malaysia

​🇻🇳 Vietnam

​Prerequisites

​For Physical Terminal Testing

​For Simulation Testing (No Terminal Required)

​1. Configure your environment

​2. Choose your testing approach

​3. Create your first payment session

​4. Monitor callbacks

​5. Verify payment details

​6. Optional: Void a payment

​Troubleshooting

​Next steps

Terminal API (H2H) Introduction

Terminal H2H

Payment Callbacks

Gateway App Configuration

​Production deployment

​Choose your C2C interface

​Prerequisites

​Steps

​Troubleshooting

​Next steps

Terminal C2C API Reference

Gateway App Operations

Terminal API (H2H)

​Production deployment

​Prerequisites

​Steps

​Troubleshooting

​Next steps

Android SDK Deep Dive

iOS SDK Deep Dive

Migration Guidance

​Production deployment

Choose how you want to accept payments

Device-Only Setup

Choose your integration path

Host-to-Host (H2H) — Terminal API

Client-to-Client (C2C)

Select your payment provider(s)

🇮🇩 Indonesia

🇹🇭 Thailand

🇲🇾 Malaysia

🇻🇳 Vietnam

Prerequisites

For Physical Terminal Testing

For Simulation Testing (No Terminal Required)

1. Configure your environment

2. Choose your testing approach

3. Create your first payment session

4. Monitor callbacks

5. Verify payment details

6. Optional: Void a payment

Troubleshooting

Next steps

Production deployment

Choose your C2C interface

Prerequisites

Steps

Troubleshooting

Next steps

Production deployment

Prerequisites

Steps

Troubleshooting

Next steps

Production deployment