Esta API permite conectar los sistemas internos de tu empresa (ERP o software contable) directamente con Banco Guayaquil para automatizar el pago de sueldos y proveedores, sin cargas de archivos manuales y con confirmaciones de estado en tiempo real. Sigue estos pasos para completar la integración.
¿Qué necesitas para empezar?
Requisitos comerciales
- Ser cliente corporativo de Banco Guayaquil con una cuenta transaccional activa (Corriente o Ahorros).
- Tener contratado el servicio de Pago de Nómina o Pago a Terceros. Solicítalo con el formulario de activación de medios de interconexión. El banco te asignará un contractId y un serviceCode.
Requisitos técnicos
- Tener activa una conexión VPN site-to-site con Banco Guayaquil. Consulta las especificaciones en el anexo técnico para configuración VPN de interconexión API.
- Solicitar a tu oficial de cuenta las credenciales corporativas para la autenticación: client_id, client_secret, tenant y scope.
¿Cómo funciona el flujo de integración?
El ciclo de vida de un pago a través de la API consta de tres etapas:
| Etapa | Nombre | Qué hace tu sistema |
| 1 | Autenticación | Solicita un token de seguridad temporal a Microsoft Azure AD. |
| 2 | Creación de la orden | Envía la instrucción de pago: quién paga, a quién se le paga y cuánto. |
| 3 | Consulta de estado | Consulta si el pago fue procesado o si hubo algún rechazo. |
¿Cómo consumir la API paso a paso?
Las URLs base (endpoints) para cada ambiente (Pruebas y Producción) son provistas por el banco una vez formalizada la contratación.
Para el detalle completo de payloads, catálogos y códigos de respuesta, consulta el manual técnico de PaymentOrder API.
Paso 1: Genera un token de autenticación
La API utiliza el estándar OAuth 2.0 (Client Credentials) respaldado por Azure Active Directory (v2). Antes de consumir cualquier método, solicita un token de acceso:
- POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Encabezado:
- Content-Type: application/x-www-form-urlencoded
Cuerpo de la petición:
- client_id={client_id}&client_secret=
{client_secret}&grant_type=client_credentials&scope={scope}
Incluye el access_token recibido en todas las peticiones a la API dentro del encabezado:
- Authorization: Bearer {access_token}
Paso 2: Crea una orden de pago
Registra una orden con una o varias instrucciones de transferencia.
- POST /v1/payment-order
El cuerpo de la petición (JSON) contiene la información del deudor (tu empresa) y un arreglo con las instrucciones de pago (los beneficiarios). Ten en cuenta los siguientes catálogos:
| Dato | Campo en la API | Valores soportados |
| Tipo de identificación | type (debtor y creditor) | R (RUC), C (Cédula), P (Pasaporte), E (Extranjera), O (Otro) |
| Tipo de cuenta | accountType (debtor y creditor) | AHO (Ahorros), CTE (Corriente), CM (Cuenta Amiga / Peigo, solo destino) |
| Moneda | amount.currency | USD |
| Valores decimales | amount.value | Usar punto . para decimales. Ejemplo: 353.56. |
Respuesta exitosa (HTTP 200):
El sistema devuelve un controlRecordReference (ID de la carga) y un traceId. Guarda el controlRecordReference: es obligatorio para consultar el estado del pago más adelante.
Paso 3: Consulta el estado de una orden
Recupera el detalle y el estado de una orden previamente enviada.
- GET /v1/payment-orders
Parámetros de consulta obligatorios:
- channel: enviar "BVI".
- initiatingParty: enviar "API_CLIENT".
- debtorContractId y debtorOrganizationId: provistos por el banco.
- controlRecordReference: el ID de carga obtenido al crear la orden.
- initiationDateFrom / initiationDateTo: rango de fechas de búsqueda (formato yyyy-MM-dd).
Estados de respuesta:
El campo status dentro del arreglo paymentInstructions indica si la transacción individual está pendiente, procesada o si sufrió un error.
Importante
- El rango máximo permitido entre initiationDateFrom e initiationDateTo es de 15 días.
- Los códigos HTTP reflejan el resultado: 400 para errores de formato o datos, 500 para intermitencias del servidor. El campo status del cuerpo del error siempre coincide con el código HTTP.
- Toda respuesta incluye un traceId (ejemplo: 0HNJ9MDS4H6SU:00000001). Guárdalo siempre: es indispensable para reportar incidentes a la mesa de ayuda técnica del banco.
- Ante errores transitorios del servidor (HTTP 5xx), implementa reintentos automáticos con una estrategia de backoff exponencial.
Casos especiales
Si presentas errores persistentes durante la integración o dudas sobre la configuración de credenciales y VPN, escríbenos por ChatBG a WhatsApp al 0983730100 para que un asesor derive tu caso a la mesa de ayuda técnica. Incluye siempre el traceId del incidente para agilizar el diagnóstico.