Crear pago

API v0.1.0

En esta página

Crea un payment_intent en estado created. Requiere sk_. Devuelve un client_secret que se entrega al navegador para confirmar el pago.

Endpoint

POST/v1/payments

Request

Headers:

bash

Authorization: Bearer sk_live_xxxxxxxx
Content-Type: application/json
Idempotency-Key: <opcional pero recomendado>

Body:

json

{
  "amount": 50000,
  "currency": "VES",
  "customer_phone": "04141234567",
  "customer_id_document": "V12345678",
  "customer_bank_code": "0114"
}

Campos del body

Campo	Tipo	Validación
`amount`	int	Céntimos. `≥ 1`, `≤ 100_000_000_000` (mil millones). Ejemplo: `50000` = Bs. 500,00.
`currency`	string	"VES" o "USD" (case-sensitive).
`customer_phone`	string	Formato 04XXXXXXXXX (11 dígitos).
`customer_id_document`	string	V/E/J/G/P + 6-9 dígitos. Se normaliza a mayúsculas automáticamente.
`customer_bank_code`	string	Código de 4 dígitos. Debe estar listado en `/v1/banks`.

Respuesta 201 Created

json

{
  "id": "8d3a4b5c-2e74-41f6-a091-f7036f8d6a8c",
  "external_id": "pi_L9limdfjZ6SHJjpkXueO1w",
  "status": "created",
  "amount_cents": 50000,
  "currency": "VES",
  "customer_phone": "04141234567",
  "customer_id_document": "V12345678",
  "customer_bank_code": "0114",
  "expires_at": "2026-05-13T15:30:00",
  "client_secret": "pi_L9limdfjZ6SHJjpkXueO1w_secret_tjxQABDZZWMokatGobBsZocUItksOJIZ",
  "created_at": "2026-05-13T15:15:00",
  "updated_at": "2026-05-13T15:15:00"
}

Ejemplos

typescript

const resp = await fetch(`${process.env.RUTIVA_BASE_URL}/v1/payments`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.RUTIVA_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    amount: 50000,
    currency: "VES",
    customer_phone: "04141234567",
    customer_id_document: "V12345678",
    customer_bank_code: "0114",
  }),
});
const intent = await resp.json();
// Enviar SOLO { id: intent.id, client_secret: intent.client_secret } al frontend.

Idempotencia

El header Idempotency-Key evita duplicar intents si un request se reintenta por error de red.

Misma key + body idéntico → devuelve el intent existente con HTTP 200. El client_secret no se incluye en el replay (solo en la creación original).
Misma key + body distinto → HTTP 422 {"detail":"idempotency_key_mismatch"}.
Formato: max 100 chars, regex ^[A-Za-z0-9_\-:.]+$. Recomendado: UUID v4 por intento de pago lógico.

Expiración

Cada intent expira a los 15 minutos de creación (expires_at en la respuesta). Pasado ese tiempo, intentar confirmar devuelve 400 payment_expired y el intent queda canceled automáticamente.