API StatusAPI ReferenceError DocsInstitutionsSupportSign inCreate a Sandbox account

PSE Payment intents: inflow payments

Collect payments in 🇨🇴 Colombia from your customers not using a Belvo-integrated institution.

Suggest Edits

Belvo's Payment Initiation API allows you to securely collect payments from your users in 🇨🇴 Colombia, even if their financial institution isn't integrated with our platform. This guide will walk you through the process of collecting a payment outside our Belvo flow. 🤓

PSE flow

  1. Create a customer
  2. Create a payment intent
  3. Complete a payment intent
  4. Receive a webhook confirming payment

📘

Webhooks notifications

We’ll let you know when certain webhooks (and their types) are sent to the webhook URL so you can keep track of the payment lifecycle along the way.

Check our Webhooks article for more info. 🤓

Create a customer

To create a customer, you need to make a POST Create a new customer request with your user's information. Remember that you only need to create a customer for new users of your application.

{
  "customer_type": "INDIVIDUAL",
  "country": "COL",
  "name": "Carlos Vives",
  "email": "[email protected]",
  "identifier_type": "CC",
  "identifier": "1018760936",
  "address": "Calle Carlos Vives 432, 80300 Bogota",  // optional field
  "phone": "3210987636" // optional field
}

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 intent 🤓.

{
   "id": "c1b70f8f-b033-4891-bb38-167ea6a1c290", // ID used later to create payment intents
   "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": "1098712345",
   "identifier_type": "CC"
}

👍

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.

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 new 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 intent

A payment intent is a request to collect payments from your customer, and it keeps in-depth information about your user's journey throughout the payment process.

The way it works is:

  1. You create a payment intent by making a POST Create a new payment intent request.
  2. You fill in the payment intent with all the information about your customer through subsequent PATCH Complete a payment intent requests.
Payment intent flow using the non-Belvo flow

Payment intent flow using the non-Belvo flow

To create a payment intent, you need to make a POST Create a new payment intent request with the following core information:

{
	"allowed_payment_method_types":["pse"],
	"amount": "amount_to_pay_as_an_integer",
	"customer": "the_customer_uuid",
	"description": "payment_description",
	"payment_method_details":{
		"pse":{
			"beneficiary_bank_account":"your_account_uuid", // The account that collects the payment
			"callback_url": "url_to_redirect_to_if_process_successful" // The callback URL that your user will be redirected to after confirming the payment in their banking application.
		}
	},
	"provider": "payments_way"
}


{
	"allowed_payment_method_types":["pse"],
	"amount": "350000",
	"customer": "c1b70f8f-b033-4891-bb38-167ea6a1c290",
	"description": "Awesome training Sneaker",
	"payment_method_details":{
		"pse":{
			"beneficiary_bank_account":"82582a40-2e75-42a5-b5e7-f593cfdbdf64",
			"callback_url": "https://www.acmecorp.com/checkout/3487565/success"
		}
	},
	"provider": "payments_way"
}

📘

Additional info about 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 the following response containing instructions (in the next_step object) you’ll need to follow to guide your user through the payment flow. In this case, you’ll receive a pse_display_payment_method_information instruction with a list of institutions that you need to display to your user for them to select from.

