APIs de Dispersión Síncronas y Asíncronas - Dispersión de Fondos Síncrona

Especificación Técnica API Dispersión de Fondos Síncrona

Este documento describe los servicios web desarrollados por ATC, diseñados a medida para su integración con las distintas empresas aceptantes.

Todos los servicios expuestos están implementados siguiendo el estilo REST API y utilizan JSON como formato de intercambio de información.

1. Catálogo de Servicios Web

API	Endpoint	Método
Leer imagen QR	`/payout/sync/v3/qr/scan`	`POST`
Pagar imagen QR	`/payout/sync/v3/qr/confirm`	`POST`
Consulta estado QR	`/payout/sync/v3/qr/status/{numeroReferencia}`	`GET`

2. Autenticación y Autorización

Los servicios web utilizan la autenticación OAuth 2.0 (Client Credentials) para obtener un Access Token.

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.

Autenticación — Obtención del Access Token

Para utilizar los servicios de este documento, el integrador debe obtener un access_token válido mediante el flujo OAuth 2.0 Client Credentials.

Atributo	Valor
Método HTTP	`POST`
URL (TEST)	`/oauth-client-credentials/access-token?grant_type=client_credentials`
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 ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2IwMDQ3OmQ2OWVlZjQxLTFkMmYtNDBlZC1iNGQ0LTc5MzFiYjljYmI3NA==
  Content-Type: application/x-www-form-urlencoded

http

600;">POST /oauth-client-credentials/access-token?grant_type=client_credentials
Headers:
  Authorization: Basic ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2IwMDQ3OmQ2OWVlZjQxLTFkMmYtNDBlZC1iNGQ0LTc5MzFiYjljYmI3NA==
  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í

Response — 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"
}

Respuesta exitosa — Access Token

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. Servicio Web Leer Imagen QR

