APIs de Cobro - Cobro por QR Activos Virtuales Binance

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

1. Introducción

El presente documento describe los lineamientos y especificaciones técnicas para la integración con la API QR Binance publicada por ATC Redenlace mediante Sensedia. El servicio permite a comercios integradores generar códigos QR Binance, consultar el estado de la transacción y recibir confirmaciones automáticas mediante webhook.

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 Binance de pago.
Consulta de estado de la transacción QR.
Webhook de confirmación de pago.

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

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 consumir los servicios QR, el comercio 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/binance/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/binance/v2/generar
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

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

Campos del Request Body

json

{
    "numeroReferencia": 200397,
    "glosa": "401306|COMERCIO ATC|MISCELANEAS|TRANSACCION QR BINANCE",
    "monto": 0.01,
    "moneda": "BOB",
    "tiempoQr": "00:05:00",
    "canal": "WEB",
    "campoExtra": "",
    "webhook": {
        "url": "https://dominio.com/qrbinance/confirmed",
        "value": "x-api-key",
        "key": "b6f89d9c-7c1b-4c4e-9d5e-13d57a0b8f3e"
    }
}

json

{
    "numeroReferencia": 200397,
    "glosa": "401306|COMERCIO ATC|MISCELANEAS|TRANSACCION QR BINANCE",
    "monto": 0.01,
    "moneda": "BOB",
    "tiempoQr": "00:05:00",
    "canal": "WEB",
    "campoExtra": "",
    "webhook": {
        "url": "https://dominio.com/qrbinance/confirmed",
        "value": "x-api-key",
        "key": "b6f89d9c-7c1b-4c4e-9d5e-13d57a0b8f3e"
    }
}

Campo	Tipo	Obligatorio	Descripción
`numeroReferencia`	String	Sí	Código único transaccional del comercio integrador. Mínimo 1, máximo 10. (asignada por el integrador). Ej: `'200397'`.
`glosa`	String	Sí	Datos del comercio separados por PIPE: `glosa=codigo_sucursal,nombre_sucursal,rubro_comercio,descripción de pago o servcio.`
`moneda`	String	Sí	Moneda de la transacción. Valores: BOB o USD.
`monto`	Decimal	Sí	Importe del pago. Máximo 2 decimales. Ej: `10.50`.
`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`.
`campoExtra`	String	No	Campo reservado.
`tiempoQR`	String	Sí	Tiempo de vida del QR. Valor máximo 5 minutos (Ej. 00:05:00).
`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 BINANCE con éxito",
    "moneda": "BOB",
    "monto": 0.01,
    "origenNumeroReferencia": "200397",
    "numeroReferencia": "11193568",
    "imagen": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBw...............................................",
    "montoConversion": 0.00083046,
    "monedaConversion": "USDT",
    "tipoCambio": 12.04,
    "qrExpiracion": "2026-09-17 14:43:51"
}

json

{
    "codigoRespuesta": "PENDING",
    "detalleRespuesta": "Se generó cobro QR BINANCE con éxito",
    "moneda": "BOB",
    "monto": 0.01,
    "origenNumeroReferencia": "200397",
    "numeroReferencia": "11193568",
    "imagen": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBw...............................................",
    "montoConversion": 0.00083046,
    "monedaConversion": "USDT",
    "tipoCambio": 12.04,
    "qrExpiracion": "2026-09-17 14:43:51"
}

Campo	Tipo	Descripción
`codigoRespuesta`	String	Código de respuesta de la acción
`detalleRespuesta`	String	Detalle del resultado.
`moneda`	String	Tipo de moneda de la transacción, ej. `BOB`
`monto`	String	Monto de la transacción, ej. `0.01`
`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. Consulta de Estado QR

