APIs de Cobro - Cobro por QR Activos Virtuales

Especificación Técnica Servicio API ACTIVOS VIRTUALES con OAuth 2.0

1. Introducción

Este documento describe los lineamientos y especificaciones técnicas para la integración con la API de Generación y Consulta de Códigos QR activos virtuales de ATC (Redenlace Bolivia). El servicio permite a establecimientos y aplicaciones cliente generar códigos QR de cobro liquidables en activos virtuales y verificar el estado de las transacciones asociadas.

La integración contempla los siguientes flujos:

Autenticación mediante OAuth 2.0 (Client Credentials) para obtención del Access Token.
Generación de un código QR de pago.
Verificación del estado de la transacción QR.

Credenciales

El Token Basic (Authorization), el client_id y el access_token de producción son proporcionados exclusivamente por ATC para cada integrador habilitado. Los valores mostrados en este documento corresponden únicamente al ambiente de pruebas.

Todos los servicios de la API requieren el envío de los siguientes encabezados HTTP en cada petición. El Access Token debe obtenerse previamente mediante el servicio de autenticación OAuth 2.0 (ver sección 3.1).

Header	Descripción	Oblig.	Ejemplo
`Authorization`	Token de autorización. Se envía como `Bearer` seguido del `access_token` obtenido en la autenticación.	Sí	`Bearer 1442981c-....-....-b...-ea12258c9...`
`client_id`	Identificador único del cliente integrador. Proporcionado por ATC.	Sí	`1e063b89-....-....-....-ed73d60cbc67`
`Content-Type`	Formato del cuerpo de la petición. Para todos los servicios: JSON.	Sí	`application/json`

Autenticación previa obligatoria Para obtener el access_token que se usa en el header Authorization, primero debe invocarse el servicio de autenticación OAuth (sección 3.1). El token Basic requerido en ese paso es provisto por ATC.

3. Generar Transacción QR

3.1. Autenticación — Obtención del Access Token

Antes de poder generar un QR, el integrador debe obtener un Access Token válido mediante el flujo OAuth 2.0 Client Credentials.

Atributo	Valor
Método HTTP	`POST`
Endpoint	`/oauth-client-credentials/access-token`
Content-Type	`application/x-www-form-urlencoded`
Query Param	`grant_type=client_credentials`

Request — Autenticación (obtener Access Token)

http

600;">POST /oauth-client-credentials/access-token?grant_type=client_credentials
   Headers:
   Authorization: Basic ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2Iw==
   Content-Type: application/x-www-form-urlencoded

http

600;">POST /oauth-client-credentials/access-token?grant_type=client_credentials
   Headers:
   Authorization: Basic ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2Iw==
   Content-Type: application/x-www-form-urlencoded

Header de autenticación

Header	Descripción	Obligatorio
`Authorization`	Codificado en Base64 (`client_id:client_secret`).	Sí
`Content-Type`	`application/x-www-form-urlencoded`	Sí

Respuesta exitosa — Access Token

json

{
  "access_token": "1442981c-....-....-b...-ea12258c9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.qr"
}

json

{
  "access_token": "1442981c-....-....-b...-ea12258c9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api.qr"
}

Campo	Tipo	Descripción
`access_token`	String	Token de portador para usar en los headers de los servicios QR.
`token_type`	String	Tipo de token. Siempre `'Bearer'`.
`expires_in`	Integer	Tiempo de validez en segundos.
`scope`	String	Alcance del token otorgado.

3.2. Servicio de Generación de QR

Una vez obtenido el Access Token, se puede invocar el servicio de generación del código QR de pago.

Atributo	Valor
Método HTTP	`POST`
ENDPOINT	`/qr/koibanx/v2/generar`
Header: `access_token`	`{access_token obtenido en autenticación}`
Header: `client_id`	`{client_id provisto por ATC}`
Header: `Content-Type`	`application/json`

Request — Generar QR

http

