Skip to main content

​
Overview

The Terminal API enables you to process in-person payments using Xendit’s terminal devices. This API provides comprehensive functionality for creating payment sessions, managing terminal operations, and handling real-time payment callbacks.
BRI / NTT pre-install required: For BRI and NTT terminals, install the Terminal Gateway App or the Terminal H2H SDK on your local device before using the Terminal API. Other providers (Cashup, SHC, Atom) connect directly — no pre-install needed.
New to Terminal API? Start with our quickstart guide to get your first terminal payment processed in under 10 minutes.

​
Key Features

The Terminal API provides these core capabilities:
  • Payment Session Management: Create and manage payment sessions for terminal transactions
  • Terminal Operations: Push commands to terminal devices for various operations
  • Real-time Callbacks: Receive instant notifications for payment events and status changes
  • Error Handling: Comprehensive error management for different payment scenarios
  • Multi-device Support: Manage multiple terminal devices from a single integration

​
Prerequisites

​
Essential Requirements

  • Xendit Account: Active account with Terminal API access
  • API Credentials: In-Person Payment API key from Xendit team

​
For Physical Terminal Integration

  • Terminal H2H: App or SDK installed on your terminal devices
  • Network Access: Terminal devices must have internet connectivity

​
For Simulation Testing (No Terminal Required)

  • Nothing else needed! Start integrating immediately using simulation mode
Don’t have a physical terminal yet? Perfect! You can begin integration right away using our simulation capabilities. Test payment flows, error handling, and webhook integrations without waiting for terminal delivery. All you need is your API key.

​
API Endpoints

Choose the appropriate endpoint for your environment:

Development

Base URL: https://terminal-dev.xendit.co Use this endpoint for testing and development with sandbox data.

Production

Base URL: https://terminal.xendit.co Use this endpoint for live transactions and production use.

​
Authentication

The Terminal API uses HTTP Basic Authentication for all requests:
  • Username: Your Terminal API key
  • Password: Empty string (leave blank)
cURL
curl -X POST 'https://terminal-dev.xendit.co/v1/terminal/sessions' \
  -u 'your_terminal_api_key:' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-key: unique-key-123' \
  -H 'for-user-id: SUB_ACCOUNT_USER_ID' \
  -H 'with-split-rule: SPLIT_RULE_ID' \
  -d '{
    "session_type": "PAY",
    "mode": "TERMINAL",
    "currency": "IDR",
    "amount": 10000,
    "country": "ID",
    "channel_properties": {
      "terminal_id": "TERM001"
    }
  }'
Critical: Always include the colon (:) after your API key when encoding for Basic Authentication, even though the password is empty.

​
Optional Headers (xenPlatform)

If you have access to xenPlatform, you can include these optional headers on the Create Terminal Payment Session request:
HeaderTypeDescription
for-user-idstringThe sub-account user-id to make this transaction for. See xenPlatform for more information.
with-split-rulestringThe XenPlatform split rule ID that will be applied to this transaction.

​
Device connectivity

For BRI and NTT terminals, your device needs the Terminal Gateway App or Terminal H2H SDK installed to relay commands between the Terminal API and the physical terminal hardware. Choose the option that fits your deployment:
  • Terminal Gateway App — A ready-to-use companion application for Windows, macOS, or Android. Minimal development effort.
  • Terminal H2H SDK — Embed device connectivity inside your own Android or iOS application. Tighter UX but requires mobile engineering.
Other providers (Cashup, SHC, Atom) connect directly to the Terminal API without any pre-install.

​
API Reference

Explore the complete Terminal API documentation:

Create Payment Session

Create new payment sessions for terminal transactions.

Get Payment Session

Retrieve payment session details and status information.

Retry Payment Session

Retry payment session on terminal devices.

Get Payment Detail

Retrieve payment transaction details and status.

Void Payment

Cancel or void payment transactions when needed.

Push Operation Command

Send operational commands to terminal devices.

Payment Callbacks

Handle real-time payment notifications and status updates.

Error Handling

Understand error codes and troubleshooting common issues.

​
OpenAPI Specification

Download the complete OpenAPI 3.0 specification for integration with your development tools and API clients. The specification is available in YAML format and can be imported into tools like Postman, Insomnia, or any OpenAPI-compatible client.

Download YAML

Download the complete OpenAPI 3.0 specification in YAML format

View in Browser

View the api directly in your browser
Integration Tips: - Import the YAML file into Postman or Insomnia for easy API testing - Use the specification to generate client SDKs in your preferred language - The spec includes all endpoints, request/response schemas, and authentication details

​
Changelog

​
Version 0.4.2
Released December 5, 2025

​
New Features

  • Added API endpoint for retrying payment sessions on terminal devices

​
API Endpoints

  • POST /v1/terminal/sessions/{id}/retry - Retry payment sessions
​
Version 0.4.1
Released August 26, 2025

​
New Features

  • Added comprehensive testing guide for real terminal devices
  • Enhanced error handling and debugging capabilities

​
Improvements

  • Updated API documentation with more detailed examples
  • Improved error messages for better developer experience
​
Version 0.4.0
Released June 2, 2025

​
New Features

  • Payment Session Management: Create and retrieve payment session details
  • Terminal Operations: Push operation commands to terminal devices
  • Real-time Callbacks: Receive instant payment notifications
  • Multi-device Support: Manage multiple terminals from single integration

​
API Endpoints

  • POST /v1/terminal/sessions - Create payment sessions
  • GET /v1/terminal/sessions/{id} - Get session details
  • GET /v1/terminal/payments/{id} - Get payment details (authenticated)
  • GET /public/v1/terminal/payments/{id} - Get payment details (public)
  • POST /v1/terminal/payments/{id}/void - Void payment transactions
  • POST /v1/terminal/commands - Push terminal commands

​
Need Help?

Contact Support

Get personalized assistance from our Terminal API support team for integration questions or technical issues.