Pix keys (DICT)

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET /v1/consumers/{consumerId}/pix-keys

List the Pix keys on the consumer's account

The account's live DICT inventory, read from the provider on every call. The account is always resolved server-side from the credential's organization and the consumer id, never taken from the caller, so this can only ever reach an account the caller's own organization holds.

A failed inventory read is an ERROR, never an empty list. unanswered is not no keys, and rendering it as an empty account is the mistake this route refuses to make: a caller that read zero keys would go on to register a key the account may already have, spending one of its limited DICT slots.

In a Test project, a consumer with no active Pix funding source is served from the account bound to it by the project's open account binding, while the project's collect capability is active. That read is counted in the project's provider call budget first.

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/consumers/{consumerId}/pix-keys HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const r = await cs.api.response("get", "/v1/consumers/{consumerId}/pix-keys", {
  path: {
    consumerId: "csm_0000000000000000"
  }
});
// r.status is one of the documented statuses (200, 422),
// each with its own body shape in r.data; nothing here throws on 422.
if (r.ok) {
  console.log(r.data);
}

{
  "account_masked": "string",
  "keys": [
    {
      "key": "string",
      "key_type": "string"
    }
  ],
  "count": 1
}

POST /v1/consumers/{consumerId}/pix-keys

Register a Pix key on the consumer's account

Registers a DICT entry on the consumer's account. The account is ALWAYS resolved on the server from (organization, consumerId) — there is no account field in the body — so a caller can only ever reach an account of a consumer its own organization holds.

key_type is explicit, EVP included, so nobody mints a random key by omission. For EVP the key field must be ABSENT (the provider mints it); for EMAIL, PHONE, CPF and CNPJ it is the key value. A CNPJ key is 14 ALPHANUMERIC characters, which is the DICT rule in force, not 14 digits.

A CPF/CNPJ KEY MAY ONLY BE THE HOLDER'S OWN DOCUMENT, which is a DICT rule. The check is against the document recorded on the account and it fails closed whenever that document is known; where the record predates it and carries none, the provider adjudicates.

AN EMAIL/PHONE KEY MAY REQUIRE PROOF OF POSSESSION: while that check is enforced on the deployment, the contact must have been verified first through POST /v1/consumers/{consumerId}/contact-verifications, and its absence answers 409 pix_key_ownership_unverified before the provider is called at all.

THE 409 pix_key_registration_uncertain IS THE CASE TO READ BEFORE INTEGRATING: the registration was accepted, the response was unreadable, and the account's key list could not settle whether the key landed. DO NOT REPEAT IT. Every repeated EVP mints ANOTHER key against the account's five-key allowance. List the keys with the GET on this same path and delete whatever should not be there.

422 AGAINST 502 IS ALSO DELIBERATE: 422 pix_key_provider_refused is the provider having ADJUDICATED and said no, and repeating the same input cannot succeed; 502 pix_key_provider_unavailable is transient and retriable. Their details differ, and the 502 block below says how — that field is not uniform across the three failures that produce it.

In a Test project, a consumer with no active Pix funding source is served from the account bound to it by the project's open account binding, while the project's collect capability is active. That account registers only a random key (key_type EVP): any other type answers 422 pix_key_type_unavailable before anything is sent, and the registration is counted in the project's provider call budget first.

Path parameters

Request body

Responses

Response 201

curl -X POST https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "key_type": "EVP",
       "key": "string"
     }'

POST /v1/consumers/{consumerId}/pix-keys HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "key_type": "EVP",
  "key": "string"
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "key_type": "EVP",
      "key": "string"
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "key_type": "EVP",
    "key": "string"
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/consumers/{consumerId}/pix-keys", {
  path: {
    consumerId: "csm_0000000000000000"
  },
  body: {
    key_type: "EVP",
    key: "string"
  }
});
// r.status is one of the documented statuses (200, 403, 422),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "key": "string",
  "key_type": "string",
  "account_masked": "string",
  "cache_filled": true,
  "reconciled": true
}

DELETE /v1/consumers/{consumerId}/pix-keys/{key}

Delete a Pix key from the consumer's account

Removes the key from DICT, then reconciles the local cache of the consumer's receiving key. The key is canonicalized before both steps, so a CPF registered bare and deleted punctuated is the same key.

The cache reconciliation is part of the contract, not a detail. An empty cache is what makes the wallet mint a fresh random EVP nobody asked for, burning a DICT slot and switching the consumer onto a key they did not choose. So when the delete clears the cache, the account's remaining keys are re-read and one is cached back, preferring a non-EVP key. cache_refilled_with reports which. The just-deleted value is excluded from the candidates, because DICT releases a deleted entry asynchronously and can still list it for a minute or more.

The key travels in a path segment. Fastify percent-decodes it, and a literal + in a path segment stays a +, so e-mail and phone keys are safe either way.

Path parameters

Responses

Response 200

curl -X DELETE https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys/{key} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

DELETE /v1/consumers/{consumerId}/pix-keys/{key} HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.delete(
    "https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys/{key}",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/consumers/{consumerId}/pix-keys/{key}", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const r = await cs.api.response("delete", "/v1/consumers/{consumerId}/pix-keys/{key}", {
  path: {
    consumerId: "csm_0000000000000000",
    key: "string"
  }
});
// r.status is one of the documented statuses (200, 422),
// each with its own body shape in r.data; nothing here throws on 422.
if (r.ok) {
  console.log(r.data);
}

{
  "key": "string",
  "account_masked": "string",
  "deleted": true,
  "cache_cleared": true,
  "cache_refilled_with": "string"
}