Skip to main content

​
¿Qué es un Cliente?

Un cliente es la representación de una persona natural o jurídica dentro de OnePay. Es el objeto central al que se asocian métodos de pago (tarjetas, cuentas bancarias), cobros y dispersiones. Debes crear un cliente antes de poder:
  • Registrar tarjetas o cuentas bancarias
  • Crear cargos (débitos directos)
  • Enviar dispersiones (payouts)
  • Crear suscripciones

​
¿Cuándo crear un Cliente?

Escenario¿Necesitas un cliente?
Enviar un link de pago (POST /payments)No (solo necesitas phone o email)
Debitar una tarjeta o cuenta (POST /charges)Sí
Dispersar dinero a un tercero (POST /cashouts)Sí
Crear una suscripción recurrenteSí
Emitir una tarjeta (Issuing)Sí

​
Tipos de cliente

  • natural: Persona natural (identificada con CC, CE o PASSPORT)
  • company: Persona jurídica (identificada con NIT)

​
Ejemplo rápido

curl https://api.onepay.la/v1/customers \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: cli-001" \
  -d '{
    "user_type": "natural",
    "first_name": "María",
    "last_name": "López",
    "email": "maria@ejemplo.com",
    "phone": "+573201112233",
    "document_type": "CC",
    "document_number": "1060500333"
  }'

​
Relaciones

Cliente
  ├── Cuentas bancarias (/accounts)
  ├── Tarjetas (/cards)
  ├── Suscripciones (/subscriptions)
  ├── Tarjetas emitidas (/issuing/cards)
  └── Billetera (/wallets)
Para consultar los métodos de pago de un cliente específico, usa:

​
Endpoints

MétodoEndpointDescripción
POST/customersCrear cliente
GET/customersListar clientes
GET/customers/Detalle de un cliente
DELETE/customers/Eliminar cliente