Iniciación de pagos (Chile)

Permite que tus usuarios hagan una transferencia dentro de tu app

Nuestra API de Iniciación de Pagos permite que tus usuarios con cuentas bancarias chilenas hagan transferencias desde tu misma app o página web. Algunos casos de uso son:

  • Tienes un e-commerce y quieres que tus usuarios paguen con transferencia.
  • Tienes una app tipo wallet digital y quieres que tus usuarios carguen su wallet fácilmente.
  • Permitir que los usuarios de tu app transfieran a otros usuarios (transferencias peer-to-peer).

Flujo de Iniciación de Pagos

Fintoc usa el objeto PaymentIntent para representar el intento de pago de tu usuario y es el que recibirás cuando pidas información del pago.

1. Suscríbete al evento de pago exitoso

Cada vez que una transferencia se complete exitosamente, enviaremos un evento payment_intent.succeeded por webhook. Es muy importante que te suscribas a este evento, porque pueden existir casos en que la transferencia demore más de lo común en ejecutarse y el usuario podría cerrar el Widget antes de tiempo. Así que espera este evento antes de ejecutar acciones post-pago, como enviar email de confirmación a tu usuario, ingresar la venta a tu base de datos o empezar el proceso de envío de productos.

Para suscribirte al evento, puedes leer la sección de webhooks de nuestra documentación. Recuerda que el evento se llama payment_intent.succeeded.

2. Crea un PaymentIntent

Desde tu servidor crea un PaymentIntent con el monto, moneda y recipiente del pago. Siempre crea el PaymentIntent desde tu servidor, o si no un usuario malicioso podría cambiar cualquiera de esos campos. Acá te dejamos un ejemplo:

curl --request POST "https://api.fintoc.com/v1/payment_intents" \
--header 'Authorization: sk_live_nfy1ynwARTxN74NNhHmGyBct_YLxqAWKTLyi-KJCiXY9td3T19xGhs_WJ_KTP5XK' \
--header 'Content-Type: application/json' \
--data-raw '{
        "amount": 1000,
        "currency": "clp",
        "recipient_account": {
          "holder_id": "147237065",
          "number": "12312312",
          "type": "checking_account",
          "institution_id": "cl_banco_estado"
    }
}'

La respuesta que recibirás será parecida a esta:

{
  "id": "pi_XXXXXXXXXXXX",
  "object": "payment_intent",
  "widget_token": "pi_XXXXXXXXXX_sec_YYYYYYYYY",
  "created_at": "2021-10-15T15:23:11.474Z",
  "recipient_account": {
    "holder_id": "12345678",
    "number": "49882780",
    "type": "checking_account",
    "institution_id": "cl_banco_estado"
   },
   "sender_account": null,
   "amount": 1000,
   "currency": "CLP"
}

Como puedes ver, al crear un PaymentIntent también se crea un widget_token, el cual tienes que ocupar para completar el proceso de pago desde el Widget. Te lo explicamos en la siguiente sección.

3. Configura el widget con el widget_token

Una vez que creas el PaymentIntent, debes enviar el widget_token a tu frontend. Usa el widget_token para configurar el widget, puedes basarte en este ejemplo simple:

<head>
  <script src="https://js.fintoc.com/v1/"></script>
</head>

<body>
  <script>
    const widget = Fintoc.create({
      holderType: 'individual',
      widgetToken: 'pi_XXXXX_sec_YYYYY',
      product: 'payments',
      publicKey: 'pk_live_NSx_XfEuRNn4xnA7MJ7DQQpje7cjghYA',
      onSuccess: () => {},
    });
    widget.open();
  </script>
</body>

Usando el widget_token, el Widget queda configurado con todos los detalles del intento de pago: monto, moneda y recipiente. Luego, tus usuarios solo deben seguir el flujo del Widget!

Notarás que existe la función onSuccess, acá se espera recibir una función a ejecutar cuando el pago es exitoso. Esta función la debes definir tú (puede llamarse como quieras) y es la que se ejecutará una vez el proceso de la Iniciación de Pagos se complete exitosamente.

4. Término del pago

Una vez que el pago es exitoso, recibirás el PaymentIntent en el callback onSuccess del widget y te enviaremos el evento payment_intent.succeeded por webhook. Recuerda que es muy importante que esperes este evento y no debes basarte únicamente en el callback onSuccess del Widget porque tus usuarios pueden cerrar el browser o la app antes de que el callback se ejecute.

