Creating a payment

POST /api/connect/v1/payments

7.1 Required fields

Field	Type	Rule
`amount`	number	Minimum 0.01. Decimal units, not cents (150.50 = L 150.50). No maximum enforced by the API.
`external_reference`	string	Your order id. Max 191. Not unique (see 11).
`name`	string	Label the customer sees at checkout. Max 191.

7.2 Optional fields

Field	Type	Notes
`currency_code`	string	ISO 4217 numeric (`"340"` = HNL). Defaults to the terminal's currency. Only currencies enabled on that terminal are accepted.
`description`	string	Max 120.
`metadata`	object	Your own key/value pairs. Must be an object: a string returns 422. See 10.
`success_url` / `cancel_url`	string	Return URLs. Use HTTPS (see 12.4).
`expires_at`	string	Honduras time (UTC-6), must be in the future. Accepts `YYYY-MM-DD HH:MM:SS` and ISO 8601.
`sales_tax_type`	enum	`none` (default), `fixed`, `percentage`.
`sales_tax_value`	number	Required when the type is not `none`. As a percentage, max 100.
`tip_enabled`	boolean	See 8.2.
`service_fee_enabled`	boolean	See 8.3.
`reusable`	boolean	See 8.4.
`customer`	object	Prefills the checkout: `name`, `email`, `phone`, `identity_number`. See 7.5.
`lock_customer_fields`	boolean	Makes the prefilled fields read-only. See 7.5.

7.3 Minimal example

{
  "amount": 150.00,
  "external_reference": "order-1001",
  "name": "Order #1001"
}

7.4 Response (201)

{
  "id": 706,
  "status": "pending",
  "name": "Order #1001",
  "description": null,
  "amount": 150,
  "reusable": false,
  "subtotal": 150,
  "sales_tax_amount": 0,
  "service_fee_amount": 0,
  "total": 150,
  "currency": "340",
  "currency_iso": "HNL",
  "external_reference": "order-1001",
  "metadata": {},
  "checkout_url": "https://aura.roki.systems/pay/link/example1a2b3c",
  "transaction_id": null,
  "expires_at": "2026-08-09 18:00:00",
  "created_at": "2026-08-08 14:30:07",
  "paid_at": null
}

Store id in your database - it is the direct handle on the payment. GET /payments can also filter by external_reference (9.2), but that answers with a page of matches, not one payment, because external_reference is not unique. Then redirect the customer to checkout_url.

Two notes on that response. transaction_id is null until the payment is charged, and it is a UUID string - it changed type from an integer in an earlier version, and it is the identifier required by void, refund and receipts. And the checkout_url slug is a 12-character lowercase string: it carries no prefix, so never pattern-match a slug - redirect to the exact URL you were given.

7.5 Prefilling the customer

The optional customer object prefills the hosted checkout with a known customer's details. Every field inside it is optional and independent:

{
  "customer": {
    "name": "Ahmed Khan",
    "email": "ahmed@example.com",
    "phone": "+50499999999",
    "identity_number": "0801199000000"
  },
  "lock_customer_fields": true
}

By default prefilled fields stay editable. With lock_customer_fields: true, every field you send with a non-empty value becomes read-only at checkout; fields you omit stay blank and editable even then.

identity_number is worth sending: it is also the preferred identifier for looking up that customer's saved cards later (see section 23).

Both fields are echoed back in the response, which matters more than it sounds: because this API ignores unknown fields rather than rejecting them, the echoed customer object is how you confirm from the response that the prefill actually applied. Check it - together with warnings (12.1) - rather than assuming the 201 means it worked.

"customer": { "name": "Ahmed Khan", "email": "ahmed@example.com",
              "phone": "+50499999999", "identity_number": "0801199000000" },
"lock_customer_fields": true