Crear un pago

Crea un pago a un beneficiario aprobado. Exige Idempotency-Key y firma. Responde 202: el resultado llega por webhook o en GET /v1/payments/{id}. Si la respuesta se corta, repite con la misma clave: nunca crea un segundo pago. in_review con retryable: false quedó registrado: esa clave repite el rechazo, y volver a intentarlo exige otra.

Dato	Valor
Método y ruta	`POST /v1/payments`
Servidor	`https://widget.fital.xyz`
`operationId`	`createPayment`
Acceso	Llave con el scope `payments:write`
Firma de petición	Obligatoria en producción y en la cuenta de prueba. El simulador público no la valida. Ver Firma de petición
Idempotencia	Obligatoria, con `Idempotency-Key`. Ver Idempotencia
Escenarios	`payment_completed`, `insufficient_funds`, `payment_held`. Ver Ambientes

El riel sale del beneficiario: no se elige aquí.
quote_id es opcional. Si lo envías, debe ser de este mismo beneficiario, monto y moneda, y max_source_amount manda sólo si es menor que lo cotizado.
202 con processing no es fallo: el resultado llega por webhook o en GET /v1/payments/{id}. El encabezado Location trae la ruta del pago.

Encabezados de la petición

Encabezado	Obligatorio	Descripción
`Authorization`	Sí	`Bearer` y tu llave.
`Content-Type`	Sí	`application/json`.
`Idempotency-Key`	Sí	Clave única de esta operación, de 8 a 200 caracteres. Repetirla con el mismo cuerpo devuelve la misma respuesta durante 7 días. Con otro cuerpo da `422 idempotency_key_reused`, también pasado ese plazo.
`X-Fital-Timestamp`	Sí	Hora Unix en segundos. Se acepta hasta 300 s de diferencia.
`X-Fital-Signature`	Sí	Firma `v1=` de la petición con el secreto de firma de la llave.
`X-Fital-Scenario`	No	Sólo simuladores: elige la respuesta que quieres practicar.

Cuerpo

Campo	Tipo	Obligatorio	Descripción
`amount`	texto	Sí	Monto a enviar, como decimal en texto.
`beneficiary_id`	texto	Sí	Beneficiario aprobado que recibe el pago.
`currency`	texto	Sí	Moneda del monto.
`external_ref`	texto	Sí	Tu referencia del pago, hasta 120 caracteres imprimibles. Vuelve en el pago y en sus eventos. Hasta 120 caracteres.
`max_source_amount`	texto	No	Máximo a debitar. Con cotización, manda el menor de los dos.
`metadata`	objeto	No	Hasta 20 pares clave y valor tuyos. Valores de hasta 500 caracteres.
`quote_id`	texto	No	Cotización vigente de este mismo beneficiario, monto y moneda. Fija el tope de débito.
`reference`	texto	No	Concepto del pago, hasta 140 caracteres imprimibles. Hasta 140 caracteres.

{
  "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "amount": "1500.00",
  "currency": "MXN",
  "external_ref": "factura-1042"
}

Respuestas correctas

202 Aceptado: el resultado final llega después

