API reference

13 operations. This page is generated from the OpenAPI specification, so it cannot describe a contract the API no longer has.

Base: https://aura.roki.systems/api/connect/v1. The environment is decided by the key prefix: sk_test_ is sandbox and sk_live_ is production, over identical routes.

GET/meWhich merchant does this key belong to

Responses

Code	Means
`200`	The merchant this key belongs to.
`401`	The `Authorization` header is missing or the key is invalid.

GET/paymentsList payments

Parameters

Name	In	Required	Description
`per_page`	query	no	Page size. Defaults to 20. Note `limit` is ignored - only `per_page` changes the page size.
`page`	query	no	1-based page number. Use `meta.last_page` to know when to stop.
`status`	query	no	Filter by payment status. An unrecognized value returns `422` rather than being ignored.
`external_reference`	query	no	Filter by your own order id. Since `external_reference` is not unique, this can return more than one payment.
`from`	query	no	Start of a creation-date range, `YYYY-MM-DD`, Honduras time.
`to`	query	no	End of the creation-date range, inclusive.

Responses

Code	Means
`200`	A page of payments, newest first.
`401`	The `Authorization` header is missing or the key is invalid.
`422`	An invalid filter value, for example an unknown `status`.

POST/paymentsCreate a payment

Body

Field	Type	Required	Notes
`amount`	number	yes	The exact total to charge in this checkout, in decimal units (150.50 = L 150.50), not cents. Take it from the invoice or cart in your backend. The API enforces no maximum and accepts numeric strings; enforce a sane ceiling on your side.
`external_reference`	string	yes	Your order id. Not unique - duplicate protection comes from `Idempotency-Key`.
`name`	string	yes	Payment label shown to the customer at checkout.
`currency_code`	string	no	ISO 4217 numeric code (`"340"` = HNL). Defaults to the terminal's currency. Only currencies enabled on that terminal are accepted.
`description`	string	no
`metadata`	object	no	Merchant-defined key/value pairs, returned untouched on retrieval and in every webhook. Not shown to the customer.
`success_url`	string	no	Return URL after payment. Landing there does not confirm payment. The API accepts `http://` although the docs require HTTPS; always use HTTPS.
`cancel_url`	string	no
`expires_at`	string	no	Link expiry in Honduras time (UTC-6), must be in the future. Accepts `YYYY-MM-DD HH:MM:SS` and ISO 8601.
`customer`	any	no
`lock_customer_fields`	boolean	no	When `true`, every prefilled field that carries a non-empty value becomes read-only at checkout. Customer fields you do not send stay blank and remain editable even when this is `true`. Verified caveat: accepted with `201` but not echoed in the response, so a success code alone does not prove the prefill was applied. Confirm by opening the checkout.
`reusable`	boolean	no	`false` (default) makes the payment single-use: it is consumed after an approved charge. `true` keeps the link payable until it expires or is disabled - recommended for mode 2 remounts. With `true`, creating again with the same `external_reference`, or the same customer email/identity plus amount and currency, may return the existing payment id while it is still payable.
`sales_tax_type`	string	no	Tax mode. If not `none`, `sales_tax_value` is required. Computed on the subtotal only.
`sales_tax_value`	number	no	Fixed amount or percentage. As a percentage it cannot exceed 100.
`tip_enabled`	boolean	no	When `true`, define exactly one mode: a fixed tip (`tip_type` + `tip_value`) or customer selection (`tip_customer_selectable: true`). Omitting both returns `422`.
`tip_type`	string	no
`tip_value`	number	no
`tip_customer_selectable`	boolean	no	The customer picks the tip at checkout, so the total at creation excludes it.
`tip_preset_percentages`	array	no
`tip_allow_custom`	boolean	no
`tip_min_amount`	number	no	Cannot exceed `amount`.
`tip_max_amount`	number	no	Cannot exceed `amount` - a larger value returns `422` ("Tip limits cannot be greater than the plan amount.").
`service_fee_enabled`	boolean	no	Per-request switch. `true` passes ROKI's processing costs to the customer: the checkout total is increased by reverse calculation so the merchant nets the original `amount`. Omitted or `false` means no service fee. Do not replicate the calculation. Rates, the fixed 3-D Secure charge and the threshold are per-merchant configuration. Read `service_fee_amount` and `total` from the response. Exact field name: `service_fee_enabled`. Variants such as `service_fee` or `pass_fees_to_customer` are silently ignored and produce a payment with no fee.

Responses

Code	Means
`201`	Payment created.
`401`	The `Authorization` header is missing or the key is invalid.
`422`	Validation failed or a business rule was violated: required field, length, type, currency not enabled on the terminal, tip above the amount, tax percentage above 100, expiry in the past, or a missing mandatory `Idempotency-Key` on the charge endpoints.

GET/payments/{id}Retrieve a payment

Parameters

