Payments links
In Wompi, you can create payment links using our Business' Dashboard or our public API, which can be shared with your customers via e-mail, social networks, Whatsapp, etc. These links have many features you can take advantage of:
- Single-use payment links (or multiple by default).
- Set an expiration date (optional).
- Set an exact amount to be paid, or leave this field as
nullso customers decide what amount they want to pay, which is useful for several cases.
Payment links can be created in a programmatic way, as explained below in this step by step guide:
Step by Step
step 1: Payment link creation
Creating a payment link using our API is done using the POST /v1/payment_links endpoint. Remember to include your Private Key with the following structure in the Bearer <LLAVE_PRIVADA> request header in the Authorization header:
Authorization: Bearer prv_test_Hl3V675pH555OJ00046aKuYo444sKbta
The request body must have the following structure:
{
"name": "Monthly rent - Wompi Tower Apartments", // Payment link name
"description": "Pay here your apartment monthly rent", // Payment link description
"single_use": false, // `true` in case a single APPROVED transaction is desired for this payment link; `false` in case multiple APPROVED transactions are allowed for this payment link
"collect_shipping": false, // If you want to collect the customer's shipping information during checkout
"currency": "COP", // Only COP (Colombian Peso) is valid at the moment. We will support more currencies in the future
// -------------------------------------------
// ---- The following fields are OPTIONAL ----
// -------------------------------------------
"amount_in_cents": null, // If the payment is for a specific amount, set it here. Otherwise, leave it as `null` and customers will choose the amount if no value is included
"expires_at": "2022-12-10 14:30:00", // Expiry date in ISO 8601 format and UTC timezone
"redirect_url": null, // URL where the customer will be redirected once the payment has been completed
"image_url": null, // Image URL for the payment link
"sku": null, // Internal unique product identifier. 36 chars max.
"customer_data": { // Custom fields (max. 2) where you can collect extra data from your customers if needed. Below a couple of examples.
"customer_references": [
{
"label": "Apartment #", // Field name. 24 chars max.
"is_required": true // Whether this field is required or not
},
{
"label": "Passport Number",
"is_required": true
}
]
}
}
Example 1: Minimum necessary fields
The minimun required fields for creating a payment link have the following structure:
{
"name": "Monthly rent - Wompi Tower Apartments", // Name of the payment link
"description": "Pay here your apartment monthly rent", // Payment description
"single_use": false, // `false` in case a single APPROVED transaction is desired for this payment link; `false` in case multiple APPROVED transactions are allowed for this payment link
"collect_shipping": false // If you want to collect the customer's shipping information during checkout
}
In this case a payment link will be created with the following properties:
- It has no amount specified, hence it will accept any value when creating a transaction that uses the payment link.
- The currency will always be COP (Colombian peso).
example 2: Payment link with fix value
To create a payment link that accepts a specific amount, when creating a transaction it must have the fields currency and amount_in_cents specified as follows:
{
"name": "Monthly rent - Wompi Tower Apartments", // Payment link name
"description": "Pay here your apartment monthly rent", // Payment link description
"single_use": false, // `true` in case a single APPROVED transaction is desired for this payment link; `false` in case multiple APPROVED transactions are allowed for this payment link
"collect_shipping": false, // If you want to collect the customer's shipping information during checkout
"currency": "COP", // Only COP (Colombian Peso) is valid at the moment. We will support more currencies in the future
"amount_in_cents": 500000, // If the payment is for a specific amount, set it here. Otherwise, leave it as `null` and customers will choose the amount if no value is included
}
Example 3: Payment link with expiration date
To create a payment link that has an expiration date, the structure needs to have the field expires_at defined as follows:
{
"name": "Monthly rent - Wompi Tower Apartments", // Payment link name
"description": "Pay here your apartment monthly rent", // Payment link description
"single_use": false, // `true` in case a single APPROVED transaction is desired for this payment link; `false` in case multiple APPROVED transactions are allowed for this payment link
"collect_shipping": false, // If you want to collect the customer's shipping information during checkout
"expires_at": "2022-12-10 14:30:00", // Expiry date in ISO 8601 format and UTC timezone when the payment link will no longer work
}
This will create a payment link that will not allow any transaction to be created after the date specified in the field expires_at.
Example 4: Payment links with custom fields
You can create a payment link where you can ask your customers for additional information before creating a transaction. This can be achieved by using custom fields. These are defined by using the field customer_data as follows:
{
"name": "Monthly rent - Wompi Tower Apartments", // Payment link name
"description": "Pay here your apartment monthly rent", // Payment link description
"single_use": false, // `true` in case a single APPROVED transaction is desired for this payment link; `false` in case multiple APPROVED transactions are allowed for this payment link
"collect_shipping": false, // If you want to collect the customer's shipping information during checkout
"customer_data": { // Custom fields (max. 2) where you can collect extra data from your customers if needed. Below a couple of examples.
"customer_references": [
{
"label": "Apartment #", // Field name. 24 chars max.
"is_required": true // Whether this field is required or not
},
{
"label": "Passport Number",
"is_required": true
}
]
}
}
Inside customer_data, you must also define a field called customer_references which will have an array containing the additional references that you want from your customer. Each reference has a label which will be the name of the field (i.e apartment #) and a boolean is_required which indicates if the field is required to make the payment.
When you successfully create a payment link you should receive something like the following response from our API:
{
"data": {
"id": "3Z0Cfi", // <--- PAYMENT LINK ID
"name": "Monthly rent - Wompi Tower Apartments",
"description": "Pay here your apartment monthly rent",
"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": "Apartment #",
"is_required": true
},
{
"label": "Passport Number",
"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": {}
}
If you wish to retrieve a payment link's information you can do it by performing a request to the GET /v1/payment_links/:payment_link_id endpoint. You will receive the same response as the JSON above. This endpoint doesn't require any kind of authentication.
Example 5: Payment link with fixed amount and taxes
You can create a payment link with tax information and your clients will have the details of these when they generate the payment. This can be achieved by creating a payment link in the following way using the taxes field:
When the amount is fixed, the structure of the field is as follows:
{
"name": "Lombardia building rent payment - AP 505", // Payment link name
"description": "Monthly rent", // Payment description
"single_use": false, // `false` if the payment link can receive multiple APPROVED transactions or `true` if it should stop accepting transactions after the first APPROVED payment
"collect_shipping": false, // Whether you want the customer to insert their shipping information at checkout, or not
"amount_in_cents": 2000, // Total value of the payment link
"currency": "COP", // Only Colombian pesos (COP) are available at the moment. We will support more currencies in the future
"taxes": [
{
"type": "VAT", // Tax type. (Allowed values "VAT" for VAT and "CONSUMPTION" for consumption tax)
"amount_in_cents": 120000 // It is the amount that represents the tax within the total amount, you must express the current value in cents.
}
]
}
Note: This is not a required field, so you can create a payment link with a fixed amount and no taxes.
Please note that the amount_in_cents field of the payment link must include the tax value(s).
Example 6: Payment link with open amount and taxes
You can create a payment link with tax information and your clients will have the details of these when they generate the payment. This can be achieved by creating a payment link in the following way using the taxes field:
When the amount is open, the structure of the field is as follows:
{
"name": "Lombardia building rent payment - AP 505", // Payment link name
"description": "Monthly rent", // Payment description
"single_use": false, // `false` if the payment link can receive multiple APPROVED transactions or `true` if it should stop accepting transactions after the first APPROVED payment
"collect_shipping": false, // If you want the customer to insert their shipping information at checkout, or not
"taxes": [
{
"type": "VAT", // Tax type. (Allowed values "VAT" for VAT and "CONSUMPTION" for consumption tax)
"percentage": 19 // It is the percentage of the tax
}
]
}
Note: This is not a required field, therefore you can create a payment link with open amount and without taxes. Please note that when processing a transaction with an open payment link with taxes, it is understood that the associated transaction amount includes taxes.
Step 2: Share payment link
Now that you have created a payment link, you can share it with your customers, who will be able to pay using the generated URL, which has the following structure:
https://checkout.wompi.co/l/:payment_link_id
For instance, in the previous example, the resulting link would be:
https://checkout.wompi.co/l/3Z0Cfi