Campo	Tipo	Obligatorio	Descripción
`amount`	texto o `null`	Sí	Monto pedido.
`beneficiary_id`	texto o `null`	Sí	Beneficiario del pago.
`created_at`	texto o `null`	Sí	Fecha de creación. ISO 8601 en UTC.
`currency`	texto o `null`	Sí	Moneda pedida.
`external_ref`	texto o `null`	Sí	Tu referencia.
`failure_code`	texto o `null`	Sí	Código del catálogo de errores si el pago falló, null en cualquier otro estado. En `GET /v1/payments` siempre es null: léelo en `GET /v1/payments/{id}` o en `payment.failed`. Trata la lista como extensible. `payment_rejected`: Rechazado sin un motivo más específico. `insufficient_funds`: Saldo insuficiente al ejecutar. `limit_exceeded`: Se superó el tope acumulado de la empresa o un límite del riel. `amount_below_minimum`: El monto quedó por debajo del mínimo aplicable. `account_restricted`: La cuenta tiene una restricción. `in_review`: Una revisión detuvo la ejecución. `quote_changed`: El débito superaría lo permitido. `quote_expired`: La cotización venció antes de ejecutar.
`final_amount`	texto o `null`	Sí	Monto final, cuando se conoce.
`final_currency`	texto o `null`	Sí	Moneda del monto final.
`freshness`	objeto	No	De dónde sale `status`. Sólo en `GET /v1/payments/{id}`.
`freshness.as_of`	texto o `null`	Sí	Hora de esa lectura, de la última que se aplicó o de la cancelación confirmada. Null si aún no hay ninguna. ISO 8601 en UTC.
`freshness.status`	texto	Sí	De dónde sale `status`. `current`: `status` sale de una lectura de ahora. `delayed`: La lectura no concluyó y `status` es lo último que se sabe. No lo tomes como un resultado nuevo.
`id`	texto	Sí	Identificador del pago, con prefijo `pay_`.
`metadata`	objeto	Sí	Los pares que enviaste al crear el pago.
`reference`	texto o `null`	Sí	Concepto del pago.
`status`	texto	Sí	Estado público. `processing`: Aceptado y en curso, o aún sin confirmar. Consúltalo hasta un estado terminal. `in_review`: En revisión. No lo repitas: el pago ya existe. `completed`: Se pagó. Aún puede pasar a `returned`. `failed`: No se hizo y no queda dinero en tránsito. `returned`: Se devolvió y el saldo ya volvió. `canceled`: Se canceló antes de ejecutarse.

Valores de `failure_code`

Valor	Significado
`payment_rejected`	Rechazado sin un motivo más específico.
`insufficient_funds`	Saldo insuficiente al ejecutar.
`limit_exceeded`	Se superó el tope acumulado de la empresa o un límite del riel.
`amount_below_minimum`	El monto quedó por debajo del mínimo aplicable.
`account_restricted`	La cuenta tiene una restricción.
`in_review`	Una revisión detuvo la ejecución.
`quote_changed`	El débito superaría lo permitido.
`quote_expired`	La cotización venció antes de ejecutar.

Con failed, GET /v1/payments/{id} y payment.failed siempre traen un código: payment_rejected si no hay uno más específico. En cualquier otro estado, y en la lista GET /v1/payments, es null. Trata la lista como extensible.

Valores de `freshness.status`

Valor	Significado
`current`	`status` sale de una lectura de ahora.
`delayed`	La lectura no concluyó y `status` es lo último que se sabe. No lo tomes como un resultado nuevo.

Valores de `status`

Valor	Significado
`processing`	Aceptado y en curso, o aún sin confirmar. Consúltalo hasta un estado terminal.
`in_review`	En revisión. No lo repitas: el pago ya existe.
`completed`	Se pagó. Aún puede pasar a `returned`.
`failed`	No se hizo y no queda dinero en tránsito.
`returned`	Se devolvió y el saldo ya volvió.
`canceled`	Se canceló antes de ejecutarse.

{
  "amount": "1500.00",
  "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "created_at": "2026-11-04T18:00:00.000Z",
  "currency": "MXN",
  "external_ref": "pedido-7731",
  "failure_code": null,
  "final_amount": null,
  "final_currency": null,
  "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "metadata": {},
  "reference": "Factura 1042",
  "status": "processing"
}

Variante payment_completed:

{
  "amount": "1500.00",
  "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "created_at": "2026-11-04T18:00:00.000Z",
  "currency": "MXN",
  "external_ref": "pedido-7731",
  "failure_code": null,
  "final_amount": null,
  "final_currency": null,
  "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "metadata": {},
  "reference": "Factura 1042",
  "status": "processing"
}

Variante payment_failed:

{
  "amount": "1500.00",
  "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "created_at": "2026-11-04T18:00:00.000Z",
  "currency": "MXN",
  "external_ref": "pedido-7731",
  "failure_code": null,
  "final_amount": null,
  "final_currency": null,
  "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "metadata": {},
  "reference": "Factura 1042",
  "status": "processing"
}

Variante payment_returned:

{
  "amount": "1500.00",
  "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "created_at": "2026-11-04T18:00:00.000Z",
  "currency": "MXN",
  "external_ref": "pedido-7731",
  "failure_code": null,
  "final_amount": null,
  "final_currency": null,
  "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "metadata": {},
  "reference": "Factura 1042",
  "status": "processing"
}

Encabezados de la respuesta

