Crear clientes

curl https://api.onepay.la/v1/customers \
  -X POST \
  -H "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: customer-001" \
  -d '{
    "user_type": "natural",
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "document_type": "CC",
    "document_number": "1234567890",
    "enable_notifications": true
  }'

const response = await fetch('https://api.onepay.la/v1/customers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi',
    'Content-Type': 'application/json',
    'x-idempotency': 'customer-001'
  },
  body: JSON.stringify({
    user_type: 'natural',
    first_name: 'Juan',
    last_name: 'Pérez',
    email: 'juan@example.com',
    phone: '+573001234567',
    document_type: 'CC',
    document_number: '1234567890',
    enable_notifications: true
  })
});

const customer = await response.json();
console.log(customer);

import requests

response = requests.post(
    'https://api.onepay.la/v1/customers',
    headers={
        'Authorization': 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi',
        'Content-Type': 'application/json',
        'x-idempotency': 'customer-001'
    },
    json={
        'user_type': 'natural',
        'first_name': 'Juan',
        'last_name': 'Pérez',
        'email': 'juan@example.com',
        'phone': '+573001234567',
        'document_type': 'CC',
        'document_number': '1234567890',
        'enable_notifications': True
    }
)

customer = response.json()
print(customer)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onepay.la/v1/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi",
    "Content-Type: application/json",
    "x-idempotency: customer-001"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "user_type" => "natural",
    "first_name" => "Juan",
    "last_name" => "Pérez",
    "email" => "juan@example.com",
    "phone" => "+573001234567",
    "document_type" => "CC",
    "document_number" => "1234567890",
    "enable_notifications" => true
  ])
]);

$response = curl_exec($curl);
curl_close($curl);

$customer = json_decode($response, true);
print_r($customer);
?>

{
  "id":"9da58912-101d-46f8-86c9-20a52119c0bf",
  "first_name":"John",
  "last_name":"Doe",
  "email":"john.doe@example.com",
  "phone":"+573100001020",
  "document_type":"CC",
  "document_number":"1060500333",
  "nationality":"CO",
  "birthdate":"1990-01-01",
  "created_at":"2024-12-04T20:09:08.000000Z"
}

{
   "message":"El campo nombre es obligatorio. (y 6 errores m\u00e1s)",
   "code":10001,
   "code_name":"validation_error",
   "errors":{
      "first_name":[
         "El campo nombre es obligatorio."
      ],
      "last_name":[
         "El campo apellido es obligatorio."
      ],
      "phone":[
         "El campo tel\u00e9fono es obligatorio."
      ],
      "email":[
         "El campo correo electr\u00f3nico es obligatorio."
      ],
      "user_type":[
         "El campo user type es obligatorio."
      ],
      "document_type":[
         "El campo document type es obligatorio."
      ],
      "document_number":[
         "El campo document number es obligatorio."
      ],
      "nationality":[
         "El código de país debe seguir el formato ISO 3166-1 alpha-2"
      ],
      "birthdate":[
         "La fecha debe tener el formato YYYY-MM-DD"
      ]
   }
}

{
  "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
  "code": 10003,
  "code_name": "idempotency_error"
}

POST

customers

curl https://api.onepay.la/v1/customers \
  -X POST \
  -H "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: customer-001" \
  -d '{
    "user_type": "natural",
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "document_type": "CC",
    "document_number": "1234567890",
    "enable_notifications": true
  }'

const response = await fetch('https://api.onepay.la/v1/customers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi',
    'Content-Type': 'application/json',
    'x-idempotency': 'customer-001'
  },
  body: JSON.stringify({
    user_type: 'natural',
    first_name: 'Juan',
    last_name: 'Pérez',
    email: 'juan@example.com',
    phone: '+573001234567',
    document_type: 'CC',
    document_number: '1234567890',
    enable_notifications: true
  })
});

const customer = await response.json();
console.log(customer);

import requests

response = requests.post(
    'https://api.onepay.la/v1/customers',
    headers={
        'Authorization': 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi',
        'Content-Type': 'application/json',
        'x-idempotency': 'customer-001'
    },
    json={
        'user_type': 'natural',
        'first_name': 'Juan',
        'last_name': 'Pérez',
        'email': 'juan@example.com',
        'phone': '+573001234567',
        'document_type': 'CC',
        'document_number': '1234567890',
        'enable_notifications': True
    }
)

customer = response.json()
print(customer)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onepay.la/v1/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi",
    "Content-Type: application/json",
    "x-idempotency: customer-001"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "user_type" => "natural",
    "first_name" => "Juan",
    "last_name" => "Pérez",
    "email" => "juan@example.com",
    "phone" => "+573001234567",
    "document_type" => "CC",
    "document_number" => "1234567890",
    "enable_notifications" => true
  ])
]);

$response = curl_exec($curl);
curl_close($curl);

$customer = json_decode($response, true);
print_r($customer);
?>

{
  "id":"9da58912-101d-46f8-86c9-20a52119c0bf",
  "first_name":"John",
  "last_name":"Doe",
  "email":"john.doe@example.com",
  "phone":"+573100001020",
  "document_type":"CC",
  "document_number":"1060500333",
  "nationality":"CO",
  "birthdate":"1990-01-01",
  "created_at":"2024-12-04T20:09:08.000000Z"
}

{
   "message":"El campo nombre es obligatorio. (y 6 errores m\u00e1s)",
   "code":10001,
   "code_name":"validation_error",
   "errors":{
      "first_name":[
         "El campo nombre es obligatorio."
      ],
      "last_name":[
         "El campo apellido es obligatorio."
      ],
      "phone":[
         "El campo tel\u00e9fono es obligatorio."
      ],
      "email":[
         "El campo correo electr\u00f3nico es obligatorio."
      ],
      "user_type":[
         "El campo user type es obligatorio."
      ],
      "document_type":[
         "El campo document type es obligatorio."
      ],
      "document_number":[
         "El campo document number es obligatorio."
      ],
      "nationality":[
         "El código de país debe seguir el formato ISO 3166-1 alpha-2"
      ],
      "birthdate":[
         "La fecha debe tener el formato YYYY-MM-DD"
      ]
   }
}

