> ## Documentation Index
> Fetch the complete documentation index at: https://base39-release-notes-06-mar.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Validação de chave PIX

A validação de chave PIX pode ser solicitada em dois momentos:

* Ao [Criar um método de pagamento](/reference/post-v1-payment-methods)
* Ao [Verificar método de pagamento](/reference/post-v1-payment-method-id-verify)
* No Portal Cliente, a verificação é feita logo antes do usuário enviar uma proposta de empréstimo. Nesse momento, o Portal Cliente utiliza o [Verificar método de pagamento](/reference/post-v1-payment-method-id-verify).

A validação possui um processo de cache para evitar múltiplas requisições. Você pode solicitar uma nova verificação a cada 30 dias. Todas as chamadas de verificações nesse período serão reaproveitadas.

## Status

| Status               | Descrição                                                                                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| not\_verified        | O método de pagamento não foi verificado                                                                                                                                 |
| verified             | O método de pagamento foi verificado                                                                                                                                     |
| validated            |                                                                                                                                                                          |
| verification\_failed | A verificação do método de pagamento falhou. É possível solicitar uma nova verificação pelo [Verificar método de pagamento](/reference/post-v1-payment-method-id-verify) |
| errored              |                                                                                                                                                                          |
| void                 | O método de pagamento foi anulado e não pode mais ser usado                                                                                                              |

## Configuração

A configuração é feita no `validations.pix` pelo endpoint [Atualizar as configurações](/reference/post-v1-settings). A configuração padrão é `mock`.

Existem alguns tipos de integração para validação de chave PIX:

### Mock

O tipo mock é usado para testes e sempre retorna chave válida. Também pode ser usado em live para alguns cenários que impedem a validação de chaves de forma antecipada.

```json
// POST https://api.base39.io/v1/settings
{
  "validations": {
    "pix": {
      "type": "mock"
    }
  }
}
```

### Customizado

O tipo customizado permite que você integre a sua API ou de um terceiro que a Base39 não oferece suporte nativo. A autenticação deve ser feita através de *headers*.

```json
// POST https://api.base39.io/v1/settings
{
  "validations": {
    "pix": {
      "credentials": {
        "headers": {
          "Authorization": "value"
        },
        "url": "https://api.example.com"
      },
      "type": "custom"
    }
  }
}
```

#### Payload da requisição

A API configurada receberá uma requisição com os *headers* informados e o *body* com o objeto *PaymentMethod*:

```json
// Object PaymentMethod
{
  "status": "not_verified",
  "method": "pix_key",
  "methodData": {
    "keyType": "document",
    "keyValue": "pix@mail.com",
    "accountHolderName": "João da Silva",
    "accountHolderType": "individual",
    "accountHolderDocument": "12312312312",
    "bankCode": "",
    "bankName": "",
    "branch": "",
    "number": "",
    "digit": "",
    "accountType": ""
  }
}
```

#### Respostas esperada

A API deve responder status 200 e o *body* com os valores atualizados:

```json
// Object PaymentMethod
{
  "status": "verified",
  "method": "pix_key",
  "methodData": {
    "keyType": "document",
    "keyValue": "pix@mail.com",
    "accountHolderName": "string",
    "accountHolderType": "individual",
    "accountHolderDocument": "string",
    "bankCode": "string",
    "bankName": "string",
    "branch": "string",
    "number": "string",
    "digit": "string",
    "accountType": "current"
  }
}
```

## QITech

Veja o [Guia de Integração QITECH](/docs/qitech#validação-de-chave-pix)

## Testando

Para testar a validação de chave PIX, você pode criar um método de pagamento e em seguida consultar o status.

1. Faça uma requisição para [Criar um método de pagamento](/reference/post-v1-payment-methods) com o `method: pix_key`.
2. Aguarde alguns segundos para que a requisição de validação seja feita.
3. Faça uma requisição para [Obter um método de pagamento](/reference/post-v1-payment-method-id-verify) para verificar o status. O status deve ser `verified`.

## Erros comuns

### Falha na validação

Se o status do método de pagamento é `verification_failed`, esse erro pode surgir de múltiplos fatores.

Para integração `custom`, verifique se a resposta da sua API está correta e se o status é 200.

Para integração `qitech`, confirme se as credenciais estão corretas.