Encabezado	Contenido
`X-Request-Id`	Identificador de la petición. Cítalo con soporte.
`Idempotent-Replayed`	`true` si la respuesta repite una anterior con esa clave.
`Location`	Ruta del recurso, con `201` y `202`.
`Retry-After`	Segundos a esperar, con `429`, con `409 idempotency_in_progress` y a veces con `503`.

Errores

Todos usan la forma de Errores: error.code, message, request_id, details, retryable y docs_url. Decide por code.

HTTP	Código	Cuándo sale	`retryable`
400	`invalid_request`	Algún campo no cumple el esquema. También si `amount` es cero, si lleva decimales en una moneda sin decimales, o si `quote_id` es de otra operación.	`false`
400	`idempotency_key_required`	Falta `Idempotency-Key`.	`false`
400	`idempotency_key_invalid`	La clave no mide entre 8 y 200 caracteres, o viene duplicada.	`false`
401	`invalid_api_key`	La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida.	`false`
401	`wrong_environment`	La llave es de otro ambiente.	`false`
401	`invalid_signature`	Falta la firma, no coincide o tiene más de 5 minutos.	`false`
403	`rail_not_enabled`	El riel del beneficiario no está habilitado para tu empresa.	`false`
403	`not_enabled`	PIX sin activación vigente para tu empresa.	`false`
403	`account_restricted`	La cuenta tiene una restricción. Puede llegar antes de ejecutar, o quedar registrado al ejecutar.	`false`
403	`forbidden_scope`	La llave no tiene el scope de esta operación. `details.required_scope` lo nombra.	`false`
403	`ip_not_allowed`	La IP de origen no está activa en la lista de esa llave.	`false`
403	`kyb_required`	La empresa no tiene KYB aprobado o aún no está inscrita.	`false`
403	`account_not_active`	La cuenta no está activa.	`false`
404	`not_found`	El beneficiario o la cotización no existen, o son de otra empresa.	`false`
409	`payment_in_flight`	Otra salida de dinero de tu empresa sigue sin confirmarse.	`true`
409	`quote_changed`	El débito superaría `max_source_amount` o lo cotizado. No se creó ningún pago.	`false`
409	`quote_expired`	La cotización `quote_id` venció.	`false`
409	`idempotency_in_progress`	Una petición anterior con esa clave sigue en curso. Llega con `Retry-After`.	`true`
413	`invalid_request`	El cuerpo supera 64 KB.	`false`
422	`beneficiary_not_approved`	El beneficiario existe pero no está `approved`.	`true`
422	`rail_unavailable`	El riel no está disponible por ahora.	`true`
422	`currency_not_supported`	`currency` no es la moneda del riel del beneficiario.	`false`
422	`in_review`	Una revisión frena la operación. Con `retryable: true` se frenó antes de ejecutar y no hay `pay_`. Con `retryable: false` quedó registrado: el pago queda `failed` con `failure_code: in_review`.	`true`
422	`insufficient_funds`	Saldo insuficiente. El rechazo queda registrado con esa clave.	`false`
422	`limit_exceeded`	Se superó un límite del riel. El rechazo queda registrado con esa clave.	`false`
422	`amount_below_minimum`	El monto está por debajo del mínimo aplicable. El rechazo queda registrado con esa clave.	`false`
422	`payment_rejected`	El pago se rechazó sin un motivo más específico. El rechazo queda registrado con esa clave.	`false`
422	`idempotency_key_reused`	Usaste esa clave con otro cuerpo, también pasados 7 días.	`false`
422	`invalid_beneficiary` (sólo cuenta de prueba)	El beneficiario se dio de baja, o usaste el escenario `invalid_beneficiary`.	`false`
422	`limit_exceeded` (sólo cuenta de prueba)	El monto supera 1,000,000 ficticios por pago.	`false`
429	`rate_limited`	Superaste un límite de peticiones. Llega con `Retry-After`.	`true`
429	`sandbox_limit` (sólo cuenta de prueba)	Alcanzaste 100 pagos y cobros de hoy.	`false`
500	`internal_error`	Fallo nuestro. El resultado de la petición no se conoce.	`true`
503	`service_unavailable`	El servicio no está disponible por ahora. El resultado de la petición no se conoce.	`true`

Ejemplos de error

400 invalid_request:

{
  "error": {
    "code": "invalid_request",
    "message": "Petición inválida",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {
      "fields": {
        "amount": "Valor inválido"
      }
    },
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request"
  }
}

