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:

NombreTipoDescripci贸nRequerido
goverment_idstringIdentificador personal del Customer seg煤n su nacionalidad. Por ejemplo: para Chile RUT, para M茅xico CURP.:radio-button: Si
mailstringCorreo que se utilizar谩 para contactar al Customer.:radio-button: Si
namestringNombre por el cual nos referimos al Customer en los mensajes.:white-circle: No
phone_numberstringN煤mero de tel茅fono del Customer para contactarlo por SMS y Whatsapp:white-circle: No
pac_mandate_idstringIdentificador del mandato que se pondr谩 al inscribir el PAC asociado al customer.:white-circle: No
default_agentstringCorreo del asistente que tendr谩 asignado por defecto responder al Customer en caso de que este responda alg煤n mensaje.:white-circle: No
send_mailbooleanFlag 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":white-circle: 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 nuestros 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

NombreTipoDescripci贸nRequerido
customerstringID del Customer entregado en su creaci贸n.:radio-button: Si
product_idstringIdentificador interno del producto que genera el Invoice. Puede ser un n煤mero de contrato o de propuesta.:radio-button: Si
due_datedateFecha de vencimiento del Invoice, en formato YYYY-MM-DD.:white-circle: No
amountfloatMonto adeudado en la CLP por default. En caso de tratarse de otra moneda, esta debe estar definida en la webapp de Toku.:white-circle: No
is_paidbooleanIndica si el Invoice se encuentra pagado o no.:white-circle: No
is_voidbooleanIndica si el Invoice se encuentra anulado o no. Los Invoices anulados se tratan como si hubiesen sido borrados.:white-circle: No
link_paymentstringURL 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.:white-circle: No
metadatajsonValores 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铆.:white-circle: 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

Par谩metros para crear Webhook Endpoint
NombreTipoDescripci贸nNecesario
enabled_eventslistLista de eventos a la que se suscribe este Webhook Endpoint.:radio-button: Si
urlstringURL de tu endpoint, al cual se le notificar谩n los eventos mediante requests POST.:radio-button: Si
statusstringEstado del Webhook Endpoint. Si es enabled, enviar谩 notificaciones de los eventos suscritos. En caso contrario definir como disabled.:white-circle: 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.

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

La respuesta recibida es de la forma:

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

NombreTipoDescripci贸nRequerido
id'int`ID del evento.:radio-button: Si
event_typestringTipo de evento.:radio-button: Si
- objectjsonValores adicionales espec铆ficos de cada evento.:radio-button: Si
Toku-SignaturestringFirma para verificar validez del evento.:radio-button: 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, y su construcci贸n se explica en la siguiente secci贸n.

馃毀

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. Esto quedar谩 m谩s claro en los ejemplos que se exponen a continuaci贸n.

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.

Verificar que los eventos sean enviados por Toku

Toku firma cada evento enviado a tus Webhook Endpoints con el campo Toku-Signature en el header del request POST al momento de notificar un evento. Esta es una firma que te permite verificar que es Toku y no un tercero quien env铆a la notificaci贸n.

Para verificar la firma, es necesario que poseas el secret relacionado al Webhook Endpoint, el cual se retorna al momento de su creaci贸n.

El header Toku-Signature contiene un timestamp y una firma, separados por una coma ,. El timestamp viene precedido de t=, y la firma viene precedida de s=. Un ejemplo de firma es:

't=1618960495,s=c896f1eb1438c706f4eb8b59d5453582b44a4cb442fd23ed9eb2690e1f9213b7'

Las firmas enviadas por Toku son c贸digos HMAC, generados al firmar el id del request con la funci贸n de hash SHA-256, en el momento indicado por el timestamp. Se utiliza como key de la funci贸n de hash el secret del Webhook Endpoint.

A continuaci贸n, explicamos los pasos a llevar a cabo para validar la firma del evento. Utilizamos como ejemplo el siguiente evento:

{
    "id": "evt_MOnNVXKNYDCZXzI9slA3smhASQmuRleM",
    "event_type": "payment_method.attached",
    "payment_method": {
        "id": "pm_9tN0ZtjUDjS1qi8qZQ3uJHJbwtcXYH9d",
        "customer": "cus_lq1wGjwgFyqQm4ACZx0QjE84qKm8fffa",
        "gateway": "transbank_oneclick",
        "card_type": "Visa",
        "card_number": "XXXXXXXXXXXX6623",
        "status": "chargeable"
    }
}

Los ejemplos de c贸digo utilizan el lenguaje Python.

Extraer el timestamp y la firma desde el header.

Separa el valor del header en una lista utilizando el car谩cter , como separador. Luego, separa cada elemento de la lista utilizando el separador = para obtener un par prefijo-valor. Finalmente, obt茅n los valores correspondientes de cada prefijo.

header_value = request.headers.get('Toku-Signature')
timestamp, event_signature = [x.split('=')[1] for x in header_value.split(',')]

Construir el mensaje que se firmar谩

El mensaje a firmar se compone al concatenar el valor del timestamp, el car谩cter . y el campo id, el cual se encuentra en el body del request.

message = '{}.{}'.format(timestamp, event_id)

En el caso del ejemplo, el mensaje ser铆a:

'1618960495.evt_MOnNVXKNYDCZXzI9slA3smhASQmuRleM'

Generar tu firma

Firma el mensaje utilizando la funci贸n SHA-256 y el secret de tu Webhook Endpoint como llave.

import hmac
from hashlib import sha256

encoded_secret = YOUR_WEBHOOK_ENDPOINT_SECRET.encode('utf-8')
encoded_message = message.encode('utf-8')
hmac_object = hmac.new(encoded_secret, msg=encoded_message, digestmod=sha256)
signature = hmac_object.hexdigest()

Comparar las firmas

Finalmente, compara la firma 'Toku-Signature' presente en el header con la obtenida al firmar el evento. Si ambas firmas coinciden, entonces el evento ha sido enviado por Toku.

import hmac

valid_signature = hmac.compare_digest(signature, event_signature)

Previene un ataque de reinyecci贸n

Para evitar un ataque de reproducci贸n de mensajes, recomendamos que utilices una marca de tiempo. Al recibir y obtener el聽timestamp聽de un evento, verifica que este se encuentre dentro de tu rango de tolerancia. De no ser as铆, puedes descartar el evento.

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.