Subir deudas y recibir pagos
Crear customer
Esta sección explica el proceso de creación de Customers a través de la API REST de Toku. También puedes verlo en la documentación de la API aquí.
El primer paso para habilitar los pagos para tus clientes es registrarlos. A continuación se explica la creación de Customers utilizando la API REST de Toku.
Qué es un Customer
Un Customer contiene la información de la persona, junto con sus medios de contacto. La creación de un Customer genera un id único de la forma cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fff
, el cual se envía en la respuesta de la API. Este id debe ser guardado, ya que se utiliza luego para la creación de Invoices para ese Customer, y para identificar las acciones que lleve a cabo el Customer en el Portal de Pagos, explicados en secciones posteriores.
Crear un Customer - POST /customer
/customer
A traves de un request POST a la API se puede crear un Customer, para lo que existen los siguientes parámetros:
Nombre | Tipo | Descripción | Requerido |
---|---|---|---|
goverment_id | string | Identificador personal del Customer según su nacionalidad. Por ejemplo: para Chile RUT, para México CURP. | 🔘 Si |
string | Correo que se utilizará para contactar al Customer. | 🔘 Si | |
name | string | Nombre por el cual nos referimos al Customer en los mensajes. | ⚪ No |
phone_number | string | Número de teléfono del Customer para contactarlo por SMS y Whatsapp | ⚪ No |
pac_mandate_id | string | Identificador del mandato que se pondrá al inscribir el PAC asociado al customer. | ⚪ No |
default_agent | string | Correo del asistente que tendrá asignado por defecto responder al Customer en caso de que este responda algún mensaje. | ⚪ No |
send_mail | boolean | Flag que nos indica si quieres mandar automáticamente un correo al crear el customer. Se le enviará con la secuencia "Invitación inscripción medio de pago" | ⚪ No |
external_id <> goverment_id
En caso de no contar con el identificador nacional del cliente es posible utilizar el campo mail o un parámetro diferente que identifique de forma única al cliente, el que se denominará external_id. Este campo reemplace a la columna goverment_id requerida por default. Esta configuración debe realizarse por el equipo de Toku.
Formato del request y la respuesta que genera
El Body del request debe ser de la siguiente forma:
{
"goverment_id": "18579878K",
"mail": "[email protected]",
"name": "Jon Snow",
"phone_number": "+56987654321",
"pac_mandate_id": "196579888",
"default_agent": "[email protected]",
"send_mail": true
}
La respuesta recibida es de la forma:
{
"id": "cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fffa",
"goverment_id": "18579878K",
"mail": "[email protected]",
"name": "Jon Snow",
"phone_number": "+56987654321",
"pac_mandate_id": "196579888",
"default_agent": "[email protected]",
}
Recuerda que debes capturar el campo id
incluido en esta respuesta ya que será el código al que se asociara la deuda y con el que podrás identificar los eventos que ocurran en Toku.
Asociar Invoices a Customers
Esta sección explica el proceso de creación de Invoices a través de la API REST de Toku. También puedes verlo en la documentación de la API aquí.
Tras tener registrados los clientes en Toku como Customers y haber guardado sus ids, podemos cargar deudas asociados a ellos, a las que llamaremos Invoices . A continuación se explica la creación de Invoices utilizando la API REST de Toku.
Qué es un Invoice
Un Invoice contiene la información de una deuda. La creación de un Invoice requiere del id único del Customer para poder relacionarlo a sus datos de contacto, el cual tiene la forma cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fff
. Este ID debe ser capturado al crear el Customer en Toku, explicado en el paso previo de esta guía.
Crear un Invoice - POST /invoices
/invoices
Al momento de crear un Invoice a traves de una request POST a la API en Toku existen campos obligatorios, campos opcionales y adicionalmente existe un campo para asociar valores adicionales específicos a la deuda.
Parametros para crear Invoice
Nombre | Tipo | Descripción | Requerido |
---|---|---|---|
customer | string | ID del Customer entregado en su creación. | 🔘 Si |
product_id | string | Identificador interno del producto que genera el Invoice. Puede ser un número de contrato o de propuesta. | 🔘 Si |
due_date | date | Fecha de vencimiento del Invoice, en formato YYYY-MM-DD. | ⚪ No |
amount | float | Monto adeudado en la CLP por default. En caso de tratarse de otra moneda, esta debe estar definida en la webapp de Toku. | ⚪ No |
is_paid | boolean | Indica si el Invoice se encuentra pagado o no. | ⚪ No |
is_void | boolean | Indica si el Invoice se encuentra anulado o no. Los Invoices anulados se tratan como si hubiesen sido borrados. | ⚪ No |
link_payment | string | URL en el que se debe pagar el Invoice. Dejar en blanco en caso de usar el portal de pagos de Toku. Incluir solo en el case de que poseas tu propio procesador de pagos. | ⚪ No |
metadata | json | Valores adicionales específicos de cada deuda. Son tratados como valores de texto y que no pueden tener más de 256 caracteres cada uno. Debes agregarlos en la webapp de Toku antes de poder utilizarlos aquí. | ⚪ No |
Importante
link_payment
es un campo opcional, el cual no debe enviarse en caso de utilizar el Portal de Pagos proporcionado por Toku. Solo debe enviarse en caso de utilizar un portal de pagos externo.
El Body del request debe ser de la siguiente forma:
{
"customer": "cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fffa",
"is_paid": false,
"is_void": false,
"amount": 1000,
"product_id": "92792",
"due_date": "2021-03-04",
"link_payment": "https://portal.pagos.com/tu-empresa",
"metadata": {
"car_brand": "Toyota",
"car_model": "Yaris"
}
}
Como ves, el campo customer
permite asociar este Invoice a los datos de contacto del Customer, y se usará para notificarte acciones tales como inscripciones o pagos realizados.
La respuesta recibida es de la forma:
{
"customer": "cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fffa",
"is_paid": false,
"is_void": false,
"amount": 1000,
"product_id": "92792",
"due_date": "2021-03-04",
"link_payment": "https://portal.pagos.com/tu-empresa",
"metadata": {
"car_brand": "Toyota",
"car_model": "Yaris"
},
"id": "in_5tswGjwgAxrQm4ACZx0QjE84qKm8fgsw"
}
El campo id
identifica al Invoice creado, y es de la forma in_5tswGjwgAxrQm4ACZx0QjE84qKm8fgsw
. Puede ser utilizado para consultar el estado de un Invoice en Toku o para anular el mismo en caso de que ya no deba ser cobrado.
Escuchar via Webhook
Inscripción de Webhook Endpoints
A continuación, te explicamos cómo inscribir un Webhook Endpoint a través de una request POST a la API.
POST /webhook_endpoints
/webhook_endpoints
Parámetros para crear Webhook Endpoint
Nombre | Tipo | Descripción | Necesario |
---|---|---|---|
enabled_events | list | Lista de eventos a la que se suscribe este Webhook Endpoint. | 🔘 Si |
url | string | URL de tu endpoint, al cual se le notificarán los eventos mediante requests POST. | 🔘 Si |
status | string | Estado del Webhook Endpoint. Si es enabled, enviará notificaciones de los eventos suscritos. En caso contrario definir como disabled. | ⚪ No |
Luego de inscrito, puedes hacer una request PUT /webhook_endpoints/{id}
para hacer las siguientes modificaciones:
- Editar la lista de eventos, enviando el parámetro
enabled_events
- Deshabilitar el endpoint para no seguir recibiendo eventos, enviando el parametro
status
comodisabled
Importante
Luego de cada creación de Webhook Endpoints, se deben almacenar los campos
id
ysecret
, los cuales son utilizados para las verificaciones de seguridad explicadas en la siguiente sección.
Ejemplo de body para crear un Webhook Endpoint:
{
"enabled_events": [
"payment_method.attached",
"payment_intent.succeeded"
],
"status": "enabled",
"url": "https://prueba.com"
}
Ejemplo de respuesta recibida al crear un Webhook Endpoint:
{
"enabled_events": [
"payment_method.attached",
"payment_intent.succeeded"
],
"status": "enabled",
"url": "https://prueba.com",
"id": "whe_oJJDbbiXBgwOEzpIBzJMWAids_5xgmHS",
"secret": "whesec_DTouU4ek2-tMhBO9sBUZNVC8tIIJuZsn"
}
Recibir Eventos en Webhook Endpoints
Una vez inscrito un Webhook Endpoint, Toku notificará los eventos suscritos. Lo hará a través de una request POST a la URL suscrita. Debes tener habilitado este endpoint para poder recibir y almacenar la información que se le envíe. A continuación, listamos los parámetros con los que Toku enviará las requests POST a tus Webhook Endpoints.
Parámetros enviados en un evento a un Webhook Endpoint
Parámetros en los headers
Nombre | Tipo | Descripción | Requerido |
---|---|---|---|
Toku-Signature | string | Firma para verificar validez del evento. | 🔘 Si |
Parámetros del body
Nombre | Tipo | Descripción | Requerido |
---|---|---|---|
id | int | ID del evento. | 🔘 Si |
event_type | string | Tipo de evento. | 🔘 Si |
- object | json | Valores adicionales específicos de cada evento. | 🔘 Si |
Importante
El parámetro
Toku-Signature
se incluye en el Header de la request POST, a diferencia del resto de los parámetros incluidos en el Body. Este puede ser utilizado para comprobar que la notificación proviene de Toku y no de un tercero. Es de la format=1618960495,s=c896f1eb1438c706f4eb8b59d5453582b44a4cb442fd23ed9eb2690e1f9213b7
.¡Para saber como validar la firma de Toku referirse a la documentación de webhooks!
Atención
- El nombre del parámetro
object
cambiará dependiendo delevent_type
. Corresponderá a la primera mitad del nombre del evento. Para el eventopayment_method.attached
,object
serápayment_method
, y para los eventospayment_intent.succeeded
ypayment_intent.payment_failed
,object
serápayment_intent
.Para más información de los eventos puedes visitar el listado de eventos soportados por Toku.
Probar el webhook
En el portal sandbox en el cuál estás integrándote deberías tener acceso a botones de pago y de inscribir medios de pago automático modo demo. Si no los tienes puedes contactar a [email protected].
Para probar pago de transferencias se deben seguir las instrucciones dentro del mismo portal.
Para probar inscripción de PAC, se debe ingresar con rut 11.111.111-1 y cualquier contraseña. Luego, al momento de elegir las coordenadas de verificación saldrá siempre aprobada a menos que uno escriba las coordenadas 00 00 00. De esta forma se podrá probar la inscripción exitosa y fallida.
Utiliza nuestra API de prueba de webhooks para simular envíos de eventos y verificar la integridad de tu configuración de webhook y la capacidad de tu sistema para procesarlos adecuadamente.
Más sobre los webhooks en Toku
Para más información sobre webhooks visitar la documentación de webhooks.
Opcional: Verificar pagos diariamente
Por distintas razones algún servidor se puede caer y no queda registrado el webhook. Para asegurarse, como sistema de protección para detectar pagos se recomienda hacer una consulta diaria de los pagos realizados.
Aquí en API Reference. Esto requiere 4 campos en el body:
- page -> Cantidad de páginas, se recomienda que sea 1 por simplicidad del archivo.
- page_size -> Cantidad de pagos que van a venir por página. Se recomienda que sea un número suficientemente alto para que siempre puedan aparecer todos los pagos del día.
- start_date -> Día anterior al hacer este request
- end_date -> Día anterior al hacer este request (debe ser el mismo día que start para consultar por solo un día)
Esta request entrega una lista de pagos que se deben chequear con los webhooks recibidos durante el día.
Updated about 1 month ago