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 en 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`

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
mail	`string`	Correo que se utilizará para contactar al Customer.	⚪ No
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	`string`	Identificador del customer diferente al government_ide, en el caso de que no se quiera utilizar el RUT o el CURP, se puede crear un identificador único que cumpla con dicha función.	⚪ 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 tiene el siguiente formato:

{
  "goverment_id": "18579878K",
  "mail": "[email protected]",
  "name": "Jon Snow",
  "phone_number": "+56987654321"
}

La respuesta recibida es de la forma:

{
  "external_id": "18579878K",
  "government_id": "18579878K",
  "name": "Jon Snow",
  "mail": "[email protected]",
  "phone_number": "+56987654321",
  "metadata": {},
  "id": "cus_XmSyV8QTlDOj3EPPHd7wsnfhEJJptg7r"
}

HINT: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 nuestros clientes en Toku como Customers y haber guardado sus id's, 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 una Invoice?

Una Invoice contiene la información de una deuda. La creación de una 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 una Invoice - POST `/invoices`

Al momento de crear una 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.	🔘 Si
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.	🔘 Si
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 caso 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
invoice_external_id	`string`	ID de la Invoice, este campo solo es necesario en caso de tener Invoices con el mismo product_id y misma due_date	⚪ 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 se puede apreciar, el campo customer permite asociar esta 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 a la Invoice creada, 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 vía 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`

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.	🔘 Si

Nombre

Tipo

Descripción

Necesario

enabled_events

list

Lista de eventos a la que se suscribe este Webhook Endpoint.

🔘

url

string

URL de tu endpoint, al cual se le notificarán los eventos mediante requests POST.

🔘

status

string

Estado del Webhook Endpoint. Si es enabled, enviará notificaciones de los eventos suscritos. En caso contrario definir como disabled.

🔘

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 statuscomo disabled

🚧
Importante
Luego de cada creación de Webhook Endpoints, se deben almacenar los campos id y secret, 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

Nombre

Tipo

Descripción

Requerido

Toku-Signature

string

Firma para verificar validez del evento.

🔘

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

Nombre

Tipo

Descripción

Requerido

int

ID del evento.

🔘

event_type

string

Tipo de evento.

🔘

- object

json

Valores adicionales específicos de cada evento.

🔘

❗️
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 forma t=1618960495,s=c896f1eb1438c706f4eb8b59d5453582b44a4cb442fd23ed9eb2690e1f9213b7.
¡Para saber como validar la firma de Toku referirse a ladocumentación de webhooks!

🚧
Atención

El nombre del parámetro object cambiará dependiendo del event_type. Corresponderá a la primera mitad del nombre del evento. Para el evento payment_method.attached , object será payment_method, y para los eventos payment_intent.succeeded y payment_intent.payment_failed, object será payment_intent.

Para más información de los eventos puedes visitar ellistado 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] o 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 transacciones 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)
stauts (opcional) -> Si sólo quieres verificar los pagos, es decir, las transacciones exitosas, debes agregar status = SUCCESS.

Esta request entrega una lista de transacciones que se deben chequear con los webhooks recibidos durante el día.

Crear customer

¿Qué es un Customer?

Crear un Customer - POST /customer

*external_id <> goverment_id

Formato del request y la respuesta que genera

Asociar Invoices a Customers

¿Qué es una Invoice?

Crear una Invoice - POST /invoices

Importante

Escuchar vía Webhook

Inscripción de Webhook Endpoints

POST /webhook_endpoints

Parámetros para crear Webhook Endpoint

Importante

Recibir Eventos en Webhook Endpoints

Parámetros enviados en un evento a un Webhook Endpoint

Importante

Atención

Probar el webhook

Más sobre los webhooks en Toku

Opcional: Verificar transacciones diariamente

Crear un Customer - POST `/customer`

Crear una Invoice - POST `/invoices`

POST `/webhook_endpoints`