600;">POST /qr/koibanx/v2/generar
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">POST /qr/koibanx/v2/generar
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

Campos del Request Body

json

{
  "numeroReferencia": 2320,
  "glosa": "422717|Comercio test|MISCELANEAS|Pago de servicio",
  "monto": 10.50,
  "moneda": "BOB",
  "activoVirtual": "UP",
  "canal": "WEB",
  "tiempoVencimientoQR": 180,
  "campoExtra": "",
  "webhook": {
    "url": "https://qr.enlacedev.com/confirmed.php",
    "key": "x-api-key",
    "value": "f4a1b6d9c3e8f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6"
  }
}

json

{
  "numeroReferencia": 2320,
  "glosa": "422717|Comercio test|MISCELANEAS|Pago de servicio",
  "monto": 10.50,
  "moneda": "BOB",
  "activoVirtual": "UP",
  "canal": "WEB",
  "tiempoVencimientoQR": 180,
  "campoExtra": "",
  "webhook": {
    "url": "https://qr.enlacedev.com/confirmed.php",
    "key": "x-api-key",
    "value": "f4a1b6d9c3e8f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6"
  }
}

Campo	Tipo	Obligatorio	Descripción
`numeroReferencia`	String	Sí	Referencia interna del sistema originante (asignada por el integrador). Ej: `'2320'`.
`glosa`	String	Sí	`glosa=codigo_sucursal,nombre_sucursal,rubro_comercio,descripción de pago o servcio.`
`moneda`	String	Sí	Código ISO de moneda. Valores permitidos: `BOB`, `USD`.
`monto`	Decimal	Sí	Importe del pago. Máximo 2 decimales. Ej: `10.50`.
`activoVirtual`	String	Sí	Tipo de moneda virtual de liquidación de la transacción: `UT` (activo virtual USDT), `UP` (activo virtual USDC), `BK` (activo virtual).
`canal`	String	Sí	Identificador de canal (permite agrupar y distinguir): `APP` (aplicación móvil), `WEB` (sitio web abierto desde navegador de PC), `WAP` (página HTML abierta desde navegador móvil), `OTHERS`.
`tiempoVencimientoQR`	Int	Sí	Tiempo de vida del QR, en segundos. Mínimo `30`, máximo `90`.
`campoExtra`	String	No	Campo reservado.
`webhook`	Objeto	Sí	Campo requerido para que el comercio reciba la respuesta de la transacción.

Detalle del objeto `webhook`

Campo	Tipo	Descripción
`url`	String	URL del webhook
`key`	String	Tipo de key utilizado (ejemplo: `x-api-key`)
`value`	String	Valor del key usado

Campos de la Respuesta Exitosa

json

{
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Se generó cobro QR con éxito",
  "moneda": "BOB",
  "monto": 50,
  "numeroReferencia": "200716",
  "origenNumeroReferencia": "321",
  "imagen": "{cadenaQR en base64}",
  "montoConversion": 3.93,
  "monedaConversion": "usdc",
  "tipoCambio": 12.72,
  "qrExpiracion": "2026-05-28T16:31:42.057"
}

json

{
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Se generó cobro QR con éxito",
  "moneda": "BOB",
  "monto": 50,
  "numeroReferencia": "200716",
  "origenNumeroReferencia": "321",
  "imagen": "{cadenaQR en base64}",
  "montoConversion": 3.93,
  "monedaConversion": "usdc",
  "tipoCambio": 12.72,
  "qrExpiracion": "2026-05-28T16:31:42.057"
}

