Guías

Cobrar una vez con enlace de pago

Crea una sesión y envía checkout_url. El comprador paga en PayForce. Tú marcas el pedido cuando llega payment.succeeded.

curl -X POST https://api.payforce.co/api/v1/sessions \
  -H "Authorization: Bearer pf_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4500,
    "currency": "eur",
    "description": "Reserva 18 septiembre",
    "customer_email": "ana@ejemplo.com"
  }'

Copia checkout_url en el email o en el botón «Pagar». No confirmes el cobro solo porque el cliente volvió a success_url: espera el webhook.

Suscripción recurrente por SEPA

Primero crea o localiza al cliente. Luego crea la suscripción. El estado inicial es PENDING_CARD hasta que el cliente firma el mandato (en SEPA) o guarda la tarjeta.

curl -X POST https://api.payforce.co/api/v1/customers \
  -H "Authorization: Bearer pf_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ana López", "email": "ana@ejemplo.com" }'

curl -X POST https://api.payforce.co/api/v1/subscriptions \
  -H "Authorization: Bearer pf_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sub-ana-2026" \
  -d '{
    "customer_id": "cus_01HX8",
    "amount": 2900,
    "currency": "eur",
    "interval": "month"
  }'

En el dashboard, activa SEPA Direct Debit en la cuenta. Envía al cliente el enlace de alta de mandato (payment link o checkout en modo suscripción). El primer cargo se intenta en la fecha de cobro. Si el banco lo devuelve, el registro pasa a impago.

Checkout embebido en tu web

Crea la sesión de widget. Monta esa URL en un iframe o redirige a ella.

curl -X POST https://api.payforce.co/api/v1/checkout/sessions \
  -H "Authorization: Bearer pf_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1990, "currency": "eur", "mode": "payment" }'

{
  "id": "cs_01HX8EMBED",
  "object": "checkout_session",
  "url": "https://www.payforce.co/checkout-widget/cs_01HX8EMBED",
  "client_secret": "pi_3Sabc_secret_xyz",
  "status": "open",
  "expires_at": "2026-09-11T16:00:00.000Z",
  "mode": "payment",
  "created_at": "2026-09-11T14:10:00.000Z"
}

<iframe
  src="https://www.payforce.co/checkout-widget/cs_01HX8EMBED"
  title="Pagar"
  style="width:100%;min-height:480px;border:0;border-radius:12px"
></iframe>

También puedes usar la clave pública pf_pk_live_ en el snippet del Dashboard → Desarrolladores (data-payforce-key) para montar el formulario sin iframe a página completa.

Recuperar un impago

Un impago aparece cuando falla un recibo SEPA o una cuota. En el dashboard, abre Impagos. Tienes tres acciones habituales:

1. Generar un enlace de cobro (cuota + recargo, si lo tienes activo).
2. Reintentar el cargo sobre el mismo mandato o tarjeta.
3. Marcar como pagado si el cliente te pagó fuera (transferencia, efectivo).

El enlace de recuperación es un payment link más. Cuando el cliente paga, llegapayment.succeeded y el impago queda cerrado. No borres el registro a mano: así el dunning no vuelve a avisar.