docs.api.pages.payment-requests

Peça um pagamento a um cliente e receba, numa só resposta, todas as formas de ele pagar: link com cartão, CLABE SPEI dessa cobrança, boleto em dinheiro e se ele tem débito automático ativo. Feito para agentes de IA: eles não escolhem gateway nem método.

Criar uma solicitação

O Recaudo cria um link de pagamento para o cliente e monta cada forma de pagamento disponível para o seu negócio. Se uma não estiver disponível (por exemplo, dinheiro não configurado) ela vem como null e as outras funcionam igual. Passa pelos limites de dinheiro de agentes: acima do limite 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 do cliente. Obrigatório.
• amount Valor em decimais. Obrigatório.
• description O que o cliente vê. Obrigatório.
• invoice_id Fatura que está sendo paga; o pagamento é aplicado a ela.
• allow_partial Permitir pagamentos parciais.
• methods O que montar: card, spei, cash. Por padrão, todas.
• expires_at Vencimento. Por padrão, 7 dias.

Esperar o pagamento

GET /v1/payment-requests/{id}/wait espera até 25 segundos o status ou o valor pago mudar e responde o status com waited_seconds. Se continuar pending, chame de novo. A ferramenta MCP é wait_for_payment.

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

Status

pending, partially_paid, paid, expired, canceled.

Webhooks

payment_request.paid quando o total é coberto, payment_request.partially_paid a cada pagamento parcial e payment_request.expired ao vencer. O corpo é o mesmo objeto payment_request. Os eventos do link (payment_link.*) continuam chegando.