Fuentes de pago & Tokenización
Cambio importante en el API
Para la creación de transacciones y fuentes de pago, pensando en la privacidad y el correcto manejo de los datos personales de nuestros usuarios, es ahora obligatorio el uso de Tokens de Aceptación a la hora de crear cualquiera de estos dos recursos a través de nuestro API.
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 de una suscripción a una revista por ejemplo, o el cobro de un servicio on-demand, como entregas a domicilio o servicios de transporte, 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, y requieren que el usuario lleve a cabo un único proceso inicial, donde provea bien sea la información de su tarjeta, que será usada posteriormente para hacer los cobros respectivos.
Tan sólo debes seguir el paso a paso descrito a continuación:
Guía de nivel intermedio - avanzado
Los pasos descritos a continuación requieren una integración y uso directo de nuestra API, por lo cual está orientado a desarrolladores de nivel intermedio-avanzado que estén familiarizados con el uso de APIs. Sin embargo, Wompi planea facilitar el proceso pronto, ofreciendo realizar el primer paso a través de nuestro Widget.
Paso a paso
- Paso 1 — Obten un token de aceptación prefirmado.
- Paso 2 — Solicita la información del método de pago.
- Paso 3 — Crea una fuente de pago con 3Ds Secure.
- Paso 4 — Crea una transacción usando la fuente de pago.
Paso 1: Obtener un token de aceptación prefirmado
Para obtener un token de aceptación prefirmado debes acceder al endpoint usando tu llave pública GET /merchants/:llave_publica_de_comercio. Este endpoint mostrará los datos de tu comercio incluyendo el Token de Aceptación de la siguiente manera:
{
"data": {
// Otros datos del comercio...
"presigned_acceptance": {
"acceptance_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb250cmFjdF9pZCI6MSwicGVybWFsaW5rIjoiaHR0cHM6Ly93b21waS5jby93cC1jb250ZW50L3VwbG9hZHMvMjAxOS8wOS9URVJNSU5PUy1ZLUNPTkRJQ0lPTkVTLURFLVVTTy1VU1VBUklPUy1XT01QSS5wZGYiLCJmaWxlX2hhc2giOiIzZGNkMGM5OGU3NGFhYjk3OTdjZmY3ODExNzMxZjc3YiIsImppdCI6IjE1ODEwOTIzNjItMzk1NDkiLCJleHAiOjE1ODEwOTU5NjJ9.JwGfnfXsP9fbyOiQXFtQ_7T4r-tjvQrkFx0NyfIED5s",
"permalink": "https://wompi.pa/wp-content/uploads/2019/09/TERMINOS-Y-CONDICIONES-DE-USO-USUARIOS-WOMPI.pdf",
"type": "END_USER_POLICY"
}
}
}
Paso 2: 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. Para eso, usarás nuestro API de manera que **Wompi almacene de manera segura información de tarjetas.
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": "424242",
"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.
Clave
Para pagos con Clave, el endpoint que debes usar es /v1/tokens/clave realizando un POST con la Llave Pública como autorizador con el siguiente cuerpo JSON:
{
"commerce_client_id": 12345, // id del cliente en el sistema del comercio
"commerce_operation": "RECURRING_CHARGE"
}
Recibirás como respuesta en la propiedad id_token el token con el que podrás registrar la fuente de pago.
{
"data": {
"id_token": "clave_prod_EOoscJEkrGJkLz6CAmDWt2f6EJn5PJaR",
"status": "APPROVED",
"commerce_client_id": "12345",
"commerce_operation": "RECURRING_CHARGE"
},
"meta": {}
}
Paso 3: 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"CLAVE"o"CARD""token"el token de Clave 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": 333,
"public_data": {
"bin": "424242",
"last_four": "4242",
"exp_month": "06",
"exp_year": "29",
"card_holder": "Pedro Pérez",
"validity_ends_at": "2026-01-14T14:28:48.749+00:00",
"type": "CARD"
},
"token": "tok_devtest_196_4963b22704de91b358746294cf4a738f",
"type": "CARD",
"status": "AVAILABLE",
"customer_email": "prueba@test.com"
}
}
Clave
El cuerpo de la petición debe ser similar al siguiente:
{
"type": "CLAVE",
"token": "clave_prod_EOoscJEkrGJkLz6CAmDWt2f6EJn5PJaR",
"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": 123,
"public_data": {
"type": "CLAVE",
"commerce_client_id": "12345",
"commerce_operation": "RECURRING_CHARGE"
},
"token": "clave_devtest_EOoscJEkrGJkLz6CAmDWt2f6EJn5PJaR",
"type": "CLAVE",
"status": "AVAILABLE",
"customer_email": "pepito_perez@example.com"
},
"meta": {}
}
Paso 4: 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": 4499, // Monto current centavos
"currency": "USD", // Moneda
"signature": "37c8407747e595535433ef8f6a811d853cd943046624a0ec04662b17bbf33bf5", // Firma de integridad
"customer_email": "example@gmail.com", // Email del usuario
"payment_method": {
"installments": 1 // 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**
Tarjetas
Autenticación Inicial:
Para habilitar pagos recurrentes, el cliente debe completar todas las fases de ** transacción mediante 3D Secure** utilizando el método de pago "CARD" y el "payment_source" que previamente se ha generado. Es importante destacar que, en este contexto, no es necesario tokenizar nuevamente la tarjeta; en cambio, se debe emplear la fuente de pago creada en la fase anterior.
{
"acceptance_token": "acceptance_token", // Generado en el 1 paso
"amount_in_cents": 100,
"currency": "USD",
"customer_email": "pepito_perez@example.com",
"reference": "AHJDFDSFK184", // Valor unico para identificar la transaccion
"payment_method": {
"type": "CARD"
},
"payment_source_id": 3891 // ID de fuente de pago creada
}
Y continuaria con el resto del flujo de 3ds, si la transaccion es aprovada los siguientes pagos no requeriran de interaccion del cliente.
Clave
Autenticación Inicial:
Para permitir pagos recurrentes, el cliente debe realizar todos los pasos de pago simple utilizando el método de pago Clave y utilizando el payment_source que se creo anteriormente. Durante este proceso, el cliente seguirá todos los pasos de autenticación requeridos por Clave para autorizar el cobro. Esta transacción inicial garantizará que el cliente esté de acuerdo con el uso futuro de pagos recurrentes.
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.
