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

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

JSON

{
  "goverment_id": "18579878K",
  "mail": "[email protected]",
  "name": "Jon Snow",
  "phone_number": "[phone]",
  "pac_mandate_id": "196579888",
  "default_agent": "[email protected]",
   "send_mail": true
}

La respuesta recibida es de la forma:

JSON

{
  "id": "cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fffa",
  "goverment_id": "18579878K",
  "mail": "[email protected]",
  "name": "Jon Snow",
  "phone_number": "[phone]",
  "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

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:

JSON

{
  "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:

JSON

{
  "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

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 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:

JSON

{
  "enabled_events": [
    "payment_method.attached",
		"payment_intent.succeeded"
  ],
  "status": "enabled",
  "url": "https://prueba.com"
}

Ejemplo de respuesta recibida al crear un Webhook Endpoint:

JSON

{
  "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 forma t=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 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 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.