Fuentes de pago & Tokenización
En Wompi, no sólo puedes ofrecer a tus usuarios realizar pagos de una sola vez -como el de un carrito de compras-, sino que también puedes ofrecer que paguen por tus productos y servicios sin su intervención directa, como es el caso de un cobro periódico -una suscripción a una revista por ejemplo-, o el cobro de un servicio on-demand, como entregas a domicilio o servicios de transporte, por ejemplo, donde idealmente tus usuarios sólo provean su información de pago una única vez y los cargos se hagan a futuro, según lo requiera tu modelo de negocio.
A este tipo de pagos se les conoce también como pagos automáticos.
Esto lo puedes ofrecer usando nuestra funcionalidad de fuentes de pago del API. Tus usuarios los pueden realizar usando tarjetas o cuentas Nequi, y requieren que el usuario lleve a cabo un único proceso inicial, donde provea bien sea la información de su tarjeta o de su cuenta Nequi, que será usada posteriormente para hacer los cobros respectivos.
Tan sólo debes seguir el paso a paso descrito a continuación:
Paso a paso
- Paso 1 — Solicita la información del método de pago.
- Paso 2 — Crea una fuente de pago.
- Paso 3 — Crea una transacción usando la fuente de pago.
Paso 1: Solicita la información del método de pago
El primero de estos 3 pasos para realizar un cobro usando fuentes de pago, requiere el almacenamiento de forma segura de una tarjeta o cuenta Nequi. Para eso, usarás nuestro API de manera que Wompi almacene de manera segura información de tarjetas y cuentas Nequi.
Al proceso de guardar y representar la información de una tarjeta de manera segura le llamamos: Tokenización. Esto quiere decir que debes enviar al endpoint respectivo del API de Wompi la información del método de pago, una única vez, y obtendrás un token el cual podrás usar para crear la fuente de pago en el Paso 2 de esta guía.
Tarjetas
Para tarjetas de crédito o débito el endpoint que debes usar es /v1/tokens/cards realizando un POST con el siguiente cuerpo JSON:
{
"number": "4242424242424242", // Número de tarjeta (como un string, sin espacios)
"exp_month": "06", // Mes de expiración (como string de 2 dígitos)
"exp_year": "29", // Año de expiración (como string de 2 dígitos)
"cvc": "123", // Código de seguridad (como string de 3 o 4 dígitos)
"card_holder": "Pedro Pérez" // Nombre del tarjeta habiente (string de mínimo 5 caracteres)
}
Como resultado a esta petición recibirás la siguiente respuesta:
{
"status": "CREATED",
"data": {
"id": "tok_prod_15_44c5638281if67l04eA63f705bfA5bde",
"created_at": "2020-09-07T19:09:31.585+00:00",
"brand": "VISA",
"name": "VISA-4242",
"last_four": "4242",
"bin": "538696",
"exp_year": "29",
"exp_month": "06",
"card_holder": "Pedro Pérez",
"expires_at": "2021-09-05T19:09:30.000Z"
}
}
Si en el campo status recibes el valor "CREATED", esto quiere decir que la tarjeta ha sido tokenizada correctamente y puedes usar la propiedad id para registrar la fuente de pago.
Cuentas Nequi
Para pagos con Nequi, el endpoint que debes usar es /v1/tokens/nequi realizando un POST con la Llave Pública como autorizador con el siguiente cuerpo JSON:
{
"phone_number": "3017654321"
}
Recibirás como respuesta en la propiedad id el token con el que podrás registrar la fuente de pago. Sin embargo, el cliente tendrá que haber aceptado primero la suscripción en su celular de modo que el estado pase de "PENDING" a "APPROVED".
{
"data": {
"id": "nequi_prod_RQkUiuv3lEnDLiSao2Cz0iQLdFlyQOI5",
"status": "PENDING",
"phone_number": "3107654321",
"name": "Company Name"
}
}
Para chequear el estado de la suscripción, puedes hacer GET en el endpoint de /v1/tokens/nequi/ con el token obtenido:
GET /v1/tokens/nequi/nequi_prod_RQkUiuv3lEnDLiSao2Cz0iQLdFlyQOI5
Una vez se obtenga un "APPROVED" en la propiedad "status" será posible registrar la fuente de pago.
{
"data": {
"id":"nequi_prod_RQkUiuv3lEnDLiSao2Cz0iQLdFlyQOI5",
"status":"APPROVED",
"phone_number":"3107654321",
"name":"Company Name"
}
}
Paso 2: Crea una fuente de pago
Para crear una fuente de pago, se debe hacer un POST a
/v1/payment_sources
Con los campos:
"customer_email"que es el email del pagador"type"para indicar el medio de pago correspondiente al token, que puede ser"NEQUI"o"CARD""token"el token de Nequi o Tarjeta que hayas obtenido"acceptance_token"un token de aceptación
Tarjetas
El cuerpo de la petición debe ser similar al siguiente:
{
"type": "CARD",
"token": "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301",
"customer_email": "pepito_perez@example.com",
"acceptance_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb250cmFjdF9pZCI6MSwicGVybWFsaW5rIjoiaHR0cHM6Ly93b21waS5jby93cC1jb250ZW50L3VwbG9hZHMvMjAxOS8wOS9URVJNSU5PUy1ZLUNPTkRJQ0lPTkVTLURFLVVTTy1VU1VBUklPUy1XT01QSS5wZGYiLCJmaWxlX2hhc2giOiIzZGNkMGM5OGU3NGFhYjk3OTdjZmY3ODExNzMxZjc3YiIsImppdCI6IjE1ODEwOTIzNjItMzk1NDkiLCJleHAiOjE1ODEwOTU5NjJ9.JwGfnfXsP9fbyOiQXFtQ_7T4r-tjvQrkFx0NyfIED5s"
}
Obtendremos una respuesta con una estructura como la siguiente indicándonos que fue creada exitosamente:
{
"data": {
"id": 3891,
"public_data": {
"type": "CARD"
},
"type": "CARD",
"status": "AVAILABLE"
}
}
Cuentas Nequi
El cuerpo de la petición debe ser similar al siguiente:
{
"type": "NEQUI",
"token": "nequi_prod_RQkUiuv3lEnDLiSao2Cz0iQLdFlyQOI5",
"customer_email": "pepito_perez@example.com",
"acceptance_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb250cmFjdF9pZCI6MSwicGVybWFsaW5rIjoiaHR0cHM6Ly93b21waS5jby93cC1jb250ZW50L3VwbG9hZHMvMjAxOS8wOS9URVJNSU5PUy1ZLUNPTkRJQ0lPTkVTLURFLVVTTy1VU1VBUklPUy1XT01QSS5wZGYiLCJmaWxlX2hhc2giOiIzZGNkMGM5OGU3NGFhYjk3OTdjZmY3ODExNzMxZjc3YiIsImppdCI6IjE1ODEwOTIzNjItMzk1NDkiLCJleHAiOjE1ODEwOTU5NjJ9.JwGfnfXsP9fbyOiQXFtQ_7T4r-tjvQrkFx0NyfIED5s"
}
Obtendremos una respuesta con una estructura como la siguiente indicándonos que fue creada exitosamente:
{
"data": {
"id": 3891,
"public_data": {
"type": "NEQUI",
"phone_number": "3105671703"
},
"type": "NEQUI",
"status": "AVAILABLE"
}
}
Paso 3: Crea una transacción
Al tener disponible un id de una fuente de pago, podrás usarlo para hacer cargos a tus usuarios sin necesidad de que ellos intervengan directamente en cada ocasión. Así podrás por ejemplo cobrar mensualmente una suscripción a un servicio, realizar cobros por servicios on-demand (como ventas a domicilio o servicios de transporte), cobrar por el uso de tu plataforma, etc.
Para esto, debes usar el mismo endpoint de transacciones que usan los pagos simples (POST a /v1/transactions), con la diferencia de que en esta ocasión enviarás información del método de pago (objeto payment_method) con el número de cuotas si la fuente de pago representa una tarjeta, de lo contrario este objeto no se tiene que enviar. En cualquier caso debes enviar un payment_source_id, por ejemplo:
{
"amount_in_cents": 4990000, // Monto current centavos
"currency": "COP", // Moneda
"signature": "37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5", //Firma de integridad
"customer_email": "example@gmail.com", // Email del usuario
"payment_method": {
"installments": 2 // Número de cuotas si la fuente de pago representa una tarjeta de lo contrario el campo payment_method puede ser ignorado.
},
"reference": "sJK4489dDjkd390ds02", // Referencia única de pago
"payment_source_id": 3891 // ID de la fuente de pago
}
NOTA: Si tienes dudas de como generar el valor de la firma de integridad puedes revisar la siguiente documentación: Genera una firma de integridad
Transacciones con COF
Cuando el medio de pago corresponde a una tarjeta de la franquicia MasterCard o VISA y el procesador de pagos es RBM, se puede hacer uso de Credential On File (COF) y así aumentar la taza de aprobación en las transacciones del comercio. Para esto, es necesario enviar recurrent, teniendo en cuenta que payment_source_id se convierte en un campo obligatorio.
recurrent debe ser un valor Booleano:
- true: Hace referencia a todas las transacciones en las que el titular autoriza que se almacenen los datos de su tarjeta y posteriormente se realicen cobros con el mismo monto de manera periódica. (Transacción de venta COF con recurrencia)
- false: Hace referencia a todas las transacciones en las que el titular autoriza que se almacenen los datos de su tarjeta y posteriormente se realicen cobros con diferentes montos sin ningún tipo de periodicidad. (Transacción de venta COF almacenada)
{
"amount_in_cents": 4990000, // Monto en centavos
"currency": "COP", // Moneda
"customer_email": "example@gmail.com", // Email del usuario
"payment_method": {
"installments": 2 // Número de cuotas si la fuente de pago representa una tarjeta de lo contrario el campo payment_method puede ser ignorado.
},
"reference": "sJK4489dDjkd390ds02", // Referencia única de pago
"payment_source_id": 3891, // ID de la fuente de pago (obligatorio)
"recurrent": true // Recurrente
}
- Sí no se envía
recurrent, la transacción se realizará sin COF. - Sí se envía
recurrenten transacciones con tarjetas de franquicia diferente a MasterCard o VISA, la transacción se realizará sin COF. - Sí se envía
recurrenty el procesador habilitado para el comercio es diferente a RBM, la transacción se realizará sin COF.
Widget en modo de tokenización
Puedes integrar nuestro Widget en modo tokenización para que puedas guardar la información de tus usuarios de forma más rápida y segura.
Con tan solo unas líneas de HTML:
<form method="POST" action="/process_token">
<script
src="https://checkout.wompi.co/widget.js"
data-render="button"
data-widget-operation="tokenize"
data-public-key="pub_test_X0zDA9xoKdePzhd8a0x9HAez7HgGO2fH"
>
</script>
</form>
Con el token dentro de la respuesta debes hacer un POST a /v1/payment_sources desde tu servidor y usando tu llave privada de comercio. Recuerda nunca usar la llave privada en contextos inseguros como tu código HTML.