{
	"id": "e9cfd041-368c-404b-8a16-2a8db16a75b1",
	"allowed_payment_method_types":["pse"],
	"amount": "350000",
	"charges":[],
	"created_at":"2023-03-03T19:24:49.825406Z",
	"created_by":"cefab866-b96b-4a9f-b6e2-9857dec88ec8",
	"currency": "COP",
	"customer": "c1b70f8f-b033-4891-bb38-167ea6a1c290",
	"description": "Awesome training Sneaker",
	"failure_code": null,
	"failure_message": null,
	"metadata":{},
	"next_step":{   // This is the next step in the payment flow you need to follow.
		"type": "pse_display_payment_method_information",
		"pse_display_payment_method_information":{
			"customer_bank_accounts":[],
			"institutions":[
				{
					"id": "045dcbe4-fc39-4d70-8eec-0808821a371f",
					"active": true,
					"country": "COL",
					"display_name":"Erebor Bank",
					"form_fields":[
						{
							"name":"username",
							"type":"text",
							"label": "Usuario",
							"validation": "^(?=.*[0-9])(?=.*[a-zA-Z])([a-zA-Z0-9ñ]){8,20}$",
							"placeholder": "Usuario",
							"validation_message":"Requiere entre 8 y 20 dígitos, 1 número y 1 letra"
						},
						{
							"name": "password",
							"type": "password",
							"label": "Clave",
							"validation": "^\\d{4}$",
							"placeholder":"****",
							"validation_message": "Requiere 4 dígitos"
						},
						{
							"name": "token",
							"type": "number",
							"label": "Clave Dinámica",
							"length": 6,
							"optional": false,
							"validation": "^\\d{6}$",
							"validation_message": "Requiere 6 dígitos"
						}
					],
					"icon_logo": "https://statics.belvo.io/institutions/icon_logos/ereborbank.svg",
					"logo": "https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
					"name": "ereborbank",
					"primary_color": "#fdbc24",
					"text_logo": "https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
					"website": "https://www.grupoereborcolombia.com"
				},
...
			]
		},
		"ready_to_confirm": false // When set to true, it means you can confirm the payment intent in the PATH request.
	},
	"last_error":{},
	"payment_method_details":{
		"pse":{
			"beneficiary_bank_account":"82582a40-2e75-42a5-b5e7-f593cfdbdf64",
      		"belvo_flow": false,
      		"callback_url": "https://www.acmecorp.com/checkout/3487565/success"
		}
	},
	"payment_method_information":{},
	"provider": "payments_way",
	"selected_payment_method_type": "pse",
	"status": "REQUIRES_PAYMENT_METHOD",
	"updated_at": "2023-03-03T19:24:50.078445Z"
}

👍

Tip!

Make sure to save the id you receive, as you’ll need it to complete the payment intent flow 🤓.

Complete a payment intent

Now that you've created the payment intent, you need to fill in with required information about your customer. To do so, you need to make PATCH Complete a payment intent requests. With each PATCH request, Belvo returns a next step that lets you know what information you need to send through next.

📘

Check our PSE Payments reference guide for more detailed info on next steps.

Selecting an institution

When you create a payment intent for first-time customers, Belvo returns a pse_display_payment_method_information next step. You’ll need to display a list of institutions to your user for them to select. Once they’ve selected the institution they want to use, you’ll need to send through that institution in a PATCH Complete a payment intent request (as shown below).

{
	"payment_method_details":{
		"pse":{
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f"
		}
	}
}

You'll receive the following response containing instructions (in the next_step object) you’ll need to follow to guide your user through the payment flow. In this case, you’ll receive a pse_display_needs_redirect instruction to let your customer know they'll be redirected to their banking application to continue with the payment process. 

{
	"id":"e9cfd041-368c-404b-8a16-2a8db16a75b1",
...
	"next_step":{  // This is the next step in the payment flow you need to follow.
		"type":"pse_display_needs_redirect",
		"pse_display_needs_redirect":{
			"payer_institution":{
				"id":"045dcbe4-fc39-4d70-8eec-0808821a371f",
				"active":true,
				"country":"COL",
				"display_name":"Erebor Bank",
				"form_fields":[],
				"icon_logo":"https://statics.belvo.io/institutions/icon_logos/ereborbank.svg",
				"logo":"https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
				"name":"ereborbank",
				"primary_color":"#386292",
				"text_logo":"https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
				"website":"https://www.grupoereborcolombia.com/"
			}
		},
		"ready_to_confirm":true // When set to true, it indicates the payment intent is ready to be processed in the next PATCH request.
	},
	"last_error":{},
	"payment_method_details":{
		"pse":{
			"beneficiary_bank_account":"82582a40-2e75-42a5-b5e7-f593cfdbdf64",
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f",
      		"belvo_flow": false,
      		"callback_url": "https://www.acmecorp.com/checkout/3487565/success"
		}
	},
	"payment_method_information":{},
	"provider":"payments_way",
	"selected_payment_method_type":"pse",
	"status":"REQUIRES_PAYMENT_METHOD",
	"updated_at":"2023-03-04T01:52:55.820245Z"
}

