Costa Rica — recetas de integración

El rail cableado en el endpoint /payments de pagos alternativos para Costa Rica es QuickPay QR.

Setup (hazlo una sola vez)

Todas las recetas asumen las variables de abajo. Configúralas en tu shell antes de ejecutar cualquier curl. El host (sb-mw.migopayments.com) y el path (/api/v1/integrations/...) son el sandbox público alcanzable por integradores externos. Las rutas de Pagos Alternativos aceptan el token de comercio de larga duración de 64 caracteres como token Bearer — ve Autenticación → Formato del header por endpoint.

export MIGO_BASE="https://sb-mw.migopayments.com"
export MIGO_CLIENT="<your-client-slug>"
export MIGO_TOKEN="<your-64-char-merchant-token>" # 64 hex chars
export MIGO_USER_ID="+50600000000"

export UID=$(
  curl -s -X POST "$MIGO_BASE/api/v1/integrations/transactions" \
    -H "Authorization: Bearer $MIGO_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"amount\": 250000,
      \"channel\": \"web\",
      \"client\": \"$MIGO_CLIENT\",
      \"userId\": \"$MIGO_USER_ID\",
      \"customKeys\": { \"orderId\": \"recipe-test\" }
    }" | jq -r '.data.uid'
)

Inspecciona los paymentMethods retornados para confirmar qué rails tiene habilitados tu cliente (resueltos en runtime desde clientConfig.processors).

---

QuickPay QR (quickPayQR)

País: Costa Rica (también GT, SV, HN) · Tipo: Agregador QR interbancario · payment-intents previo: No · Payload de respuesta: json.

curl -X POST "$MIGO_BASE/api/v1/integrations/transactions/$UID/payments" \
  -H "Authorization: Bearer $MIGO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "processor": "quickPayQR", "data": {} }'

Respuesta — el type y data vienen directo del paymentRequest del procesador:

{
  "success": true,
  "message": "Success",
  "data": {
    "transaction_id": "…",
    "type": "<paymentRequest.type>",
    "data": "<paymentRequest.data>",
    "cancelAt": null
  }
}

quickPayQR soporta revert vía POST $MIGO_BASE/revert con body {"transactionUid":"$UID","processor":"quickPayQR"} (esquema JWT-Bearer, separado de esta superficie de token de comercio).

Checklist de hecho

• Payload del QR renderizado desde data.data.
• El webhook llega tras el escaneo.

---

Errores comunes a todos los rails

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 (amount, channel, client, userId, customKeys, o processor)
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 final

• Token de comercio enviado como Authorization: Bearer $MIGO_TOKEN; transacción creada.
• Cada rail disponible de arriba probado en sandbox.