Primer pago

Esta guía muestra el recorrido completo de una integración de negocio. Usá primero el ambiente test; las credenciales y métodos de test están aislados de live.

Antes de empezar

Necesitás:

la URL base del ambiente;
un usuario de management;
una API key de prueba con payment_methods:read, payments:create y payments:read;
al menos un método de pago test activo y habilitado para esa key;
una URL HTTPS capaz de recibir webhooks, si necesitás actualizaciones asíncronas.

Si todavía no existe el método, un usuario debe crearlo desde Métodos de pago de la cuenta y vincularlo con la API key.

1. Verificar los métodos disponibles

curl --request GET "$PAGOFAST_BASE_URL/v1/payment-methods" \
  --header "Authorization: Bearer $PAGOFAST_API_KEY"

Elegí un elemento active que incluya la capability payments. Guardá su id; es el valor que se envía como payment_method.

2. Crear el pago

Generá una clave de idempotencia estable para este intento lógico. Si se pierde la respuesta, repetí el mismo body con la misma clave.

curl --request POST "$PAGOFAST_BASE_URL/v1/payments" \
  --header "Authorization: Bearer $PAGOFAST_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-9821-payment-1" \
  --data '{
    "amount": { "value": "12500.00", "currency": "ARS" },
    "external_reference": "order-9821",
    "description": "Pedido #9821",
    "payment_method": "019f704f-89d7-7e83-b3e1-f07c33801024",
    "webhook_url": "https://merchant.example.com/webhooks/pagofast"
  }'

No interpretes un 2xx como aprobación automática. Leé siempre data.status:

approved: el pago terminó aprobado;
pending o processing: el resultado todavía puede cambiar;
declined: hubo una respuesta concluyente de rechazo;
failed: la operación falló sin aprobación.

Si action.type es display_qr, mostrale action.qr_data al pagador y esperá la confirmación por webhook o consulta.

3. Consultar el resultado

curl --request GET \
  "$PAGOFAST_BASE_URL/v1/payments/019f7061-2010-7698-8827-e32f86e14298" \
  --header "Authorization: Bearer $PAGOFAST_API_KEY"

La consulta sirve como reconciliación y como respaldo si un webhook se demora. No generes un segundo pago solo porque venció el timeout de tu cliente: primero repetí idempotentemente o consultá el pago conocido.

4. Procesar webhooks

Verificá la firma usando el body crudo, deduplicá por id y respondé 2xx después de persistir el evento. Los eventos pueden repetirse y llegar fuera de orden; aplicá el cambio usando payment.updated_at y una máquina de estados válida.

Leé Eventos de webhook y Firma antes de habilitar producción.

5. Pasar a producción

Creá credenciales y métodos nuevos en live; no reutilices valores de test. Antes del corte comprobá:

secretos almacenados en un gestor seguro y nunca en frontend;
timeouts y retries que respetan idempotencia;
firma de webhooks verificada sobre el body crudo;
manejo de pending, duplicados y eventos fuera de orden;
logs con X-Request-Id, sin API keys ni datos sensibles;
conciliación periódica mediante GET /v1/payments/{payment_id}.

Siguiente paso

La referencia completa está en Pagos. Para errores recuperables y no recuperables, consultá Errores.