Look up a PIX key before paying it

curl --request GET \
  --url https://api.example.com/v1/entries/{entryId}/lookup \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/entries/{entryId}/lookup"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/entries/{entryId}/lookup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "endToEndId": "E87654321202610061200abcdefghijk",
  "keyType": 2,
  "nrConta": "0007654321",
  "payee": {
    "accountDigit": "",
    "accountNumber": "0007654321",
    "accountType": 0,
    "branch": "0001",
    "document": "11222333000181",
    "ispb": "87654321",
    "key": "payee@example.com",
    "name": "Payee Comercio Ltda"
  },
  "personType": 1,
  "tradeName": "Payee"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Look up a PIX key before paying it

Resolves a PIX key you are about to PAY - anyone’s key, at any institution - into the recipient a payment needs (§8.2.14 Consultar Chave de Endereçamento). entryId is the key value, URL-encoded; account_id is YOUR account, the one the payment will leave from. Call it right before POST /v1/transactions: copy payee into that body as it stands and send endToEndId with it. payee.key plus endToEndId is what makes the payment one initiated by key (JDPI tpIniciacao=1); a payment by key without the endToEndId goes out as a manually typed one. The endToEndId belongs to this lookup: one lookup, one payment, and a new lookup before every payment.

The answer is what DICT holds now: the holder’s document, name and person type, the institution (ispb), branch, account and account type. DICT returns the account as ONE string (nrConta) and does not say where a check digit is, so it is never split: payee.accountNumber carries it whole and payee.accountDigit is empty, and the payment hands JD the same string. Unlike GET /v1/entries//details, the holder is NOT compared against you: resolving someone else’s key is the purpose of this route.

Nothing is written here, but the call is not free. DICT counts every lookup against the payer (PI-PayerId, your account holder’s CPF/CNPJ) and against this institution, and a lookup that is not followed by a payment still spends that budget (§8.2.14, §8.2.31). This deployment therefore limits lookups per payer account before DICT is asked, always, whether or not its general request limits are switched on: by default 100 lookups per payer account per 60 seconds, which the operator tunes apart from every other limit. Past it the call is 429 PIX-0009 with Retry-After, and DICT itself refusing is 429 PIX-1008. Look a key up when the payer is about to pay it, never to browse or to validate a list - POST /v1/entries/verification is the batch existence check.

Refusals: 400 PIX-0061 when account_id is missing or blank, or ispb is not 8 digits; 404 PIX-2016 when account_id does not resolve to an account; 404 PIX-1011 when DICT holds no such key; 429 PIX-0009 (this deployment’s per-payer limit) or PIX-1008 (DICT’s); 503 PIX-1050 when JDPI is unavailable and 503 PIX-1054 when it cannot be reached; 504 PIX-1051 when JDPI does not answer in time.

Which of this deployment’s direct participants asks DICT is decided by ispb, by exactly the rule an order’s payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. Send the participant the payment will be paid by: the endToEndId carries the ISPB of the participant that asked.

GET

entries

{entryId}

lookup

Look up a PIX key before paying it

curl --request GET \
  --url https://api.example.com/v1/entries/{entryId}/lookup \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/entries/{entryId}/lookup"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/entries/{entryId}/lookup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "endToEndId": "E87654321202610061200abcdefghijk",
  "keyType": 2,
  "nrConta": "0007654321",
  "payee": {
    "accountDigit": "",
    "accountNumber": "0007654321",
    "accountType": 0,
    "branch": "0001",
    "document": "11222333000181",
    "ispb": "87654321",
    "key": "payee@example.com",
    "name": "Payee Comercio Ltda"
  },
  "personType": 1,
  "tradeName": "Payee"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Autorizações

Authorization

string

header

obrigatório

JWT bearer token issued by the identity provider.

Parâmetros de caminho

entryId

string

obrigatório

The PIX key to resolve, URL-encoded.

Exemplo:

"payee@example.com"

Parâmetros de consulta

account_id

string

obrigatório

The CRM account id of the PAYER - the account the payment will leave from. Its holder's CPF/CNPJ is the identity DICT counts the lookup against.

Exemplo:

"acc-123"

ispb

string

The ISPB of the direct participant the payer banks at, and therefore the one that asks DICT. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them asks. OPTIONAL while it acts as a single participant: omit it and that one asks. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. Send the same participant as the payment's payerIspb: the endToEndId DICT mints carries the ISPB of the participant that asked. Sending it empty (ispb=) reads the same as omitting it.

Pattern: ^[0-9]{8}$

Exemplo:

"12345678"

Resposta

endToEndId

string

obrigatório

The end-to-end id DICT minted for THIS lookup. Send it on POST /v1/transactions together with payee.key: that pair is what makes the payment one initiated by key (JDPI tpIniciacao=1). One lookup, one payment.

Exemplo:

"E87654321202610061200abcdefghijk"

keyType

integer<int64>

obrigatório

Numeric eKeyType of the key (0=CPF,1=CNPJ,2=EMAIL,3=PHONE,4=RANDOM).

Exemplo:

2

nrConta

string

obrigatório

DICT nrConta as returned, the same value payee.accountNumber carries.

Exemplo:

"0007654321"

payee

object

obrigatório

The recipient, ready to be sent as the payee of POST /v1/transactions.

Show child attributes

personType

integer<int64>

obrigatório

The holder's person type (DICT tpPessoa): 0=Pessoa Fisica, 1=Pessoa Juridica.

Exemplo:

1

tradeName

string

The holder's trade name (DICT nomeFantasia), when DICT holds one.

Exemplo:

"Payee"

APIs do participante direto

APIs de participantes indiretos

Look up a PIX key before paying it

Autorizações

Parâmetros de caminho

Parâmetros de consulta

Resposta