Skip to Content
Conceptos ClaveContactos y Cuentas Bancarias

Contactos y Cuentas Bancarias

Los Contactos representan a tus clientes o proveedores en el sistema Koywe, almacenando su información y cuentas bancarias vinculadas para operaciones de pago.

¿Qué son los Contactos?

Un Contacto es una persona o entidad comercial con la que interactúas a través de pagos:

  • Clientes que te pagan (PAYIN)
  • Proveedores a los que tú pagas (PAYOUT)
  • Ambos en escenarios de marketplace

¿Por qué Usar Contactos?

📈Seguimiento

Rastrea el historial de pagos por cliente o proveedor

🛡️Cumplimiento

Almacena información KYC/cumplimiento (documentos, IDs fiscales)

💸Pagos Simplificados

Vincula cuentas bancarias para pagos recurrentes fáciles

🧾Reportes

Genera reportes por contacto o tipo de negocio

Estructura de Contacto

Campos Requeridos

{
  "email": "cliente@ejemplo.com",           // Opcional pero recomendado
  "fullName": "Juan Pérez",                 // Nombre legal completo
  "countrySymbol": "CO",                    // Código de país
  "businessType": "PERSON"                  // PERSON, COMPANY, etc.
}

Campos Opcionales

{
  "phone": "+573001234567",                 // Número de teléfono
  "documentType": "CC",                     // Tipo de documento de ID
  "documentNumber": "1234567890",           // Número de documento de ID
  "taxIdType": "NIT",                       // Tipo de ID fiscal
  "taxIdNumber": "900123456",               // Número de ID fiscal
  "address": {
    "street": "Calle 123",
    "city": "Bogotá",
    "state": "Cundinamarca",
    "zipCode": "110111",
    "country": "CO"
  }
}

Crear Contactos

Creación Básica de Contacto