Name	In	Required	Description
`id`	path	yes	Numeric payment identifier returned at creation.

Responses

Code	Means
`200`	Payment found.
`401`	The `Authorization` header is missing or the key is invalid.
`404`	`code: "payment_not_found"` - no payment with that id exists for the key in use, often an id from the other environment. Three different failures share HTTP 404 here; tell them apart by `code`, never by the message, which is localised: - `payment_not_found` - well-formed identifier, no such record. - `transaction_id_expected` - a transaction route was given the numeric payment id. - `not_found` - the path is not in the router at all. This one, and only this one, carries the raw framework prose `"The route ... could not be found."` and stays in English.

POST/payments/{transaction_id}/voidVoid a transaction

Parameters

Name	In	Required	Description
`transaction_id`	path	yes	The transaction UUID from the payment response - not the numeric payment `id`. Passing a numeric payment id returns 404 with `code: "transaction_id_expected"` and a message naming the identifier it wanted. The endpoint exists and answered; only the kind of identifier was wrong. This used to be a routing 404 (`"The route ... could not be found."`). It is not any more, verified 2026-08-21. Client code that classifies this error by matching the message text for `"could not be found"` now files it under "no such payment" and sends the developer hunting for a bad id instead of a bad identifier type. Branch on `code`.

Body

Field	Type	Required	Notes
`reason`	string	no	Optional free-text reason, stored with the void.

Responses

Code	Means
`200`	Transaction voided.
`401`	The `Authorization` header is missing or the key is invalid.
`404`	`code: "payment_not_found"` - transaction not found, or not owned by this merchant. If you instead get `code: "transaction_id_expected"`, you passed the numeric payment id where a transaction UUID is required. That is a live endpoint rejecting the identifier, not a missing route. Until 2026-08-21 this case answered the routing 404 instead, so older integrations that switch on `"could not be found"` now misfile it as "no such payment".
`422`	Not voidable. `errors.void` carries the reason: already voided, already refunded (use refund), not in a voidable state, or already settled (use refund).

POST/payments/{transaction_id}/refundRefund a transaction

Parameters

Name	In	Required	Description
`transaction_id`	path	yes	The transaction UUID from the payment response - not the numeric payment `id`. Passing a numeric payment id returns 404 with `code: "transaction_id_expected"` and a message naming the identifier it wanted. The endpoint exists and answered; only the kind of identifier was wrong. This used to be a routing 404 (`"The route ... could not be found."`). It is not any more, verified 2026-08-21. Client code that classifies this error by matching the message text for `"could not be found"` now files it under "no such payment" and sends the developer hunting for a bad id instead of a bad identifier type. Branch on `code`.

Body

Field	Type	Required	Notes
`amount`	number	yes	Amount to refund, up to the remaining refundable amount.
`reason`	string	no

Responses

Code	Means
`200`	Refund applied.
`401`	The `Authorization` header is missing or the key is invalid.
`404`	`code: "payment_not_found"` - transaction not found, or not owned by this merchant. If you instead get `code: "transaction_id_expected"`, you passed the numeric payment id where a transaction UUID is required. That is a live endpoint rejecting the identifier, not a missing route. Until 2026-08-21 this case answered the routing 404 instead, so older integrations that switch on `"could not be found"` now misfile it as "no such payment".
`422`	Rejected. `errors.amount`: below 0.01, or above the remaining refundable amount. `errors.refund`: transaction is voided (a voided transaction cannot be refunded), not in a refundable state, or a processor rejection such as `"Invalid transaction"`.

GET/payments/{transaction_id}/receiptGet receipt metadata

Parameters

Name	In	Required	Description
`transaction_id`	path	yes	The transaction UUID from the payment response - not the numeric payment `id`. Passing a numeric payment id returns 404 with `code: "transaction_id_expected"` and a message naming the identifier it wanted. The endpoint exists and answered; only the kind of identifier was wrong. This used to be a routing 404 (`"The route ... could not be found."`). It is not any more, verified 2026-08-21. Client code that classifies this error by matching the message text for `"could not be found"` now files it under "no such payment" and sends the developer hunting for a bad id instead of a bad identifier type. Branch on `code`.

Responses

Code	Means
`200`	Receipt metadata.
`401`	The `Authorization` header is missing or the key is invalid.
`404`	`code: "payment_not_found"` - transaction not found, or not owned by this merchant. If you instead get `code: "transaction_id_expected"`, you passed the numeric payment id where a transaction UUID is required. That is a live endpoint rejecting the identifier, not a missing route. Until 2026-08-21 this case answered the routing 404 instead, so older integrations that switch on `"could not be found"` now misfile it as "no such payment".

GET/payments/{transaction_id}/receipt/downloadDownload the receipt PDF

Parameters

