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 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 before DICT is asked, always, whether or not its general request limits are switched on: by default 100 lookups per payer per 60 seconds, which the operator tunes apart from every other limit. The payer is account_id or, on an indirect’s lookup, the X-Payer-Document it declares, counted apart for each indirect. 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 the payer is not named exactly one way (account_id on a direct lookup; X-Payer-Document or account_id on an indirect one), X-Payer-Document is not a CPF or CNPJ, 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. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Send the participant the payment will be paid by: the endToEndId carries the ISPB of the participant that asked.

Paying through an INDIRECT participant: send indirectId, the same one the payment order will carry. The lookup then asks DICT on that indirect’s behalf, so the endToEndId names the indirect - the institution the payment originates from - rather than the direct participant it rides (JDPI §8.2.14 PI-RequestingParticipant). Without it the endToEndId names the direct participant and does not match the order’s payer. indirectId is validated before DICT is asked, by the rules the order applies: 404 PIX-0095 unknown to this tenant, 422 PIX-0100 not ACTIVE, 422 PIX-0111 while the indirect-participants feature is off. The lookup acts as the direct participant that indirect is mounted on: omit ispb, or send that participant’s ISPB; any other is 422 PIX-0102. The payer of an indirect’s payment is the indirect’s customer: declare its CPF/CNPJ in the X-Payer-Document header instead of account_id. account_id there is deprecated, and refused 400 PIX-0061 when an Access Manager partner is behind the request.

GET /v1/entries/{entryId}/lookup

Look up a PIX key before paying it

cURL

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

200

{
  "accountNumber": "0007654321",
  "endToEndId": "E87654321202610061200abcdefghijk",
  "keyType": 2,
  "payee": {
    "accountDigit": "",
    "accountNumber": "0007654321",
    "accountType": 0,
    "branch": "0001",
    "document": "11222333000181",
    "ispb": "87654321",
    "key": "[e-mail]",
    "name": "Payee Comercio Ltda"
  },
  "personType": 1,
  "tradeName": "Payee"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Payer-Document · string

The CPF/CNPJ of the indirect participant's customer who pays, as the indirect declares it, mask allowed. Only with indirectId, and required there unless the legacy account_id is sent instead: an indirect keeps its customers in its own core, so this plugin reads no record of them and sends this document to DICT as the payer (PI-PayerId), canonical (digits, and the letters of an alphanumeric CNPJ). Refused 400 PIX-0061 without indirectId, together with account_id, or when it is not a CPF of 11 digits or a CNPJ of 14 characters.

Example:

"52998224725"

Path Parameters

entryId · string · required

The PIX key to resolve, URL-encoded.

Example:

"[e-mail]"

Query Parameters

account_id · string

The Midaz ledger account id of the PAYER - the account the payment will leave from, a customer of the asking direct participant. Its holder's CPF/CNPJ is the identity DICT counts the lookup against. REQUIRED on a direct lookup (absent or blank is 400 PIX-0061). With indirectId it is DEPRECATED in favour of the X-Payer-Document header: an indirect keeps its customers in its own core, so the payer is the customer it declares. account_id is still accepted there, unchanged, when the direct participant's own credential sends the lookup, and refused 400 PIX-0061 when an Access Manager partner is behind the request. Sending it together with X-Payer-Document is 400 PIX-0061.

Example:

"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b"

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-9A-Z]{8}$

Example:

"12345678"

indirectId · string<uuid>

The registered indirect participant (UUID) the payment will be paid through - send the SAME indirectId the payment order will carry. DICT then mints the endToEndId under that indirect's ISPB, which is the institution the payment originates from; without it the endToEndId names the direct participant, and a payment by key ordered with an indirectId would go out naming the wrong institution. Omit it for a payment the direct participant pays. Validated before DICT is asked, exactly as the order validates it: 404 PIX-0095 unknown to this tenant, 422 PIX-0100 not ACTIVE, 422 PIX-0111 while this deployment's indirect-participants feature is off - the lookup is never made as a direct one instead. The lookup then acts as the direct participant the indirect is mounted on: omit ispb, or send that participant's ISPB; any other is 422 PIX-0102. A token confined to one indirect has to name it here, and may name no other.

Example:

"3f2504e0-4f89-41d3-9a0c-0305e82c3301"

Response

200

application/json

OK

accountNumber · string · required

The account number as DICT returns it, the same value payee.accountNumber carries.

Example:

"0007654321"

endToEndId · string · required

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.

Example:

"E87654321202610061200abcdefghijk"

keyType · integer<int64> · required

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

Example:

2

payee · object · required

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

Show child attributes

personType · integer<int64> · required

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

Example:

1

tradeName · string

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

Example:

"Payee"