Empezar en 5 minutos

Cuatro pasos: API key, crear el checkout, redirigir, y confirmar con payment.succeeded. Los importes van en céntimos.

1. Obtener la API key

Entra en el Dashboard → Desarrolladores. Crea una clave secreta. En producción empieza por pf_live_. En test, por pf_test_.

La clave de test solo funciona en https://sandbox-api.payforce.co. La de live, en https://api.payforce.co o en https://www.payforce.co.

Authorization: Bearer pf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Crear el checkout

POST /api/v1/sessions con importe y moneda. Respuesta 201. El campo que usas para redirigir es checkout_url.

curl -X POST https://api.payforce.co/api/v1/sessions \
  -H "Authorization: Bearer pf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": 1990,
    "currency": "eur",
    "description": "Pedido 1042",
    "customer_email": "cliente@ejemplo.com",
    "success_url": "https://tienda.ejemplo.com/ok",
    "cancel_url": "https://tienda.ejemplo.com/cancelado"
  }'

{
  "id": "cmlink_01HX8K2N4P",
  "object": "session",
  "checkout_url": "https://www.payforce.co/pay/tok_8f2a1c90e4b7",
  "url": "https://www.payforce.co/pay/tok_8f2a1c90e4b7",
  "client_secret": "pi_3Sabc_secret_xyz",
  "amount": 1990,
  "currency": "eur",
  "description": "Pedido 1042",
  "status": "open",
  "expires_at": "2026-09-11T15:04:00.000Z",
  "created_at": "2026-09-11T14:04:00.000Z"
}

Si prefieres el widget embebible, el endpoint es POST /api/v1/checkout/sessions. Ahí el campo se llama url y apunta a /checkout-widget/{id}.

3. Redirigir al checkout_url

Envía al comprador a checkout_url. Paga en esa página. Si enviastesuccess_url, vuelve ahí cuando el pago termina.

HTTP/1.1 302 Found
Location: https://www.payforce.co/pay/tok_8f2a1c90e4b7

4. Recibir payment.succeeded

Registra un endpoint en Dashboard → Desarrolladores o con POST /api/v1/webhooks. PayForce hace POST a tu URL cuando el cobro entra.

curl -X POST https://api.payforce.co/api/v1/webhooks \
  -H "Authorization: Bearer pf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tienda.ejemplo.com/webhooks/payforce",
    "events": ["payment.succeeded", "payment.failed"]
  }'

{
  "id": "whe_01HX8K9Q2M",
  "object": "webhook_endpoint",
  "secret": "whsec_4b91c0e2a7d6f1",
  "url": "https://tienda.ejemplo.com/webhooks/payforce",
  "events": ["payment.succeeded", "payment.failed"],
  "created_at": "2026-09-11T14:05:12.000Z"
}

Cuando el comprador paga, llega un cuerpo como este:

POST /webhooks/payforce
Content-Type: application/json
X-PayForce-Event: payment.succeeded
X-PayForce-Delivery-Id: 7c2e1a90-4b11-4d88-9f03-2a8c0e14b6d1
X-PayForce-Signature: t=1726063512000,v1=3f8c…

{
  "event": "payment.succeeded",
  "payment": {
    "id": "pf_pay_test",
    "amount": 1990,
    "currency": "eur",
    "status": "succeeded",
    "description": "Pedido 1042",
    "customer_email": "cliente@ejemplo.com",
    "created_at": "2026-09-11T14:06:02.000Z"
  }
}

Responde 2xx en menos de 10 segundos. Verifica la firma antes de marcar el pedido como pagado. El detalle está en Webhooks.