PSE Payment Links (inflow payments)
Belvo's Open Payments API makes use of Colombia's Pagos Seguros en LΓnea (PSE) system to make payments securely with payment links while also building upon PSE to optimize your user's experience.
Intro
After you have registered your beneficiary account (you only need to do it once), you can then go ahead and:
- Create a customer
A customer is a user (and individual) that will make the payment to your account. You only need to create a customer for new users of your application.
Tip!
Whenever your user signs up for your application, you can already request the information required to create a customer. Once they complete your sign-up process, you can automatically create a customer in Belvo.
-
Create a payment link
A payment link requires you to provide basic information about the payment (such as the amount, the account which will receive the payment, and a description). In return, you will receive a URL to a hosted widget, fully responsive for web and mobile applications, that will guide your user through the payment flow. Simple, elegant, and headache-free. -
Your user completes payment in the widget
The Payment Link Widget will guide your user through the necessary steps to complete the payment, including choosing their bank and confirming the details, and proceeding with the payment. -
Receive a webhook confirming payment
Youβll get notified every time money is successfully transferred to your account. π
Create a customer
To create a customer, you need to make a POST Create a new customer call with the following core information:
{
"customer_type": "INDIVIDUAL",
"country": "COL",
"name": "Carlos Vives",
"email": "[email protected]",
"identifier_type": "CC",
"identifier": "1018760936",
"address": "Calle Carlos Vives 432, 80300 Bogota",
"phone": "3210987636"
}
Youβll receive the following response from our API, confirming that the customer was created. Make sure to save the id
you receive, as this ID is required when creating a payment link π€.
{
"id":"1c83ead8-6665-429c-a17a-ddc76cb3a95e", // ID used for creating payment links
"created_at":"2022-02-09T08:45:50.406032Z",
"created_by":"1c83ead8-6665-429c-a17a-ddc76cb3a95e",
"customer_type":"INDIVIDUAL",
"name":"Carlos Vives",
"address":"Calle Carlos Vives 432, 80300 Bogota",
"country":"COL",
"email":"[email protected]",
"phone":"3210987636",
"identifier":"1018760936",
"identifier_type":"CC"
}
Now, with the customer.id
youβve just received, you can go ahead and create a payment link.
Need more info? Check out our API reference! π€
Is your customer not registered in PSE?
To make payments using Belvoβs API in Colombia, your user needs to be registered in the PSE system. If your user is not registered (or uses a different email address from the one you provided when creating a customer), then Belvo will automatically:
- Register your user in PSEβs portal using the email you provided in the request
- Create a customer with the userβs information
Since you've just registered your customer in PSE, they'll receive an email confirming their successful registration in the system.
Create a payment link
To create a payment link, you need to make a POST Create a payment link call with the following core information:
{
"allowed_payment_method_types": [
"pse"
],
"payment_method_details": {
"pse": {
"beneficiary_bank_account": "your_account_uuid"
}
},
"callback_urls": {
"cancel": "url_to_redirect_to_if_process_cancelled",
"success": "url_to_redirect_to_if_process_successful"
},
"amount": "amount_to_pay_as_an_integer",
"customer": "the_customer_uuid",
"description": "payment_description",
"provider": "payments_way",
"expires_in": "payment_link_expiration_time"
}
{
"allowed_payment_method_types": [
"pse"
],
"payment_method_details": {
"pse": {
"beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
}
},
"callback_urls": {
"cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
"success": "https://www.acmecorp.com/checkout/3487548/success"
},
"amount": 1000,
"customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
"description": "Awesome training Sneaker",
"provider": "payments_way",
"expires_in": "7d"
}
For
amount
, you can only send whole numbers (integers), meaning digits 0-9 with no decimals points. Otherwise, our API will return a 400 Invalid Error.
You'll receive a response containing a unique link (the payment_url
) that you can share with your user and be guided through the payment process.
{
"id": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
"created_at": "2022-02-09T08:45:50.406032Z",
"created_by": "62053a72-e2d5-4c95-a578-6b16616900ac",
"payment_url": "https://pay.belvo.io/YggaKvPbM5aJhksu1BEwDI5FKTcUc5wZqNB-wH7MFGU",
"payment_intent": "b7dd85b1-671e-45c7-aba6-b4b37a8fc0c2",
"access_token": "YggaKvPbM5aJhksu1BEwDI5FKTcUc5wZqNB-wH7MFGU",
"callback_urls": {
"cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
"success": "https://www.acmecorp.com/checkout/3487548/success"
},
"updated_at": "2022-02-09T08:45:50.406032Z",
"status": "ACTIVE",
"expires_in":"7d",
"expires_at":"2022-02-09T08:45:50.406032Z"
}
Tip!
Make sure to store the
payment_intent.id
you receive in the response, you can use it later to relate the payment intent with the payment transaction that confirms the payment.
Done! Now that youβve created the payment link, you can share it with your customers. Theyβll use this URL to start the Payment Link Widget that will guide them through the payment process. π
Need more info? Check out our API reference! π€
Widget Payment Process
You'll need to share the payment_url
with your user so they can start Belvoβs Payment Link Widget (a fully responsive hosted widget for web and mobile applications). The widget will guide your user through the payment flow.
This is an example implementation of sharing the payment_url
:
<html lang="en-US">
<head>
<meta charset="utf-8">
<title>Pay with Belvo</title>
</head>
<body>
<!-->Simple link for a user to pay with Belvo <-->
<a id="link" href="">Pay with Belvo</a>
<script>
// Sending a request to your backend so that you can send a request
// to Belvo to generate the Payment Link
fetch('https://yourawesomebackend.com/api').then(function (response) {
// The API call was successful! Return the JSON response from Belvo.
return response.json();
}).then(function (data) {
// This is the JSON from your backend
console.log({ data });
// Set the payment link URL that is shown to the user
document.querySelector('#link').href = data.payment_url;
}).catch(function (err) {
// There was an error
console.warn('Something went wrong. Please try again.', err);
});
</script>
</body>
</html>
To help you keep track of your userβs process within the Payment Link widget, Belvo sends payment intent
status
update webhook events.For more info, check our Payment intents webhook article.

