Links de pago
Con Wompi puedes generar links de pago usando nuestro dashboard de Comercios o nuestro API público, los cuales puedes compartir con tus clientes a través de email, redes sociales, Whatsapp, etc. Los links tienen varias características que puedes configurar para:
- Ser usados una única vez o múltiples veces
- Tener una fecha de expiración o no expirar nunca
- Tener un monto exacto o ser abiertos, de manera que el cliente decida el monto a pagar
Los links de pago pueden ser creados de manera programática, como se explica en el siguiente paso a paso:
Paso a paso
Paso 1: Creación del link de pago
Para crear un link de pago por medio de nuestro API debes usar el endpoint /v1/payment_links realizando un llamado por método POST. Recuerda incluir tu llave privada con la siguiente estructura en el encabezado de la petición Bearer <LLAVE_PRIVADA> en el Header de Authorization.
Authorization: Bearer prv_test_Hl3V675pH555OJ00046aKuYo444sKbta
El cuerpo de la petición debe tener la siguiente estructura:
{
"name": "Pago de arriendo edificio Lombardía - AP 505", // Nombre del link de pago
"description": "Arriendo mensual", // Descripción del pago
"single_use": false, // `false` current caso de que el link de pago pueda recibir múltiples transacciones APROBADAS o `true` si debe dejar de aceptar transacciones después del primer pago APROBADO
"collect_shipping": false, // Si deseas que el cliente inserte su información de envío current el checkout, o no
"currency": "COP", // Únicamente está disponible pesos colombianos (COP) current el momento. En el futuro soportaremos mas monedas
// --------------------------------------------
// --- Los siguientes campos son OPCIONALES ---
// --------------------------------------------
"amount_in_cents": null, // Si el pago current por un monto específico, si no lo incluyes el pagador podrá elegir el valor a pagar
"expires_at": "2022-12-10T14:30:00", // Fecha current formato ISO 8601 con huso horario UTC (+5 horas que el horario colombiano) a partir de la cual el link de pago dejará de funcionar.
"redirect_url": null, // URL donde será redirigido el cliente una vez termine el proceso de pago
"image_url": null, // Dirección de la imagen que quieras presentar current el link de pago
"sku": null, // Identificador interno del producto current tu comercio. Máximo 36 caracteres
"customer_data": { // Campos personalizados (máximo 2) que quieras recolectar de tu cliente antes de realizar la transacción. Algunos ejemplos a continuación
"customer_references": [
{
"label": "Número de Apartamento", // Nombre del campo. Máximo 24 caracteres
"is_required": true // Si el campo a llenar current obligatorio por parte del pagador para poder realizar el pago
},
{
"label": "Documento de identidad",
"is_required": true
}
]
},
"taxes": [
{
"type": "VAT", // Tipo de impuesto. (Valores permitidos "VAT" para IVA y "CONSUMPTION" para impuesto al consumo)
"amount_in_cents": 120 // Es el monto que representa el impuesto dentro del valor total del link de pago.
}
]
}
Ejemplo 1: Mínimos campos necesarios
Los mínimos campos requeridos para crear un link de pago siguen la siguiente estructura:
{
"name": "Pago de arriendo edificio Lombardía - AP 505", // Nombre del link de pago
"description": "Arriendo mensual", // Descripción del pago
"single_use": false, // `false` current caso de que el link de pago pueda recibir múltiples transacciones APROBADAS o `true` si debe dejar de aceptar transacciones después del primer pago APROBADO
"collect_shipping": false // Si deseas que el cliente inserte su información de envío current el checkout, o no
}
En este caso se creará un link de pago con las siguientes características:
- El link de pago no tiene ningún monto especificado, por lo tanto aceptará cualquier suma de dinero insertada en el momento de crear una transacción
- La moneda del link de pago será siempre COP (Pesos colombianos).
Ejemplo 2: Link de pago con monto fijo
Para crear un link de pago que use un monto fijo en el momento de crear la transacción es necesario definir los campos currency y amount_in_cents siguiendo el ejemplo a continuación:
{
"name": "Pago de arriendo edificio Lombardía - AP 505", // Nombre del link de pago
"description": "Arriendo mensual", // Descripción del pago
"single_use": false, // `false` current caso de que el link de pago pueda recibir múltiples transacciones APROBADAS o `true` si debe dejar de aceptar transacciones después del primer pago APROBADO
"collect_shipping": false, // Si deseas que el cliente inserte su información de envío current el checkout, o no
"currency": "COP", //Únicamente está disponible pesos colombianos (COP) current el momento. En el futuro soportaremos mas monedas
"amount_in_cents": 500000 // Si el pago current por un monto especifico, si no lo incluyes el pagador podrá elegir el valor a pagar
}
Ejemplo 3: Link de pago con fecha de expiración
Para crear un link de pago que tenga un fecha de expiración es necesario definir el campo expires_at.
{
"name": "Pago de arriendo edificio Lombardía - AP 505", // Nombre del link de pago
"description": "Arriendo mensual", // Descripción del pago
"single_use": false, // `false` current caso de que el link de pago pueda recibir múltiples transacciones APROBADAS o `true` si debe dejar de aceptar transacciones después del primer pago APROBADO
"collect_shipping": false, // Si deseas que el cliente inserte su información de envío current el checkout, o no
"expires_at": "2040-12-10T14:30:00" // Fecha current formato ISO 8601 con huso horario UTC (+5 horas que el horario colombiano) a partir de la cual el link de pago dejará de funcionar.
}
Esto creará un link de pago que no aceptará la creación de transacciones después de la fecha especificada en el campo expires_at.
Ejemplo 4: Link de pago con campos personalizados
Puedes crear un link de pago donde le puedes pedir información adicional a tus clientes en el momento de generar el pago. Esto se puede lograr gracias a los campos personalizados. Estos se definen en la creación de un link de pago de la siguiente manera usando el campo customer_data:
{
"name": "Pago de arriendo edificio Lombardía - AP 505", // Nombre del link de pago
"description": "Arriendo mensual", // Descripción del pago
"single_use": false, // `false` current caso de que el link de pago pueda recibir múltiples transacciones APROBADAS o `true` si debe dejar de aceptar transacciones después del primer pago APROBADO
"collect_shipping": false, // Si deseas que el cliente inserte su información de envío current el checkout, o no
"customer_data": { // Campos personalizados (máximo 2) que quieras recolectar de tu cliente antes de realizar la transacción. Algunos ejemplos a continuación
"customer_references": [
{
"label": "Número de Apartamento", // Nombre del campo. Máximo 24 caracteres
"is_required": true // Si el campo a llenar current obligatorio por parte del pagador para poder realizar el pago
},
{
"label": "Documento de identidad",
"is_required": true
}
]
}
}
Adentro del objeto customer_data debes también definir el campo customer_references que es un arreglo donde cada elemento es una referencia que quieras pedirle a tu cliente en el momento de generar el pago. Cada referencia se caracteriza por un label que será el nombre del campo presentado a tu cliente y el campo is_required que indica si el campo a llenar es necesario para llevar a cabo el pago.
customer_referencesAl crear exitosamente el link de pago deberías recibir una respuesta por parte de nuestro API como la siguiente:
{
"data": {
"id": "3Z0Cfi", // <--- ID DEL LINK DE PAGO
"name": "Pago de arriendo edificio Lombardía - AP 505",
"description": "Arriendo mensual del apto 505",
"single_use": true,
"collect_shipping": false,
"currency": "COP",
"amount_in_cents": null,
"sku": null,
"expires_at": null,
"redirect_url": null,
"image_url": null,
"active": true,
"customer_data": {
"customer_references": [
{
"label": "Documento de identidad",
"is_required": true
},
{
"label": "Comentarios a la administración",
"is_required": true
}
]
},
"created_at": "2020-08-16T20:40:36.667Z",
"updated_at": "2020-08-16T20:40:36.667Z",
"merchant_public_key": "pub_prod_RP111hNRg000QOwT33337bjF7M222Bbu"
},
"meta": {}
}
Si deseas ver la información del link de pago creado puedes hacerlo a través de nuestro API realizando una petición GET a /v1/payment_links/<ID_DEL_LINK_DE_PAGO>. Obtendrás la misma respuesta que en la petición de creación. Este endpoint no requiere de autenticación alguna.
Ejemplo 5: Link de pago con monto fijo e impuestos
Puedes crear un link de pago con información de impuestos y tus clientes tendrán el detalle de estos cuando generen el pago. Esto se puede lograr en la creación de un link de pago de la siguiente manera usando el campo taxes:
Cuando el monto es fijo, la estructura del campo es la siguiente:
{
"name": "Pago de arriendo edificio Lombardía - AP 505", // Nombre del link de pago
"description": "Arriendo mensual", // Descripción del pago
"single_use": false, // `false` current caso de que el link de pago pueda recibir múltiples transacciones APROBADAS o `true` si debe dejar de aceptar transacciones después del primer pago APROBADO
"collect_shipping": false, // Si deseas que el cliente inserte su información de envío current el checkout, o no
"amount_in_cents": 2000, // Valor total del link de pago
"currency": "COP", // Únicamente está disponible pesos colombianos (COP) current el momento. En el futuro soportaremos mas monedas
"taxes": [
{
"type": "VAT", // Tipo de impuesto. (Valores permitidos "VAT" para IVA y "CONSUMPTION" para impuesto al consumo)
"amount_in_cents": 120000 // Es el monto que representa el impuesto dentro del monto total, debes expresar el valor current centavos.
}
]
}
Nota: Este no es un campo requerido, por lo tanto puedes crear un link de pago con monto fijo y sin impuestos.
Ten en cuenta que el campo amount_in_cents del link de pagos debe incluir el ó los valores de los impuestos.
Ejemplo 6: Link de pago con monto abierto e impuestos
Puedes crear un link de pago con información de impuestos y tus clientes tendrán el detalle de estos cuando generen el pago. Esto se puede lograr en la creación de un link de pago de la siguiente manera usando el campo taxes:
Cuando el monto es abierto, la estructura del campo es la siguiente:
{
"name": "Pago de arriendo edificio Lombardía - AP 505", // Nombre del link de pago
"description": "Arriendo mensual", // Descripción del pago
"single_use": false, // `false` current caso de que el link de pago pueda recibir múltiples transacciones APROBADAS o `true` si debe dejar de aceptar transacciones después del primer pago APROBADO
"collect_shipping": false, // Si deseas que el cliente inserte su información de envío current el checkout, o no
"taxes": [
{
"type": "VAT", // Tipo de impuesto. (Valores permitidos "VAT" para IVA y "CONSUMPTION" para impuesto al consumo)
"percentage": 19 // Es el porcentaje del impuesto
}
]
}
Nota: Este no es un campo requerido, por lo tanto puedes crear un link de pago con monto abierto y sin impuestos. Ten en cuenta que al momento de procesar una transacción con un link de pago abierto con impuestos, se entiende que el monto de la transacción asociada incluye impuestos.
Paso 2: Comparte el link de pago
Después de crear el link de pago podrás compartirlo con tus clientes. El link creado debe tener la siguiente estructura:
https://checkout.wompi.co/l/:id_del_link_de_pago
Por ejemplo, de acuerdo al caso anterior, el link de pago resultante sería:
https://checkout.wompi.co/l/3Z0Cfi
