Avanzar un pago ficticio

Lleva un pago de sandbox a otro estado sin esperar su guion, y emite el evento firmado de ese cambio. Exige Idempotency-Key y firma. Sólo existe en sandbox: en producción da 404.

Dato	Valor
Método y ruta	`POST /sandbox/v1/payments/{id}/advance`
Servidor	`https://widget.fital.xyz/sandbox`
`operationId`	`advanceSandboxPayment`
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
Ambiente	Sólo existe en la cuenta de prueba. En producción responde `404`

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.

Parámetros

Parámetro	En	Tipo	Obligatorio	Descripción
`id`	ruta	texto	Sí	Identificador del recurso. Hasta 250 caracteres.

Cuerpo

Campo	Tipo	Obligatorio	Descripción
`status`	texto	Sí	Estado al que quieres llevar el pago ficticio. `completed`: Termina el pago. Viene de `processing` o `in_review`. `failed`: Falla el pago. Viene de `processing` o `in_review`. `returned`: Devuelve el pago. Viene de `completed`. `in_review`: Lo pasa a revisión. Viene de `processing`.

{
  "status": "completed"
}

Valores de `status`

Valor	Significado
`completed`	Termina el pago. Viene de `processing` o `in_review`.
`failed`	Falla el pago. Viene de `processing` o `in_review`.
`returned`	Devuelve el pago. Viene de `completed`.
`in_review`	Lo pasa a revisión. Viene de `processing`.

Respuestas correctas

200 Correcto

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": "1500.00",
  "final_currency": "MXN",
  "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "livemode": false,
  "metadata": {},
  "reference": null,
  "status": "completed"
}

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.
`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 parámetro o campo no cumple el esquema. Mira `details.fields`.	`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	`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`
404	`not_found`	El pago no existe o es de otra empresa.	`false`
409	`sandbox_invalid_transition`	Un pago real no puede hacer ese cambio.	`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	`insufficient_funds`	Llevar a `completed` un pago aún sin débito requiere saldo ficticio.	`false`
422	`idempotency_key_reused`	Usaste esa clave con otro cuerpo, también pasados 7 días.	`false`
429	`rate_limited`	Superaste un límite de peticiones. Llega con `Retry-After`.	`true`
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": {
        "status": "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 forbidden_scope:

{
  "error": {
    "code": "forbidden_scope",
    "message": "La llave no tiene permiso para esta operación",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {
      "required_scope": "payments:write"
    },
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope"
  }
}

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 sandbox_invalid_transition:

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

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 insufficient_funds:

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

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.

409 idempotency_in_progress: Espera Retry-After y repite con la misma clave.
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: cuenta de prueba, con tu llave

Define esto en tu terminal, con tu llave de prueba:

export FITAL_API="https://widget.fital.xyz/sandbox/v1"
export FITAL_KEY="sk_test_fital_..."
export FITAL_SIGNING_SECRET="el secreto de firma de esa llave"

Sustituye los id de ejemplo por los tuyos. Ver Inicio rápido de la cuenta de prueba.

CUERPO='{"status":"completed"}'
CLAVE="ejemplo-avanzar-pago-de-prueba"
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/pay_6nRtY1wKs3QzD8cL5mVhF2gB/advance "$HASH" "$CLAVE" \
  | openssl dgst -sha256 -hmac "$FITAL_SIGNING_SECRET" -r | cut -d' ' -f1)
curl -sS -X POST "$FITAL_API/payments/pay_6nRtY1wKs3QzD8cL5mVhF2gB/advance" \
  -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

Avanzar un pago ficticio

Encabezados de la peticiónCopiar enlace

ParámetrosCopiar enlace

CuerpoCopiar enlace

Valores de statusCopiar enlace

Respuestas correctasCopiar enlace

200 CorrectoCopiar 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

Encabezados de la petición

Parámetros

Cuerpo

Valores de `status`

Respuestas correctas

200 Correcto

Valores de `failure_code`

Valores de `freshness.status`

Valores de `status`

Encabezados de la respuesta

Errores

Ejemplos de error

Reintentos

Muestras

Guías