Payment intents

Algunos rails alternativos necesitan una selección del lado del comercio antes de que el cliente pueda pagar — el comercio debe obtener metadatos específicos del procesador, como un fixture para usar al momento del pago o una lista de selección para mostrar en el checkout. Usa payment intents para obtener estos metadatos para el procesador elegido.

POST https://mw.migopayments.com/api/v1/integrations/transactions/{transactionId}/payment-intents

Consulta la entrada en el spec en vivo: POST /api/v1/integrations/transactions/{transactionId}/payment-intents.

Cuándo llamar: invoca este endpoint antes de /payments para procesadores que necesitan un fixture o lista de selección. En Guatemala puedes saltarlo para procesadores que solo requieren datos estáticos (zigi, bamPaymentButton, akisiQR, bancoIndustrial, quickPayQR, pronet).

Fuente de verdad. Los ids de procesador que puedes llamar aquí están restringidos por el array paymentMethods por transacción que retorna POST .../transactions — ese array, no ninguna lista de esta página, es la fuente de verdad en runtime de lo que tu cuenta puede usar.

Petición

Campo	Tipo	Requerido
processor	string	sí

curl -X POST https://mw.migopayments.com/api/v1/integrations/transactions/trx_8f3c2b1d9e7a/payment-intents \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{ "processor": "fri" }'

Recordatorio de auth. Toda llamada envía Authorization: Bearer <token>. Ve Autenticación para más detalles.

Ejemplos de respuesta

fri — descriptor de campos requeridos (sandbox de Guatemala)

fri es el método de sandbox de Guatemala que usa una pre-call. El intent retorna los campos que el cliente puede proporcionar al momento de /payments — se requiere al menos uno de phoneNumber o user.

{
  "success": true,
  "message": "success",
  "data": {
    "requiredFields": {
      "phoneNumber": {
        "description": "Número de teléfono registrado en FRI",
        "required": false
      },
      "user": {
        "description": "Nombre de usuario registrado en FRI",
        "required": false
      },
      "note": "Al menos uno de los dos campos es requerido (phoneNumber o user)"
    }
  }
}

Patrones de lista de bancos y teléfono (ejemplos del mercado de Colombia — no disponibles en Guatemala)

Otros mercados usan el mismo endpoint para impulsar una lista de selección o un número de teléfono pre-llenado. Los ejemplos de abajo son rails del mercado de Colombia y no están disponibles en Guatemala — solo ilustran los patrones de lista de bancos y de teléfono.

Una respuesta de selector de banco (por ejemplo, globalPay-PSE en Colombia) retorna una lista que el frontend renderiza como dropdown:

{
  "success": true,
  "message": "success",
  "data": {
    "banks": [
      { "id": "1007", "name": "Example Bank A" },
      { "id": "1051", "name": "Example Bank B" }
    ],
    "accountTypes": ["checking", "savings"],
    "fisTypes": ["NATURAL", "JURIDICAL"],
    "userTypes": ["NIT", "CC", "CE"]
  }
}

Las llaves banks, accountTypes, fisTypes y userTypes están garantizadas; sus valores son determinados por configuración (banks proviene de un lookup externo, el resto de la configuración del procesador). Confirma los valores exactos de los enums vía una llamada en sandbox. El frontend usa data.banks para renderizar el dropdown, luego envía el id del banco seleccionado de vuelta a /payments bajo la llave que requiera el payload del rail.

Una respuesta de fixture de teléfono (por ejemplo, nequi en Colombia) retorna un valor pre-llenado:

{
  "success": true,
  "message": "success",
  "data": {
    "phoneNumber": "30058059"
  }
}

Procesadores permitidos

La lista permitida es ilustrativa y depende de tu mercado y cuenta. Para Guatemala el método pre-call/sandbox relevante es fri; los rails de lista de bancos y de fixture de teléfono como globalPay-PSE y nequi pertenecen a otros mercados. Un procesador no habilitado para tu cuenta, y que no forme parte del array paymentMethods por transacción, retorna 400 Processor not allowed.

Errores

HTTP	Causa
400	Falta transactionId o el procesador no está habilitado para este cliente
500	Falló el lookup del procesador upstream