PSE Avanza

PSE Avanza (Pago Seguro en Línea) is a popular online payment method in Colombia that allows customers to make secure, real-time payments directly from their bank accounts. Integrating PSE Avanza with EBANX enables merchants to offer Colombian customers a familiar and trusted way to complete online transactions, ensuring higher conversion rates and seamless payment experiences. This integration ensures a seamless checkout experience for customers while providing merchants with a reliable, secure, and localized payment solution in Colombia.

Requirements

API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters.

How it works

Customer initiates payment - At checkout, your customer selects PSE Avanza as the payment option.
Bank selection - A dropdown menu displays the list of banks retrieved from the /ws/getBankList endpoint. Customers select their preferred bank, and the corresponding bank code is used in the bank_code parameter.
Authentication & authorization - Customers are redirected to their bank’s PSE Avanza interface, where they log in and authorize the payment using their bank credentials.
Payment confirmation - Once authorized, EBANX will send you a notification of the status change for the payment.
Order fulfillment - Once payment is confirmed, you fulfill your customer order.

Instructions

Follow the steps below.

Select your environment
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
SandboxProduction
https://sandbox.ebanx.com/ws/direct
Prompt customer to choose a bank
Customer Bank Selection
To initiate a payment with PSE Avanza, customers need to select their preferred bank from a dropdown menu in your payment form. The list of banks, obtained from the /ws/getBankList endpoint, should be displayed as options in the dropdown. Once the customer selects a bank, its corresponding bank code should be assigned to the bank_code parameter for the next step of the payment process.
Parameters
- integration_key - Your EBANX integration key
- payment_type - Set to achpse
- country - Set to co (for Colombia)
Sample Request
```
// Get Bank List 
curl -X GET \
  --location 'https://sandbox.ebanxpay.com/ws/getBankList' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "your_ebanx_integration_key",
    "payment_type": "achpse",
    "country_code": "co"
  }'
```
Sample Response
```
// Bank list.
[
  {
      "code":"1815",
      "name":"ALIANZA FIDUCIARIA"
  },
  {
      "code":"1001",
      "name":"BANCO DE BOGOTA"
  },
  {
      "code":"1063",
      "name":"BANCO FINANDINA S.A. BIC"
  },
  ...
]
```
Use the bank list to prompt your customer to make a selection.
The bank_code in your payment request should be populated with code.
Define your parameters
With PSE Avanza payments, customers are redirected to a secure third-party website to complete the payment quickly and safely. To obtain this redirection link, call the ws/direct endpoint with the required parameters.
Defining API parameters
You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.

Essential parameters
- payment.payment_type_code - Specifies the payment method to be used for the transaction.
- payment.currency_code - Three-letter code of the payment currency
- payment.amount_total - Total amount to be charged.
Additional parameters
- EBANX Integration Key - Used to authenticate and authorize API requests.
- Customer Information
  - Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
  - While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
- Additional Context - Extra data for specific methods or countries.
To learn more about API parameters, please refer to the
API Reference Guide
At the API Reference Guide, select Colombia and PSE Avanza from the dropdown menus.

Sample request

Use the following example to initiate a request.

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "your_ebanx_integration_key",
    "operation": "request",
    "payment": {
        "name": "José Silva",
        "email": "josecolombia@example.com",
        "phone_number": "0405777687",
        "document_type": "CE",
        "document": "4023030074",
        "country": "co",
        "payment_type_code": "achpse",
        "bank_code": "1815", 
        "merchant_payment_code": "0x0W28D03-T01",
        "currency_code": "COP",
        "amount_total": "100"
    }
  }'

Sample response

A successful request will return a response similar to the example below. The payment.redirect_url parameter contains the link to the third-party website.

{
  "payment": {
    "hash": "5efc8aca4b12fbb7f069deca9a3cb61c18feb68415aeca4c",
    "country": "co",
    "merchant_payment_code": "0x0W28D03-T01",
    "order_number": null,
    "status": "PE",
    "status_date": null,
    "open_date": "2020-07-01 13:08:26",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "100.00",
    "amount_ext": "100.00",
    "amount_iof": "0.00",
    "currency_rate": "1.0000",
    "currency_ext": "COP",
    "due_date": "2020-07-04",
    "instalments": "1",
    "payment_type_code": "achpse",
    "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=5efc8aca4b12fbb7f069deca9a3cb61c18feb68415aeca4c",
    "pre_approved": false,
    "capture_available": null,
    "customer": {
      "document": "3809578453",
      "email": "josecolombia@example.com",
      "name": "José Silva",
      "birth_date": "null"
    },
    "single_transaction": {
      "amount_local": "0.00",
      "amount_crossborder": "100.00"
    },
    "requested_currency": "COP",
    "currency_ext_base": "COP"
  },
  "status": "SUCCESS",
  "redirect_url": "https://sandbox.ebanx.com/ws/redirect/execute?hash=5efc8aca4b12fbb7f069deca9a3cb61c18feb68415aeca4c"
}

At this stage, the payment will appear as pending (PE) in your

EBANX Dashboard

Redirect customer to the returned URL
Redirect your customer to the URL returned in the parameter redirect_url. After the redirection, your customer will be at a third-party website with all the necessary purchase details to finalize their payment securely and easily.
Testing PSE Avanza in a sandbox environment
In our Sandbox environment, we provide a PSE Avanza simulation interface to test bank transfer payments. This mock interface allows you to simulate different payment outcomes:
- Simulate Authorized = YES: Confirms the payment as successful.
- Simulate Authorized = NO: Denies the payment.
- Leave Pending: Leaves the payment in a pending state.
This simulation mimics the real production flow, where users are redirected to their Internet Banking to complete transactions, enabling you to thoroughly test authorized and unauthorized payments.
Monitor payment for status changes
Notifications
- EBANX will send a notification whenever a payment status changes.
- Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
- Learn more about Payment Notifications
Status
- After receiving a notification that status has changed, retrieve the payment status.
- When a payment is confirmed, the status will change from pending (PE) to confirmed (CO).
  If the customer does not complete the payment, the status will eventually change to cancelled (CA).
- Learn more about Retrieving Payment Status
Congratulations!
You have succesfully integrated PSE Avanza.
For more information, refer to the
Direct API reference guide

Resources

Use the following resources when testing in your sandbox environment.

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explore

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explore

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explore

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explore

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.

Requirements​

How it works​

Instructions​

Select your environment

Prompt customer to choose a bank

Customer Bank Selection​

Define your parameters

Sample request

Sample response

Redirect customer to the returned URL

Testing PSE Avanza in a sandbox environment​

Monitor payment for status changes

Congratulations!

Resources​

Sample Cards

API Reference

Mock Customer Data

Error Codes

Still need help?

Requirements

How it works

Instructions

Customer Bank Selection

Testing PSE Avanza in a sandbox environment

Resources