Crear un pago

post/v1/payments

Crea y procesa un pago a través del PSP resuelto. Requiere el header Idempotency-Key: reintentar con la misma key devuelve el mismo pago, nunca un segundo cobro.

Request

BASH

curl -X POST https://api.cauril.com/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "USD",
    "payment_method": {
      "type": "card",
      "token": "string",
      "brand": "visa",
      "last4": "4242"
    },
    "provider": "stripe",
    "customer_id": "string",
    "description": "string",
    "capture": true,
    "return_url": "string",
    "metadata": {}
  }'

Parámetros

Idempotency-Keyheaderreq

string

Clave única por operación (ej. un UUID). Reintentar con la misma key replica la respuesta original.

Cuerpo CreatePayment

amountreq	Money
currencyreq	Currency
payment_methodreq	PaymentMethod
provider	string	Forzar un PSP. Si se omite, se usa el provider por defecto de la organización.
customer_id	string
description	string
capture	boolean	Default: `true`.
return_url	string
metadata	object

Respuestas

201	Pago creado	Payment
400	Error	Error
401	Error	Error
402	Error	Error
409	Error	Error
422	Error	Error

Ejemplo de respuesta · 201

JSON

{
  "object": "payment",
  "id": "pay_01J...",
  "status": "created",
  "amount": 5000,
  "amount_refunded": 5000,
  "currency": "USD",
  "provider": "stripe",
  "provider_payment_id": null,
  "payment_method": {
    "type": "card",
    "token": "string",
    "brand": "visa",
    "last4": "4242"
  },
  "customer_id": null,
  "description": null,
  "metadata": {},
  "next_action": {
    "type": "redirect",
    "url": "string"
  },
  "failure": {
    "code": "card_declined",
    "message": "string"
  },
  "attempts": [
    {
      "object": "payment_attempt",
      "id": "string",
      "provider": "string",
      "status": "string",
      "provider_payment_id": null,
      "error_code": null,
      "latency_ms": null,
      "created_at": "2026-06-01T12:00:00Z"
    }
  ],
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T12:00:00Z",
  "livemode": true
}