Plantilla de receta

Esta es la estructura canónica para cualquier receta de país. Cópiala tal cual al agregar un nuevo mercado o rail. La estructura es lo que hace que las recetas sean consumibles tanto por humanos como por agentes de integración.

## {Nombre del rail} (`processorKey`)

> **País:** … · **Tipo:** … · **`payment-intents` previo:** … · **Payload de respuesta:** `url` | `qr` | `html` | `payButton` | `json`.

### Prerrequisitos

- El `clientConfig.processors` del comercio incluye `processorKey`.
- Tienes el token de comercio de larga duración de 64 caracteres (ve [Autenticación → Token del comercio](/introduction/authentication#merchant-token)). Pagos Alternativos lo acepta como `Authorization: Bearer <token>`.
- Campos requeridos al usuario: …

### Paso 1 — Crear la transacción

`​`​`bash
curl -X POST https://sb-mw.migopayments.com/api/v1/integrations/transactions \
  -H "Authorization: Bearer $MIGO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1000, "channel": "web", "client": "your-client-slug", "userId": "+50200000000", "customKeys": { "orderId": "…" } }'
`​`​`

Campos requeridos: `amount`, `channel`, `client`, `userId`, `customKeys`. Respuesta esperada (resumida):

`​`​`json
{
  "success": true,
  "data": {
    "uid": "trx_…",
    "paymentMethods": [ "processorKey", … ]
  }
}
`​`​`

### Paso 2 — (Solo si aplica) Obtener payment intent

`​`​`bash
curl -X POST https://sb-mw.migopayments.com/api/v1/integrations/transactions/$UID/payment-intents \
  -H "Authorization: Bearer $MIGO_TOKEN" \
  -d '{ "processor": "processorKey" }'
`​`​`

Retorna los metadatos que tu frontend necesita (bancos, sesiones). El handler de `payment-intents` solo trata de forma especial a unos pocos procesadores (`globalPay-PSE`, `fri`, `nequi`); los demás retornan `{ "success": true, "data": null }`.

### Paso 3 — Procesar el pago

`​`​`bash
curl -X POST https://sb-mw.migopayments.com/api/v1/integrations/transactions/$UID/payments \
  -H "Authorization: Bearer $MIGO_TOKEN" \
  -d '{ "processor": "processorKey", "data": { … } }'
`​`​`

El envoltorio de éxito es `{ "success": true, "message": "…", "data": { … } }`. Lee el payload del rail desde `data.data` (y llaves específicas del procesador como `data.html` para `globalPay-PSE`). No hay un campo `statusCode` de nivel superior en el body JSON.

### Paso 4 — Entrega del estado

El estado del pago se entrega a través del callback del comercio que configuras en `clientConfig.callback` — el payload es lo que defina tu plantilla `data` de callback, no un envoltorio fijo de la plataforma. Ve [Merchant Generic Callback](/card-payments/merchant-generic-callback).

> Hoy no existe un firmador de webhook saliente en el código — la plataforma no emite actualmente un header `X-Migo-Signature`.

### Datos de sandbox

- `…`

### Errores comunes

El middleware de pagos alternativos lanza own-codes de 4 dígitos (no el catálogo `7xxx` del ALI Gateway):

| HTTP | own-code | Cuándo |
|---|---|---|
| 400 | `5000` | Params faltantes/inválidos |
| 400 | — | `processor` no permitido para este cliente |
| 400 | `5004` | Config del cliente no encontrada |
| 400 | `2002` | Falló la creación de la transacción |
| 400 | `2003` | Monto fuera del rango permitido |

### Checklist de hecho

- [ ] `POST .../transactions` retornó `processorKey` en `paymentMethods`.
- [ ] `POST .../payments` retornó el `data.type` esperado, payload leído de `data.data`.
- [ ] El frontend renderizó la superficie correcta.
- [ ] Callback del comercio recibido con el estado esperado en sandbox.

Las páginas de país concatenan uno de estos bloques por rail; el header de país en la cima pre-rellena la sección de auth/setup una sola vez para toda la página.