Crear Destinatario (ACH)

Visión General

Este endpoint permite a las entidades crear un nuevo destinatario ACH, el cual podrá ser utilizado únicamente para operaciones relacionadas con ACH (por ejemplo, dispersión ACH). Los destinatarios creados mediante este endpoint no pueden utilizarse para pagos Bre-B, flujos de QR ni para ningún otro producto.

El destinatario puede representar una PERSONA NATURAL (INDIVIDUAL) o una EMPRESA (BUSINESS) y debe incluir la información de identificación y los datos bancarios requeridos para una transferencia ACH.

Detalles del Endpoint

Parámetro	Descripción
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/recipients/ach
Método	POST
Encabezados	Content-Type: application/json, Authorization
Autenticación	Token de Acceso (Bearer Token)

Cuerpo de la Solicitud

Parámetro	Tipo	Restricciones	Requerido	Descripción
customer_id	String	N/A	Sí	Identificador único del cliente de la entidad que crea el destinatario.
alias	String	[0-128]	No	Nombre o etiqueta amigable para identificar al destinatario ACH. Ej: “Pepito SAS5”.
recipient_type	String	`BUSINESS` o `INDIVIDUAL`	Sí	Tipo de destinatario.
identification_type	String	`CC`, `CE`, `NUIP`, `PPT`, `PEP`, `NIT`, `PAS`, `TDI`	Sí	Tipo de identificación. CC: Cédula de Ciudadanía CE: Cédula de Extranjería NUIP: Número Único de Identificación Personal PPT: Permiso por Protección Temporal PEP: Permiso Especial de Permanencia NIT: Número de Identificación Tributaria PAS: Pasaporte TDI: Tarjeta de Identidad
account_type	String	`LOW_VALUE`, `ORDINARY`, `CHECKING`, `SAVINGS`, `INCLUSIVE_LOW_VALUE`	Sí	Tipo de cuenta ACH.
account_number	String	[1-18]	Sí	Número de cuenta bancaria para ACH
bank_name	String	Ver lista de bancos abajo.	Sí	Nombre del banco asociado a la cuenta.

Listado de Bancos

Nombre de los Bancos
BANCAMIA S.A BANCO AGRARIO BANCO AV VILLAS BANCO BGT PACTUAL BANCO CAJA SOCIAL BANCO CITIBANK COLOMBIA BANCO CONTACTAR S.A. BANCO COOPERATIVO COOPCENTRAL BANCO CREDIFINANCIERA SA BANCO DE BOGOTÁ BANCO DE OCCIDENTE BANCO FALABELLA BANCO FINANDINA BANCO GNB SUDAMERIS BANCO MUNDO MUJER BANCO PICHINCHA S.A. BANCO POPULAR BANCO PROCREDIT BANCO SERFINANZA SA BANCO UNION BANCO W SA BANCOLDEX BANCOLOMBIA BANCOOMEVA BANCO SANTANDER DE NEGOCIOS BBVA BNP PARIBAS COLOMBIA BOLD CFCFA FINANCIERA ANTIOQUIA COINK COLTEFINANCIERA CONFIAR COTRAFA ENTIDAD FINANCIERA CREZCAMOS DAVIPLATA DAVIVIENDA DING TECNIPAGOS SA FINANCIERA JURISCOOP CFG GLOBAL66 IRIS CFI ITAU BANCO CORPBANCA ITAU* HELM BANK J.P. MORGAN COLOMBIA JFK COOPERATIVA FINANCIERA LULO BANK S.A. MIBANCO MOVII NEQUI NUPI BANK POWWI RAPPIPAY SCOTIABANK COLPATRIA UALA

Ejemplo de Solicitud

JSON
    
 
curl --location --request POST 'https://api.paas.develop.co.passportfintech.com/v1/recipients/ach' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
    "customer_id": "8bebf7a7-9ca7-4a69-878b-e87f1578f7be",
    "alias": "Pepito SASA223222235232222",
    "recipient_type": "BUSINESS", 
    "identification_type": "NIT",
    "identification_number": "123456789",
    "account_type": "LOW_VALUE",
    "account_number": "880909090912",
    "bank_name": "BANCOLOMBIA"
}'
Copy

Cuerpo de la Respuesta

Código HTTP: 200 OK
Retorna los datos del destinatario creado junto con su ID único.

Ejemplo de Respuesta

JSON
    
 
{
    "created_at": "2025-11-17T17:08:24.890Z",
    "updated_at": "2025-11-17T17:08:24.890Z",
    "type": "ACH",
    "owner": {
        "type": "BUSINESS",
        "identification_type": "NIT",
        "identification_number": "123456789"
    },
    "alias": "Pepito SASA223222235232222",
    "account": {
        "account_type": "LOW_VALUE",
        "account_number": "880909090912"
    },
    "id": "c49714fc-b196-4e43-8efd-0d207922fa68",
    "customer_id": "8bebf7a7-9ca7-4a69-878b-e87f1578f7be"
}
Copy

El campo id es el identificador único del destinatario, que se utilizará para futuras transacciones.

Errores Comunes y Manejo

Código HTTP	Significado	Descripción
400 Bad Request	Datos inválidos	Faltan campos requeridos o contienen valores incorrectos.
401 Unauthorized	Token inválido	El token de acceso ha expirado o es inválido.
403 Forbidden	Acceso denegado	La solicitud no está autorizada para validar crear un destinatario.
500 Server Error	Error del servidor	Se produjo un error inesperado durante la creación del destinatario.

Buenas Prácticas

Verifica que el customer_id pertenezca a un cliente válido.
Valida los datos de identificación del destinatario antes de enviarlos.

Última actualización el