Campo	Tipo	Descripción
`codigoRespuesta`	String	Código de respuesta de la acción
`detalleRespuesta`	String	Detalle de la respuesta de la acción
`moneda`	String	Tipo de moneda de la transacción, ej. `BOB`
`monto`	String	Monto de la transacción, ej. `BOB`
`numeroReferencia`	String	Código único transaccional de ATC
`origenNumeroReferencia`	String	Código único transaccional generado por el comercio integrador
`imagen`	String	Cadena con la imagen QR
`montoConversion`	Number	Monto después de la conversión a la moneda virtual, ejemplo a USDT
`monedaConversion`	String	Moneda de la conversión (ej. USDT/USDC)
`tipoCambio`	Number	Valor del tipo de cambio de la conversión del monto a `montoConversion`
`qrExpiracion`	String	Fecha en la que expira el QR generado

4. Verificar Estado QR

Permite consultar el estado actual de un QR previamente generado. Se usa el numeroReferencia interno asignado por ATC (campo data.numeroReferencia de la respuesta de generación), no el numeroReferencia originante del integrador.

Request — Consulta de Estado

Atributo	Valor
Método HTTP	`GET`
ENDPOINT	`/qr/koibanx/v2/estado/{numeroReferencia}`
Header: `access_token`	`{access_token obtenido en autenticación}`
Header: `client_id`	`{provisto por la APP al momento de tener un cliente en el devportal}`
Header: `Content-Type`	`application/json`
Parámetro de ruta	`{numeroReferencia}` — Referencia interna ATC. Ej: `200699`

http

600;">GET    /qr/koibanx/v2/estado/200699
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">GET    /qr/koibanx/v2/estado/200699
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

4.1. Campos de la Respuesta Exitosa

Response — Estado QR expirado

json

{
  "codigoRespuesta": "EXPIRED",
  "detalleRespuesta": "Transacción expirada",
  "data": {
    "monto": 50.00,
    "moneda": "BOB",
    "montoConversion": 50.00,
    "monedaConversion": "usdc",
    "tipoCambio": 12.72,
    "numeroReferencia": 200699
  }
}

json

{
  "codigoRespuesta": "EXPIRED",
  "detalleRespuesta": "Transacción expirada",
  "data": {
    "monto": 50.00,
    "moneda": "BOB",
    "montoConversion": 50.00,
    "monedaConversion": "usdc",
    "tipoCambio": 12.72,
    "numeroReferencia": 200699
  }
}

Response — Estado QR pendiente

json

{
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Transacción pendiente de procesamiento",
  "data": {
    "monto": 50.00,
    "moneda": "BOB",
    "montoConversion": 50.00,
    "monedaConversion": "usdc",
    "tipoCambio": 12.72,
    "numeroReferencia": 200699
  }
}

json

{
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Transacción pendiente de procesamiento",
  "data": {
    "monto": 50.00,
    "moneda": "BOB",
    "montoConversion": 50.00,
    "monedaConversion": "usdc",
    "tipoCambio": 12.72,
    "numeroReferencia": 200699
  }
}

Campo	Tipo	Descripción
`codigoRespuesta`	String	Código del estado de la transacción
`detalleRespuesta`	String	Descripción de estado de la transacción
`data`	Objeto	Datos de la transacción

Detalle del objeto `data`

Campo	Tipo	Descripción
`monto`	Number	Monto de la transacción
`moneda`	String	Tipo de moneda de la transacción
`montoConversion`	Number	Monto después de la conversión a la moneda virtual, ejemplo a USDC
`monedaConversion`	String	Moneda de la conversión (ej. USDC)
`tipoCambio`	Number	Valor del tipo de cambio de la conversión del monto a `montoConversion`
`numeroReferencia`	Number	Código único transaccional de ATC

Descripción de `codigoRespuesta`

Código	Descripción
`PENDING`	Estado cuando la transacción se dio de alta pero aún no fue cobrada.
`SUCCESS`	Estado cuando la transacción se completó de manera satisfactoria.
`CANCELLED`	Estado cuando la transacción ha sido cancelada sin ser pagada.
`EXPIRED`	Estado cuando el código QR de la transacción ha expirado.
`ERROR`	Error de servicio.

5. Ejemplos

5.1. Generar Transacción QR Activos virtuales

Request — Autenticación (obtener Access Token)