📘

The response returns "ready_to_confirm": true, which means that the payment intent is ready to be processed. You'll need to send through the confirmation in the Confirming the payment step.

Confirming the payment

When Belvo returns pse_display_needs_redirect next step, you'll need to let your customer know they'll be redirected to their banking application to continue with the payment process. To do so, you'll need to send through the confirmation of the payment intent in a PATCH Complete a payment intent request (as shown below). 

{
	"confirm": true
}

You'll receive the following response containing instructions (in the next_step object) you’ll need to follow to guide your user through the payment flow. In this case, you’ll receive a pse_display_payment_processing instruction to show that the payment is being processed. In this response, Belvo also returns the redirect_url that will redirect your customer to their banking application to complete the payment flow.

{
    "id":"e9cfd041-368c-404b-8a16-2a8db16a75b1",
...
    "next_step":{ // This is the next step in the payment flow you need to follow.
        "type":"pse_display_payment_processing",
        "pse_display_payment_processing":{
            "payer_institution":{
                "id":"045dcbe4-fc39-4d70-8eec-0808821a371f",
                "active":true,
                "country":"COL",
                "display_name":"Erebor Bank",
                "form_fields":[],
                "icon_logo":"https://statics.belvo.io/institutions/icon_logos/ereborbank.svg",
                "logo":"https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
                "name":"ereborbank",
                "primary_color":"#fdbc24",
                "text_logo":"https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
                "website":"https://www.grupoereborcolombia.com"
            }
        }
    },
    "last_error": {},
    "payment_method_details": {
        "pse": {
            "payer_institution": "045dcbe4-fc39-4d70-8eec-0808821a371f",
            "beneficiary_bank_account": "82582a40-2e75-42a5-b5e7-f593cfdbdf64",
      		"belvo_flow": false,
      		"callback_url": "https://www.acmecorp.com/checkout/3487565/success"
        }
    },
    "payment_method_information": {
        "pse": {
            "redirect_url": "https://registro.pse.com.co/PSENF/index.html?enc=g%3dVFlWpdMtZhUnTvHTWUqCVuoXsX4DAuvAwiBQAw2bIHOCrB", // The is the URL that redirects the user to their banking application.
            "provider_request_id": "eabae5ee-5a71-48a9-98be-dcc5449d8335",
            "bank_payment_id": null,
      		"end_to_end_id": "1237300520"
        }
    },
    "provider": "payments_way",
    "selected_payment_method_type": "pse",
    "status": "PROCESSING",
    "updated_at": "2023-03-10T22:18:11.062057Z"
}

📘

Webhooks notification

Belvo will send a payment intent status update webhook event to let you know the payment intent is now PROCESSING.

Check our Webhooks article for more info. 🤓

Done! 🎉 Once Belvo confirms that the payment has been processed and the money has been transferred to the beneficiary account, you'll receive:

  • a payment intent status update webhook event to inform you that the payment intent is now SUCCEEDED (or FAILED if something went wrong).
  • a new webhook called Transactions (object_created) to notify you that an actual transfer of funds from one account to another has occurred.

Check our Webhooks article for more info. 🤓

What's next? You can confirm the transfer of funds by checking the status of the payment intent and listening to the Transactions webhook.

How do you know that your payment has been completed?

Once the payment intent is processed, it’ll automatically change its status to SUCCEEDED or FAILED.