{
  "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
  "code": 10003,
  "code_name": "idempotency_error"
}

Si el cliente ya existe, no se crea otro. Antes de crear, buscamos en tu cuenta, en el mismo ambiente (pruebas o producción), un cliente:

Con el mismo document_type y document_number. Los puntos del documento no cuentan: 1.234.567.890 y 1234567890 son el mismo.
Si no hay, con el mismo email, sin importar mayúsculas ni espacios.

Si lo encontramos, respondemos 200 con ese cliente (un cliente nuevo responde 201) y actualizamos su phone, email, nationality, birthdate y enable_notifications con lo que envíes. El nombre solo se actualiza si se parece al que ya tenía, y el documento nunca cambia. Los clientes eliminados no cuentan.Si varios de tus clientes comparten un correo, compara el document_number de la respuesta con el que enviaste: si no coincide, la respuesta es la de otro cliente que ya tenía ese correo.

Headers

string

required

Token único para garantizar la idempotencia de la petición

Body

string

required

Tipo de usuario, valores permitidos: natural, company

string

required

Primer Nombre del cliente

string

required

Apellidos del cliente

string

Correo electrónico del cliente. Obligatorio, salvo que envíes related_to.

string

Número de teléfono del cliente usa el prefijo de la región ejemplo: +57. Obligatorio, salvo que envíes related_to.

string

required

Tipo de documento de identidad (CC, CE, NIT, PASSPORT)

string

required

Número de documento de identidad

boolean

default:"true"

Habilita notificaciones automáticas por email y SMS al cliente sobre pagos aprobados, rechazados, y links de pago. Valor por defecto: true.

string

Nacionalidad del cliente, Formato ISO 3166-1 alpha-2

string

Fecha de nacimiento del cliente, formato YYYY-MM-DD

Id del cliente al que se relaciona. Si lo envías, email y phone son opcionales.

Response

string

Identificador único del cliente en formato UUID

string

Nombre del cliente

string

Correo electrónico del cliente

string

Número de teléfono del cliente

string

Número de documento de identidad del cliente

string

Tipo de documento de identidad del cliente (ej. DNI, RUC, CE)

date

Fecha y hora de creación del cliente

{
  "id":"9da58912-101d-46f8-86c9-20a52119c0bf",
  "first_name":"John",
  "last_name":"Doe",
  "email":"john.doe@example.com",
  "phone":"+573100001020",
  "document_type":"CC",
  "document_number":"1060500333",
  "nationality":"CO",
  "birthdate":"1990-01-01",
  "created_at":"2024-12-04T20:09:08.000000Z"
}

{
   "message":"El campo nombre es obligatorio. (y 6 errores m\u00e1s)",
   "code":10001,
   "code_name":"validation_error",
   "errors":{
      "first_name":[
         "El campo nombre es obligatorio."
      ],
      "last_name":[
         "El campo apellido es obligatorio."
      ],
      "phone":[
         "El campo tel\u00e9fono es obligatorio."
      ],
      "email":[
         "El campo correo electr\u00f3nico es obligatorio."
      ],
      "user_type":[
         "El campo user type es obligatorio."
      ],
      "document_type":[
         "El campo document type es obligatorio."
      ],
      "document_number":[
         "El campo document number es obligatorio."
      ],
      "nationality":[
         "El código de país debe seguir el formato ISO 3166-1 alpha-2"
      ],
      "birthdate":[
         "La fecha debe tener el formato YYYY-MM-DD"
      ]
   }
}

{
  "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
  "code": 10003,
  "code_name": "idempotency_error"
}

curl https://api.onepay.la/v1/customers \
  -X POST \
  -H "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: customer-001" \
  -d '{
    "user_type": "natural",
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "document_type": "CC",
    "document_number": "1234567890",
    "enable_notifications": true
  }'

const response = await fetch('https://api.onepay.la/v1/customers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi',
    'Content-Type': 'application/json',
    'x-idempotency': 'customer-001'
  },
  body: JSON.stringify({
    user_type: 'natural',
    first_name: 'Juan',
    last_name: 'Pérez',
    email: 'juan@example.com',
    phone: '+573001234567',
    document_type: 'CC',
    document_number: '1234567890',
    enable_notifications: true
  })
});

const customer = await response.json();
console.log(customer);

import requests

response = requests.post(
    'https://api.onepay.la/v1/customers',
    headers={
        'Authorization': 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi',
        'Content-Type': 'application/json',
        'x-idempotency': 'customer-001'
    },
    json={
        'user_type': 'natural',
        'first_name': 'Juan',
        'last_name': 'Pérez',
        'email': 'juan@example.com',
        'phone': '+573001234567',
        'document_type': 'CC',
        'document_number': '1234567890',
        'enable_notifications': True
    }
)

customer = response.json()
print(customer)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onepay.la/v1/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi",
    "Content-Type: application/json",
    "x-idempotency: customer-001"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "user_type" => "natural",
    "first_name" => "Juan",
    "last_name" => "Pérez",
    "email" => "juan@example.com",
    "phone" => "+573001234567",
    "document_type" => "CC",
    "document_number" => "1234567890",
    "enable_notifications" => true
  ])
]);

$response = curl_exec($curl);
curl_close($curl);

$customer = json_decode($response, true);
print_r($customer);
?>

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Headers

Body

Response

​Headers

​Body

​Response

Headers

Body

Response