API reference

12 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/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`	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
`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),
`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
`description`	string	no
`metadata`	object	no	Merchant-defined key/value pairs, returned untouched on retrieval and in every webhook.
`success_url`	string	no	Return URL after payment. Landing there does not confirm payment. The API accepts
`cancel_url`	string	no
`expires_at`	string	no	Link expiry in Honduras time (UTC-6), must be in the future. Accepts
`customer`	any	no
`lock_customer_fields`	boolean	no	When `true`, every prefilled field that carries a non-empty value becomes read-only at
`reusable`	boolean	no	`false` (default) makes the payment single-use: it is consumed after an approved charge.
`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
`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`
`service_fee_enabled`	boolean	no	Per-request switch. `true` passes ROKI's processing costs to the customer: the checkout

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

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`	No payment with that id exists for the key in use - often an id from the other environment.

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`.

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`	Transaction not found, or not owned by this merchant.
`422`	Not voidable. `errors.void` carries the reason: already voided, already refunded

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`.

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`	Transaction not found, or not owned by this merchant.
`422`	Rejected. `errors.amount`: below 0.01, or above the remaining refundable amount.

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`.

Responses

Code	Means
`200`	Receipt metadata.
`401`	The `Authorization` header is missing or the key is invalid.
`404`	Transaction not found, or not owned by this merchant.

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`.

Responses

Code	Means
`200`	PDF document.
`401`	The `Authorization` header is missing or the key is invalid.
`404`	Transaction not found, or not owned by this merchant.

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. An empty list is a normal `200` with `data: []`,
`401`	The `Authorization` header is missing or the key is invalid.

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
`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

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.

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.