# 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 simply wait for the purchase to arrive.
This guide provides instructions for PSE payments, including request examples, redirection handling, and notification processing.
## Requirements
Before integrating PSE you need to:
* Generate an access token through the [Authentication endpoint](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/authentication).
* Configure a public HTTPS `callback_url` that receives status updates after customers complete the transaction.
* Bank List Retrieval: Call the banklookup endpoint to obtain the list of active banks to display to the customer.
PSE is only available in Colombia and expects **COP** currency.
## Use Cases Specifics
When integrating PSE via Getnet, specific market requirements apply. To know more about the specific requirements of Colombia, be sure to review the resources below before you go live:
* [Currency codes](https://docs.globalgetnet.com/en/articles?article=currency-codes)
* [Document types](https://docs.globalgetnet.com/en/articles?article=document-types)
* [Local taxes and regulations](https://docs.globalgetnet.com/en/articles?article=taxes-and-regulations)
## Characteristics
The table below summarizes the behavior and requirements for PSE payments.
| Capability | Details |
| :----------------------- | :------------------------------------------------------------------------------------ |
| **Customer interaction** | Customer selects bank, redirects to PSE/Bank portal, logs in, and authorizes payment. |
| **Confirmation** | Asynchronous: initial `PENDING` status, then `APPROVED` or `DECLINED` via webhook. |
| **Notifications** | Webhooks are required 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`):** User selects their bank and is redirected to authorize the debit. Flow is **redirect-based**.
This operation is asynchronous; the final state is only confirmed when Getnet receives the webhook.
## 1. Fetching the bank list
Before initiating 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 ' \
--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"
}
]
}
```
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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments/post/dpm/payments-gwproxy/v2/payments).
You must specify `WALLET` as the payment method and provide the `brand` as `PSE`. The user's selected bank code must be passed in `additional_data`.
The 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 ' \
--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`, which **must be used 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."
}
```
## 2. User Experience
1. The user is redirected to the PSE page.
1. The user enters their email.
2. The user is redirected to their bank to complete the deposit. A payment notification is received.
## 3. Verify payment status
When the customer completes the payment, a webhook notification is sent to your configured `callback_url` with the updated payment status (`APPROVED` or `DECLINED`).
Always rely on the webhook for the final status, as the customer might close the browser before returning to your site.
## Business Rules
* `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 be sourced from the banklookup endpoint.
## Read more
* [Authentication](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dauthentication) for token management.