async function createContact(token, orgId, merchantId, contactData) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts`,
    {
      email: contactData.email,
      phone: contactData.phone,
      fullName: contactData.fullName,
      countrySymbol: contactData.country,
      documentType: contactData.documentType,
      documentNumber: contactData.documentNumber,
      businessType: 'PERSON'  // o 'COMPANY'
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Uso - Crear contacto de cliente
const customer = await createContact(token, orgId, merchantId, {
  email: 'cliente@ejemplo.com',
  phone: '+573001234567',
  fullName: 'Juan Pérez',
  country: 'CO',
  documentType: 'CC',
  documentNumber: '1234567890'
});
 
console.log('Contacto creado:', customer.id);
def create_contact(token, org_id, merchant_id, contact_data):
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/contacts',
        json={
            'email': contact_data['email'],
            'phone': contact_data['phone'],
            'fullName': contact_data['full_name'],
            'countrySymbol': contact_data['country'],
            'documentType': contact_data['document_type'],
            'documentNumber': contact_data['document_number'],
            'businessType': 'PERSON'
        },
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    
    return response.json()
 
# Uso
customer = create_contact(token, org_id, merchant_id, {
    'email': 'cliente@ejemplo.com',
    'phone': '+573001234567',
    'full_name': 'Juan Pérez',
    'country': 'CO',
    'document_type': 'CC',
    'document_number': '1234567890'
})
curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/TU_ORG_ID/merchants/TU_MERCHANT_ID/contacts' \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "cliente@ejemplo.com",
    "phone": "+573001234567",
    "fullName": "Juan Pérez",
    "countrySymbol": "CO",
    "documentType": "CC",
    "documentNumber": "1234567890",
    "businessType": "PERSON"
  }'

Respuesta:

{
  "id": "cnt_abc123",
  "email": "cliente@ejemplo.com",
  "phone": "+573001234567",
  "fullName": "Juan Pérez",
  "countrySymbol": "CO",
  "documentType": "CC",
  "documentNumber": "1234567890",
  "businessType": "PERSON",
  "createdAt": "2025-11-13T10:00:00Z",
  "merchantId": "mrc_xyz789"
}

Tipos de Documento por País

Colombia (CO)

Tipo de DocumentoCódigoDescripciónEjemplo
Cédula de CiudadaníaCCID Nacional1234567890
Cédula de ExtranjeríaCEID Extranjero1234567
NITNITID Fiscal (empresas)900123456-1

Brasil (BR)

Tipo de DocumentoCódigoDescripciónEjemplo
CPFCPFID Fiscal Individual123.456.789-00
CNPJCNPJID Fiscal de Empresa12.345.678/0001-90

México (MX)

Tipo de DocumentoCódigoDescripciónEjemplo
RFCRFCID FiscalXAXX010101000
CURPCURPRegistro de PoblaciónABCD123456HDFXXX09

Chile (CL)

Tipo de DocumentoCódigoDescripciónEjemplo
RUTRUTID Fiscal11.111.111-1

Argentina (AR)

Tipo de DocumentoCódigoDescripciónEjemplo
DNIDNIID Nacional12345678
CUITCUITID Fiscal20-12345678-9

Cuentas Bancarias

Vincular Cuentas Bancarias a Contactos

Para operaciones PAYOUT, necesitas vincular una cuenta bancaria al contacto:

Asociación Automática: Las cuentas bancarias se vinculan automáticamente con la información del contacto. El nombre del titular se toma del fullName del contacto. Los códigos bancarios pueden deducirse de los números de cuenta para la mayoría de los países.

Campos Opcionales con Valores por Defecto

CampoTipoValor por DefectoDescripción
accountTypestringVIRTUALTipo de cuenta: SAVINGS, CHECKING, o VIRTUAL. Requerido para Colombia. Opcional para la mayoría de países.
isVirtualbooleanfalseSi es una cuenta virtual.
isTrackedbooleanfalseSi la cuenta tiene seguimiento para monitoreo de saldo.

Campos Requeridos por País

Paísentity (código banco)Notas
Colombia (CO)RequeridoDebe proporcionar código de banco
Chile (CL)RequeridoDebe proporcionar código de banco
Perú (PE)OpcionalAuto-deducido del número de cuenta (CCI)
Argentina (AR)OpcionalAuto-deducido de CVU/CBU
México (MX)OpcionalAuto-deducido de CLABE
Brasil (BR)OpcionalAuto-deducido
async function addBankAccountToContact(token, orgId, merchantId, contactId, bankData) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts/${contactId}/accounts`,
    {
      countrySymbol: bankData.country,
      currencySymbol: bankData.currency,
      entity: bankData.entity,           // Requerido para CO, CL. Opcional para otros (auto-deducido)
      accountNumber: bankData.accountNumber,
      accountType: bankData.accountType  // Requerido para Colombia: 'SAVINGS' o 'CHECKING'
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Uso - Colombia (entity requerido)
const bankAccountCO = await addBankAccountToContact(token, orgId, merchantId, 'cnt_abc123', {
  country: 'CO',
  currency: 'COP',
  entity: 'BANCOLOMBIA',       // Requerido para Colombia y Chile
  accountNumber: '1234567890',
  accountType: 'SAVINGS'       // Requerido para Colombia
});
 
// Uso - Perú (entity auto-deducido del CCI)
const bankAccountPE = await addBankAccountToContact(token, orgId, merchantId, 'cnt_def456', {
  country: 'PE',
  currency: 'PEN',
  accountNumber: '00219100012345678901'  // CCI de 20 dígitos - código banco auto-deducido
});
 
console.log('Cuenta bancaria agregada:', bankAccountCO.id);
def add_bank_account_to_contact(token, org_id, merchant_id, contact_id, bank_data):
    payload = {
        'countrySymbol': bank_data['country'],
        'currencySymbol': bank_data['currency'],
        'accountNumber': bank_data['account_number']
    }
    
    # entity requerido para CO, CL; opcional para otros
    if bank_data.get('entity'):
        payload['entity'] = bank_data['entity']
    
    # accountType requerido para Colombia; opcional para otros países (por defecto VIRTUAL)
    if bank_data.get('account_type'):
        payload['accountType'] = bank_data['account_type']
    
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/contacts/{contact_id}/accounts',
        json=payload,
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    
    return response.json()
 
# Uso - Colombia (entity requerido)
bank_account_co = add_bank_account_to_contact(token, org_id, merchant_id, 'cnt_abc123', {
    'country': 'CO',
    'currency': 'COP',
    'entity': 'BANCOLOMBIA',      # Requerido para Colombia
    'account_number': '1234567890',
    'account_type': 'SAVINGS'        # Requerido para Colombia
})
 
# Uso - Chile (entity requerido)
bank_account_cl = add_bank_account_to_contact(token, org_id, merchant_id, 'cnt_ghi789', {
    'country': 'CL',
    'currency': 'CLP',
    'entity': 'BANCO_ESTADO',     # Requerido para Chile
    'account_number': '12345678901'
})
# Colombia - entity (código banco) requerido
curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/TU_ORG_ID/merchants/TU_MERCHANT_ID/contacts/cnt_abc123/accounts' \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "countrySymbol": "CO",
    "currencySymbol": "COP",
    "entity": "BANCOLOMBIA",
    "accountNumber": "1234567890",
    "accountType": "SAVINGS"
  }'

Requisitos por País: Consulta Cuentas Externas del Comercio para reglas de validación detalladas por país. Las cuentas bancarias de contactos siguen las mismas validaciones (CLABE para México, CCI para Perú, CVU/CBU para Argentina, etc.).

Recuperar Contactos

Listar Todos los Contactos

async function listContacts(token, orgId, merchantId, options = {}) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts`,
    {
      params: {
        search: options.search,        // Opcional: buscar por nombre o email
        limit: options.limit || 50,
        page: options.page || 1
      },
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return response.data;
}
 
// Uso
const contacts = await listContacts(token, orgId, merchantId, {
  search: 'juan',
  limit: 20
});
 
console.log(`Se encontraron ${contacts.length} contactos`);

Obtener Contacto Específico

async function getContact(token, orgId, merchantId, contactId) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts/${contactId}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return response.data;
}
 
// Uso
const contact = await getContact(token, orgId, merchantId, 'cnt_abc123');
console.log('Contacto:', contact);

Obtener Cuentas Bancarias del Contacto

async function getContactBankAccounts(token, orgId, merchantId, contactId) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts/${contactId}/accounts`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return response.data;
}
 
