Reglas compartidas del contrato REST: versión, JSON, montos, headers, paginación y compatibilidad.

Convenciones de API

Base URL, ambientes y versión

La URL base depende del ambiente y debe ser provista por PagoFast. Todas las rutas públicas versionadas comienzan con /v1:

GET {base_url}/v1/payment-methods

Los recursos de test y live están aislados. Una API key sk_test_... no puede acceder a métodos live, y una key sk_live_... no puede acceder a métodos test.

Headers comunes

Header	Dirección	Uso
`Authorization: Bearer <token>`	Request	JWT de usuario o API key (`sk_test_...` / `sk_live_...`).
`Content-Type: application/json`	Request	Obligatorio cuando hay body JSON.
`Idempotency-Key`	Request	Obligatorio en escrituras de negocio documentadas como idempotentes.
`X-Request-Id`	Request	Opcional; si no se envía, la API lo genera.
`X-Request-Id`	Response	Identificador de correlación (eco del request o generado). Aparece también en `error.request_id`.

No registres el valor completo de Authorization ni otros secretos.

JSON y nombres

Todos los campos públicos usan snake_case. Los clientes deben ignorar campos opcionales desconocidos para tolerar extensiones compatibles.

{
  "external_reference": "order-9821",
  "created_at": "2026-07-17T13:00:00.000Z"
}

Fechas

Las fechas se expresan en ISO 8601 y UTC:

2026-07-17T13:00:00.000Z

Montos y monedas

Los montos son strings decimales para evitar errores binarios de punto flotante. La moneda usa un código ISO 4217.

{
  "amount": {
    "value": "12500.00",
    "currency": "ARS"
  }
}

No envíes números JSON (12500.00), separadores de miles ("12.500,00") ni símbolos ("$12500"). La cantidad de decimales admitida depende de la moneda y del contrato del endpoint.

Respuestas exitosas

Un recurso individual se devuelve bajo data:

{
  "data": {
    "id": "019f704f-89d7-7e83-b3e1-f07c33801024"
  }
}

Un listado agrega pagination con offset:

{
  "data": [],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 128
  }
}

Usá limit y offset para paginar. total indica cuántos ítems coinciden con el filtro.

Errores

Los errores usan un envelope diferente:

{
  "error": {
    "code": "invalid_request",
    "message": "La solicitud no cumple el contrato.",
    "category": "validation",
    "retryable": false,
    "request_id": "req_019f704f89d77e83",
    "details": {}
  }
}

Tomá decisiones programáticas con code y retryable, no analizando message. Conservá request_id para soporte. Consultá el catálogo de errores.

Idempotencia

Las escrituras de negocio indicadas en su referencia requieren Idempotency-Key. La falta del header devuelve 400 idempotency_key_required. Una repetición con el mismo body recupera la respuesta guardada; reutilizar la clave con otro body devuelve 409 idempotency_key_reused.

Consultá Idempotencia para elegir claves y reintentar correctamente.

Compatibilidad

Agregar campos opcionales es compatible.
Los clientes deben tolerar campos desconocidos.
Eliminar campos, volver obligatorio un campo opcional o cambiar su semántica requiere una nueva versión.
No implementes switch exhaustivos sobre enums sin una rama segura para valores futuros.
Los cambios relevantes se anuncian en el changelog.

Recomendación para soporte

Al reportar una falla incluí ambiente, endpoint, fecha UTC, X-Request-Id, external_reference e ID del recurso. No compartas API keys, JWT, credenciales del procesador ni cuerpos con datos sensibles.