Inicio rápido de la cuenta de prueba

Al terminar habrás creado un pago ficticio en tu cuenta de prueba, lo habrás visto llegar a completed y sabrás forzar otros desenlaces. Nada mueve dinero. Si aún no tienes cuenta, empieza por Tu primer pago de prueba, que corre sin registro.

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.

1. Crea tu llaveCopiar enlace

En el panel elige el ambiente Sandbox y, en la pantalla Llaves, Crear llave de API. Dale al menos estos scopes: balances:read, beneficiaries:read, payments:read y payments:write. Guarda la llave y su secreto de firma: se muestran una sola vez.

2. Prepara tus variablesCopiar enlace

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"

3. Mira tu saldo ficticioCopiar enlace

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

Tu cuenta nace con saldo ficticio en MXN y USD.

4. Elige un beneficiarioCopiar enlace

La cuenta ya trae beneficiarios aprobados. Cada uno termina sus pagos de una forma: el nombre lo dice.

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

Mientras el pago a PROVEEDOR FICTICIO INCIERTO sigue sin confirmar, cualquier otro pago de tu empresa responde 409 payment_in_flight. Para seguir sin esperar, llévalo a completed con POST /sandbox/v1/payments/{id}/advance.

La respuesta da sólo el id: la pantalla Sandbox del panel muestra el nombre de cada uno. Guarda en BENEFICIARIO el id del de éxito:

export BENEFICIARIO="ben_..."

5. Crea un pagoCopiar enlace

REF="mi-primer-pago"
CUERPO=$(printf '{"beneficiary_id":"%s","amount":"100.00","currency":"MXN","external_ref":"%s"}' "$BENEFICIARIO" "$REF")
CLAVE="pago-$REF-$BENEFICIARIO"
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"

Responde 202 con status: processing y un id con prefijo pay_. La clave de idempotencia sale de tu referencia y del beneficiario: si corres esto otra vez, recibes el mismo pago, con Idempotent-Replayed: true, y no uno nuevo. Para crear otro pago, cambia la referencia. Ver Idempotencia.

Guarda el id:

export PAGO="pay_..."

6. Míralo terminarCopiar enlace

Espera unos 30 segundos y consúltalo:

curl -sS "$FITAL_API/payments/$PAGO" \
  -H "Authorization: Bearer $FITAL_KEY"

status llega en completed. Si sigue en processing, espera unos segundos y consulta otra vez, o llévalo a completed con el paso 7. Si tienes un destino de webhook, también recibes payment.completed.

7. Fuerza otro desenlaceCopiar enlace

Sin esperar su guion, lleva un pago a otro estado con POST /sandbox/v1/payments/{id}/advance. O provoca un error al crear el pago con X-Fital-Scenario. La lista está en Ambientes.

Errores comunesCopiar enlace

• 401 wrong_environment: usas una llave de otro ambiente. Aquí va tu llave sk_test_fital_…, no la llave pública del simulador.
• 401 invalid_signature: firmaste la ruta con /sandbox. Se firma siempre /v1/....
• 403 forbidden_scope: a tu llave le falta un scope. details.required_scope lo nombra.
• 409 payment_in_flight: otro pago de tu empresa sigue sin confirmarse. Termínalo con el paso 7 o espera a que se resuelva.
• 404 not_found: el id no es de un beneficiario de tu cuenta.
• 422 invalid_beneficiary: el beneficiario se dio de baja.

Qué sigueCopiar enlace

Cuenta de prueba e Inicio rápido de webhooks.

Ver esta página en Markdown