{
	"id":"e9cfd041-368c-404b-8a16-2a8db16a75b1",
...
	"next_step":{ // This is the next step in the payment flow you need to follow.
		"type":"pse_display_payment_succeeded",
		"pse_display_payment_succeeded":{
			"payer_name":"Carlos Vives",
			"payer_identifier":"1098712345",
			"payer_institution":{
				"id":"045dcbe4-fc39-4d70-8eec-0808821a371f",
				"logo":"https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
				"name":"ereborbank",
				"active":true,
				"country":"COL",
				"website":"https://www.grupoereborcolombia.com",
				"icon_logo":"https://statics.belvo.io/institutions/icon_logos/ereborbank.svg",
				"text_logo":"https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
				"form_fields":[],
				"display_name":"Erebor Bank",
				"primary_color":"#fdbc24"
			},
			"beneficiary_bank_account":{
				"id":"f3a426c2-8d1d-422c-98af-bd293aa68855",
				"holder":{
					"type":"BUSINESS",
					"information":{
						"name":"Acme Corp"
					}
				},
				"number":null,
				"institution":null
			}
		}
	},
	"last_error":{},
	"payment_method_details":{
		"pse":{
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f",
			"beneficiary_bank_account":"f3a426c2-8d1d-422c-98af-bd293aa68855",
      		"belvo_flow": false,
      		"callback_url": "https://www.acmecorp.com/checkout/3487565/success"
		}
	},
	"payment_method_information":{
		"pse":{
			"redirect_url":"https://registro.pse.com.co/PSENF/index.html?enc=g%3dVFlWpdMtZhUnTvHTWUqCVuoXsX4DAuvAwiBQAw2bIHOCrB",
			"provider_request_id":"eabae5ee-5a71-48a9-98be-dcc5449d8335",
			"bank_payment_id":"null",
      		"end_to_end_id": "1237300520"
		}
	},
	"provider":"payments_way",
	"selected_payment_method_type":"pse",
	"status":"SUCCEEDED",
	"updated_at":"2023-03-04T02:12:11.059189Z"
}

{
	"id":"e9cfd041-368c-404b-8a16-2a8db16a75b1",
...
	"failure_code": "expired",
	"failure_message": "This Payment Intent was marked as failed because its associated Payment Link was expired.",
	"next_step":{ // This is the next step in the payment flow you need to follow.
		"type":"pse_display_payment_failed",
		"pse_display_payment_failed":{
			"payer_institution":{
				"id":"045dcbe4-fc39-4d70-8eec-0808821a371f",
				"logo":"https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
				"name":"ereborbank",
				"active":true,
				"country":"COL",
				"website":"https://www.grupoereborcolombia.com",
				"icon_logo":"https://statics.belvo.io/institutions/icon_logos/ereborbank.svg",
				"text_logo":"https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
				"form_fields":[],
				"display_name":"Erebor Bank",
				"primary_color":"#fdbc24"
			}
		}
	},
	"last_error":{},
	"payment_method_details":{
		"pse":{
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f",
			"beneficiary_bank_account":"f3a426c2-8d1d-422c-98af-bd293aa68855",
      		"belvo_flow": true,
      		"callback_url": "https://www.acmecorp.com/checkout/3487565/success"
		}
	},
	"payment_method_information":{},
	"provider":"payments_way",
	"selected_payment_method_type":"pse",
	"status":"FAILED",
	"updated_at":"2022-12-22T21:17:23.566053Z"
},

We’ll also 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 request using the object_id of the transaction (which you receive in the webhook event).

{
  "id": "8828c442-eb79-404c-a813-ab3992c6d079",
  "created_at": "2023-03-04T02:13:30.775015Z",
  "created_by": "cefab866-b96b-4a9f-b6e2-9857dec88ec8",
  "amount": "350000",
  "currency": "COP",
  "description": "Awesome training Sneaker",
  "transaction_type": "INFLOW",
  "beneficiary": "f3a426c2-8d1d-422c-98af-bd293aa68855",
  "payer": {
    "bank_account": "d170b8a6-7247-47d9-84e2-4d39da01f712",
    "bank_account_information":{},
    "institution": "045dcbe4-fc39-4d70-8eec-0808821a371f"
  },
  "payment_intent": "e9cfd041-368c-404b-8a16-2a8db16a75b1",
  "customer": "c1b70f8f-b033-4891-bb38-167ea6a1c290"
}

👍

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 intent
  • how to navigate the payment intent flow
  • confirm that a payment intent is successful

👍

If you have any questions, just reach out to us out to us and we’ll help you right away. 🙂

Updated 1 day ago