> ## 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 (Colombia)

Localpayment permite a los comercios procesar pagos seguros en línea a través de PSE (Pagos Seguros en Línea), el sistema oficial de pagos bancarios en línea de Colombia, desarrollado por ACH (Automated Clearing House) Colombia. Esta guía describe el proceso para iniciar pagos basados ​​en PSE mediante la API de Localpayment, detallando los parámetros necesarios, el manejo de las respuestas y la interpretación de los códigos de estado para una integración perfecta con la infraestructura bancaria colombiana.

## Antes de comenzar

Asegúrate de tener:

* [Credenciales API](https://docs.localpayment.com/es/docs/api-keys-and-environments.md) válidas (token de acceso).

***

## Paso 1. Crear pago PSE

Para iniciar un pago PSE en Colombia, envía una solicitud `POST` al endpoint [Crear Payin](https://docs.localpayment.com/es/reference/payins.md) con los parámetros específicos de PSE.

### Parámetros clave de la solicitud

La solicitud requiere varios objetos clave específicos para los pagos PSE de Colombia:

| Objeto | Descripción | Requerido |
| - | - | - |
| `paymentMethod.type` | Debe ser `BankTransfer`. | ✅ |
| `paymentMethod.code` | Utiliza `1936` para PSE de Colombia. | ✅ |
| `sender` | Información del remitente para fines de cumplimiento. | ✅ |
| `merchant` | Datos del comerciante/negocio. | ✅ |
| `merchant.merchantId` | Un identificador único para tu negocio, proporcionado por el equipo de Localpayment. Se utiliza para identificar al comerciante en el sistema. | ✅ |
| `paymentMethod` | Configuración del método de pago. | ✅ |
| `amount` | Importe de la transacción. | ✅ |
| `currency` | Código de moneda de la transacción. | ✅ |
| `country` | Debe ser `COL`. | ✅ |

Consulta todos los [parámetros disponibles](https://docs.localpayment.com/es/reference/payins.md) en la solicitud.

### Ejemplo de solicitud

A continuación se muestra un ejemplo que utiliza `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"
    }
}
'
```

***

## Paso 2. Gestionar la respuesta

### Respuesta exitosa

La creación exitosa de un pago PSE incluye la URL de redireccionamiento y los detalles de la transacción:

```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": []
}
```

### Campos de respuesta clave

| Parámetro | Descripción | Caso de uso |
| - | - | - |
| `redirectUrl` | URL para redirigir al cliente al portal bancario de PSE. | Autenticación directa del cliente con el banco y procesamiento del pago. |
| `wireInstructions.referenceCode` | Código de referencia de pago único. | Mostrar al cliente para el seguimiento del pago. |
| `externalId` | Tu número de referencia original. | Conciliación interna y cotejo de pedidos. |
| `status.code` | Estado actual de la transacción (`100` = `INPROGRESS`) | Determinar los siguientes pasos en el flujo de pagos. |
| `date.creationDate` | Cuando se creó la transacción. | Análisis y seguimiento del rendimiento. |

#### Respuesta de error

Cuando falla la creación del pago PSE para Colombia, recibirás información de error específica:

```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"
        }
    ]
}
```

***

## Paso 3. Gestionar el flujo de pagos de PSE

1. **Iniciación del pago**: Redirigir al cliente a la URL de pago de PSE.
2. **Autenticación bancaria**: El cliente inicia sesión en su entorno de banca en línea.
3. **Autorización de pago**: El cliente confirma el pago a través de su interfaz bancaria.
4. **Confirmación en tiempo real**: Localpayment recibe la notificación de pago.
5. **Actualización de estado**: Tu sistema recibe un webhook con la confirmación del pago.

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

Página de inicio de sesión de Bancolombia

***

## Paso 4. Seguimiento del estado de la transacción

Supervisa el progreso de los pagos de PSE a través de estos métodos:

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real cuando cambie el estado de la transacción. Más eficiente para entornos de producción.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado de las transacciones mediante programación. Útil para sondear o recuperar notificaciones de webhook perdidas.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado de las transacciones.

### Códigos de estado comunes

La API de Localpayment proporciona varios códigos de estado para indicar el progreso y el resultado del pago en la respuesta.

| Código | Estado | Descripción |
| :- | :- | :- |
| `103` | `APPROVED` | El payin se confirmó, pero aún no se ha abonado. |
| `200` | `Completed` | El payin se ha completado. |
| `811` | `Rejected` | La cantidad solicitada es mayor o menor que los valores máximos/mínimos permitidos. |

> [!NOTE]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## Requisitos específicos de cada país

### Bancos colombianos apoyados (PSE)

Los pagos PSE son compatibles con las siguientes instituciones financieras:

> [accordion] Lista de bancos
>
> * BANCO DE BOGOTA
> * BANCO POPULAR
> * BANCO ITAU
> * BANCOLOMBIA
> * CITIBANK
> * BANCO GNB SUDAMERIS
> * BANCO BBVA COLOMBIA SA
> * DAVIBANK
> * BANCO DE OCCIDENTE
> * BANCO CAJA SOCIAL
> * BANCO AGRARIO
> * BANCO MUNDO MUJER
> * BANCO DAVIVIENDA
> * BANCO AV VILLAS
> * BANCAMIA SA
> * BANCO PICHINCHA S.A.
> * BANCOOMEVA S.A.
> * BANCO FALABELLA
> * BANCO FINANDINA SA BIC
> * BANCO SANTANDER COLOMBIA
> * BANCO COOPERATIVO COOPCENTRAL
> * BANCO SERFINANZA
> * LULO BANK
> * JP MORGAN COLOMBIA SA
> * DALE
> * CFA COOPERATIVA FINANCIERA
> * JFK COOPERATIVA FINANCIERA
> * COTRAFA CONFIAR COOPERATIVA FINANCIERA
> * BANCO UNION (antes GIROS COLTEFINANCIERA)
> * NEQUI
> * AVIPLATA
> * BAN100
> * IRIS
> * MOVII S.A.
> * UALÁ
> * NU
> * RAPPIPAY
> * ALIANZA FIDUCIARIA S.A.
> * CREZCAMOS
> * BOLD CF
> * DING

***

## Probando tu integración

### Entorno de pruebas

Utiliza el entorno de prueba para realizar las pruebas:

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

### Escenarios de prueba para Colombia

Verifica que tu integración gestione estos escenarios:

1. **Pago exitoso**: Flujo de pago completo de PSE con simulación bancaria.
2. **Autenticación bancaria**: Prueba diferentes flujos de autenticación bancaria.
3. **Caducidad del pago**: Gestionar la caducidad de la sesión de pago de forma adecuada.
4. **Fallo de autenticación**: Prueba de escenarios de inicio de sesión bancario fallidos.
5. **Actualizaciones de estado**: Gestión de webhooks y sondeo de estado.

***

## Próximos pasos

Tras implementar los pagos PSE, considera estas capacidades adicionales:

> [card] [Reembolsar la transacción](https://docs.localpayment.com/es/docs/refund-apm-payment.md)
>
> Si es necesario, puedes reembolsar el pago al cliente. Consulta la documentación para obtener más detalles.

> [card] [Revisar los detalles de la transacción](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Puedes recuperar información sobre las transacciones utilizando la API de Localpayment para obtener información detallada.


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