Ir al contenido
Global66 Developers

Migrar de v1 a v2

En la versión 1, el pago se debita de la cuenta principal de tu empresa en la moneda que indicas en originCurrency. En la versión 2 eliges qué cuenta se debita con walletId, y la moneda de origen es la de esa cuenta. El resto del payload (REMITTANCE, P2P y EXCHANGE), el permiso TRANSACTIONS y la respuesta 200 no cambian. Para conocer el walletId, tu credencial también necesita el permiso MOVEMENTS.

Antes de empezar, revisa Versiones del API para conocer cómo se elige la versión.

Pasos para migrar

  1. Obtén el walletId de la cuenta de origen

    Autentícate con POST /b2b/auth y consulta GET /b2b/accounts. Cada cuenta de la respuesta trae su walletId (un número entero). Elige la cuenta por moneda, alias o isPrincipal, y verifica que tenga saldo suficiente. Solo se aceptan cuentas de la empresa autenticada.

    GET /b2b/accounts exige el permiso MOVEMENTS, además del TRANSACTIONS que ya usas para pagar. Si tu credencial no lo tiene, la consulta responde 403 INSUFFICIENT_SCOPE.

  2. Agrega el header de versión

    Envía X-Api-Version: 2 en la petición de pago. Solo el valor exacto 2 activa la versión 2; cualquier otro valor se atiende como versión 1 sin devolver un error.

  3. Envía walletId y quita originCurrency

    Agrega walletId como número entero (nunca como texto) en el lugar de originCurrency. Si envías originCurrency en v2, se ignora.

  4. Expresa amount según way

    Con way: "ORIGIN", el amount es el monto que envías y se expresa en la moneda de la cuenta elegida: si tu cuenta es en COP, el monto está en COP. Con way: "DESTINY", el amount es el monto que recibe el beneficiario.

  5. Consulta el resultado

    El flujo de consulta no cambia: usa GET /b2b/transactions/detail con el identificador que devuelve el pago.

El flujo completo de una integración en v2 es: POST /b2b/auth, GET /b2b/accounts, POST /b2b/transactions/payments con el header y GET /b2b/transactions/detail.

Antes y después

Versión 1 (sin header, con originCurrency):

Copiar código

Versión 2 (con el header y walletId en lugar de originCurrency):

Copiar código

Errores nuevos en la versión 2

HTTPReglaCuándo ocurre
400NOT_NULL sobre walletIdFalta el walletId (“The wallet id is required.”).
400ORIGIN_WALLET_NOT_FOUNDEl walletId no existe o no pertenece a tu empresa (“The walletId was not found or does not belong to the company.”).
502ACCOUNT_ENRICHMENT_FAILEDNo se pudo consultar la cuenta por un error interno.

Después de un rechazo, corrige la causa y reintenta con un externalReferenceId nuevo. El detalle de cada respuesta está en Errores y reintentos.