Este servicio permite leer una imagen QR y obtener la información contenida en ella, para posteriormente mostrarla en la aplicación y/o sistema correspondiente. De esta manera, el usuario puede identificar y validar la información del destinatario antes de realizar el pago.

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`
URL	`/payout/sync/v3/qr/scan`
Header: `access_token`	`{access_token obtenido en autenticación}`
Header: `client_id`	`{provisto por APP al momento de tener un cliente en el devportal}`
Header: `Content-Type`	`application/json`

Request — Leer Imagen QR

http

600;">POST /payout/sync/v3/qr/scan
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">POST /payout/sync/v3/qr/scan
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

Body del request

json

{
  "imagen": "iw2VTUp51O0g+rAg+5+PLQ33oB90AFXfQw3Jr1aY0CnB9py8FmrEkRz4Lnz5C……"
  }
}

json

{
  "imagen": "iw2VTUp51O0g+rAg+5+PLQ33oB90AFXfQw3Jr1aY0CnB9py8FmrEkRz4Lnz5C……"
  }
}

Parámetro	Tipo	Longitud	Requerido	Descripción
`imagen`	String	Variable (depende del tamaño de la cadena del QR)	Sí	Cadena de texto obtenida directamente por la aplicación de la empresa aceptante al escanear el código QR.

Estructura de respuesta

json

{
  "data": {
    "importe": 0,
    "moneda": "BOB",
    "glosa": "QR MLD BS",
    "numeroReferencia": "547260814000002110",
    "cuentaDestino": "1311713043",
    "ciNitDestino": "2274887",
    "titularDestino": "PERSONA NATURAL",
    "codigoBancoDestino": "1918",
    "nombreBancoDestino": "",
    "fechaVencimiento": "2026-09-05"
  },
  "code": "00"
}

json

{
  "data": {
    "importe": 0,
    "moneda": "BOB",
    "glosa": "QR MLD BS",
    "numeroReferencia": "547260814000002110",
    "cuentaDestino": "1311713043",
    "ciNitDestino": "2274887",
    "titularDestino": "PERSONA NATURAL",
    "codigoBancoDestino": "1918",
    "nombreBancoDestino": "",
    "fechaVencimiento": "2026-09-05"
  },
  "code": "00"
}

Parámetro	Tipo	Longitud	Req.	Descripción
`titularDestino`	String	Variable (Min=1, Max=255)	Sí	Nombre del destinatario de la transacción.
`ciNitDestino`	String	Variable (Min=1, Max=5)	Sí	Documento de identidad del destinatario.
`cuentaDestino`	String	Variable (Min=1, Max=255)	Sí	Número de cuenta del destinatario.
`moneda`	String	3	Sí	Código de la moneda utilizada en la transacción, para este caso `"BOB"`.
`importe`	Numeric(18,2)	—	Sí	Monto de la transacción, este puede ser 0.
`glosa`	String	Variable (Min=0, Max=255)	No	Campo opcional para comentarios.
`numeroReferencia`	String	20	Sí	Identificador único de la transacción generado por ATC.
`codigoBancoDestino`	String	Variable (Min=0, Max=10)	Sí	Código de banco destino.
`nombreBancoDestino`	String	Variable (Min=1, Max=255)	Sí	Nombre de banco destino.
`fechaVencimiento`	String	Formato `AAAAMMDD`	Sí	Fecha de expiración del QR.

Nota: esta información se obtiene siempre y cuando sea una imagen QR válida.

4. Servicio Web Pagar Imagen QR

Este servicio permite realizar el pago asociado a un código QR previamente leído desde la aplicación correspondiente.

Una vez obtenido el Access Token, se puede invocar el servicio.

Atributo	Valor
Método HTTP	`POST`
URL	`/payout/sync/v3/qr/confirm`
Header: `access_token`	`{access_token obtenido en autenticación}`
Header: `client_id`	`{provisto por APP al momento de tener un cliente en el devportal}`
Header: `Content-Type`	`application/json`

Request — Pagar Imagen QR

http

600;">POST /payout/sync/v3/qr/confirm
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">POST /payout/sync/v3/qr/confirm
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

Body de la Solicitud

json

{
  "numeroReferencia": "547260813000002109",
  "cuentaOrigen": "7010123451",
  "transaccionId": "REQ-TEST07",
  "importe": "100.50",
  "glosa": ""
}

json

{
  "numeroReferencia": "547260813000002109",
  "cuentaOrigen": "7010123451",
  "transaccionId": "REQ-TEST07",
  "importe": "100.50",
  "glosa": ""
}

Parámetro	Tipo	Long.	Req.	Descripción
`numeroReferencia`	String	20	Sí	Identificador único de la transacción generado por ATC.
`transaccionId`	String	32	Sí	Identificador único de la transacción generado por la empresa aceptante.
`cuentaOrigen`	String	20	Sí	La cuenta de ATC.
`importe`	Numeric(18,2)	—	Sí	Monto de la transacción. El monto a enviar debe ser mayor a cero cuando, al leer la imagen QR, el valor obtenido sea 0. En caso contrario, se debe enviar `0.00`.
`glosa`	String	Variable (Min=0, Max=255)	No	Comentario de la transacción. La glosa debe enviarse siempre que, al leer la imagen QR, el campo glosa no exista o esté vacío. En caso contrario, no se debe incluir este campo en la solicitud.

Estructura de la respuesta

El payload de respuesta en texto plano (es decir, sin cifrar) tiene la siguiente estructura:

json

{
  "data": {
    "numeroReferencia": "547260814000002111",
    "transaccionId": "REQ-TEST07",
    "fechaHoraTransaccion": "2026-08-14T11:00:36.320",
    "numOrdenAch": "14262608140249823031",
    "importe": 100.50,
    "moneda": "BOB",
    "estado": "APROBADA",
    "glosa": "QR MLD BS",
    "cuentaDestino": "1311713043",
    "titularDestino": "PERSONA NATURAL",
    "ciNitDestino": "2274887",
    "nombreBancoDestino": "",
    "codigoBancoDestino": "1918",
    "cuentaOrigen": "7010123451",
    "titularOrigen": "alias test 218"
  },
  "code": "00"
}

json

{
  "data": {
    "numeroReferencia": "547260814000002111",
    "transaccionId": "REQ-TEST07",
    "fechaHoraTransaccion": "2026-08-14T11:00:36.320",
    "numOrdenAch": "14262608140249823031",
    "importe": 100.50,
    "moneda": "BOB",
    "estado": "APROBADA",
    "glosa": "QR MLD BS",
    "cuentaDestino": "1311713043",
    "titularDestino": "PERSONA NATURAL",
    "ciNitDestino": "2274887",
    "nombreBancoDestino": "",
    "codigoBancoDestino": "1918",
    "cuentaOrigen": "7010123451",
    "titularOrigen": "alias test 218"
  },
  "code": "00"
}

Parámetro	Tipo	Long.	Req.	Descripción
`numeroReferencia`	String	20	Sí	Identificador único de la transacción generado por ATC.
`transaccionId`	String	32	Sí	Identificador único de la transacción generado por la empresa aceptante.
`fechaHoraTransaccion`	DateTime	—	Sí	Fecha y hora de la transacción.
`numOrdenAch`	String	Variable	Sí	Número de orden ACH.
`cuentaOrigen`	String	Variable (Min=0, Max=255)	Sí	Cuenta de origen de la transacción (cuenta de ATC).
`titularOrigen`	String	Variable (Min=0, Max=255)	Sí	Titular de la cuenta de origen (alias de la cuenta de ATC).
`cuentaDestino`	String	Variable (Min=0, Max=255)	Sí	Cuenta destino de la transacción.
`titularDestino`	String	Variable (Min=0, Max=255)	Sí	Titular de la cuenta destino.
`ciNitDestino`	String	Variable (Min=1, Max=50)	Sí	Documento de identidad del destinatario.
`importe`	Numeric(18,2)	—	Sí	Monto de la transacción.
`moneda`	String	3	Sí	Código de la moneda utilizada en la transacción, para este caso `"BOB"`.
`glosa`	String	Variable (Min=0, Max=255)	No	Campo opcional para comentarios.
`estado`	String	Variable (Min=5, Max=15)	Sí	Estado de la transacción: `APROBADA`.
`codigoBancoDestino`	String	Variable (Min=0, Max=10)	Sí	Código de banco destino.
`nombreBancoDestino`	String	Variable (Min=1, Max=255)	Sí	Nombre de banco destino.

Nota: esta información se obtiene siempre y cuando la transacción sea aprobada.

5. Servicio Web Consultar Estado QR

Este servicio permite consultar el estado actual de una transacción QR utilizando el número de referencia generado por ATC.

Una vez obtenido el Access Token, se puede invocar el servicio.

Atributo	Valor
Método HTTP	`POST`
URL	`/payout/sync/v3/qr/status/{numeroReferencia}`
Header: `access_token`	`{access_token obtenido en autenticación}`
Header: `client_id`	`{provisto por APP al momento de tener un cliente en el devportal}`
Header: `Content-Type`	`application/json`

Request — Consultar QR

http

600;">POST /payout/sync/v3/qr/status/{numeroReferencia}
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">POST /payout/sync/v3/qr/status/{numeroReferencia}
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

Estructura de solicitud

Parámetro de ruta

Parámetro	Tipo	Long.	Req.	Descripción
`numeroReferencia`	String	20	Sí	Identificador único de la transacción generado por ATC.

Estructura de respuesta

La respuesta exitosa utiliza la siguiente estructura general:

json

{
  "data": {
    "numeroReferencia": "547250827000000004",
    "transaccionId": "1234567890",
    "fechaHoraTransaccion": "2026-07-20T14:17:35",
    "estado": "APROBADA",
    "mensaje": "La transacción fue aprobada.",
    "importe": 10.00,
    "moneda": "BOB",
    "glosa": "Comentario a enviar",
    "cuentaOrigen": "1020255020",
    "titularOrigen": "A.T.C. S.A.",
    "cuentaDestino": "1006375018",
    "titularDestino": "MIRTHA ESCOBAR",
    "ciNitDestino": "1234567",
    "nombreBancoDestino": "BANCO DESTINO",
    "codigoBancoDestino": "001",
    "numOrdenAch": "123456789012345"
  },
  "code": "00"
}

json

{
  "data": {
    "numeroReferencia": "547250827000000004",
    "transaccionId": "1234567890",
    "fechaHoraTransaccion": "2026-07-20T14:17:35",
    "estado": "APROBADA",
    "mensaje": "La transacción fue aprobada.",
    "importe": 10.00,
    "moneda": "BOB",
    "glosa": "Comentario a enviar",
    "cuentaOrigen": "1020255020",
    "titularOrigen": "A.T.C. S.A.",
    "cuentaDestino": "1006375018",
    "titularDestino": "MIRTHA ESCOBAR",
    "ciNitDestino": "1234567",
    "nombreBancoDestino": "BANCO DESTINO",
    "codigoBancoDestino": "001",
    "numOrdenAch": "123456789012345"
  },
  "code": "00"
}

Parámetro	Tipo	Long.	Req.	Descripción
`numeroReferencia`	String	20	Sí	Identificador único de la transacción generado por ATC.
`transaccionId`	String	Máx. 32	No	Identificador único de la transacción generado por la empresa aceptante.
`fechaHoraTransaccion`	DateTime	—	No	Fecha y hora de la transacción en formato ISO-8601. Puede ser nula cuando la operación todavía no fue procesada.
`estado`	String	Variable	Sí	Estado actual de la transacción.
`mensaje`	String	Variable	Sí	Descripción del estado actual de la transacción.
`importe`	Numeric(18,2)	—	Sí	Monto de la transacción.
`moneda`	String	3	Sí	Código de la moneda utilizada en la transacción, para este caso `"BOB"`.
`glosa`	String	Variable (Min=0, Max=255)	No	Campo opcional para comentarios.
`cuentaOrigen`	String	Variable (Min=0, Max=255)	Sí	Cuenta de origen de la transacción (cuenta de ATC).
`titularOrigen`	String	Variable (Min=0, Max=255)	Sí	Titular de la cuenta de origen (alias de la cuenta de ATC).
`cuentaDestino`	String	Variable (Min=0, Max=255)	Sí	Cuenta destino de la transacción.
`titularDestino`	String	Variable (Min=0, Max=255)	Sí	Titular de la cuenta destino.
`ciNitDestino`	String	Variable	Sí	Documento de identidad del destinatario.
`nombreBancoDestino`	String	Máx=255	No	Nombre de banco destino.
`codigoBancoDestino`	String	Variable (Min=0, Max=10)	Sí	Código de banco destino.
`numOrdenAch`	String	Variable	Condicional	Número de orden ACH. Se devuelve únicamente cuando la transacción se encuentra aprobada y el dato está disponible.

Campos generales de la respuesta

Parámetro	Tipo	Requerido	Descripción
`data`	Object	Sí	Información de la transacción en caso de ser exitosa.
`code`	String	Sí	Código de respuesta / error en caso de ser fallida la transacción.
`errorMessage`	String	Sí	Descripción del error. No se retorna cuando la operación es exitosa.

Estados de la transacción

Estado	Mensaje	Descripción
`APROBADA`	La transacción fue aprobada	El pago fue confirmado correctamente.
`RECHAZADA`	La transacción fue rechazada	El pago fue rechazado o no pudo completarse definitivamente.
`PENDIENTE_PAGO`	La transacción está pendiente de pago.	La transacción fue generada, pero el flujo de pago todavía no fue iniciado o completado.
`EN_PROCESO`	La transacción se encuentra en proceso	El pago se encuentra siendo procesado.
`PENDIENTE_CONFIRMACION`	La transacción está pendiente de confirmación.	El resultado definitivo todavía requiere validación o regularización interna. Se debe realizar una nueva consulta posteriormente.

Ejemplo de respuesta con error

json

{
  "code": "04",
  "errorMessage": "Transacción no encontrada."
}

json

{
  "code": "04",
  "errorMessage": "Transacción no encontrada."
}

7. Códigos de Respuesta

Código	Descripción
`00`	Operación exitosa
`02`	Datos de entrada inválidos
`04`	Transacción no encontrada
`08`	QR expirado
`09`	QR no válido
`10`	Moneda QR no válida
`11`	Monto obligatorio
`12`	Glosa obligatoria
`13`	Saldo insuficiente
`14`	Estado de transacción no válido
`15`	Número de cuenta no encontrada
`94`	Error o resultado no confirmado en sistema de saldos
`95`	Error interno
`96`	Error o resultado no confirmado en emisor – ATC
`99`	Error interno no controlado

8. Tiempos de Respuesta

API	Timeout
Leer imagen QR	El cliente deberá configurar un timeout máximo de 40 segundos para esta operación.
Pagar imagen QR	El cliente deberá configurar un timeout máximo de 90 segundos para esta operación.
Consultar estado QR	El cliente deberá configurar un timeout máximo de 90 segundos para esta operación.

Nota: los tiempos indicados corresponden al tiempo máximo de espera que el cliente debe configurar antes de considerar que una solicitud ha excedido el límite permitido. Estos valores no representan el tiempo habitual ni el tiempo promedio de respuesta de los servicios.

9. Ambientes

Sandbox	Producción
`https://atcgwapitest.redenlace.com.bo/sandbox`	`https://api.redenlace.com.bo`

En esta página

Especificación Técnica API Dispersión de Fondos Síncrona