# Alta de beneficiario, pendiente de aprobar en el panel

POST /v1/beneficiaries

Da de alta una cuenta destino. Nace pendiente y se aprueba en el panel, nunca por API: una llave robada no paga a un destino nuevo. Exige `Idempotency-Key` y firma. 201 si el alta quedó registrada; 202 si aún no se confirma: repite con la misma clave.

| Dato | Valor |
|---|---|
| Método y ruta | `POST /v1/beneficiaries` |
| Servidor | `https://widget.fital.xyz` |
| `operationId` | `createBeneficiary` |
| Acceso | Llave con el scope `beneficiaries: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](/docs/autenticacion/#firma-de-petición) |
| Idempotencia | **Obligatoria**, con `Idempotency-Key`. Ver [Idempotencia](/docs/idempotencia/) |

- `rail` decide qué campos se piden: cada variante del cuerpo tiene los suyos.
- En `latam`, `entity`, `account_type`, `document_type` y `document` dependen del país: [`GET /v1/latam/countries`](/docs/operaciones/listar-paises-latam/) dice qué pide cada uno. En `pix`, `document` es opcional.
- Si la misma cuenta ya estaba registrada, la respuesta trae el beneficiario que ya existe, con su `id` y su estado. Guarda el `id` que recibes, no el que esperabas.
- `202` significa que el alta aún no se confirma: el `id` ya es válido y `rail`, `country` y `created_at` llegan en `null`. Repite con la misma clave, o consulta el `id`.
- El beneficiario nace `pending_approval` y se aprueba en el panel, nunca por API. En la cuenta de prueba nace `approved`.

## 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

### Con `rail: mxn_spei`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `clabe` | texto | Sí | CLABE de 18 dígitos. |
| `holder_name` | texto | Sí | Titular de la cuenta destino. Hasta 140 caracteres. |
| `rail` | texto | Sí | Riel de pago. Decide qué campos se piden. `mxn_spei`: SPEI, en México. |

```json
{
  "rail": "mxn_spei",
  "holder_name": "PROVEEDOR FICTICIO SA DE CV",
  "clabe": "999180000000000011"
}
```

### Con `rail: usd_ach`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `account_number` | texto | Sí | Número de cuenta, de 4 a 17 dígitos. |
| `account_type` | texto | Sí | Tipo de cuenta. `checking`: Cuenta de cheques o corriente. `savings`: Cuenta de ahorro. |
| `address` | objeto | Sí | Domicilio del titular. |
| `address.city` | texto | Sí | Ciudad. Hasta 100 caracteres. |
| `address.country` | texto | Sí | País, en código de 3 letras. 3 caracteres. |
| `address.postal_code` | texto | Sí | Código postal. Hasta 20 caracteres. |
| `address.state` | texto | Sí | Estado o provincia. Hasta 100 caracteres. |
| `address.street_line_1` | texto | Sí | Calle y número. De 4 a 35 caracteres. |
| `holder_name` | texto | Sí | Titular de la cuenta destino. Hasta 140 caracteres. |
| `rail` | texto | Sí | Riel de pago. Decide qué campos se piden. `usd_ach`: ACH, en Estados Unidos. |
| `routing_number` | texto | Sí | Número de ruta, 9 dígitos. |

```json
{
  "rail": "usd_ach",
  "holder_name": "PROVEEDOR FICTICIO LLC",
  "routing_number": "999999999",
  "account_number": "000123456789",
  "account_type": "checking",
  "address": {
    "street_line_1": "100 Calle Ficticia",
    "city": "Ciudad Ficticia",
    "state": "TX",
    "postal_code": "00000",
    "country": "USA"
  }
}
```

### Con `rail: usd_wire`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `account_number` | texto | Sí | Número de cuenta, de 4 a 17 dígitos. |
| `account_type` | texto | Sí | Tipo de cuenta. `checking`: Cuenta de cheques o corriente. `savings`: Cuenta de ahorro. |
| `address` | objeto | Sí | Domicilio del titular. |
| `address.city` | texto | Sí | Ciudad. Hasta 100 caracteres. |
| `address.country` | texto | Sí | País, en código de 3 letras. 3 caracteres. |
| `address.postal_code` | texto | Sí | Código postal. Hasta 20 caracteres. |
| `address.state` | texto | Sí | Estado o provincia. Hasta 100 caracteres. |
| `address.street_line_1` | texto | Sí | Calle y número. De 4 a 35 caracteres. |
| `holder_name` | texto | Sí | Titular de la cuenta destino. Hasta 140 caracteres. |
| `rail` | texto | Sí | Riel de pago. Decide qué campos se piden. `usd_wire`: Wire, en Estados Unidos. |
| `routing_number` | texto | Sí | Número de ruta, 9 dígitos. |

```json
{
  "rail": "usd_wire",
  "holder_name": "PROVEEDOR FICTICIO LLC",
  "routing_number": "999999999",
  "account_number": "000123456789",
  "account_type": "checking",
  "address": {
    "street_line_1": "100 Calle Ficticia",
    "city": "Ciudad Ficticia",
    "state": "TX",
    "postal_code": "00000",
    "country": "USA"
  }
}
```

### Con `rail: eur_sepa`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `bic` | texto | Sí | Código BIC del banco. De 8 a 11 caracteres. |
| `holder_name` | texto | Sí | Titular de la cuenta destino. Hasta 140 caracteres. |
| `iban` | texto | Sí | IBAN de la cuenta. De 15 a 34 caracteres. |
| `iban_country` | texto | Sí | País del IBAN, en código de 3 letras. 3 caracteres. |
| `rail` | texto | Sí | Riel de pago. Decide qué campos se piden. `eur_sepa`: SEPA, en la zona euro. |

```json
{
  "rail": "eur_sepa",
  "holder_name": "PROVEEDOR FICTICIO SL",
  "iban": "XX00FICTICIO0000000000",
  "bic": "FICTXXXX",
  "iban_country": "ESP"
}
```

### Con `rail: gbp_fps`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `account_number` | texto | Sí | Número de cuenta, 8 dígitos. |
| `holder_name` | texto | Sí | Titular de la cuenta destino. Hasta 140 caracteres. |
| `rail` | texto | Sí | Riel de pago. Decide qué campos se piden. `gbp_fps`: Faster Payments, en Reino Unido. |
| `sort_code` | texto | Sí | Sort code, 6 dígitos. |

```json
{
  "rail": "gbp_fps",
  "holder_name": "PROVEEDOR FICTICIO LTD",
  "account_number": "00000000",
  "sort_code": "000000"
}
```

### Con `rail: cop`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `bre_b_key` | texto | Sí | Llave Bre-B del titular. Hasta 100 caracteres. |
| `holder_name` | texto | Sí | Titular de la cuenta destino. Hasta 140 caracteres. |
| `rail` | texto | Sí | Riel de pago. Decide qué campos se piden. `cop`: Bre-B, en Colombia. |

```json
{
  "rail": "cop",
  "holder_name": "PROVEEDOR FICTICIO SAS",
  "bre_b_key": "llave-bre-b-de-ejemplo"
}
```

### Con `rail: pix`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `document` | texto | No | Documento del titular. Hasta 20 caracteres. |
| `holder_name` | texto | Sí | Titular de la cuenta destino. Hasta 140 caracteres. |
| `pix_key` | texto | Sí | Llave PIX del titular. Hasta 100 caracteres. |
| `rail` | texto | Sí | Riel de pago. Decide qué campos se piden. `pix`: PIX, en Brasil. |

```json
{
  "rail": "pix",
  "holder_name": "PROVEEDOR FICTICIO LTDA",
  "pix_key": "llave-pix-de-ejemplo",
  "document": "00000000000"
}
```

### Con `rail: latam`

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `account_number` | texto | Sí | Número de cuenta. `GET /v1/latam/countries` dice qué pide cada país. De 4 a 40 caracteres. |
| `account_type` | texto | No | Tipo de cuenta, si el país lo pide. `GET /v1/latam/countries` dice qué pide cada país. `checking`: Cuenta de cheques o corriente. `savings`: Cuenta de ahorro. |
| `country` | texto | Sí | País de la cuenta, en código de 2 letras. 2 caracteres. |
| `currency` | texto | Sí | Moneda de la cuenta, en código de 3 letras. 3 caracteres. |
| `document` | texto | No | Documento del titular, si el país lo pide. Hasta 30 caracteres. |
| `document_type` | texto | No | Tipo de documento del titular, si el país lo pide. `GET /v1/latam/countries` dice qué pide cada país. Hasta 20 caracteres. |
| `entity` | texto | No | Banco o entidad, si el país lo pide. Los valores salen de `GET /v1/latam/countries/{country}/entities`. Hasta 40 caracteres. |
| `holder_name` | texto | Sí | Titular de la cuenta destino. Hasta 140 caracteres. |
| `rail` | texto | Sí | Riel de pago. Decide qué campos se piden. `latam`: Transferencia local en otros países de América Latina. |

```json
{
  "rail": "latam",
  "holder_name": "PROVEEDOR FICTICIO SPA",
  "country": "CL",
  "currency": "CLP",
  "account_number": "00000000",
  "entity": "000",
  "document_type": "RUT",
  "document": "00000000-0"
}
```

### Valores de `rail`

| Valor | Significado |
|---|---|
| `mxn_spei` | SPEI, en México. Ver [Pago SPEI](/docs/recetas/pago-spei/). |
| `usd_ach` | ACH, en Estados Unidos. Ver [Pago ACH](/docs/recetas/pago-ach/). |
| `usd_wire` | Wire, en Estados Unidos. Ver [Pago wire](/docs/recetas/pago-wire/). |
| `eur_sepa` | SEPA, en la zona euro. Ver [Pago SEPA](/docs/recetas/pago-sepa/). |
| `gbp_fps` | Faster Payments, en Reino Unido. Ver [Pago FPS](/docs/recetas/pago-fps/). |
| `cop` | Bre-B, en Colombia. Ver [Pago Bre-B](/docs/recetas/pago-bre-b/). |
| `pix` | PIX, en Brasil. Ver [Pago PIX](/docs/recetas/pago-pix/). |
| `latam` | Transferencia local en otros países de América Latina. Ver [Pago LatAm](/docs/recetas/pago-latam/). |

### Valores de `account_type`

| Valor | Significado |
|---|---|
| `checking` | Cuenta de cheques o corriente. |
| `savings` | Cuenta de ahorro. |

## Respuestas correctas

### 201 Creado

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `country` | texto o `null` | Sí | País de la cuenta, si se conoce. |
| `created_at` | texto o `null` | Sí | Fecha de creación. ISO 8601 en UTC. |
| `id` | texto | Sí | Identificador del beneficiario, con prefijo `ben_`. |
| `rail` | texto o `null` | Sí | Riel del beneficiario. null mientras el alta no se confirme. `mxn_spei`: SPEI, en México. `usd_ach`: ACH, en Estados Unidos. `usd_wire`: Wire, en Estados Unidos. `eur_sepa`: SEPA, en la zona euro. `gbp_fps`: Faster Payments, en Reino Unido. `cop`: Bre-B, en Colombia. `pix`: PIX, en Brasil. `latam`: Transferencia local en otros países de América Latina. |
| `status` | texto | Sí | Sólo con `approved` se le puede pagar. La aprobación se hace en el panel. `processing`: El alta sigue en curso. `pending_approval`: Falta aprobarlo en el panel. `approved`: Ya se le puede pagar. `rejected`: No se aprobó. `deleted`: Se dio de baja. |

#### Valores de `rail`

| Valor | Significado |
|---|---|
| `mxn_spei` | SPEI, en México. |
| `usd_ach` | ACH, en Estados Unidos. |
| `usd_wire` | Wire, en Estados Unidos. |
| `eur_sepa` | SEPA, en la zona euro. |
| `gbp_fps` | Faster Payments, en Reino Unido. |
| `cop` | Bre-B, en Colombia. |
| `pix` | PIX, en Brasil. |
| `latam` | Transferencia local en otros países de América Latina. |

`null` mientras el alta no se confirme.

#### Valores de `status`

| Valor | Significado |
|---|---|
| `processing` | El alta sigue en curso. |
| `pending_approval` | Falta aprobarlo en el panel. |
| `approved` | Ya se le puede pagar. |
| `rejected` | No se aprobó. |
| `deleted` | Se dio de baja. |

```json
{
  "country": "MX",
  "created_at": "2026-11-04T18:00:00.000Z",
  "id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "rail": "mxn_spei",
  "status": "pending_approval"
}
```

### 202 Aceptado: el resultado final llega después

Misma forma que la respuesta anterior.

```json
{
  "country": null,
  "created_at": null,
  "id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE",
  "rail": null,
  "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](/docs/errores/): `error.code`, `message`, `request_id`, `details`, `retryable` y `docs_url`. Decide por `code`.

| HTTP | Código | Cuándo sale | `retryable` |
|---|---|---|---|
| 400 | [`invalid_request`](/docs/errores/#invalid_request) | Algún campo no cumple el esquema de su riel. En `usd_ach` y `usd_wire`, también si `address.street_line_1` no trae número de calle. | `false` |
| 400 | [`idempotency_key_required`](/docs/errores/#idempotency_key_required) | Falta `Idempotency-Key`. | `false` |
| 400 | [`idempotency_key_invalid`](/docs/errores/#idempotency_key_invalid) | La clave no mide entre 8 y 200 caracteres, o viene duplicada. | `false` |
| 401 | [`invalid_api_key`](/docs/errores/#invalid_api_key) | La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida. | `false` |
| 401 | [`wrong_environment`](/docs/errores/#wrong_environment) | La llave es de otro ambiente. | `false` |
| 401 | [`invalid_signature`](/docs/errores/#invalid_signature) | Falta la firma, no coincide o tiene más de 5 minutos. | `false` |
| 403 | [`account_restricted`](/docs/errores/#account_restricted) | La cuenta tiene una restricción. | `false` |
| 403 | [`rail_not_enabled`](/docs/errores/#rail_not_enabled) | El riel no está habilitado para tu empresa. En la cuenta de prueba, cualquier riel que no sea `mxn_spei`. | `false` |
| 403 | [`not_enabled`](/docs/errores/#not_enabled) | El riel `latam` no está activado para tu empresa. | `false` |
| 403 | [`forbidden_scope`](/docs/errores/#forbidden_scope) | La llave no tiene el scope de esta operación. `details.required_scope` lo nombra. | `false` |
| 403 | [`ip_not_allowed`](/docs/errores/#ip_not_allowed) | La IP de origen no está activa en la lista de esa llave. | `false` |
| 403 | [`kyb_required`](/docs/errores/#kyb_required) | La empresa no tiene KYB aprobado o aún no está inscrita. | `false` |
| 403 | [`account_not_active`](/docs/errores/#account_not_active) | La cuenta no está activa. | `false` |
| 409 | [`beneficiary_ref_conflict`](/docs/errores/#beneficiary_ref_conflict) | El identificador del alta ya existe. | `false` |
| 409 | [`idempotency_in_progress`](/docs/errores/#idempotency_in_progress) | Una petición anterior con esa clave sigue en curso. Llega con `Retry-After`. | `true` |
| 413 | [`invalid_request`](/docs/errores/#invalid_request) | El cuerpo supera 64 KB. | `false` |
| 422 | [`in_review`](/docs/errores/#in_review) | Una revisión de tu cuenta frena las altas nuevas. | `true` |
| 422 | [`invalid_beneficiary`](/docs/errores/#invalid_beneficiary) | El riel rechazó la cuenta destino por sus datos. En `latam`, también un número, banco, documento, moneda o tipo de cuenta que no cumple lo que pide el país: se responde al momento. | `false` |
| 422 | [`idempotency_key_reused`](/docs/errores/#idempotency_key_reused) | Usaste esa clave con otro cuerpo, también pasados 7 días. | `false` |
| 422 | [`sandbox_real_account_rejected`](/docs/errores/#sandbox_real_account_rejected) (sólo cuenta de prueba) | La CLABE no empieza con `999` o el titular no incluye `FICTICIO`. | `false` |
| 422 | [`limit_exceeded`](/docs/errores/#limit_exceeded) (sólo cuenta de prueba) | Ya tienes 20 beneficiarios. | `false` |
| 429 | [`rate_limited`](/docs/errores/#rate_limited) | Superaste un límite de peticiones. Llega con `Retry-After`. | `true` |
| 500 | [`internal_error`](/docs/errores/#internal_error) | Fallo nuestro. El resultado de la petición no se conoce. | `true` |
| 503 | [`service_unavailable`](/docs/errores/#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`:

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

`401 invalid_api_key`:

```json
{
  "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 account_restricted`:

```json
{
  "error": {
    "code": "account_restricted",
    "message": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#account_restricted"
  }
}
```

`409 beneficiary_ref_conflict`:

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

`413 invalid_request`:

```json
{
  "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 in_review`:

```json
{
  "error": {
    "code": "in_review",
    "message": "La operación está en revisión",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#in_review"
  }
}
```

`429 rate_limited`:

```json
{
  "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`:

```json
{
  "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`:

```json
{
  "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.
- `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](/docs/recetas/reintentos/) y [Límites](/docs/limites/).

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

```bash
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](/docs/ambientes/).

```bash
CUERPO='{"rail":"mxn_spei","holder_name":"PROVEEDOR FICTICIO SA DE CV","clabe":"999180000000000011"}'
CLAVE="ejemplo-crear-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/beneficiaries "$HASH" "$CLAVE" \
  | openssl dgst -sha256 -hmac "$FITAL_SIGNING_SECRET" -r | cut -d' ' -f1)
curl -sS -X POST "$FITAL_API/beneficiaries" \
  -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"
```

```js
import { createHash, createHmac } from 'node:crypto';
const cuerpo = JSON.stringify({"rail":"mxn_spei","holder_name":"PROVEEDOR FICTICIO SA DE CV","clabe":"999180000000000011"});
const clave = 'ejemplo-crear-beneficiario';
const ts = String(Math.floor(Date.now() / 1000));
const hash = createHash('sha256').update(cuerpo).digest('hex');
const firma = createHmac('sha256', process.env.FITAL_SIGNING_SECRET)
  .update([ts, 'POST', '/v1/beneficiaries', hash, clave].join('\n')).digest('hex');
const r = await fetch(`${process.env.FITAL_API}/beneficiaries`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FITAL_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': clave,
    'X-Fital-Timestamp': ts,
    'X-Fital-Signature': `v1=${firma}`,
  },
  body: cuerpo,
});
console.log(r.status, await r.json());
```

```python
import hashlib, hmac, json, os, time, urllib.error, urllib.request
cuerpo = json.dumps({"rail":"mxn_spei","holder_name":"PROVEEDOR FICTICIO SA DE CV","clabe":"999180000000000011"}).encode()
clave = "ejemplo-crear-beneficiario"
ts = str(int(time.time()))
canon = "\n".join([ts, "POST", "/v1/beneficiaries", hashlib.sha256(cuerpo).hexdigest(), clave])
firma = hmac.new(os.environ["FITAL_SIGNING_SECRET"].encode(), canon.encode(), hashlib.sha256).hexdigest()
pet = urllib.request.Request(os.environ["FITAL_API"] + "/beneficiaries", method="POST", data=cuerpo,
    headers={"Authorization": "Bearer " + os.environ["FITAL_KEY"],
             "Content-Type": "application/json",
             "Idempotency-Key": clave,
             "X-Fital-Timestamp": ts,
             "X-Fital-Signature": "v1=" + firma})
try:
    with urllib.request.urlopen(pet) as r:
        print(r.status, json.load(r))
except urllib.error.HTTPError as e:
    print(e.code, e.read().decode())
```

```php
<?php
$cuerpo = '{"rail":"mxn_spei","holder_name":"PROVEEDOR FICTICIO SA DE CV","clabe":"999180000000000011"}';
$clave = 'ejemplo-crear-beneficiario';
$ts = (string) time();
$canon = implode("\n", [$ts, 'POST', '/v1/beneficiaries', hash('sha256', $cuerpo), $clave]);
$firma = hash_hmac('sha256', $canon, getenv('FITAL_SIGNING_SECRET'));
$c = curl_init(getenv('FITAL_API') . '/beneficiaries');
curl_setopt_array($c, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('FITAL_KEY'),
    'Content-Type: application/json',
    'Idempotency-Key: ' . $clave,
    'X-Fital-Timestamp: ' . $ts,
    'X-Fital-Signature: v1=' . $firma,
  ],
  CURLOPT_POSTFIELDS => $cuerpo,
]);
echo curl_exec($c), "\n";
```

## Guías

- [Pago SPEI](/docs/recetas/pago-spei/)
- [Pago ACH](/docs/recetas/pago-ach/)
- [Pago wire](/docs/recetas/pago-wire/)
- [Pago SEPA](/docs/recetas/pago-sepa/)
- [Pago FPS](/docs/recetas/pago-fps/)
- [Pago Bre-B](/docs/recetas/pago-bre-b/)
- [Pago PIX](/docs/recetas/pago-pix/)
- [Pago LatAm](/docs/recetas/pago-latam/)
- [Cobertura](/docs/cobertura/)
- [Autenticación](/docs/autenticacion/)
- [Lista de migración](/docs/migracion/)