Name	In	Required	Description
`transaction_id`	path	yes	The transaction UUID from the payment response - not the numeric payment `id`. Passing a numeric payment id returns 404 with `code: "transaction_id_expected"` and a message naming the identifier it wanted. The endpoint exists and answered; only the kind of identifier was wrong. This used to be a routing 404 (`"The route ... could not be found."`). It is not any more, verified 2026-08-21. Client code that classifies this error by matching the message text for `"could not be found"` now files it under "no such payment" and sends the developer hunting for a bad id instead of a bad identifier type. Branch on `code`.

Responses

Code	Means
`200`	PDF document.
`401`	The `Authorization` header is missing or the key is invalid.
`404`	`code: "payment_not_found"` - transaction not found, or not owned by this merchant. If you instead get `code: "transaction_id_expected"`, you passed the numeric payment id where a transaction UUID is required. That is a live endpoint rejecting the identifier, not a missing route. Until 2026-08-21 this case answered the routing 404 instead, so older integrations that switch on `"could not be found"` now misfile it as "no such payment".

GET/payment-methodsList a customer's saved cards

Parameters

Name	In	Required	Description
`customer[identity_number]`	query	no	National identity number of the customer. Preferred identifier.
`customer[email]`	query	no	Customer email, when the identity number is unknown.

Responses

Code	Means
`200`	The customer's saved methods, on a platform with mode 3A enabled. There, a customer with no saved cards is a normal `200` with `data: []`, not a 404. Without mode 3A the route never reaches this: it answers `422 tokenized_charge_disabled`.
`401`	The `Authorization` header is missing or the key is invalid.
`422`	`code: "tokenized_charge_disabled"` - mode 3A (saved cards) is not enabled on this platform. Returned by `GET /payment-methods`, `POST /payment-methods/{id}/charge` and `POST /payments/token-charge`, before any other validation. `DELETE /payment-methods/{id}` is not gated and keeps answering normally. Branch on `code`, not on the `errors` key. The key changes with the route - `customer` on the list, `payment_method_id` on charge, `payment_token` on token-charge - so this reads like a validation error on that field, and it is not: no value of that field will fix it. Show the merchant "saved cards are not enabled for this account" and ask ROKI to enable it. The message is localized by `Accept-Language` (`"Tokenized one-click charging is not enabled on this platform."` in English). New since 2026-09-23. Before that the list answered `200` with `data: []` even with the feature off, which is why an empty list used to be ambiguous.

DELETE/payment-methods/{payment_method_id}Revoke a saved card

Parameters

Name	In	Required	Description
`payment_method_id`	path	yes	Opaque saved-card reference, prefixed `pm_`.

Responses

Code	Means
`200`	Payment method revoked.
`401`	The `Authorization` header is missing or the key is invalid.
`404`	Payment method not found.

POST/payment-methods/{payment_method_id}/chargeCharge a saved card

Parameters

Name	In	Required	Description
`payment_method_id`	path	yes	Opaque saved-card reference, prefixed `pm_`.

Body

Field	Type	Required	Notes
`amount`	number	yes
`currency_code`	string	no	Accepts the alphabetic code here (`"HNL"`), unlike payment creation which uses the numeric code (`"340"`).
`external_reference`	string	no
`metadata`	object	no

Responses

Code	Means
`201`	Charge processed.
`401`	The `Authorization` header is missing or the key is invalid.
`404`	Payment method not found or not owned by this merchant.
`422`	Validation failure (including a missing `Idempotency-Key`), or a processor decline carrying `IsoResponseCode` and `Errors`. On a platform without mode 3A enabled, every call answers `code: "tokenized_charge_disabled"` - checked before anything else, so it wins even over a missing `Idempotency-Key`. See `TokenizedChargeDisabled`.

POST/payments/token-chargeCharge a saved card (alias)

Body

Field	Type	Required	Notes
`payment_token`	string	yes	The saved payment method reference.
`amount`	number	yes
`currency_code`	string	no
`external_reference`	string	no
`metadata`	object	no

Responses

Code	Means
`200`	Charge processed.
`401`	The `Authorization` header is missing or the key is invalid.
`422`	Validation failure or processor decline. On a platform without mode 3A enabled, every call answers `code: "tokenized_charge_disabled"`, before any other check - see `TokenizedChargeDisabled`.

POST/confirmConfirm an embedded-components payment

Body

Field	Type	Required	Notes
`amount`	number	yes
`currency_code`	string	yes	Accepts `"HNL"` or the numeric `"340"`.
`payment_token`	string	yes	The `tok_*` produced by the browser SDK after the customer submits the card.
`publishable_key`	string	yes	The same publishable key the SDK was mounted with.
`external_reference`	string	no
`success_redirect_url`	string	no
`failed_redirect_url`	string	no
`description`	string	no
`metadata`	object	no

Responses

Code	Means
`200`	Outcome of the charge. Inspect `status`: `approved`, `declined` or `pending`.
`401`	The `Authorization` header is missing or the key is invalid.
`422`	Validation failure or processor decline.