// Uso
const bankAccounts = await getContactBankAccounts(token, orgId, merchantId, 'cnt_abc123');
console.log('Cuentas bancarias:', bankAccounts);

Actualizar Contactos

async function updateContact(token, orgId, merchantId, contactId, updates) {
  const response = await axios.put(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts/${contactId}`,
    updates,
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Uso - Actualizar teléfono o dirección
const updated = await updateContact(token, orgId, merchantId, 'cnt_abc123', {
  phone: '+573009876543',
  address: {
    street: 'Calle 456',
    city: 'Medellín'
  }
});

Requisitos de Validación

Persona vs Empresa

Para PERSON (individual):

  • Usa tipos de documento individual (CC, DNI, CPF, etc.)
  • businessType: "PERSON"
  • Nombre completo del individuo

Para COMPANY (empresa):

  • Usa tipos de documento de empresa (NIT, CNPJ, CUIT, etc.)
  • businessType: "COMPANY"
  • Nombre legal de la empresa

Formatos de Número de Documento

Los números de documento deben coincidir con el formato esperado para cada país:

  • Colombia CC: 6-10 dígitos
  • Brasil CPF: 11 dígitos (con o sin formato)
  • México RFC: 12-13 caracteres
  • Chile RUT: Formato XX.XXX.XXX-X

Mejores Prácticas

Cuándo Crear Contactos

Crear contactos para:

  • Clientes haciendo pagos (PAYIN) - para seguimiento y cumplimiento
  • Proveedores recibiendo pagos (PAYOUT) - requerido para vinculación de cuenta bancaria
  • Transacciones recurrentes con la misma entidad

Reutilizar Contactos

Reutiliza contactos existentes para el mismo cliente/proveedor para:

  • Mantener historial de pagos
  • Evitar registros duplicados
  • Simplificar reconciliación
// Verificar si el contacto existe antes de crear
async function getOrCreateContact(token, orgId, merchantId, email) {
  // Intentar encontrar existente
  const contacts = await listContacts(token, orgId, merchantId, { search: email });
  
  if (contacts.length > 0) {
    return contacts[0];  // Devolver existente
  }
  
  // Crear nuevo si no se encuentra
  return await createContact(token, orgId, merchantId, {
    email: email,
    // ... otros campos
  });
}

Privacidad de Datos

Consideraciones de Seguridad:

  • Almacena solo información necesaria
  • Sigue regulaciones GDPR/protección de datos
  • No almacenes datos sensibles en campos de metadata
  • Implementa controles de acceso apropiados

Escenarios Comunes

Escenario 1: Pago de Cliente E-Commerce

// 1. Crear contacto de cliente
const customer = await createContact(token, orgId, merchantId, {
  email: 'cliente@ejemplo.com',
  fullName: 'María García',
  country: 'CO',
  documentType: 'CC',
  documentNumber: '1234567890',
  phone: '+573001234567'
});
 
// 2. Crear orden PAYIN vinculada al contacto
const order = await createPayinOrder(token, orgId, merchantId, {
  contactId: customer.id,
  amount: 50000,
  currency: 'COP',
  // ... otros campos
});

Escenario 2: Pago a Proveedor

// 1. Crear contacto de proveedor
const provider = await createContact(token, orgId, merchantId, {
  email: 'proveedor@ejemplo.com',
  fullName: 'Servicios ABC SAS',
  country: 'CO',
  documentType: 'NIT',
  documentNumber: '900123456-1',
  businessType: 'COMPANY'
});
 
// 2. Agregar cuenta bancaria del proveedor
const bankAccount = await addBankAccountToContact(token, orgId, merchantId, provider.id, {
  country: 'CO',
  currency: 'COP',
  entity: 'BANCOLOMBIA',        // Requerido para Colombia
  accountNumber: '1234567890',
  accountType: 'CHECKING'       // Requerido para Colombia
  // holderName auto-vinculado de provider.fullName
});
 
// 3. Crear orden PAYOUT
const payout = await createPayoutOrder(token, orgId, merchantId, {
  contactId: provider.id,
  destinationAccountId: bankAccount.id,  // Vincular a cuenta bancaria
  amount: 500000,
  currency: 'COP'
});

Próximos Pasos

🧾Órdenes y Tipos de Orden

Aprende cómo se usan los contactos en las órdenes

💵Aceptar Pagos

Crear órdenes PAYIN con contactos de clientes

💸Pagar Proveedores

Guía completa para pagos a proveedores

💻Referencia API

Documentación completa de API de contactos

Last updated on
Cuentas Externas del ComercioÓrdenes y Tipos de Orden