Crear un pago

POST /api/connect/v1/payments

7.1 Campos obligatorios

Campo	Tipo	Regla
`amount`	number	Mínimo 0.01. Unidades decimales, no centavos (150.50 = L 150.50). La API no impone un máximo.
`external_reference`	string	El id de tu orden. Máx 191. No es único (ver 11).
`name`	string	Etiqueta que el cliente ve en el checkout. Máx 191.

7.2 Campos opcionales

Campo	Tipo	Notas
`currency_code`	string	ISO 4217 numérico (`"340"` = HNL). Por defecto usa la moneda de la terminal. Solo se aceptan las monedas habilitadas en esa terminal.
`description`	string	Máx 120.
`metadata`	object	Tus propios pares clave/valor. Tiene que ser un objeto: un string devuelve 422. Ver 10.
`success_url` / `cancel_url`	string	URLs de retorno. Usá HTTPS (ver 12.4).
`expires_at`	string	Hora de Honduras (UTC-6), tiene que estar en el futuro. Acepta `YYYY-MM-DD HH:MM:SS` e ISO 8601.
`sales_tax_type`	enum	`none` (por defecto), `fixed`, `percentage`.
`sales_tax_value`	number	Obligatorio cuando el tipo no es `none`. Como porcentaje, máx 100.
`tip_enabled`	boolean	Ver 8.2.
`service_fee_enabled`	boolean	Ver 8.3.
`reusable`	boolean	Ver 8.4.
`customer`	object	Prellena el checkout: `name`, `email`, `phone`, `identity_number`. Ver 7.5.
`lock_customer_fields`	boolean	Deja los campos prellenados de solo lectura. Ver 7.5.

7.3 Ejemplo mínimo

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

7.4 Respuesta (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
}

Guardá el id en tu base de datos - es la única forma de volver a consultar el pago (no hay búsqueda por external_reference). Después redirigí al cliente a checkout_url.

Dos notas sobre esa respuesta. transaction_id es null hasta que se cobra el pago, y es un string UUID - cambió de tipo, en una versión anterior era un entero, y es el identificador que exigen la anulación, el reembolso y los recibos. Y el slug de checkout_url es una cadena de 12 caracteres en minusculas: no lleva ningun prefijo, asi que la API de producción no usa, así que nunca hagas coincidencia de patrones sobre un slug - redirigí a la URL exacta que te dieron.

7.5 Prellenar los datos del cliente

El objeto opcional customer prellena el checkout alojado con los datos de un cliente conocido. Cada campo dentro de él es opcional e independiente:

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

Por defecto los campos prellenados siguen siendo editables. Con lock_customer_fields: true, cada campo que envíes con un valor no vacío queda de solo lectura en el checkout; los campos que omitas quedan en blanco y editables incluso entonces.

Vale la pena enviar identity_number: también es el identificador preferido para buscar más adelante las tarjetas guardadas de ese cliente (ver sección 23).

Ambos campos se reflejan de vuelta en la respuesta, lo cual importa más de lo que suena: como esta API ignora silenciosamente los campos desconocidos, el objeto customer reflejado es tu única forma de confirmar desde la respuesta que el prellenado sí se aplicó. Revisalo en lugar de asumir que el 201 significa que funcionó.

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