FITALAPI
Referencia por operación

Un pago

GET /v1/payments/{id}

Un pago de tu empresa. completed exige confirmación del riel. freshness dice de dónde sale el estado: con current es la lectura de ahora y as_of su hora; con delayed no hubo lectura concluyente y es lo último que se sabe, a la hora de as_of. Una cancelación confirmada responde canceled con delayed hasta que una lectura la confirme. Si un pago cancelado vuelve a processing con current, se reabrió de verdad.

DatoValor
Método y rutaGET /v1/payments/{id}
Servidorhttps://widget.fital.xyz
operationIdgetPayment
AccesoLlave con el scope payments:read
Firma de peticiónNo aplica
IdempotenciaNo aplica
  • freshness sólo existe aquí. Con delayed, consulta otra vez más tarde. Ver Frescura del detalle.
  • Con failed, failure_code siempre trae un código: payment_rejected si no hay uno más específico o si el detalle ya no se puede leer. En cualquier otro estado es null.

Encabezados de la petición

EncabezadoObligatorioDescripción
AuthorizationSíBearer y tu llave.
X-Fital-ScenarioNoSólo simuladores: elige la respuesta que quieres practicar.

Parámetros

ParámetroEnTipoObligatorioDescripción
idrutatextoSíIdentificador del recurso. Hasta 250 caracteres.

Respuestas correctas

200 Correcto

CampoTipoObligatorioDescripción
amounttexto o nullSíMonto pedido.
beneficiary_idtexto o nullSíBeneficiario del pago.
created_attexto o nullSíFecha de creación. ISO 8601 en UTC.
currencytexto o nullSíMoneda pedida.
external_reftexto o nullSíTu referencia.
failure_codetexto o nullSí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_amounttexto o nullSíMonto final, cuando se conoce.
final_currencytexto o nullSíMoneda del monto final.
freshnessobjetoNoDe dónde sale status. Sólo en GET /v1/payments/{id}.
freshness.as_oftexto o nullSí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.statustextoSí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.
idtextoSíIdentificador del pago, con prefijo pay_.
metadataobjetoSíLos pares que enviaste al crear el pago.
referencetexto o nullSíConcepto del pago.
statustextoSí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

ValorSignificado
payment_rejectedRechazado sin un motivo más específico.
insufficient_fundsSaldo insuficiente al ejecutar.
limit_exceededSe superó el tope acumulado de la empresa o un límite del riel.
amount_below_minimumEl monto quedó por debajo del mínimo aplicable.
account_restrictedLa cuenta tiene una restricción.
in_reviewUna revisión detuvo la ejecución.
quote_changedEl débito superaría lo permitido.
quote_expiredLa 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

ValorSignificado
currentstatus sale de una lectura de ahora.
delayedLa lectura no concluyó y status es lo último que se sabe. No lo tomes como un resultado nuevo.

Valores de status

ValorSignificado
processingAceptado y en curso, o aún sin confirmar. Consúltalo hasta un estado terminal.
in_reviewEn revisión. No lo repitas: el pago ya existe.
completedSe pagó. Aún puede pasar a returned.
failedNo se hizo y no queda dinero en tránsito.
returnedSe devolvió y el saldo ya volvió.
canceledSe canceló antes de ejecutarse.
{
  "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "status": "processing",
  "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "amount": "1500.00",
  "currency": "MXN",
  "final_amount": null,
  "final_currency": null,
  "reference": "Factura 1042",
  "external_ref": "factura-1042",
  "metadata": {},
  "failure_code": null,
  "created_at": "2026-11-04T18:00:00.000Z",
  "freshness": {
    "status": "current",
    "as_of": "2026-11-04T18:00:00.000Z"
  }
}

processing con delayed: la lectura no concluyó:

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

En revisión: no lo repitas:

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

failed, con su código:

{
  "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "status": "failed",
  "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "amount": "1500.00",
  "currency": "MXN",
  "final_amount": null,
  "final_currency": null,
  "reference": "Factura 1042",
  "external_ref": "factura-1042",
  "metadata": {},
  "failure_code": "insufficient_funds",
  "created_at": "2026-11-04T18:00:00.000Z",
  "freshness": {
    "status": "current",
    "as_of": "2026-11-04T18:00:00.000Z"
  }
}

returned: se devolvió después de completed:

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

canceled con delayed: falta la lectura que lo confirme:

{
  "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "status": "canceled",
  "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "amount": "1500.00",
  "currency": "MXN",
  "final_amount": null,
  "final_currency": null,
  "reference": "Factura 1042",
  "external_ref": "factura-1042",
  "metadata": {},
  "failure_code": null,
  "created_at": "2026-11-04T18:00:00.000Z",
  "freshness": {
    "status": "delayed",
    "as_of": "2026-11-04T18:01:30.000Z"
  }
}

Variante payment_completed:

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

Variante payment_failed:

{
  "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB",
  "status": "failed",
  "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "amount": "1500.00",
  "currency": "MXN",
  "final_amount": null,
  "final_currency": null,
  "reference": "Factura 1042",
  "external_ref": "factura-1042",
  "metadata": {},
  "failure_code": "payment_rejected",
  "created_at": "2026-11-04T18:00:00.000Z",
  "freshness": {
    "status": "current",
    "as_of": "2026-11-04T18:00:00.000Z"
  }
}

Variante payment_returned:

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

Encabezados de la respuesta

EncabezadoContenido
X-Request-IdIdentificador de la petición. Cítalo con soporte.
Retry-AfterSegundos a esperar, con 429 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.

HTTPCódigoCuándo saleretryable
400invalid_requestAlgún parámetro o campo no cumple el esquema. Mira details.fields.false
401invalid_api_keyLa llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida.false
401wrong_environmentLa llave es de otro ambiente.false
403forbidden_scopeLa llave no tiene el scope de esta operación. details.required_scope lo nombra.false
403ip_not_allowedLa IP de origen no está activa en la lista de esa llave.false
403kyb_requiredLa empresa no tiene KYB aprobado o aún no está inscrita.false
403account_not_activeLa cuenta no está activa.false
404not_foundEl pago no existe o es de otra empresa.false
429rate_limitedSuperaste un límite de peticiones. Llega con Retry-After.true
500internal_errorFallo nuestro. El resultado de la petición no se conoce.true
503service_unavailableEl 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": {
        "limit": "Entre 1 y 100"
      }
    },
    "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:read"
    },
    "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"
  }
}

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

Es una lectura: repetirla no tiene efecto.

  • 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"

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-consultar-pago.sh
curl -sS "$FITAL_API/payments/pay_6nRtY1wKs3QzD8cL5mVhF2gB" \
  -H "Authorization: Bearer $FITAL_KEY"

Guías

Ver esta página en Markdown

Crear un pago

POST /v1/payments

Cancelar un pago que aún espera fondos

POST /v1/payments/{id}/cancel

En esta página

Encabezados de la peticiónParámetrosRespuestas correctas200 CorrectoValores de failure_codeValores de freshness.statusValores de statusEncabezados de la respuestaErroresEjemplos de errorReintentosMuestrasGuías