docs.api.pages.payment-requests

Pide un pago a un cliente y recibe, en una sola respuesta, todas las formas en que puede pagar: link con tarjeta, CLABE SPEI de ese cobro, ficha de efectivo y si tiene domiciliación activa. Pensado para agentes de IA: no eligen pasarela ni método.

Crear una solicitud

Recaudo crea un link de pago para el cliente y arma cada forma de pago disponible para tu negocio. Si una no está disponible (por ejemplo, no tienes efectivo configurado) viene en null y las demás salen igual. Pasa por los límites de dinero de agentes: arriba del límite responde 202.

curl -X POST https://recaudo.app/api/v1/payment-requests \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: abono-nov-7f3a" \
  -H "Content-Type: application/json" \
  -d '{"customer": "8c2f…", "amount": 1500.00, "description": "Abono de noviembre"}'

{
    "object": "payment_request",
    "id": "3f0a9c7e-\u2026",
    "status": "pending",
    "amount": 1500,
    "amount_paid": 0,
    "amount_remaining": 1500,
    "currency": "MXN",
    "url": "https://recaudo.app/pay/\u2026",
    "options": {
        "card": {
            "url": "https://recaudo.app/pay/\u2026"
        },
        "spei": {
            "clabe": "646180111800000000",
            "bank": "STP",
            "concept": "ord-\u2026",
            "amount": 1500,
            "expires_at": "2026-11-09T23:59:00-06:00"
        },
        "cash": {
            "reference": "9300 0000 0000 00",
            "url": "\u2026",
            "amount": 1500,
            "expires_at": "\u2026"
        },
        "direct_debit": null
    },
    "expires_at": "2026-11-14T12:00:00-06:00"
}

Parámetros

• customer UUID del cliente. Obligatorio.
• amount Monto en decimales. Obligatorio.
• description Concepto que ve el cliente. Obligatorio.
• invoice_id Factura que se paga; el pago se aplica a ella.
• allow_partial Permitir abonos.
• methods Qué armar: card, spei, cash. Por omisión, todas.
• expires_at Vencimiento. Por omisión, 7 días.

Esperar el pago

GET /v1/payment-requests/{id}/wait espera hasta 25 segundos a que cambie el estado o el monto pagado y responde el estado con waited_seconds. Si sigue en pending, vuelve a llamar. La herramienta MCP es wait_for_payment.

https://recaudo.app/api/v1/payment-requests/{id}/wait?timeout=25

Estados

pending, partially_paid, paid, expired, canceled.

Webhooks

payment_request.paid cuando se cubre el total, payment_request.partially_paid en cada abono y payment_request.expired al vencer. El cuerpo es el mismo objeto payment_request. También siguen llegando los eventos del link (payment_link.*).