Tu primer pago de prueba

Al terminar habrás consultado un saldo, creado un pago y leído su estado final, todo contra el simulador público. No necesitas cuenta. El simulador responde ejemplos fijos: enseña la forma de la API, no guarda nada entre llamadas.

1. Prepara tus variablesCopiar enlace

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"

Esta llave y este secreto son públicos y sólo sirven en el simulador. Tus llaves reales nunca van aquí.

2. Consulta tus saldosCopiar enlace

curl -sS "$FITAL_API/balances" -H "Authorization: Bearer $FITAL_KEY"

3. Crea un pagoCopiar enlace

Un pago es una escritura de dinero: lleva Idempotency-Key y firma. La clave sale de tu identificador interno, para que un reinicio de tu proceso repita la misma clave y no pague dos veces.

CUERPO='{"beneficiary_id":"ben_3kTMd9wQp2LxZ7vR1nYcA4bE","amount":"1500.00","currency":"MXN","external_ref":"factura-1042"}'
CLAVE="pago-factura-1042"
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"

Un 202 con processing significa que el pago se aceptó y sigue en curso. No es un fallo.

4. Consulta el pagoCopiar enlace

Con X-Fital-Scenario pides al simulador la respuesta que quieres practicar. Aquí, el estado final:

curl -sS "$FITAL_API/payments/pay_6nRtY1wKs3QzD8cL5mVhF2gB" \
  -H "Authorization: Bearer $FITAL_KEY" \
  -H "X-Fital-Scenario: payment_completed"

5. Practica un errorCopiar enlace

Repite el POST del paso 3 con un encabezado más, X-Fital-Scenario: insufficient_funds, y otra clave de idempotencia. Va en el POST porque el saldo se revisa al crear el pago: en el GET del paso 4 este escenario no aplica.

CUERPO='{"beneficiary_id":"ben_3kTMd9wQp2LxZ7vR1nYcA4bE","amount":"1500.00","currency":"MXN","external_ref":"factura-1043"}'
CLAVE="pago-factura-1043"
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" \
  -H "X-Fital-Scenario: insufficient_funds" \
  -d "$CUERPO"

Responde 422 con error.code en insufficient_funds y retryable en false: decide con code y guarda request_id. La lista completa de escenarios, y a qué operación va cada uno, está en Ambientes.

Errores comunesCopiar enlace

• 401 invalid_signature en la cuenta de prueba o en producción: la firma cubre el cuerpo exacto que envías. Firma los mismos bytes.
• Cambiar la clave de idempotencia al reintentar: crea otra operación. Reintenta siempre con la misma.

Qué sigueCopiar enlace

Prueba con estado real en el inicio rápido de la cuenta de prueba. Necesitas acceso al panel, en merchants.fital.xyz: entran las empresas con KYB aprobado en empresa.fital.xyz. Si tu empresa aún no tiene cuenta, regístrala ahí y completa el KYB. Entiende el modelo en Conceptos y las diferencias entre ambientes en Ambientes.

Ver esta página en Markdown