PSE

PSE is a real-time online bank transfer payment method in Colombia. At checkout, the customer selects the name of their bank and logs in to their online banking environment. They review the pre-populated payment details, authorize the payment, and then wait for the purchase to arrive.

This guide provides instructions for PSE payments, including request examples, redirection handling, and notification processing.

Requirements

Before you integrate PSE, you need to:

Generate an access token through the Authentication endpoint.
Configure a public HTTPS callback_url that receives status updates after customers complete the transaction.
Call the banklookup endpoint to get the list of active banks to display to the customer.

Important: PSE is only available in Colombia and expects COP currency.

Use case specifics

When you integrate PSE through Getnet, specific market requirements apply. Before you go live, review the resources below to learn about the specific requirements of Colombia:

Characteristics

The table below summarizes the behavior and requirements for PSE payments.

Capability	Details
Customer interaction	Customer selects a bank, is redirected to the PSE/bank portal, logs in, and authorizes the payment.
Confirmation	Asynchronous: initial `PENDING` status, then `APPROVED` or `DECLINED` via webhook.
Notifications	You need webhooks to confirm the final status of the transaction.

Available features

Use the matrix below to confirm the scenarios currently supported for PSE.

Payment flow	Supported countries	Purchases	Refunds	Partial refunds	Multiple refunds	Pre-authorizations
Redirect	Colombia	✅	❌	❌	❌	❌

Payment flow

This section guides you through the complete process of implementing PSE payments. The diagram below provides an overview of the PSE payment process:

Supported flow

This is the payment flow currently supported by Getnet:

PSE Transfer (INSTANT_TRANSFER): The user selects their bank and is redirected to authorize the debit. The flow is redirect-based.

Important: This operation is asynchronous; the final state is only confirmed when Getnet receives the webhook.

1. Fetch the bank list

Before you initiate the payment, you must retrieve the current list of participating financial institutions to display to the customer.

Request to retrieve available banks:

bash

curl --location --request GET 'https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/banklookup' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json'

bash

curl --location --request GET 'https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/banklookup' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json'

Example response:

json

{
  "banks": [
    {
      "name": "BANCO DE BOGOTA",
      "code": "1039"
    },
    {
      "name": "BANCO DAVIVIENDA",
      "code": "1051"
    },
    {
      "name": "BANCO UNION COLOMBIANO",
      "code": "1022"
    }
  ]
}

json

{
  "banks": [
    {
      "name": "BANCO DE BOGOTA",
      "code": "1039"
    },
    {
      "name": "BANCO DAVIVIENDA",
      "code": "1051"
    },
    {
      "name": "BANCO UNION COLOMBIANO",
      "code": "1022"
    }
  ]
}

Important: Capture the code for the selected bank (for example: 1022) to use in the subsequent payment request.

2. Create the payment request

To initiate a payment, call the Create - Authorize endpoint.

You must specify WALLET as the payment method and provide the brand as PSE. You must pass the user's selected bank code in additional_data.

The following table outlines the minimum fields required for a PSE payment.

Attribute	Description	Required value
`payment_method`	Payment method identifier	`WALLET`
`brand`	Brand identifier	`PSE`
`amount`	Transaction amount in cents	Integer (e.g. `400` for $4.00)
`currency`	ISO currency code	`COP`
`payment.instant_transfer.bank_code`	Selected bank code	String (e.g., `1022`)
`customer.document_type`	Customer's ID type	`CC`, `NIT`, etc.
`customer.document_number`	Customer's ID number	String
`customer.email`	Customer email	Valid email address

PSE request example

bash

curl --location --request POST 'https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
    "idempotency_key": "uuid-pse-v2-unique",
    "request_id": "req-id-v2-unique",
    "order_id": "1234123423128",
    "data": {
        "amount": 400,
        "currency": "COP",
        "customer_id": "customer-uuid",
        "payment": {
            "instant_transfer": {
                "bank_code": "1022"
            },
            "payment_id": "payment-uuid",
            "payment_method": "WALLET",
            "brand": "PSE",
            "soft_descriptor": "PSE TEST"
        },
        "additional_data": {
            "callback_url": "https://your-store.com/webhooks/pse",
            "customer": {
                "email": "customer@email.com",
                "document_number": "50506468",
                "document_type": "NIT",
                "name": "Jose da Silva",
                "phone_number": "34700000000",
                "billing_address": {
                    "street": "Avenida Siempre Viva",
                    "number": "123",
                    "city": "Bogota",
                    "state": "DC",
                    "country": "CO",
                    "postal_code": "110111"
                }
            }
        }
    }
}'

bash

curl --location --request POST 'https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
    "idempotency_key": "uuid-pse-v2-unique",
    "request_id": "req-id-v2-unique",
    "order_id": "1234123423128",
    "data": {
        "amount": 400,
        "currency": "COP",
        "customer_id": "customer-uuid",
        "payment": {
            "instant_transfer": {
                "bank_code": "1022"
            },
            "payment_id": "payment-uuid",
            "payment_method": "WALLET",
            "brand": "PSE",
            "soft_descriptor": "PSE TEST"
        },
        "additional_data": {
            "callback_url": "https://your-store.com/webhooks/pse",
            "customer": {
                "email": "customer@email.com",
                "document_number": "50506468",
                "document_type": "NIT",
                "name": "Jose da Silva",
                "phone_number": "34700000000",
                "billing_address": {
                    "street": "Avenida Siempre Viva",
                    "number": "123",
                    "city": "Bogota",
                    "state": "DC",
                    "country": "CO",
                    "postal_code": "110111"
                }
            }
        }
    }
}'

The response contains the redirect_url. Use it to redirect the customer to the PSE portal.

json

{
  "payment_id": "47b9163c-64f3-41d1-8bd2-69512b9c1419",
  "status": "PENDING",
  "payment_method": "WALLET",
  "redirect_url": "https://gateway.pse.com.co/redirect/token-xyz",
  "reason_message": "Waiting for bank authorization."
}

json

{
  "payment_id": "47b9163c-64f3-41d1-8bd2-69512b9c1419",
  "status": "PENDING",
  "payment_method": "WALLET",
  "redirect_url": "https://gateway.pse.com.co/redirect/token-xyz",
  "reason_message": "Waiting for bank authorization."
}

3. User experience

After you redirect the customer, the payment continues on the PSE side:

The user is redirected to the PSE page.

The user enters their email.
The user is redirected to their bank to complete the deposit. You receive a payment notification.

4. Verify payment status

When the customer completes the payment, your configured callback_url receives a webhook notification with the updated payment status (APPROVED or DECLINED).

Important: Always rely on the webhook for the final status, as the customer might close the browser before returning to your site.

Business rules

The following rules apply to PSE payments:

payment_method must be WALLET.
brand must be PSE.
Currencies supported: COP.
Payment is an asynchronous operation.
Refunds: Not supported for this payment method.
Bank selection: The bank_code is mandatory and must come from the banklookup endpoint.

See the following page for more information:

Authentication for token management.

On this page

PSE

Ecommerce

Card Present

Reference

Webhooks

PSE

Requirements

Use case specifics

Characteristics

Available features

Payment flow

Supported flow

1. Fetch the bank list

2. Create the payment request

3. User experience

4. Verify payment status

Business rules

Read more