> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PSE（哥伦比亚）

Localpayment 使商家能够通过 PSE（Pagos Seguros en Línea，哥伦比亚官方在线支付系统，由 ACH Colombia 开发）处理安全的在线支付。本指南概述了通过 Localpayment 的 API 发起基于 PSE 的支付流程，详细说明了所需的参数、响应处理以及状态码的解读，以实现与哥伦比亚银行基础设施的无缝集成。

## 开始之前

请确保您已备好：

* 有效的 [API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌）。

***

## 步骤 1. 创建 PSE 付款

要在哥伦比亚发起 PSE 付款，请向 [创建付款](https://docs.localpayment.com/zh/reference/payins.md) endpoint 发送 `POST` 请求，并附带 PSE 特定参数。

### 关键请求参数

该请求需要几个与哥伦比亚 PSE 支付相关的关键对象：

| 对象 | 描述 | 必需的 |
| - | - | - |
| `paymentMethod.type` | 必须是 `BankTransfer`。 | ✅ |
| `paymentMethod.code` | 哥伦比亚 PSE 请使用 `1936`。 | ✅ |
| `sender` | 发件人信息，用于合规性审查。 | ✅ |
| `merchant` | 商家/企业详情。 | ✅ |
| `merchant.merchantId` | 由 Localpayment 团队提供的用于识别您企业的唯一标识符。用于在系统中识别商家。 | ✅ |
| `paymentMethod` | 支付方式配置。 | ✅ |
| `amount` | 交易金额。 | ✅ |
| `currency` | 交易货币代码。 | ✅ |
| `country` | 必须是 `COL`。 | ✅ |

查看请求中所有[可用的参数](https://docs.localpayment.com/zh/reference/payins.md)。

### 示例请求

以下是使用 `curl` 的示例：

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/ \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'content-type: application/json' \
     --data '
{
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1936",
        "flow": "REDIRECT"
    },
    "currency": "COP",
    "merchant": {
        "merchantId": "12345",
        "type": "COMPANY",
        "document": {
            "type": "NIT",
            "id": "9012754183"
        },
        "phone": {
            "countryCode": "57",
            "areaCode": "1",
            "number": "5551234"
        },
        "address": {
            "street": "Carrera 7",
            "number": "123",
            "city": "Bogotá D.C.",
            "state": "Bogotá D.C.",
            "country": "COL",
            "zipCode": "110111",
            "comment": "Edificio Torre Central, Piso 15"
        },
        "name": "TechColombia S.A.S.",
        "userReference": "TCH2026",
        "birthdate": "2000-01-01",
        "nationality": "COL"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "document": {
            "id": "9012754183",
            "type": "NIT"
        },
        "phone": {
            "countryCode": "co",
            "areaCode": "57",
            "number": "3009876543"
        },
        "address": {
            "street": "Calle 85",
            "number": "45-67",
            "city": "Bogotá D.C.",
            "state": "Bogotá D.C.",
            "country": "COL",
            "zipCode": "110221",
            "comment": "Torres del Parque, Apartamento 402"
        },
        "bank": {
            "account": {
                "type": "C"
            }
        },
        "name": "John",
        "lastname": "Doe",
        "email": "john.doe@example.com",
        "birthdate": "01/01/1990",
        "nationality": "COL",
        "userReference": "ARL_001"
    },
    "externalId": "5e73dada-522f-429d-a93e-5d5e968943ab",
    "country": "COL",
    "amount": 500,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0003",
    "comment": "Pago de suscripción anual",
    "bank": {
        "name": "BANCOLOMBIA",
        "code": "1007"
    },
    "account": {
        "type": "C",
        "number": "130069085"
    }
}
'
```

***

## 步骤 2：处理响应

### 成功响应

成功的 PSE 付款创建包括重定向 URL 和交易详情：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "transactionType": "PayIn",
    "externalId": "5e73dada-522f-429d-a93e-5d5e968943ab",
    "internalId": "3d010a7f-8826-4cdd-9a1a-976afeb2db5a",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1936",
        "flow": "REDIRECT"
    },
    "country": "COL",
    "currency": "COP",
    "amount": 500,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "COP",
        "amount": 500,
        "fxQuote": 1
    },
    "payment": {
        "currency": "COP",
        "fxQuote": 1,
        "financingFee": 0,
        "amount": 500
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "COP",
        "fxSource": 4015,
        "fxQuote": 1,
        "amount": 0,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "The payin is pending the confirmation"
    },
    "merchant": {
        "merchantId": "12345",
        "type": "COMPANY",
        "name": "TechColombia S.A.S."
    },
    "payer": {
        "bank": {
            "code": "1007"
        },
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "NIT",
            "id": "9012754183"
        },
        "email": "john.doe@example.com",
        "phone": {
            "countryCode": "co",
            "areaCode": "57",
            "number": "3009876543"
        },
        "address": {
            "street": "Calle 85",
            "city": "Bogotá D.C.",
            "state": "Bogotá D.C.",
            "country": "COL",
            "comment": "Torres del Parque, Apartamento 402"
        }
    },
    "intermediaries": [],
    "wireInstructions": {
        "referenceCode": "TB7X-UHSD-5JAL"
    },
    "date": {
        "creationDate": "2024-12-05T21:16:07.692+00:00",
        "processedDate": "2024-12-05T21:16:11.1682535",
        "expirationDate": "2024-12-12T21:16:10.6082303"
    },
    "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aHR0cHM6Ly9yZWdpc3Ryby5kZXNhcnJvbGxvLnBzZS5jb20uY28vUFNFTkYvaW5kZXguaHRtbD9lbmM9djF3Z0olMmZHd2phN0pwWDRjQ1dTJTJiallDVWVJRW94U3FqcFlROGtBT0tvN0ElM2Q",
    "errors": []
}
```

### 关键响应字段

| 参数 | 描述 | 用例 |
| - | - | - |
| `redirectUrl` | 将客户重定向到 PSE 银行门户网站的 URL。 | 直接对接银行进行客户身份验证和支付处理。 |
| `wireInstructions.referenceCode` | 唯一付款参考代码。 | 向客户显示付款跟踪信息。 |
| `externalId` | 您的原始参考编号。 | 内部核对和订单匹配。 |
| `status.code` | 当前交易状态（`100` = `INPROGRESS`） | 确定付款流程的后续步骤。 |
| `date.creationDate` | 交易创建时。 | 分析和绩效跟踪。 |

#### 错误响应

如果哥伦比亚的 PSE 付款创建失败，您将收到具体的错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "ce0aaa1a-4532-43b9-930a-26e780aba99b",
    "status": {
        "code": "812",
        "description": "REJECTED"
    },
    "errors": [
        {
            "code": "812",
            "detail": "External Id already used - duplication"
        }
    ]
}
```

***

## 步骤 3. 处理 PSE 付款流程

1. **发起支付**：将客户重定向到 PSE 支付网址。
2. **银行认证**：客户登录其网上银行环境。
3. **付款授权**：客户在其银行界面确认付款。
4. **实时确认**：Localpayment 收到付款通知。
5. **状态更新**：您的系统已收到包含付款确认信息的 webhook。

![](https://mintcdn.com/localpayment-1fee3d41/thasGykLOKju8tM0/images/docs/2406546564c4657c5a0a46e11681d2c812e33fb63c4fe9215a4c8f51aaab02fa-image.png?fit=max\&auto=format\&n=thasGykLOKju8tM0\&q=85\&s=0ede32412724e5c03e269bcb7df77baa)

Bancolombia 登录页面

***

## 第四步：跟踪交易状态

通过以下方式监控 PSE 付款进度：

> [card] [Webhooks（推荐）](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 交易状态变更时接收实时通知。最适用于生产环境。

> [card] [状态 API endpoint](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 以编程方式查询交易状态。可用于轮询或恢复丢失的 webhook 通知。

> [card] [Business Portal 视图](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常用状态码

Localpayment API 提供各种状态代码，以在响应中指示付款的进度和结果。

| 代码 | 状态 | 描述 |
| :- | :- | :- |
| `103` | `APPROVED` | 付款已确认，但尚未到账。 |
| `200` | `Completed` | 付款已完成。 |
| `811` | `Rejected` | 请求金额高于或低于允许的最大/最小值。 |

> [!NOTE]
>
> **完整参考**
>
> 请查看我们的[交易状态文档](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)，了解所有状态代码。

***

## 各国具体要求

### 支持的哥伦比亚银行（PSE）

以下金融机构支持 PSE 支付：

> [accordion] 银行列表
>
> * BANCO DE BOGOTA
> * BANCO POPULAR
> * BANCO ITAU
> * BANCOLOMBIA
> * 花旗银行
> * 苏达梅里斯GNB银行
> * 哥伦比亚 BBVA 银行
> * DAVIBANK
> * 西方银行
> * BANCO CAJA SOCIAL
> * BANCO AGRARIO
> * BANCO MUNDO MUJER
> * BANCO DAVIVIENDA
> * BANCO AV VILLAS
> * BANCAMIA S.A.
> * BANCO PICHINCHA S.A.
> * BANCOOMEVA S.A.
> * 法拉贝拉银行
> * BANCO FINANDINA S.A. BIC
> * BANCO SANTANDER COLOMBIA
> * 中央合作银行
> * BANCO SERFINANZA
> * LULO 银行
> * 摩根大通哥伦比亚公司
> * DALE
> * CFA COOPERATIVA FINANCIERA
> * JFK COOPERATIVA FINANCIERA
> * COTRAFA CONFIAR COOPERATIVA FINANCIERA
> * 联合银行（原 GIROS COLTEFINANCIERA）
> * NEQUI
> * AVIPLATA
> * BAN100
> * IRIS
> * MOVII S.A.
> * UALÁ
> * NU
> * RAPPIPAY
> * ALIANZA FIDUCIARIA S.A.
> * CREZCAMOS
> * BOLD CF
> * DING

***

## 测试您的集成

### 沙盒环境

使用测试环境：

```
https://api.stage.localpayment.com/api/payin/
```

### 哥伦比亚测试场景

请确认您的集成方案能够处理以下场景：

1. **支付成功**：完成 PSE 支付流程的银行模拟。
2. **银行认证**：测试不同的银行认证流程。
3. **支付过期**：妥善处理支付会话过期。
4. **身份验证失败**：测试银行登录失败场景。
5. **状态更新**：Webhook 处理和状态轮询。

***

## 后续步骤

实施 PSE 支付后，请考虑以下附加功能：

> [card] [退款](https://docs.localpayment.com/zh/docs/refund-apm-payment.md)
>
> 如有必要，您可以将款项退还给客户。详情请参阅相关文档。

> [card] [查看交易详情](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 您可以使用 Localpayment API 获取交易信息，以获得更详细的分析。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.