Quickstart

Prerequisites

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

For Physical Terminal Testing

Terminal Gateway set up (desktop app or Android/iOS SDK)
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 our simulation capabilities. Use special test amounts and terminal IDs to simulate different payment scenarios without needing 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.

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.

Install dependencies

Install required packages for your development environment:

npm install node-fetch express dotenv

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?.type, 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.

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

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.

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.

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

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 PAYMENT_CREATED, PAYMENT_SUCCEEDED, PAYMENT_FAILED, 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 Gateway 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 Introduction

Complete Terminal API documentation and reference

Terminal Gateway

Learn about Terminal Gateway 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.

Getting started

Migration

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 Introduction

Terminal Gateway

Payment Callbacks

Gateway App Configuration

Production deployment

Getting started

Migration

​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 Introduction

Terminal Gateway

Payment Callbacks

Gateway App Configuration

​Production deployment

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