Skip to main content
POST
/
v1
/
terminals
/
{terminalId}
/
payments
curl --request POST \
  --url https://your-endpoint.moduluslabs.io/v1/terminals/{terminalId}/payments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "transactionId": "TXN-20240115-001",
  "amount": "99.99",
  "currency": "USD",
  "paymentMethod": "CARD",
  "products": [
    {
      "id": "PROD-001",
      "name": "Widget",
      "price": "99.99",
      "quantity": 1
    }
  ],
  "customerInfo": {
    "customerId": "CUST-123",
    "email": "customer@example.com"
  },
  "metadata": {
    "orderId": "ORD-12345"
  }
}
'
{
  "transactionId": "TXN-20240115-001",
  "status": "SUCCESS",
  "paymentResponse": {
    "transactionId": "TXN-20240115-001",
    "status": "SUCCESS",
    "amount": "99.99",
    "currency": "USD",
    "paymentMethod": "CARD",
    "authorizationCode": "AUTH123456",
    "receiptData": "...",
    "timestamp": "2024-01-15T10:37:30.000Z"
  },
  "timestamp": "2024-01-15T10:37:30.000Z"
}
This endpoint requires HMAC-SHA256 authentication. See Authentication for signature computation details.

​
Long-Polling Behavior

This endpoint uses long-polling and waits up to 90 seconds for the terminal to respond. Plan for this timeout in your HTTP client configuration.

​
Terminal ID Resolution

The terminalId parameter is resolved in the following order:
  1. Device ID (Recommended) - First checks if the ID matches a registered deviceId
  2. Connection ID (Fallback) - If no device ID match, treats it as a connectionId
Always use deviceId when available. It provides a stable reference that doesn’t change when terminals reconnect.

​
Handling Timeouts

If you receive a 504 Gateway Timeout response:
  1. Do not retry the payment immediately
  2. Use Get Transaction to check if the payment completed
  3. Only retry if the transaction status is FAILED or CANCELLED
The payment may have completed on the terminal after the HTTP timeout. Always verify transaction status before retrying to avoid duplicate charges.

Authorizations

​
x-api-key
string
header
required

HMAC-SHA256 authentication. Requires three headers: x-api-key (your API key), x-timestamp (ISO 8601 timestamp), and x-signature (Base64-encoded HMAC-SHA256 signature). See Authentication documentation for signature computation.

Path Parameters

​
terminalId
string
required

The terminal identifier. Can be either a deviceId (recommended) or connectionId (legacy fallback).

Body

application/json

Payment request details

​
amount
required

Payment amount

​
currency
string
required

ISO 4217 currency code (e.g., USD, EUR, PHP)

​
paymentMethod
enum<string>
required

Payment method

Available options:
CARD,
CASH,
MOBILE,
OTHER
​
transactionId
string

Unique transaction identifier. Auto-generated if not provided.

​
webhookMode
boolean
default:false

When true, disables 90-second long-polling and returns 202 Accepted immediately. Payment result will be delivered via webhook. Requires at least one webhook endpoint configured.

​
products
object[]

Array of products in the transaction

​
customerInfo
object
​
metadata
object

Custom key-value pairs for your use

Response

Payment completed successfully (standard mode)

​
transactionId
string
required

Transaction identifier

​
status
enum<string>
required

Payment result status

Available options:
SUCCESS,
FAILED,
PENDING,
CANCELLED
​
timestamp
string<date-time>
required

ISO 8601 timestamp

​
paymentResponse
object