http

600;">POST /oauth-client-credentials/access-token?grant_type=client_credentials

Headers:
  Authorization: Basic ODBiM2M1NWQtNWNNi00OWRlLTkxYTAtMDcwZDM1M2IwMDQ3OmQ2OWVlZjQxLTFkMmYtNDBlZC1iNGQ0LTc5MzFiYjljYmI3NA==
  Content-Type: application/x-www-form-urlencoded

http

600;">POST /oauth-client-credentials/access-token?grant_type=client_credentials

Headers:
  Authorization: Basic ODBiM2M1NWQtNWNNi00OWRlLTkxYTAtMDcwZDM1M2IwMDQ3OmQ2OWVlZjQxLTFkMmYtNDBlZC1iNGQ0LTc5MzFiYjljYmI3NA==
  Content-Type: application/x-www-form-urlencoded

Response — Access Token

json

{
  "access_token": "1442981c-89d-46bc-b2a2-ea12258c99ab",
  "token_type": "Bearer",
  "expires_in": 3600
}

json

{
  "access_token": "1442981c-89d-46bc-b2a2-ea12258c99ab",
  "token_type": "Bearer",
  "expires_in": 3600
}

Request — Generar QR

http

600;">POST /qr/koibanx/v2/generar

Headers:
  access_token: 46a81ec8-ab9f-4c9b-8cbe-0f99052da1e
  client_id: 80b3c55d-5cb6-49de-91a0-07d353b0047
  Content-Type: application/json

http

600;">POST /qr/koibanx/v2/generar

Headers:
  access_token: 46a81ec8-ab9f-4c9b-8cbe-0f99052da1e
  client_id: 80b3c55d-5cb6-49de-91a0-07d353b0047
  Content-Type: application/json

Body:

json

{
  "numeroReferencia": 321,
  "glosa": "422717|Comercio test|MISCELANEAS|glosa test",
  "monto": 50,
  "moneda": "BOB",
  "activoVirtual": "UP",
  "canal": "WEB",
  "tiempoVencimientoQR": 180,
  "campoExtra": "",
  "webhook": {
    "url": "https://qr.enlacedev.com/confirmed.php",
    "key": "x-api-key",
    "value": "f4a1b6d9c3e8f1a2b3c4d5e6fa8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6"
  }
}

json

{
  "numeroReferencia": 321,
  "glosa": "422717|Comercio test|MISCELANEAS|glosa test",
  "monto": 50,
  "moneda": "BOB",
  "activoVirtual": "UP",
  "canal": "WEB",
  "tiempoVencimientoQR": 180,
  "campoExtra": "",
  "webhook": {
    "url": "https://qr.enlacedev.com/confirmed.php",
    "key": "x-api-key",
    "value": "f4a1b6d9c3e8f1a2b3c4d5e6fa8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6"
  }
}

Response — QR generado

json

{
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Se generó cobro QR con éxito",
  "moneda": "BOB",
  "monto": 50,
  "numeroReferencia": "200716",
  "origenNumeroReferencia": "321",
  "imagen": "{cadenaQR en base64}",
  "montoConversion": 3.93,
  "monedaConversion": "usdc",
  "tipoCambio": 12.72,
  "qrExpiracion": "2026-05-28T16:31:42.057"
}

json

{
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Se generó cobro QR con éxito",
  "moneda": "BOB",
  "monto": 50,
  "numeroReferencia": "200716",
  "origenNumeroReferencia": "321",
  "imagen": "{cadenaQR en base64}",
  "montoConversion": 3.93,
  "monedaConversion": "usdc",
  "tipoCambio": 12.72,
  "qrExpiracion": "2026-05-28T16:31:42.057"
}

5.2. Verificar Estado QR

Request — Consulta de Estado

http

600;">GET /qr/koibanx/v2/estado/200699

Headers:
  access_token: c3e71ac-e932-4c37-b9f5-1fe55b2d3db6
  client_id: 80b3c55d-5cb6-49de-91a0-070d53b0047
  Content-Type: application/json

