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

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

StatusDescrição
not_verifiedO método de pagamento não foi verificado
verifiedO método de pagamento foi verificado
validated
verification_failedA verificação do método de pagamento falhou. É possível solicitar uma nova verificação pelo Verificar método de pagamento
errored
voidO 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. 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.

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

// 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:

// 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:

// 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

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

Domínios