Crear cuenta hija

Esta API permite crear y gestionar cobros de manera flexible, adaptándose a diferentes escenarios de pago: creados, programados y normales. Los cobros pueden personalizarse con reglas de vencimiento, recargos, descuentos anticipados y notificaciones automatizadas, garantizando una integración sencilla y escalable para el comercio. Es esencial que te asegures de generar un único cobro por cada venta, pedido o interacción con el cliente, según sea apropiado.

Ruta

POST /v1/business/child

Encabezado

Name

Value

Content-Type*

application/json

x-auth-token*

{token}

Cuerpo

Datos del Negocio

Name

Type

Description

business_id*

string

Es el identificador único que se le asignará al negocio hijo en el sistema

business_name*

string

Nombre comercial de la sede o del sub-negocio.

type*

string

Categoría del negocio.

general | logistic

business_id_type

string

Tipo de documento de identificación del negocio. CC | CE | NIT | PASAPORTE | DNI | EIN

business_id_number

string

Número de identificación de la empresa (NIT sin DV).

business_id_number_dv

numeric

Dígito de verificación de la empresa Ejemplo: 1

business_phone

string

Número de celular del negocio. Ejemplo: 573112229999

business_email

string

Correo electrónico de contacto comercial del sub-negocio. Ejemplo: [email protected]

business_webhook

string

URL del webhook donde el sub-negocio recibirá los eventos de notificación. Ejemplo:https://minegocio.com/mi-aplicacion

Datos de Contacto (Usuario Principal)

Están relacionados directamente con la persona que será el contacto principal de este sub-negocio:

Name

Type

Description

first_name

string

Nombre del contacto principal.

last_name

string

Apellido del contacto principal.

nickname

string

Apodo o nombre corto para el contacto.

phone

string

Número de teléfono móvil del contacto principal (debe tener entre 10 y 15 dígitos numéricos).

user_email

string

Correo electrónico válido del contacto.

user_id_type

string

Tipo de documento de identificación del contacto principal. CC | CE | NIT | PASAPORTE | DNI | EIN

user_id_number

string

Número de identificación del usuario.

user_id_number_dv

number

Dígito de verificación del documento del usuario (opcional, por defecto es null).

Apariencia y Ubicación

Campos adicionales que permiten que el hijo tenga su propio estilo y ubicación geográfica separada del padre:

Name

Type

Description

logo

string

URL (URI válida) con la imagen del logo del sub-negocio.

main_color_brand

string

Código HEX del color principal de la marca Ejemplo #FF0000

secondary_color_brand

string

Código HEX del color secundario de la marca. Ejemplo #FF0000

city

string

Ciudad principal de operación.

state

string

Departamento o estado provincial de operación.

country

string

País de operación.

Configuración Financiera

Name

Type

Description

fee_variable_saas

number

Tarifa (fee) variable aplicada bajo el modelo SaaS para este sub-negocio específico. Se espera un número entre 0 y 1(por defecto es 0 Ejemplo: 0.1

fee_fixed_saas

number

Tarifa (fee) fija aplicada bajo el modelo SaaS para este sub-negocio específico. Ejemplo: 2000

Respuesta

{
  "message": "Child business creado exitosamente 🚀",
  "business_id": "PAY-CHILD-001",
  "managing_business_id": "PAY-001",
  "created_at": "2023-10-15T08:00:00-05:00"
}

Ejemplo

curl --location '{{base_url}}/v1/business/child' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
  "phone": "",
  "first_name": "",
  "last_name": "",
  "nickname": "",
  "user_id_type": "",
  "user_id_number": "",
  "user_email": "",
  "user_id_number_dv": null,
  "type": "general",
  "business_id": "",
  "business_name": "",
  "business_id_type": "",
  "business_id_number": 1,
  "business_id_number_dv": 1,
  "business_url": "",
  "business_phone": "",
  "business_webhook": "",
  "business_email": "",
  "logo": null,
  "main_color_brand": null,
  "secondary_color_brand": null,
  "city": null,
  "state": null,
  "country": null,
  "fee_variable_saas": 0
}'

const axios = require('axios');
let data = JSON.stringify({
  "phone": "",
  "first_name": "",
  "last_name": "",
  "nickname": "",
  "user_id_type": "",
  "user_id_number": "",
  "user_email": "",
  "user_id_number_dv": null,
  "type": "general",
  "business_id": "",
  "business_name": "",
  "business_id_type": "",
  "business_id_number": 1,
  "business_id_number_dv": 1,
  "business_url": "",
  "business_phone": "",
  "business_webhook": "",
  "business_email": "",
  "logo": null,
  "main_color_brand": null,
  "secondary_color_brand": null,
  "city": null,
  "state": null,
  "country": null,
  "fee_variable_saas": 0
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: `${base_url}/v1/business/child`,
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer YOUR_SECRET_TOKEN'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

import requests
import json

url = f"{base_url}/v1/business/child"

payload = json.dumps({
  "phone": "",
  "first_name": "",
  "last_name": "",
  "nickname": "",
  "user_id_type": "",
  "user_id_number": "",
  "user_email": "",
  "user_id_number_dv": None,
  "type": "general",
  "business_id": "",
  "business_name": "",
  "business_id_type": "",
  "business_id_number": 1,
  "business_id_number_dv": 1,
  "business_url": "",
  "business_phone": "",
  "business_webhook": "",
  "business_email": "",
  "logo": None,
  "main_color_brand": None,
  "secondary_color_brand": None,
  "city": None,
  "state": None,
  "country": None,
  "fee_variable_saas": 0
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer YOUR_SECRET_TOKEN'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Caso de uso

Cobro inmediato con notificación en WhatsApp (con datos de usuario)

curl --location --request POST '{base_url}/v1/merchant/transaction' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \

--data-raw '{
    "status": "created",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "channel": "whatsapp",
    "merchant_phone": "573112223333",
    "return_url": "https://www.qentaz.com/",
    "reminder_date": "02/10/2023",
   "expected_amount": 100000,
   "expected_date": "10/20/2023",
    "payer": {
        "phone": "573112223333"
    }
    
}'

Cobro sin vencimiento con notificación en correo (con datos de usuario)

curl --location --request POST '{base_url}/v1/merchant/transaction' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \

--data-raw '{
    "status": "unlimit",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "channel": "email",
    "merchant_phone": "573112223333",
    "return_url": "https://www.qentaz.com/",
    "reminder_date": "02/10/2023",
   "expected_amount": 100000,
   "expected_date": "10/20/2023",
    "payer": {
        "email": "[email protected]"
    }
    
}'

Cobro programado con notificación en correo (con datos de usuario)

curl --location --request POST '{base_url}/v1/merchant/transaction' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \

--data-raw '{
    "status": "unlimit",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "channel": "email",
    "merchant_phone": "573112223333",
    "return_url": "https://www.qentaz.com/",
    "reminder_date": "02/10/2023",
   "expected_amount": 100000,
   "expected_date": "10/20/2023",
    "payer": {
        "phone": "573112223333",
        "email": "[email protected]",
        "first_name": "Andrés",
        "user_id_type": "CC",
        "user_id_number": "123456789"
    }
    
}'

Última actualización hace 13 días