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
- Create a customer
- Create a payment intent
- Complete a payment intent
- 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:
- You create a payment intent by making a POST Create a new payment intent request.
- 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
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
amountandbelvo_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
falseif 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
idyou 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_errorwith 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_errorwith 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_processinginstruction to show that the payment is being processed.pse_display_confirmation_requiredinstruction 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
statusupdate webhook event to inform you that the payment intent is nowSUCCEEDED(orFAILEDif 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. 😎
Updated 2 months ago