Sandbox

Tenemos un ambiente de prueba para que puedas probar este flujo sin hacer una transferencia real, te integres fácilmente y conozcas todos los flujos que podría llegar a tener una transferencia. Ocuparlo es fácil, solo debes seguir los mismos pasos de la sección anterior, pero utilizando la Secret Key y la Public Key de prueba. Es decir:

  1. Crear el PaymentIntent cambiando el header Authorization a tu Secret Key de prueba. Esta debería tener el formato sk_test_API_KEY.
  2. Configurar el Widget utilizando tu Public Key de prueba. Esta debería tener el formato sk_test_API_KEY.

Configuraciones

El proceso de transferencia tiene dos pasos adicionales (además del login) que requieren que el usuario ingrese información: MFA (multi-factor authentication) para agregar al destinatario cuando el usuario no lo tiene registrado en su cuenta bancaria y MFA para confirmar la transferencia. Todos los bancos funcionan distinto, algunos pueden pedir MFA para agregar un nuevo destinatario mientras que otros no. Pero en el Sandbox te permitimos probar todas las combinaciones posibles para que puedas ver el flujo que realizará tu usuario y probar tu integración.

Tipos de MFA habilitados

Estos son los distintos MFA que tenemos habilitados en Sandbox:

  • Dispositivo de Seguridad: aparato electrónico que los bancos entregan a sus clientes para autorizar transacciones. Generalmente muestran un número que cambia cada cierto tiempo.
  • Aplicación Móvil: los bancos ofrecen autorizar transacciones a través de su APP móvil. En este caso, el usuario deberá autorizar la transacción desde su smartphone y nosotros detectaremos que fue autorizada automáticamente. En Sandbox, te damos la opción de simular una autorización exitosa y una fallida. Esta última simulará que el usuario rechazó la transacción.
  • SMS enviado al celular: el banco envía un código (generalmente numérico) para que el usuario autorice la transacción.
  • Tarjeta de Coordenadas: tarjeta entregada por el banco con una tabla con números. El usuario debe ingresar las coordenadas pedidas por el banco. Más información.

MFA para simular nuevo destinatario

Si quieres que el Widget pida algún tipo de MFA que simule que el usuario deba agregar el destinatario del PaymentIntent, debes personalizar los últimos dos dígitos del monto del PaymentIntent. Por ejemplo, si creas un PaymentIntent con monto 15001, se le pedirá al usuario que autorice el nuevo contacto con su Dispositivo de seguridad. A continuación está la lista de dígitos indicando a qué tipo de MFA corresponde y el código que debes ingresar para simular una autorización exitosa. Si ingresas otro código, la autorización fallará:

Últimos dos dígitos del monto

Tipo de MFA

Ejemplo

Código Correcto

01

Dispositivo de Seguridad

amount: 17501

0000

02

Aplicación Móvil Exitosa

amount: 17502

No aplica

03

Aplicación Móvil Fallida

amount: 17503

No aplica

04

SMS

amount: 17504

000000

05

Tarjeta de Coordenadas

amount: 17505

['00', '00', '00']

Si el monto del PaymentIntent no corresponde a ninguno de los dígitos anteriores, no se le pedirá al usuario el MFA para simular un nuevo destinatario y pasará directo a confirmar la transferencia

MFA de confirmación de transferencia

Este paso en todos los bancos es obligatorio, por lo tanto en Sandbox el Widget lo pedirá. También puedes personalizarlo eligiendo una cuenta bancaria de origen en específico cuando el Widget te lo pida. En Sandbox siempre te mostramos la mismas cuentas:

Vista del Widget para elegir la cuenta bancaria de origenVista del Widget para elegir la cuenta bancaria de origen

Vista del Widget para elegir la cuenta bancaria de origen

Acá te mostramos la lista de cuentas habilitadas y a qué tipo de MFA corresponde:

Número de cuenta

Tipo de MFA

Código Correcto

813990168

Dispositivo de Seguridad

0000

422159212

Aplicación Móvil Exitosa

No aplica

5233137377

Aplicación Móvil Fallida

No aplica

170086177

SMS

000000

746326042

Tarjeta de Coordenadas

['00', '00', '00']

default

Tarjeta de Coordenadas

['00', '00', '00']

Cualquier duda que tengas, puedes preguntarnos por Intercom!