http

600;">GET /qr/koibanx/v2/estado/200699

Headers:
  access_token: c3e71ac-e932-4c37-b9f5-1fe55b2d3db6
  client_id: 80b3c55d-5cb6-49de-91a0-070d53b0047
  Content-Type: application/json

Response — Estado QR expirado

json

{
  "codigoRespuesta": "EXPIRED",
  "detalleRespuesta": "Transacción expirada",
  "data": {
    "monto": 50.00,
    "moneda": "BOB",
    "montoConversion": 50.00,
    "monedaConversion": "usdc",
    "tipoCambio": 12.72,
    "numeroReferencia": 200699
  }
}

json

{
  "codigoRespuesta": "EXPIRED",
  "detalleRespuesta": "Transacción expirada",
  "data": {
    "monto": 50.00,
    "moneda": "BOB",
    "montoConversion": 50.00,
    "monedaConversion": "usdc",
    "tipoCambio": 12.72,
    "numeroReferencia": 200699
  }
}

Response — Estado QR pendiente

json

{
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Transacción pendiente de procesamiento",
  "data": {
    "monto": 50.00,
    "moneda": "BOB",
    "montoConversion": 50.00,
    "monedaConversion": "usdc",
    "tipoCambio": 12.72,
    "numeroReferencia": 200722
  }
}

json

{
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Transacción pendiente de procesamiento",
  "data": {
    "monto": 50.00,
    "moneda": "BOB",
    "montoConversion": 50.00,
    "monedaConversion": "usdc",
    "tipoCambio": 12.72,
    "numeroReferencia": 200722
  }
}

6. Ambientes

El siguiente cuadro contiene los datos de los ambientes disponibles con la URL base y el tipo de token requerido. Las credenciales específicas (Token Basic, client_id, access_token) son proporcionadas por ATC para cada ambiente y cada integrador habilitado.

Ambiente	URL Base	Credenciales	Estado
Sandbox	`https://atcgwapitest.redenlace.com.bo/sandbox`	Provisto por ATC	A solicitud
Producción	`https://api.redenlace.com.bo`	Provisto por ATC	A solicitud

Seguridad de credenciales

No almacene credenciales de ningún ambiente (especialmente producción) en repositorios de código fuente. Use variables de entorno o un gestor de secretos. Las credenciales de producción son distintas a las de desarrollo y son entregadas por ATC de forma segura tras aprobar la certificación.

En esta página

Especificación Técnica Servicio API ACTIVOS VIRTUALES con OAuth 2.0

1. Introducción

2. Header

3. Generar Transacción QR

4. Verificar Estado QR

5. Ejemplos

6. Ambientes

Especificación Técnica Servicio API ACTIVOS VIRTUALES con OAuth 2.0

1. Introducción

Credenciales

2. Header

3. Generar Transacción QR

3.1. Autenticación — Obtención del Access Token

Request — Autenticación (obtener Access Token)

Header de autenticación

Respuesta exitosa — Access Token

3.2. Servicio de Generación de QR

Request — Generar QR

Campos del Request Body

Detalle del objeto webhook

Campos de la Respuesta Exitosa

4. Verificar Estado QR

Request — Consulta de Estado

4.1. Campos de la Respuesta Exitosa

Response — Estado QR expirado

Response — Estado QR pendiente

Detalle del objeto data

Descripción de codigoRespuesta

5. Ejemplos

5.1. Generar Transacción QR Activos virtuales

Request — Autenticación (obtener Access Token)

Response — Access Token

Request — Generar QR

Response — QR generado

5.2. Verificar Estado QR

Request — Consulta de Estado

Response — Estado QR expirado

Response — Estado QR pendiente

6. Ambientes

Seguridad de credenciales

Detalle del objeto `webhook`

Detalle del objeto `data`

Descripción de `codigoRespuesta`