Permite consultar el estado actual de un QR Binance previamente generado. Se usa el numeroReferencia interno asignado por ATC (campo 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/binance/v2/verificar/{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: `11193577`

http

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

http

600;">GET    /qr/binance/v2/verificar/11193577
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": "Orden expirada",
    "data": {
        "monto": 0.01,
        "moneda": "BOB",
        "montoConversion": 0.00083045,
        "monedaConversion": "USDT",
        "tipoCambio": 12.04,
        "numeroReferencia": "11193577"
    }
}

json

{
    "codigoRespuesta": "EXPIRED",
    "detalleRespuesta": "Orden expirada",
    "data": {
        "monto": 0.01,
        "moneda": "BOB",
        "montoConversion": 0.00083045,
        "monedaConversion": "USDT",
        "tipoCambio": 12.04,
        "numeroReferencia": "11193577"
    }
}

Response — Estado QR pendiente

json

{
    "codigoRespuesta": "PENDING",
    "detalleRespuesta": "Orden pendiente de pago",
    "data": {
        "monto": 0.01,
        "moneda": "BOB",
        "montoConversion": 0.00083045,
        "monedaConversion": "USDT",
        "tipoCambio": 12.04,
        "numeroReferencia": "11193577"
    }
}

json

{
    "codigoRespuesta": "PENDING",
    "detalleRespuesta": "Orden pendiente de pago",
    "data": {
        "monto": 0.01,
        "moneda": "BOB",
        "montoConversion": 0.00083045,
        "monedaConversion": "USDT",
        "tipoCambio": 12.04,
        "numeroReferencia": "11193577"
    }
}

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.
`monedaConversion`	String	Moneda de la conversión (ej. USDT)
`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/binance/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/binance/v2/generar

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

Body:

json

{
    "numeroReferencia": 200397,
    "glosa": "401306|COMERCIO ATC|MISCELANEAS|TRANSACCION QR BINANCE",
    "monto": 0.01,
    "moneda": "BOB",
    "tiempoQr": "00:05:00",
    "canal": "WEB",
    "campoExtra": "",
    "webhook": {
        "url": "https://dominio.com/qrbinance/confirmed",
        "value": "x-api-key",
        "key": "b6f89d9c-7c1b-4c4e-9d5e-13d57a0b8f3e"
    }
}

json

{
    "numeroReferencia": 200397,
    "glosa": "401306|COMERCIO ATC|MISCELANEAS|TRANSACCION QR BINANCE",
    "monto": 0.01,
    "moneda": "BOB",
    "tiempoQr": "00:05:00",
    "canal": "WEB",
    "campoExtra": "",
    "webhook": {
        "url": "https://dominio.com/qrbinance/confirmed",
        "value": "x-api-key",
        "key": "b6f89d9c-7c1b-4c4e-9d5e-13d57a0b8f3e"
    }
}

Response — QR generado

json

{
    "codigoRespuesta": "PENDING",
    "detalleRespuesta": "Se generó cobro QR BINANCE con éxito",
    "moneda": "BOB",
    "monto": 0.01,
    "origenNumeroReferencia": "200397",
    "numeroReferencia": "11193568",
    "imagen": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBw...........................................",
    "montoConversion": 0.00083046,
    "monedaConversion": "USDT",
    "tipoCambio": 12.04,
    "qrExpiracion": "2026-09-17 14:43:51"
}

json

{
    "codigoRespuesta": "PENDING",
    "detalleRespuesta": "Se generó cobro QR BINANCE con éxito",
    "moneda": "BOB",
    "monto": 0.01,
    "origenNumeroReferencia": "200397",
    "numeroReferencia": "11193568",
    "imagen": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBw...........................................",
    "montoConversion": 0.00083046,
    "monedaConversion": "USDT",
    "tipoCambio": 12.04,
    "qrExpiracion": "2026-09-17 14:43:51"
}

5.2. Verificar Estado QR

Request — Consulta de Estado

http

600;">GET /qr/binance/v2/verificar/11193577

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

http

600;">GET /qr/binance/v2/verificar/11193577

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": "Orden expirada",
    "data": {
        "monto": 0.01,
        "moneda": "BOB",
        "montoConversion": 0.00083045,
        "monedaConversion": "USDT",
        "tipoCambio": 12.04,
        "numeroReferencia": "11193577"
    }
}

json

{
    "codigoRespuesta": "EXPIRED",
    "detalleRespuesta": "Orden expirada",
    "data": {
        "monto": 0.01,
        "moneda": "BOB",
        "montoConversion": 0.00083045,
        "monedaConversion": "USDT",
        "tipoCambio": 12.04,
        "numeroReferencia": "11193577"
    }
}

Response — Estado QR pendiente

json

{
    "codigoRespuesta": "PENDING",
    "detalleRespuesta": "Orden pendiente de pago",
    "data": {
        "monto": 0.01,
        "moneda": "BOB",
        "montoConversion": 0.00083045,
        "monedaConversion": "USDT",
        "tipoCambio": 12.04,
        "numeroReferencia": "11193577"
    }
}

json

{
    "codigoRespuesta": "PENDING",
    "detalleRespuesta": "Orden pendiente de pago",
    "data": {
        "monto": 0.01,
        "moneda": "BOB",
        "montoConversion": 0.00083045,
        "monedaConversion": "USDT",
        "tipoCambio": 12.04,
        "numeroReferencia": "11193577"
    }
}

6. WEBHOOK (NOTIFICACIÓN DE PAGO)

Cuando el pago QR Binance es confirmado, ATC envía una notificación HTTP POST al endpoint expuesto por el comercio.

Atributo	Valor
Método HTTP	POST
Endpoint del comercio	https://dominio.com/qrbinance/confirmed (Ejemplo provisto por el comercio)
Content-Type	application/json
Respuesta esperada	HTTP 200 con codigoRespuesta "00" cuando se reciba correctamente.

6.1. Payload recibido por el comercio

json

{
  "numeroReferencia": "4221",
  "estado": "00",
  "transacciones": {
    "monto": 1.00,
    "moneda": "BOB",
    "fechaHoraTransaccion": "2026-05-05T12:30:45",
    "cliente": {
      "nombreCliente": "",
      "ciCliente": ""
    }
  }
}

json

{
  "numeroReferencia": "4221",
  "estado": "00",
  "transacciones": {
    "monto": 1.00,
    "moneda": "BOB",
    "fechaHoraTransaccion": "2026-05-05T12:30:45",
    "cliente": {
      "nombreCliente": "",
      "ciCliente": ""
    }
  }
}

6.2 Respuesta requerida del comercio

json

{
  "numeroReferencia": "4221",
  "codigoRespuesta": "00",
  "detalleRespuesta": null
}

json

{
  "numeroReferencia": "4221",
  "codigoRespuesta": "00",
  "detalleRespuesta": null
}

7. 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 BINANCE con OAuth 2.0

1. Introducción

2. Header

3. Generar Transacción QR

4. Consulta de Estado QR

5. Ejemplos

6. WEBHOOK (NOTIFICACIÓN DE PAGO)

7. Ambientes

Especificación Técnica Servicio API ACTIVOS VIRTUALES BINANCE 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. Consulta de 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. WEBHOOK (NOTIFICACIÓN DE PAGO)

6.1. Payload recibido por el comercio

6.2 Respuesta requerida del comercio

7. Ambientes

Seguridad de credenciales

Detalle del objeto `webhook`

Detalle del objeto `data`

Descripción de `codigoRespuesta`