Belvo's PSE widget payment flow
And it's that easy! Then, if the same customer wants to buy something else through your application, all you need to do is create a payment link π.
Whatβs next? When Belvo confirms the payment was processed and that money was transferred to the beneficiary account, youβll get a new webhook called Transactions. π You can confirm the transfer of funds by listening to the Transactions webhook. With it, Belvo also returns the id
you need to get details about a transaction.
How do you know that your payment has been completed?
Weβll inform you of every successful payment by sending you a Transactions webhook - a payment transaction is an actual transfer of funds from one account to another π. This means that every time money has been successfully transferred to your account, youβll receive the following notification:
{
"webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
"webhook_type": "TRANSACTIONS",
"webhook_code": "OBJECT_CREATED",
"object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
"data": {}, //For OBJECT_CREATED webhooks, the data field returns an empty object.
}
You can also get details about a transaction by making a GET details call using the object_id
of the transaction (which you receive in the webhook event).
{
"id": "fd0f3303-cafb-47ea-9753-21155cb144ab",
"created_at": "2020-04-23T21:30:20.336854+00:00",
"created_by": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
"amount": "350000",
"currency": "COP",
"description": "Awesome training Sneaker",
"transaction_type": "INFLOW",
"beneficiary": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
"payer": {
"bank_account": "7c2be016-37e3-44e2-8643-db2eb1129a3f",
},
"payment_intent": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
"customer": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Need more info? Check out our API reference! π€
Summary
In this guide you learned how to:
- register customers so you can start requesting payments from them
- create a payment link you can share with your customers to start the Payment Link Widget
- confirm that a payment is successful
If you need any help, just reach out to our team at [email protected] and weβll get right to it. π
Updated 5 months ago