> ## 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 (Colômbia)

A Localpayment permite que comerciantes processem pagamentos online seguros através do PSE (Pagos Seguros en Línea), o sistema oficial de pagamentos bancários online da Colômbia, desenvolvido pela ACH (Automated Clearing House) Colombia. Este guia descreve o processo para iniciar pagamentos via PSE por meio da API da Localpayment, detalhando os parâmetros obrigatórios, o tratamento das respostas e a interpretação dos códigos de status para uma integração sem complicações com a infraestrutura bancária da Colômbia.

## Antes de começar

Certifique-se de ter:

* [Credenciais de API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md) válidas (token de acesso).

***

## Etapa 1. Criar pagamento PSE

Para iniciar um pagamento PSE na Colômbia, envie uma solicitação `POST` ao endpoint [Criar Payin](https://docs.localpayment.com/pt-br/reference/payins.md) com os parâmetros específicos do PSE.

### Parâmetros-chave da solicitação

A solicitação requer vários objetos-chave específicos para pagamentos PSE na Colômbia:

| Objeto | Descrição | Obrigatório |
| - | - | - |
| `paymentMethod.type` | Deve ser `BankTransfer`. | ✅ |
| `paymentMethod.code` | Use `1936` para o PSE da Colômbia. | ✅ |
| `sender` | Informações do remetente para fins de conformidade. | ✅ |
| `merchant` | Detalhes do comerciante/empresa. | ✅ |
| `merchant.merchantId` | Um identificador único para sua empresa, fornecido pela equipe da Localpayment. Usado para identificar o comerciante no sistema. | ✅ |
| `paymentMethod` | Configuração do método de pagamento. | ✅ |
| `amount` | Valor da transação. | ✅ |
| `currency` | Código da moeda da transação. | ✅ |
| `country` | Deve ser `COL`. | ✅ |

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/payins.md) na solicitação.

### Exemplo de solicitação

Abaixo está um exemplo usando `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"
    }
}
'
```

***

## Etapa 2. Lidar com a resposta

### Resposta bem-sucedida

A criação bem-sucedida de um pagamento PSE inclui o URL de redirecionamento e os detalhes da transação:

```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 resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `redirectUrl` | URL para redirecionar o cliente ao portal bancário da PSE. | Autenticação direta do cliente ao banco e processamento de pagamentos. |
| `wireInstructions.referenceCode` | Código de referência de pagamento único. | Exibir para o cliente para fins de rastreamento de pagamento. |
| `externalId` | Seu número de referência original. | Conciliação interna e correspondência de pedidos. |
| `status.code` | Estado atual da transação (`100` = `INPROGRESS`) | Determine os próximos passos no fluxo de pagamento. |
| `date.creationDate` | Quando a transação foi criada. | Análise e monitoramento de desempenho. |

#### Resposta de erro

Quando a criação de um pagamento PSE para a Colômbia falhar, você receberá informações de erro específicas:

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

***

## Etapa 3. Gerenciar o fluxo de pagamento PSE

1. **Iniciação de pagamento**: Redirecionar o cliente para o URL de pagamento da PSE.
2. **Autenticação bancária**: O cliente acessa seu ambiente de banco online.
3. **Autorização de pagamento**: O cliente confirma o pagamento em sua interface bancária.
4. **Confirmação em tempo real**: o Localpayment recebe a notificação de pagamento.
5. **Atualização de status**: Seu sistema recebeu um webhook com a confirmação de pagamento.

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

Página de login do Bancolombia

***

## Etapa 4. Acompanhe o status da transação

Acompanhe o progresso dos pagamentos do PSE por meio destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Códigos de status comuns

A API Localpayment fornece vários códigos de status para indicar o progresso e o resultado do pagamento na resposta.

| Código | Status | Descrição |
| :- | :- | :- |
| `103` | `APPROVED` | O Payin foi confirmado, mas ainda não foi creditado. |
| `200` | `Completed` | O Payin foi concluído. |
| `811` | `Rejected` | O valor solicitado é maior ou menor que os valores máximo/mínimo permitidos. |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Requisitos específicos de cada país

### Bancos colombianos apoiados (PSE)

Os pagamentos PSE são suportados pelas seguintes instituições financeiras:

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

***

## Testando sua integração

### Ambiente de Sandbox

Utilize o ambiente de teste para realizar os procedimentos:

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

### Cenários de teste para a Colômbia

Verifique se sua integração lida com esses cenários:

1. **Pagamento bem-sucedido**: Fluxo completo de pagamento PSE com simulação bancária.
2. **Autenticação bancária**: Teste diferentes fluxos de autenticação bancária.
3. **Expiração do pagamento**: Gerencie a expiração da sessão de pagamento de forma adequada.
4. **Falha na autenticação**: teste cenários de falha no login bancário.
5. **Atualizações de status**: gerenciamento de webhooks e consulta de status.

***

## Próximos passos

Após implementar os pagamentos PSE, considere estas funcionalidades adicionais:

> [card] [Reembolsar a transação](https://docs.localpayment.com/pt-br/docs/refund-apm-payment.md)
>
> Caso necessário, você pode reembolsar o pagamento ao cliente. Consulte a documentação para obter detalhes.

> [card] [Analisar detalhes da transação](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Você pode obter informações detalhadas sobre as transações usando a API Localpayment.


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