> ## Documentation Index
> Fetch the complete documentation index at: https://terminal-docs.xendit.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Complete API reference for in-person payment processing using Xendit Payment Terminal devices

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

<Warning>
  **BRI / NTT pre-install required**: For BRI and NTT terminals, install the [Terminal Gateway App](/sdk/gateway/app-configuration) or the [Terminal H2H SDK](/sdk/h2h/introduction) on your local device before using the Terminal API. Other providers (Cashup, SHC, Atom) connect directly — no pre-install needed.
</Warning>

<Info>
  **New to Terminal API?** Start with our [quickstart guide](/guides/getting-started/quickstart) to get
  your first terminal payment processed in under 10 minutes.
</Info>

## 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

<Info>
  **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.
</Info>

## API Endpoints

Choose the appropriate endpoint for your environment:

<CardGroup cols={2}>
  <Card title="Development" icon="code">
    **Base URL**: `https://terminal-dev.xendit.co` Use this endpoint for testing
    and development with sandbox data.
  </Card>

  <Card title="Production" icon="globe">
    **Base URL**: `https://terminal.xendit.co` Use this endpoint for live
    transactions and production use.
  </Card>
</CardGroup>

## Authentication

The Terminal API uses HTTP Basic Authentication for all requests:

* **Username**: Your Terminal API key
* **Password**: Empty string (leave blank)

```bash cURL theme={null}
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"
    }
  }'
```

<Warning>
  **Critical**: Always include the colon (`:`) after your API key when encoding
  for Basic Authentication, even though the password is empty.
</Warning>

## Optional Headers (xenPlatform)

If you have access to **xenPlatform**, you can include these optional headers on the Create Terminal Payment Session request:

| Header            | Type   | Description                                                                                                                                     |
| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `for-user-id`     | string | The sub-account user-id to make this transaction for. See [xenPlatform](https://docs.xendit.co/docs/xenplatform-overview) for more information. |
| `with-split-rule` | string | The 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](/sdk/gateway/app-configuration)** — A ready-to-use companion application for Windows, macOS, or Android. Minimal development effort.
* **[Terminal H2H SDK](/sdk/h2h/introduction)** — 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:

<CardGroup cols={2}>
  <Card title="Create Payment Session" icon="plus" href="/api-reference/payments-terminal-api/create-a-terminal-payment-session">
    Create new payment sessions for terminal transactions.
  </Card>

  <Card title="Get Payment Session" icon="magnifying-glass" href="/api-reference/payments-terminal-api/fetch-terminal-payment-session">
    Retrieve payment session details and status information.
  </Card>

  <Card title="Retry Payment Session" icon="arrow-rotate-right" href="/api-reference/payments-terminal-api/retry-terminal-payment-session">
    Retry payment session on terminal devices.
  </Card>

  <Card title="Get Payment Detail" icon="receipt" href="/api-reference/payments-terminal-api/get-terminal-payment-detail">
    Retrieve payment transaction details and status.
  </Card>

  <Card title="Void Payment" icon="x" href="/api-reference/payments-terminal-api/void-a-terminal-payment">
    Cancel or void payment transactions when needed.
  </Card>

  <Card title="Push Operation Command" icon="arrow-right" href="/api-reference/payments-terminal-api/create-terminal-commands">
    Send operational commands to terminal devices.
  </Card>

  <Card title="Payment Callbacks" icon="webhook" href="/api-reference/terminal-api/callbacks">
    Handle real-time payment notifications and status updates.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/terminal-api/errors">
    Understand error codes and troubleshooting common issues.
  </Card>
</CardGroup>

## OpenAPI Specification

<Note>
  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.
</Note>

<CardGroup cols={2}>
  <Card title="Download YAML" icon="file-code" href="/openapi-spec.yaml" download="xendit-terminal-api-spec.yaml">
    Download the complete OpenAPI 3.0 specification in YAML format
  </Card>

  <Card title="View in Browser" icon="terminal" href="/api-reference/payments-terminal-api/create-a-terminal-payment-session">
    View the api directly in your browser
  </Card>
</CardGroup>

<Tip>
  **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
</Tip>

## Changelog

<Update label="Version 0.5.1" description="Released April 8, 2026">
  ## New Features

  * Added API endpoint for listing terminal payment sessions with cursor-based pagination

  ## API Endpoints

  * `GET /v1/terminal/sessions` - List payment sessions by reference ID with cursor pagination
</Update>

<Update label="Version 0.5.0" description="Released March 17, 2026">
  ## New Features

  * Added Malaysia (`MY` / `MYR`) as a supported market
  * Added Malaysia payment methods: `MY_QR`, `MY_CARD`, `MY_EWALLET`
</Update>

<Update label="Version 0.4.3" description="Released February 10, 2026">
  ## Improvements

  * Added `REVERSED` payment status for reversed transactions
  * Added `QUERY` command type for terminal operations
</Update>

<Update label="Version 0.4.2" description="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
</Update>

<Update label="Version 0.4.1" description="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
</Update>

<Update label="Version 0.4.0" description="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
</Update>

## Need Help?

<Card title="Contact Support" icon="envelope" href="mailto:inpersonpayments@xendit.co">
  Get personalized assistance from our Terminal API support team for integration
  questions or technical issues.
</Card>