Skip to main content

Payments links

Make sure this fits your use case
Before using this API feature, please make sure whether the Widget & Checkout Web integration is better suited for your use case or not. The instructions below must be preferrably used for use cases where the programmatic creation of single or multiple Payment Links is needed and the following data is useful: expiry date, single-use or additional customer data collection.

In Wompi, you can create payment links using our Merchant's 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 expiry date (optional)
  • Set an exact amount to be paid, or leave this field as null so 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 — Create a payment link
  • Step 2 — Share a payment link

Creating a payment link using our API is done using the POST /v1/payment_links endpoint. Don't forget to use your account's Private Key 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).

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
}

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.

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.

Custom fields (customer_references)
Keep in mind that you can add, at most, 2 custom fields to your payment link.

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.

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