PSE Payment intents: new customers

Collect payments in πŸ‡¨πŸ‡΄Β  Colombia from first-time customers using a Belvo-integrated institution.

This guide will walk you through the process of collecting payments for first-time customers using Belvo's Open Payments API.

PSE Flow

  1. Create a customer
  2. Create a payment intent
  3. Complete a payment intent
  4. Get notified of collected payments

πŸ“˜

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 for new customers

Payment intent flow for new customers

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
      		"belvo_flow": true,	// Optional field - This parameter set to true (default) creates the payment intent using the Belvo flow. 
			"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",
      		"belvo_flow": true,
			"callback_url": "https://www.acmecorp.com/checkout/3487565/success"
		}
	},
	"provider": "payments_way"
}

πŸ“˜

Additional info about amount and belvo_flow

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.

belvo_flow(optional)

You can set this parameter to false if you want to create a payment intent using the non-Belvo flow. Check our PSE Payment intents: inflow payments (non-Belvo flow) guide for more info.Β πŸ™‚

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": true,
      		"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"
}
{
  "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", // This institution requires you to send through the username_type 
              "type": "select",
              "values": [
                {
                  "code": "CC",
                  "label": "CΓ©dula de CiudadanΓ­a",
                  "validation": "^[0-9]{1,10}$",
                  "placeholder": "Ej. 1057770599",
                  "validation_message": "Requiere entre 1 y 10 dΓ­gitos."
                },
                {
                  "code": "TI",
                  "label": "Tarjeta de Identidad",
                  "validation": "^[0-9]{11}$",
                  "placeholder": "Ej. 93309214440",
                  "validation_message": "Requiere 11 dΓ­gitos."
                },
                {
                  "code": "CE",
                  "label": "CΓ©dula de ExtranjerΓ­a",
                  "validation": "^[0-9]{6,7}$",
                  "placeholder": "Ej. 143898",
                  "validation_message": "Requiere entre 6 y 7 dΓ­gitos."
                },
                {
                  "code": "NITN",
                  "label": "NIT Persona Natural",
                  "validation": "^[0-9]{1,15}$",
                  "placeholder": "Ej. 1029350589",
                  "validation_message": "Requiere entre 1 y 15 dΓ­gitos."
                },
                {
                  "code": "NITE",
                  "label": "NIT Persona Extranjera",
                  "validation": "^.{1,}$",
                  "placeholder": "NΓΊmero de identificaciΓ³n.",
                  "validation_message": "Credenciales incorrectas."
                },
                {
                  "code": "NITJ",
                  "label": "NIT Persona JurΓ­dica",
                  "validation": "^.{1,}$",
                  "placeholder": "NΓΊmero de identificaciΓ³n.",
                  "validation_message": "Credenciales incorrectas."
                },
                {
                  "code": "RC",
                  "label": "Registro Civil",
                  "validation": "^[0-9]{11}$",
                  "placeholder": "Ej. 9650199510",
                  "validation_message": "Requiere 11 dΓ­gitos."
                }
              ],
              "placeholder": "Tipo de documento",
              "pre_selected": "0"
            },
            {
              "name": "username",
              "type": "text",
              "label": "NΓΊmero de identificaciΓ³n",
              "dependency": "username_type", // Indicates that for username, you must also send through the username_type.
              "validation": "^.{1,}$",
              "placeholder": "NΓΊmero de identificaciΓ³n",
              "validation_message": "Credenciales incorrectas"
            },
            {
              "name": "password",
              "type": "password",
              "label": "Clave segura",
              "validation": "^\\d{4}$",
              "placeholder": "****",
              "validation_message": "Requiere 4 dΓ­gitos"
            },
            {
              "name": "token",
              "type": "number",
              "label": "Token",
              "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": true,
      "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_credentials_required instruction with information about the institution that you need to display to your user so they can enter their credentials.

{
	"id": "e9cfd041-368c-404b-8a16-2a8db16a75b1",
 ...
	"next_step":{   // This is the next step in the payment flow you need to follow.
		"type": "pse_display_credentials_required",
		"pse_display_credentials_required":{
			"payer_institution":{
				"id": "045dcbe4-fc39-4d70-8eec-0808821a371f",
				"active": true,
				"country": "COL",
				"display_name":"Erebor Bank",
				"form_fields":[], // Pay special attention to the form fields. If username_type is required, you'll need to ask your user to input their username_type.ur
				"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":{
      		"belvo_flow": true,
      		"callback_url": "https://www.acmecorp.com/checkout/3487565/success",
			"beneficiary_bank_account":"82582a40-2e75-42a5-b5e7-f593cfdbdf64",
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f"
		}
	},
	"payment_method_information":{},
	"provider": "payments_way",
	"selected_payment_method_type": "pse",
	"status": "REQUIRES_PAYMENT_METHOD",
	"updated_at":"2023-03-03T19:42:38.569590Z"
}

πŸ“˜

Belvo stores this information so you don’t have to send it again for a customer’s subsequent payments. 😎 You can check our PSE Payment intents: subsequent payments guide for more info.

Sending the credentials

When Belvo returns pse_display_credentials_required next step, you'll need to ask your customer to input their credentials. Once they've provided their credentials, you'll need to send through this information in a PATCH Complete a payment intent request (as shown below).

πŸ“˜

Belvo encrypts these credentials and only use them to access the account in read-only mode.

{
	"payment_method_details":{
		"pse":{
			"username": "username",
			"password": "password"
		}
	}
}
{
	"payment_method_details":{
		"pse":{
      "username_type": "One of the allowed username_types listed in the institution form_fields",
			"username": "username",
			"password": "password"
		}
	}
}

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_token_required instruction with information about the institution that you need to display to your user so they can send the MFA token required by the institution.

{
	"id": "e9cfd041-368c-404b-8a16-2a8db16a75b1",
...
	"next_step":{  // This is the next step in the payment flow you need to follow.
		"type": "pse_display_token_required",
		"pse_display_token_required":{
			"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"
			}
		},
		"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":{
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f",
			"beneficiary_bank_account":"82582a40-2e75-42a5-b5e7-f593cfdbdf64",
			"username":"***", // This value is masked.
			"password":"***", // This value is masked.
      		"belvo_flow": true,
      		"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:48:56.360224Z"
}

If something wrong happens when you send through your user's credentials, Belvo will return a different next step with instructions you’ll need to follow to guide your user back to the payment flow.

  • pse_display_credentials_required: the credentials provided by the customer are invalid and you need to ask them to send the credentials again.
  • pse_display_payment_method_information: there was an unexpected error during the payment process and the customer needs to start the payment flow from the beginning.

πŸ“˜

Encountering last errors

If something doesn’t go well during the payment process, Belvo returns a last_error with information about what caused the error.

You can check our last encountered errors article for detailed info and possible solutions.

Sending the MFA token

When Belvo returns pse_display_token_required next step, you'll need to ask your customer to provide the MFA token required by the institution. Once they've sent the token, you'll need to send through the token in a PATCH Complete a payment intent request (as shown below).

{
	"payment_method_details":{
		"pse":{
			"payer_token": "123456"
		}
	}
}

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_customer_bank_accounts instruction with a list of bank accounts that you need to display to your user for them to select from.

{
	"id":"e9cfd041-368c-404b-8a16-2a8db16a75b1",
...
	"next_step":{   // This is the next step in the payment flow you need to follow.
		"type":"pse_display_customer_bank_accounts",
		"pse_display_customer_bank_accounts":{
			"beneficiary_bank_account":{
				"id": "82582a40-2e75-42a5-b5e7-f593cfdbdf64",
				"institution":null,
				"number":null,
				"holder":{
					"type":"BUSINESS",
					"information":{
						"name": "ACME Corp"
					}
				}
			},
			"customer_bank_accounts":[
				{
					"id":"f3a426c2-8d1d-422c-98af-bd293aa68855",
					"customer":"c1b70f8f-b033-4891-bb38-167ea6a1c290",
					"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"
					},
					"number": "******1234", // This value is masked.
					"holder":{
						"type":"INDIVIDUAL",
						"information":{
							"first_name":"Carlos",
							"last_name":"Vives"
						}
					},
					"details":{
						"country":"COL",
						"account_type": "Ahorros - Cuenta de Ahorro"
					}
				}
			]
		},
		"ready_to_confirm": true, // When set to true, it means you can confirm the payment intent in the PATH request.
	},
	"last_error":{},
	"payment_method_details":{
		"pse":{
			"password":"***", // This value is masked.
			"username":"***", // This value is masked.
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f",
			"beneficiary_bank_account":"82582a40-2e75-42a5-b5e7-f593cfdbdf64",
			"payer_token":"***", // This value is masked.
      		"belvo_flow": true,
      		"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:56:21.235271Z"
}

πŸ“˜

The response returns "ready_to_confirm": true, which means that the payment intent is ready to be processed. You can choose to send through the confirmation in the Selecting payer account step or in a later request.

If something wrong happens when you send through your user's token, Belvo will return a different next step with instructions you’ll need to follow to guide your user back to the payment flow.

  • pse_display_token_required: the token provided by the customer is invalid and you need to ask them to send a token again.
  • pse_display_payment_method_information: there was an unexpected error during the payment process and the customer needs to start the payment flow from the beginning.

πŸ“˜

Encountering last errors

If something doesn’t go well during the payment process, Belvo returns a last_error with information about what caused the error.

You can check our last encountered errors article for detailed info and possible solutions.

Selecting the payer account

When Belvo returns pse_display_customer_bank_accounts next step, you'll need to display a list of bank accounts to your user for them to select. Once they’ve selected the bank account they want to pay with, you’ll need to send through that bank account in a PATCH Complete a payment intent request. Here you can choose whether you want to confirm the payment intent in this step or in a later request (as shown below).

{
	"payment_method_details": {
		"pse": {
			"payer_bank_account": "f3a426c2-8d1d-422c-98af-bd293aa68855"
		}
	},
 "confirm": true, // you'll process the payment by sending through this parameter set to true.
}
{
	"payment_method_details": {
		"pse": {
			"payer_bank_account": "f3a426c2-8d1d-422c-98af-bd293aa68855"
		}
	}
}

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. Depending on whether you confirmed the payment intent or not in this step, you’ll receive a:

  • pse_display_payment_processing instruction to show that the payment is being processed.
  • pse_display_confirmation_required instruction to show that the payment is confirmed.
{
	"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":{
			"password":"***",  // This value is masked.
			"username":"***",  // This value is masked.
			"payer_token":"***",  // This value is masked.
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f",
			"beneficiary_bank_account":"f3a426c2-8d1d-422c-98af-bd293aa68855",
			"payer_bank_account":"d170b8a6-7247-47d9-84e2-4d39da01f712",
      		"belvo_flow": true,
      		"callback_url": "https://www.acmecorp.com/checkout/3487565/success"
		}
	},
	"payment_method_information":{
		"pse":{
			"redirect_url":"https://pse.com/Ereborbank/control/ElectronicPayment.ereborbank?PAYMENT_ID=456213985641233659874512459842",
			"provider_request_id":"eabae5ee-5a71-48a9-98be-dcc5449d8335",
			"bank_payment_id":"456213985641233659874512459842",
      		"end_to_end_id": "1237300520"
		}
	},
	"provider":"payments_way",
	"selected_payment_method_type":"pse",
	"status":"PROCESSING",
	"updated_at":"2023-03-04T02:12:11.059189Z"
}
{
	"id":"e9cfd041-368c-404b-8a16-2a8db16a75b1",
...
	"next_step":{ // This is the next step in the payment flow you need to follow.
		"type":"pse_display_confirmation_required",
		"pse_display_confirmation_required":{
			"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":"bancolombia",
				"primary_color":"#fdbc24",
				"text_logo":"https://statics.belvo.io/institutions/text_logos/ereborbank.svg",
				"website":"https://www.grupoereborcolombia.com"
			}
		},
		"ready_to_confirm":true
	},
	"last_error":{},
	"payment_method_details":{
		"pse":{
			"password":"***", // This value is masked.
			"username":"***", // This value is masked.
			"payer_token":"***", // This value is masked.
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f",
			"beneficiary_bank_account":"f3a426c2-8d1d-422c-98af-bd293aa68855",
			"payer_bank_account":"d170b8a6-7247-47d9-84e2-4d39da01f712",
      		"belvo_flow": true,
      		"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:57:04.227298Z"
}

πŸ“˜

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. πŸ€“

(Optional) Confirm the payment intent

If you didn't send the confirmation in the Selecting payer account step, Belvo returns a pse_display_confirmation_required next step. This means that you'll need to send through the confirmation alone 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_confirmation_required instruction to show that the payment is confirmed.

{
	"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":{
			"password":"***",  // This value is masked.
			"username":"***",  // This value is masked.
			"payer_token":"***",  // This value is masked.
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f",
			"beneficiary_bank_account":"f3a426c2-8d1d-422c-98af-bd293aa68855",
			"payer_bank_account":"d170b8a6-7247-47d9-84e2-4d39da01f712",
      		"belvo_flow": true,
      		"callback_url": "https://www.acmecorp.com/checkout/3487565/success"
		}
	},
	"payment_method_information":{
		"pse":{
			"redirect_url":"https://pse.com/Ereborbank/control/ElectronicPayment.ereborbank?PAYMENT_ID=456213985641233659874512459842",
			"provider_request_id":"eabae5ee-5a71-48a9-98be-dcc5449d8335",
			"bank_payment_id":"456213985641233659874512459842",
      		"end_to_end_id": "1237300520"
		}
	},
	"provider":"payments_way",
	"selected_payment_method_type":"pse",
	"status":"PROCESSING",
	"updated_at":"2023-03-04T02:12:11.059189Z"
}

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 (as shown below).

{
	"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":{
			"password":"***", // This value is masked.
			"username":"***", // This value is masked.
			"payer_token":"***", // This value is masked.
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f",
			"beneficiary_bank_account":"f3a426c2-8d1d-422c-98af-bd293aa68855",
			"payer_bank_account":"d170b8a6-7247-47d9-84e2-4d39da01f712",
      		"belvo_flow": true,
      		"callback_url": "https://www.acmecorp.com/checkout/3487565/success"
		}
	},
	"payment_method_information":{
		"pse":{
			"redirect_url":"https://pse.com/Ereborbank/control/ElectronicPayment.ereborbank?PAYMENT_ID=456213985641233659874512459842",
			"provider_request_id":"eabae5ee-5a71-48a9-98be-dcc5449d8335",
			"bank_payment_id":"456213985641233659874512459842",
      		"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":{
			"password":"***", // This value is masked.
			"username":"***", // This value is masked.
			"payer_token":"***", // This value is masked.
			"payer_institution":"045dcbe4-fc39-4d70-8eec-0808821a371f",
			"beneficiary_bank_account":"f3a426c2-8d1d-422c-98af-bd293aa68855",
			"payer_bank_account":"d170b8a6-7247-47d9-84e2-4d39da01f712",
      		"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. πŸ™‚

What’s next?

After your customer makes their first payment, Belvo stores the payment intent information so that the payment flow for subsequent payments is much simpler. Check our PSE Payment intents: subsequent payments guide for more information. 😎