API StatusAPI ReferenceError DocsInstitutionsSupportSign inCreate a Sandbox account

PSE Payment Links (inflow payments)

Suggest Edits

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:

  1. 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.

  1. 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.

  2. 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.

  3. 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.

1021

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