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.
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 Gateway: 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' \
  -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.

​
Terminal Gateway Setup

The Terminal Gateway is required to manage your terminal devices:
  • Desktop App
  • Mobile SDK
Available Platforms: Windows, macOSDownload and install the Terminal Gateway desktop application:
  1. Download the app from the Xendit dashboard
  2. Install and launch the application
  3. Configure your terminal devices
  4. Connect to the Xendit network
Verify the app shows “Connected” status before processing payments.

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