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

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

1. INTRODUCCION

Este documento describe cómo integrarse con la API de procesamiento de lotes de ATC. A través de este servicio, los comercios pueden gestionar sus transacciones utilizando lotes de forma simple y controlada.

Con esta API es posible autorizar lotes, consultar su estado en cualquier momento y recibir notificaciones automáticas con el resultado de cada lote.

La integración incluye los siguientes pasos:

Autenticarse mediante OAuth 2.0 (Client Credentials) para obtener un Access Token.
Enviar un lote para su autorización.
Consultar el estado del lote cuando sea necesario.
Recibir una notificación automática (Webhook/Callback) con el resultado del lote.

Credenciales

El Token Basic (Authorization), el client_id y el access_token de producción son proporcionados exclusivamente por ATC para cada integrador habilitado.

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 `Basic`.	Sí	`Basic ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2IwM==`
`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`
`branchCode`	Código de comercio.	Sí	`445545`

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).

3. AUTORIZACION DE LOTES

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

Antes de poder autorizar lotes, 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`

Header de autenticación

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

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

Response — Access Token

json

{
  "access_token": "1442981c-....-....-b...-ea12258c9...",
  "token_type": "access_token",
  "expires_in": 3600
}

json

{
  "access_token": "1442981c-....-....-b...-ea12258c9...",
  "token_type": "access_token",
  "expires_in": 3600
}

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.

4. Autorizar Lote

4.1. Método para autorizar el lote

Este método autoriza y valida el lote de transacciones. Una vez obtenido el Access Token, se puede invocar los servicios.

Atributo	Valor
Método HTTP	`POST`
URL (TEST)	`/payout/async/v3/lote/autorizar`
Header: `access_token`	`{access_token obtenido en autenticación}`
Header: `client_id`	`{client_id provisto por ATC}`
Header: `Content-Type`	`application/json`
Header: `branchCode`	`455544` ID de comercio

Request — autorizar lote

http

600;">POST /payout/async/v3/lote/autorizar
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  branchCode: 455544
  Content-Type: application/json

http

600;">POST /payout/async/v3/lote/autorizar
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  branchCode: 455544
  Content-Type: application/json

Campos del Request Body

json

{
  "processId": "66ec5b3d-61ea-4254-b366-7104545aa3c6",
  "webhookUrl": "https://dominio.com/api/confirmed?token=<token_del_comercio>",
  "transacciones": [
    {
      "transaccionId": "001002",
      "importe": 50.00,
      "fechaTransaccion": "2026-01-19",
      "cuentaOrigen": "484811311404044",
      "cuentaDestino": "1311404044",
      "codeBanco": "1018",
      "codeSucursal": "LPZ",
      "glosa": "DETALLE",
      "ciNitDestino": "54524525212",
      "titularDestino": "JOSE PEREZ",
      "tipoMoneda": "BOB"
    }
  ]
}

json

{
  "processId": "66ec5b3d-61ea-4254-b366-7104545aa3c6",
  "webhookUrl": "https://dominio.com/api/confirmed?token=<token_del_comercio>",
  "transacciones": [
    {
      "transaccionId": "001002",
      "importe": 50.00,
      "fechaTransaccion": "2026-01-19",
      "cuentaOrigen": "484811311404044",
      "cuentaDestino": "1311404044",
      "codeBanco": "1018",
      "codeSucursal": "LPZ",
      "glosa": "DETALLE",
      "ciNitDestino": "54524525212",
      "titularDestino": "JOSE PEREZ",
      "tipoMoneda": "BOB"
    }
  ]
}

Campos de la solicitud

Encabezado de la Solicitud

Campo	Tipo de Dato	Longitud	Requerido	Descripción
`processId`	string	36	Sí	Identificador único del proceso de transacciones.
`webhookUrl`	string	255	Sí	La información se usará para notificar el pago mediante método POST.

Transacciones (array de objetos)

Cada objeto dentro del array transacciones debe contener los siguientes campos:

Campo	Tipo de Dato	Longitud	Requerido	Descripción
`transaccionId`	string	Min=3, Max=14	Sí	Identificador único de la transacción.
`importe`	decimal	19.2	Sí	Monto de dinero que será transferido.
`fechaTransaccion`	string	10	Sí	Fecha de realización de la transacción (`yyyy-mm-dd`).
`cuentaOrigen`	string	Min=6, Max=30	Sí	La cuenta virtual de ATC.
`cuentaDestino`	string	Min=6, Max=30	Sí	Número de cuenta bancaria destino.
`codeBanco`	string	Min=3, Max=8	Sí	Código del banco destinatario donde se acreditará el importe (API – Lista de código bancos).
`codeSucursal`	string	3	Sí	Sucursal de la cuenta origen: Cochabamba CBB, Cobija COB, La Paz LPZ, Oruro ORU, Potosí POT, Santa Cruz SCZ, Sucre SUC, Tarija TJA y Trinidad TRI.
`glosa`	string	Min=3, Max=80	Sí	Descripción o motivo de la transacción.
`ciNitDestino`	string	Min=5, Max=20	Sí	Documento de identidad o NIT del titular de la cuenta destino.
`titularDestino`	string	Min=3, Max=80	Sí	Nombre completo del titular de la cuenta destino.
`tipoMoneda`	string	3	Sí	Tipo de moneda: `BOB`, `USD`.
`Reservado1`	string	Max=255	Opcional	Reservado para otros usos.
`Reservado2`	string	Max=255	Opcional	Reservado para otros usos.

Respuesta Exitosa

json

{
  "code": "00",
  "message": "success",
  "data": {
    "nroLote": "2601191040",
    "processId": "4554645646446",
    "transacciones": [
      {
        "transaccionId": "001001",
        "estado": "PENDIENTE",
        "numeroReferencia": "502125545442601",
        "mensaje": "Transacción en proceso."
      }
    ]
  }
}

json

{
  "code": "00",
  "message": "success",
  "data": {
    "nroLote": "2601191040",
    "processId": "4554645646446",
    "transacciones": [
      {
        "transaccionId": "001001",
        "estado": "PENDIENTE",
        "numeroReferencia": "502125545442601",
        "mensaje": "Transacción en proceso."
      }
    ]
  }
}

Detalle de la respuesta

Campo	Tipo	Longitud	Descripción
`nroLote`	string	Max=14	Número de lote de transacciones.
`processId`	string	36	Identificador único del proceso.
`transacciones`	array	—	Lista de transacciones procesadas.
`transaccionId`	string	Max=14	ID único de cada transacción del cliente.
`estado`	string	Max=16	Estado actual de la transacción (`INICIALIZADO`, `ERROR`).
`numeroReferencia`	Integer	Max=20	Número de referencia de transacción de ATC.
`mensaje`	string	Max=80	Mensaje descriptivo del estado.
`code`	string	Max=2	Código de respuesta del sistema.
`message`	string	80	Mensaje general de la operación.

Descripción:

data: Objeto principal con la respuesta.
transacciones: Array que contiene objetos de transacción.
Cada transacción tiene: transaccionId, estado, mensaje.

En caso de no encontrar al banco:

Respuesta de Error

json

{
  "data": {
    "nroLote": "2601191040",
    "processId": "66ec5b3d-61ea-4254-b366-7104545aa3c9",
    "transacciones": [
      {
        "transaccionId": "001002",
        "estado": "ERROR",
        "mensaje": "Codigo de banco no habilitado"
      }
    ]
  },
  "code": "00",
  "message": "Operación exitosa"
}

json

{
  "data": {
    "nroLote": "2601191040",
    "processId": "66ec5b3d-61ea-4254-b366-7104545aa3c9",
    "transacciones": [
      {
        "transaccionId": "001002",
        "estado": "ERROR",
        "mensaje": "Codigo de banco no habilitado"
      }
    ]
  },
  "code": "00",
  "message": "Operación exitosa"
}

Errores de Validaciones:

json

{
  "data": null,
  "code": "02",
  "message": "processId: El processId debe tener formato UUID y contener 36 caracteres"
}

json

{
  "data": null,
  "code": "02",
  "message": "processId: El processId debe tener formato UUID y contener 36 caracteres"
}

json

{
  "data": null,
  "code": "02",
  "message": "transacciones[0].fechaTransaccionValida: La fecha debe ser mayor o igual al día de hoy"
}

json

{
  "data": null,
  "code": "02",
  "message": "transacciones[0].fechaTransaccionValida: La fecha debe ser mayor o igual al día de hoy"
}

5. Consultar Estado de Lote o Transacción

5.1. Método para consultar el estado

Este método permite consultar el estado actual de un lote o una transacción específica.

Una vez obtenido el Access Token, se puede invocar los servicios.

Atributo	Valor
Método HTTP	`GET`
URL (TEST)	`/payout/async/v3/lote/estado`
Header: `access_token`	`{access_token obtenido en autenticación}`
Header: `client_id`	`{client_id provisto por ATC}`
Header: `Content-Type`	`application/json`
Header: `branchCode`	`455544` ID de comercio

Request — Consultar Estado de Lote

Ejemplos de solicitud:

Método 1 con numero de lote

http

600;">POST /payout/async/v3/lote/estado/{processId}?nroLote=2601191045
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  branchCode: 455544
  Content-Type: application/json

http

600;">POST /payout/async/v3/lote/estado/{processId}?nroLote=2601191045
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  branchCode: 455544
  Content-Type: application/json

Método 2 con ID de transacción

http

600;">POST /payout/async/v3/lote/estado/{processId}?transaccionId=545455
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  branchCode: 455544
  Content-Type: application/json

http

600;">POST /payout/async/v3/lote/estado/{processId}?transaccionId=545455
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  branchCode: 455544
  Content-Type: application/json

Parámetros de la Solicitud de Consulta

Campo	Tipo de Dato	Longitud	Requerido	Descripción
`nroLote`	string	Max=14	No	Número del lote que se desea consultar.
`transaccionId`	string	36	No	Identificador único de la transacción a consultar.

Response

Campo	Tipo	Longitud	Descripción
`nroLote`	string	Max=14	Número de lote de transacciones.
`transacciones`	array	—	Lista de transacciones procesadas.
`transaccionId`	string	Max=14	ID único de cada transacción.
`numeroReferencia`	string	Max=20	ID único referencia ATC.
`estado`	string	Max=16	Estado actual de la transacción (`PAGADO`, `PENDIENTE`, `TRANSITO`, `CANCELADO`).
`mensaje`	string	Max=80	Mensaje descriptivo del estado.
`cuentaOrigen`	string	Max=30	Número de cuenta originante (cuenta virtual ATC).
`cuentaDestino`	string	Max=30	Número de cuenta destino asociada.
`numeroAch`	string	20	Número de identificación ACH.
`numeroDestinatario`	string	20	Número de identificación Banco destinatario.
`ciCliente`	string	Max=30	Cédula de identidad del cliente.
`nombreCliente`	string	Max=30	Nombre completo del cliente.
`fechaHoraTransaccion`	LocalDateTime	—	Fecha y hora de la transacción.
`codigoBanco`	string	Max=10	Código de Banco.
`nombreBanco`	string	Max=100	Nombre de Banco.
`importe`	double	19.2	Importe de la transacción.
`moneda`	string	3	Tipo de moneda de la transacción.
`code`	string	2	Código de respuesta del sistema.
`message`	string	80	Mensaje general de la operación.

Descripción:

processId no está presente en esta respuesta.
message/code es "00" (éxito).
Nuevos campos: cuentaOrigen/cuentaDestino, numeroAch, ciCliente, nombreCliente.

Respuesta Exitosa

json

{
  "code": "00",
  "message": "Operación procesada correctamente",
  "nroLote": "L20260518000123",
  "transacciones": [
    {
      "transaccionId": "0121214",
      "numeroReferencia": "51021455454645646",
      "estado": "PAGADO",
      "mensaje": "Transacción acreditada en cuenta destino",
      "cuentaOrigen": "000123456",
      "cuentaDestino": "1234567890123",
      "numeroAch": "14000260518000001",
      "numeroDestinatario": "20260518000001",
      "ciCliente": "4567890",
      "nombreCliente": "Juan Pérez",
      "fechaHoraTransaccion": "2026-05-18T09:15:42",
      "codigoBanco": "1014",
      "nombreBanco": "Banco Nacional de Bolivia S.A.",
      "importe": 85.00,
      "moneda": "BOB"
    }
  ]
}

json

{
  "code": "00",
  "message": "Operación procesada correctamente",
  "nroLote": "L20260518000123",
  "transacciones": [
    {
      "transaccionId": "0121214",
      "numeroReferencia": "51021455454645646",
      "estado": "PAGADO",
      "mensaje": "Transacción acreditada en cuenta destino",
      "cuentaOrigen": "000123456",
      "cuentaDestino": "1234567890123",
      "numeroAch": "14000260518000001",
      "numeroDestinatario": "20260518000001",
      "ciCliente": "4567890",
      "nombreCliente": "Juan Pérez",
      "fechaHoraTransaccion": "2026-05-18T09:15:42",
      "codigoBanco": "1014",
      "nombreBanco": "Banco Nacional de Bolivia S.A.",
      "importe": 85.00,
      "moneda": "BOB"
    }
  ]
}

Respuesta de Error

Errores posibles:

Código	Descripción
`04`	Lote o transacción no encontrados: no se encontró el lote o la transacción.
`99`	Error de consulta: ocurrió un error en la consulta del estado.
`02`	Error en la validación: campo requerido al menos uno: `nroLote` o `transaccionId`.

json

{
  "data": null,
  "code": "04",
  "message": "Transacción no encontrada"
}

json

{
  "data": null,
  "code": "04",
  "message": "Transacción no encontrada"
}

6. Consultar de Bancos

6.1. Método Consultar de Bancos

Este método permite obtener la lista de bancos disponibles para realizar transacciones o acreditaciones.

Parámetros de la Solicitud de Consulta

Campo	Tipo de Dato	Requerido	Descripción
No aplica	—	—	Este método no requiere parámetros.

Respuesta Exitosa

json

{
  "code": "00",
  "message": "success",
  "data": [
    {
      "codigoBanco": "0101",
      "descripcion": "Banco Nacional de Crédito"
    },
    {
      "codigoBanco": "0202",
      "descripcion": "Banco de la Comunidad"
    }
  ]
}

json

{
  "code": "00",
  "message": "success",
  "data": [
    {
      "codigoBanco": "0101",
      "descripcion": "Banco Nacional de Crédito"
    },
    {
      "codigoBanco": "0202",
      "descripcion": "Banco de la Comunidad"
    }
  ]
}

7. Webhook de Notificación Transacciones

El comercio debe exponer un endpoint que recibirá las notificaciones de ATC una vez procesadas las transacciones. La URL y el token de seguridad se registran en el campo webhookUrl al momento de consumir el API de Autorizar.

text

POST https://dominio.com/api/confirmed?token=<token_del_comercio>

text

POST https://dominio.com/api/confirmed?token=<token_del_comercio>

Nota: Solo se permite conexión tras coordinación con el área de Infraestructura y Redes. Seguridad: token.

Campos enviados por ATC

Campo	Tipo	Longitud	Descripción
`nroLote`	string	Max=14	Número de lote de transacciones.
`transaccionId`	string	Max=14	ID único de cada transacción.
`numeroReferencia`	string	Max=20	ID único referencia ATC.
`estado`	string	Max=16	Estado actual de la transacción (`PAGADO`, `CANCELADO`).
`mensaje`	string	Max=80	Mensaje descriptivo del estado.
`cuentaOrigen`	string	Max=30	Número de cuenta originante (cuenta virtual ATC).
`cuentaDestino`	string	Max=30	Número de cuenta destino asociada.
`numeroAch`	string	20	Número de identificación ACH.
`numeroDestinatario`	string	20	Número de identificación Banco destinatario.
`ciCliente`	string	Max=30	Cédula de identidad del cliente.
`nombreCliente`	string	Max=30	Nombre completo del cliente.
`fechaHoraTransaccion`	LocalDateTime	—	Fecha y hora de la transacción.
`codigoBanco`	string	Max=10	Código de Banco.
`nombreBanco`	string	Max=100	Nombre de Banco.

Ejemplo — Body recibido por el comercio

json

{
  "nroLote": "2601191045",
  "transaccionId": "0121214",
  "numeroReferencia": "51021455454645646",
  "estado": "PAGADO",
  "mensaje": "Transacción acreditada en cuenta destino",
  "cuentaOrigen": "000123456",
  "cuentaDestino": "1234567890123",
  "numeroAch": "14000260518000001",
  "numeroDestinatario": "20260518000001",
  "ciCliente": "4567890",
  "nombreCliente": "Juan Pérez",
  "fechaHoraTransaccion": "2026-05-18T09:15:42",
  "codigoBanco": "1014",
  "nombreBanco": "Banco Nacional de Bolivia S.A.",
  "importe": 85.00,
  "moneda": "BOB"
}

json

{
  "nroLote": "2601191045",
  "transaccionId": "0121214",
  "numeroReferencia": "51021455454645646",
  "estado": "PAGADO",
  "mensaje": "Transacción acreditada en cuenta destino",
  "cuentaOrigen": "000123456",
  "cuentaDestino": "1234567890123",
  "numeroAch": "14000260518000001",
  "numeroDestinatario": "20260518000001",
  "ciCliente": "4567890",
  "nombreCliente": "Juan Pérez",
  "fechaHoraTransaccion": "2026-05-18T09:15:42",
  "codigoBanco": "1014",
  "nombreBanco": "Banco Nacional de Bolivia S.A.",
  "importe": 85.00,
  "moneda": "BOB"
}

Response Esperado del Comercio

Campo	Tipo	Descripción
`nroLote`	string	Número de referencia a la transacción.
`numeroReferencia`	string	ID único referencia ATC.
`codigoRespuesta`	string	`EXITOSO` o `FALLIDO` confirmando que el webhook fue recibido correctamente.
`detalleRespuesta`	string	Mensaje opcional (por ejemplo, `null` si todo OK).

Ejemplo JSON

json

{
  "nroLote": "2601191045",
  "numeroReferencia": "582154541121",
  "codigoRespuesta": "EXITOSO",
  "detalleRespuesta": null
}

json

{
  "nroLote": "2601191045",
  "numeroReferencia": "582154541121",
  "codigoRespuesta": "EXITOSO",
  "detalleRespuesta": null
}

8. Resumen de APIs

Método	Endpoint	Descripción
`POST`	`/payout/async/v3/lote/autorizar`	Registro de autorizaciones.
`GET`	`/payout/async/v3/lote/estado/{processId}`	Consulta el estado de un lote o una transacción. Puedes consultar por `{nroLote}` o `{transaccionId}`.
`POST`	`/payout/async/v3/bancos`	Devuelve la lista de bancos disponibles para las transacciones. No requiere parámetros adicionales.

9. AMBIENTES

El siguiente cuadro contiene los datos de ambientes con la URL y Token respectivamente.

	Desarrollo	Certificación	Producción
URL BASE	`https://atcgwapitest.redenlace.com.bo/desarrollo/`	`https://atcgwapitest.redenlace.com.bo/sandbox/`	`https://api.redenlace.com.bo/`
Token Basic	Client ID=`80b3c55d-5cb6-49de-91a0-070d353b0047` Client Secret=`d69eef41-1d2f-40ed-b4d4-7931bb9cbb74`	Solicitar el user y pass mediante correo electrónico.	Solicitar el user y pass mediante correo electrónico.

En esta página

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

1. INTRODUCCION

2. HEADER

3. AUTORIZACION DE LOTES

4. Autorizar Lote

5. Consultar Estado de Lote o Transacción

6. Consultar de Bancos

7. Webhook de Notificación Transacciones

8. Resumen de APIs

9. AMBIENTES