curl -X POST "https://api.mainmoney.net/api/v2/developers/v1/terminal-payments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"terminalId":"POS-ABC123-001","businessId":"biz_...","amount":1.03,"currencyCode":"USD","merchantReference":"crm-order-1001","metadata":{"table":"12"},"expiresInSeconds":300}'

Create a terminal payment

POST /developers/v1/terminal-payments

OAuth and merchant discovery are covered in the quickstart. This page is request/response only.

Request body

Field	Required	Description
terminalId	yes	Human terminal code (POS-…) from GET /terminals
amount	yes	Positive number (major units)
currencyCode	yes	ISO currency supported by the business
merchantReference	yes	1–128 chars [A-Za-z0-9._-], unique per app
metadata	no	JSON object echoed in webhooks
businessId	group apps	Required when the developer app belongs to a GROUP
expiresInSeconds	no	60–3600 (default 300)

Response

{
  "id": "clx...",
  "status": "PENDING",
  "terminalId": "POS-ABC123-001",
  "businessId": "...",
  "amount": 1.03,
  "currencyCode": "USD",
  "merchantReference": "crm-order-1001",
  "metadata": { "table": "12" },
  "expiresAt": "2026-07-27T10:16:00.000Z"
}

Statuses

PENDING → IN_PROGRESS → COMPLETED | FAILED | CANCELLED | EXPIRED

Cancel

POST /developers/v1/terminal-payments/:id/cancel — only while status is PENDING.

Errors (stable errorCode)

Code	Meaning
TERMINAL_NOT_FOUND	Unknown / inactive terminal for that business
BUSINESS_ID_REQUIRED	Group app missing businessId
BUSINESS_OUT_OF_SCOPE	Business not in app scope
MERCHANT_REFERENCE_CONFLICT	Reference already used
INVALID_MERCHANT_REFERENCE	Bad reference format
TERMINAL_PAYMENT_NOT_CANCELLABLE	Not PENDING

Related

• GET /developers/v1/terminal-payments/:id
• GET /developers/v1/terminal-payments?merchantReference=...
• POST /developers/v1/terminal-payments/:id/simulate-complete (sandbox)
• Webhooks