> ## 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.

# ETPAY (Chile)

A Localpayment permite que os comerciantes processem pagamentos seguros por transferência bancária por meio do ETPAY, o principal gateway de pagamentos do Chile, que viabiliza transferências bancárias diretas e a autenticação junto às principais instituições financeiras chilenas. Este guia descreve o processo para iniciar pagamentos baseados em ETPAY 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 do Chile.

## 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).
* Consulte os [limites e regras para transações bancárias](https://docs.localpayment.com/pt-br/docs/chile.md#payins-banking-transaction-limits-and-rules).

> [!WARNING]
>
> **Somente pagamentos individuais (Perfis de Home Banking) são suportados.**
>
> Este método de pagamento aceita apenas pagamentos de contas bancárias pessoais. Se `payer.type` for enviado como `COMPANY`, a transação será rejeitada.

***

## Passo 1. Criar pagamento ETPAY

Para iniciar um pagamento ETPAY no Chile, envie uma requisição `POST` ao endpoint [Criar Payin](https://docs.localpayment.com/pt-br/reference/payins.md) com parâmetros específicos do ETPAY.

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

A solicitação requer vários objetos-chave específicos para pagamentos ETPAY no Chile:

| Objeto | Descrição | Obrigatório |
| - | - | - |
| `paymentMethod.type` | Deve ser `BankTransfer`. | ✅ |
| `paymentMethod.code` | Usar `2528` para o Chile ETPAY. | ✅ |
| `sender` | Informações do remetente para fins de conformidade. | ✅ |
| `merchant` | Detalhes do comerciante/empresa. | ✅ |
| `paymentMethod` | Configuração do método de pagamento. | ✅ |
| `amount` | Valor da transação. | ✅ |
| `currency` | Código da moeda da transação. | ✅ |
| `country` | Deve ser `CHL`. | ✅ |

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": "2528",
    "flow": "REDIRECT"
  },
  "currency": "CLP",
  "merchant": {
    "type": "INDIVIDUAL",
    "document": {
      "type": "RUT",
      "id": "{{id}}"
    },
    "name": "John",
    "lastname": "Doe",
    "email": "merchant@mail.com"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "document": {
      "type": "RUT",
      "id": "{{id}}"
    },
    "phone": {
      "areaCode": "57",
      "countryCode": "57",
      "number": "12345678"
    },
    "address": {
      "country": "CHL",
      "number": "",
      "state": "RM",
      "city": "RM",
      "street": "Street",
      "comment": ""
    },
    "bank": {
      "account": {
        "type": "c",
        "number": "{{bankAccountNumber}}"
      },
      "name": "Banco Estado",
      "code": "012"
    },
    "name": "John",
    "lastname": "Doe",
    "email": "john.doe@example.com"
  },
  "externalId": "c8b360f1-895e-483d-b734-e3ea17eb2b63",
  "country": "CHL",
  "amount": 100,
  "accountNumber": "{{AccountNumber}}",
  "conceptCode": "0038",
  "comment": "Payer"
}
'
```

***

## Etapa 2. Lidar com a resposta

### Resposta bem-sucedida

A criação bem-sucedida de um pagamento ETPAY 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": "7e6c8cd9-55ea-4f94-8f05-f0e13fb24e78",
  "internalId": "6b9dfc0b-1fa0-44b4-a4ff-fd46007ae9a2",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "2528",
    "flow": "REDIRECT"
  },
  "country": "CHL",
  "currency": "CLP",
  "amount": 100,
  "accountNumber": "{{AccountNumber}}",
  "confirmed": {
    "currency": "CLP",
    "amount": 1,
    "fxQuote": 0
  },
  "payment": {
    "currency": "CLP",
    "fxQuote": 0,
    "financingFee": 0,
    "amount": 1
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "CLP",
    "fxSource": 1,
    "fxQuote": 1,
    "amount": 0,
    "account": "{{Account}}"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "The payin is pending the confirmation"
  },
  "merchant": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "{{Type}}",
      "id": "{{documentId}}"
    },
    "email": "merchant@mail.com"
  },
  "payer": {
    "bank": {
      "name": "Banco Estado",
      "code": "012",
      "account": {
        "type": "c",
        "number": "{{Number}}"
      }
    },
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "RUT",
      "id": "{{documentId}}"
    },
    "email": "john.doe@example.com",
    "phone": {
      "countryCode": "57",
      "areaCode": "57",
      "number": "3196741234"
    },
    "address": {
      "street": "Calle 123",
      "number": "0012",
      "city": "RM",
      "state": "RM",
      "country": "CHL",
      "comment": ""
    }
  },
  "intermediaries": [],
  "wireInstructions": {
    "referenceCode": "FDEG-HVCF-JUWX"
  },
  "date": {
    "creationDate": "2024-12-01T15:44:55.058+00:00",
    "processedDate": "2024-12-01T15:45:01.4368519",
    "expirationDate": "2024-12-08T15:44:55.4677488"
  },
  "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aHR0cHM6Ly9wbXQtc2FuZGJveC5ldHBheS5jb20vc2Vzc2lvbi9mT09OZkdvcEVuM1F4RUs4aUZKcWVEdGpadDU5T3ExcjhOamNUM213aFNFbjN0S2sxSzNLcXVtUjk5dTFKTFVS",
  "errors": []
}
```

### Campos de resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `redirectUrl` | URL para redirecionar o cliente para o fluxo de pagamento ETPAY. | Direcione o cliente para a autenticação bancária e o processamento do pagamento. |
| `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 ETPAY falhar para o Chile, 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 ETPAY

1. **Iniciação do pagamento**: Redirecionar o cliente para o URL de pagamento do ETPAY.
2. **Seleção do banco**: O cliente seleciona seu banco chileno dentre as instituições credenciadas.
3. **Autenticação bancária**: O cliente acessa seu ambiente de banco online.
4. **Autorização de pagamento**: O cliente confirma o pagamento em sua interface bancária.
5. **Confirmação em tempo real**: o Localpayment recebe a notificação de pagamento.
6. **Atualização de status**: Seu sistema recebeu um webhook com a confirmação de pagamento.

***

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

Acompanhe o andamento dos pagamentos do ETPAY 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).

***

## Testando sua integração

### Ambiente de Sandbox

Use o ambiente de staging para testes:

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

### Cenários de teste para o Chile

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

1. **Pagamento concluído com sucesso**: Fluxo de pagamento ETPAY finalizado com simulação bancária.
2. **Autenticação bancária**: Teste diferentes fluxos de autenticação bancária.
3. **Expiração do pagamento**: Lide com a expiração do link de pagamento de forma adequada.
4. **Falha na autenticação**: teste cenários de falha no login bancário.
5. **Rejeição bancária**: Simule a rejeição de um pagamento por parte do banco.
6. **Atualizações de status**: gerenciamento de webhooks e consulta de status.

***

## Próximos passos

Após implementar os pagamentos ETPAY, 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.