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 only way to look the payment up again (there is no search by external_reference). 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 silently ignores unknown fields, the echoed customer object is your only way to confirm from the response that the prefill actually applied. Check it 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