401 invalid_api_key:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Credencial inválida",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key"
  }
}

403 rail_not_enabled:

{
  "error": {
    "code": "rail_not_enabled",
    "message": "Operación rechazada",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#rail_not_enabled"
  }
}

404 not_found:

{
  "error": {
    "code": "not_found",
    "message": "No encontrado",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found"
  }
}

409 payment_in_flight:

{
  "error": {
    "code": "payment_in_flight",
    "message": "Operación rechazada",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#payment_in_flight"
  }
}

413 invalid_request:

{
  "error": {
    "code": "invalid_request",
    "message": "Petición inválida",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request"
  }
}

422 beneficiary_not_approved:

{
  "error": {
    "code": "beneficiary_not_approved",
    "message": "Operación rechazada",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#beneficiary_not_approved"
  }
}

429 rate_limited:

{
  "error": {
    "code": "rate_limited",
    "message": "Demasiadas peticiones",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited"
  }
}

500 internal_error:

{
  "error": {
    "code": "internal_error",
    "message": "Error interno",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error"
  }
}

503 service_unavailable:

{
  "error": {
    "code": "service_unavailable",
    "message": "Servicio no disponible",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable"
  }
}

Reintentos

Ante un timeout o una conexión cortada, repite con la misma clave: nunca crea un segundo pago. Un error con retryable: false quedó registrado o no se arregla repitiendo: la misma clave repite ese rechazo, así que corrige la causa y usa una clave nueva. Ver Qué hacer con la clave tras un rechazo.

409 payment_in_flight: Repite con la misma clave cuando la otra salida se resuelva.
409 idempotency_in_progress: Espera Retry-After y repite con la misma clave.
422 beneficiary_not_approved: Apruébalo en el panel y repite con la misma clave.
422 rail_unavailable: Repite más tarde.
422 in_review: Mira retryable. Con true, repite con la misma clave cuando la revisión se levante. Con false, el rechazo quedó registrado y esa clave lo repite: usa una clave nueva tras la revisión.
429 rate_limited: Espera lo que indique Retry-After y repite.
500 internal_error: Repite con espera exponencial.
503 service_unavailable: Repite con espera exponencial. Respeta Retry-After si viene.

Ver Reintentos y Límites.

Muestras

Variables de estas muestras: simulador público, sin cuenta

Define esto en tu terminal. Con estos valores las muestras corren tal cual contra el simulador público:

export FITAL_API="https://widget.fital.xyz/explorar/v1"
export FITAL_KEY="sk_test_sandbox_publica"
export FITAL_SIGNING_SECRET="secreto_de_firma_de_prueba_publico"

En la cuenta de prueba o en producción cambia la base, la llave y el secreto, y sustituye los id de ejemplo por los tuyos. Ver Ambientes.

op-crear-pago.sh

CUERPO='{"beneficiary_id":"ben_3kTMd9wQp2LxZ7vR1nYcA4bE","amount":"1500.00","currency":"MXN","external_ref":"factura-1042"}'
CLAVE="ejemplo-crear-pago"
TS=$(date +%s)
HASH=$(printf '%s' "$CUERPO" | openssl dgst -sha256 -r | cut -d' ' -f1)
FIRMA=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" POST /v1/payments "$HASH" "$CLAVE" \
  | openssl dgst -sha256 -hmac "$FITAL_SIGNING_SECRET" -r | cut -d' ' -f1)
curl -sS -X POST "$FITAL_API/payments" \
  -H "Authorization: Bearer $FITAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CLAVE" \
  -H "X-Fital-Timestamp: $TS" \
  -H "X-Fital-Signature: v1=$FIRMA" \
  -d "$CUERPO"

Guías

Ver esta página en Markdown

Encabezados de la peticiónCopiar enlace

CuerpoCopiar enlace

Respuestas correctasCopiar enlace

202 Aceptado: el resultado final llega despuésCopiar enlace

Valores de failure_codeCopiar enlace

Valores de freshness.statusCopiar enlace

Valores de statusCopiar enlace

Encabezados de la respuestaCopiar enlace

ErroresCopiar enlace

Ejemplos de errorCopiar enlace

ReintentosCopiar enlace

MuestrasCopiar enlace

GuíasCopiar enlace

En esta página