Create key claim

post https://api-sandbox.pismolabs.io/pix-dict/v2/pix/claims

The Brazil Central Bank maintains Pix keys in the Diretório de Identificadores de Contas Transacionais (DICT), a national Pix key registry and database.

On PSP timeout, a 202 Accepted response is returned and the process continues asynchronous, eventually emitting a claim successful creation event.

This endpoint generates a Pix key claim status changed event.

For more information, see Pix key transfer (key claim).

Body Params

claimer_account

object

required

key

string

required

length ≤ 77

Value, based on a key's type, used to encrypt Pix key.

key_type

string

required

User information that can be used to create a Pix key:

CPF - Cadastro de Pessoas Fisicas (Indiviual Taxpayer Registry) number. Similar to a Social Security number in the US.
CNPJ - Cadastro Nacional de Pessoa Juridica (National Registry of Legal Entities) number. Unique ID for legal entities, such as companies and organizations, in Brazil
EMAIL - Email
PHONE - Phone number
EVP - Endereco de pagamento virtual (virtual payment address). A randomly-generated UUID number.

type

string

required

Key claim type:

OWNERSHIP - Transfers key ownership between individuals in the same or another bank.
PORTABILITY- Transfers key ownership for the same individual to another bank.

name_type

string

Name type:

REGISTRATION_NAME - Name assigned at birth
SOCIAL_NAME - Preferred name, not necessarily REGISTRATION_NAME

Headers

Authorization

string

required

Account token - token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.

Idempotency-Key

string

required

A unique UUID identifier to ensure the operation remains idempotent, allowing for operation repitition without causing unintended effects or duplication. An idempotent operation is one that can be applied multiple times, yet the outcome remains the same. it ensures that network errors, retries, or failures can occur without introducing inconsistencies.

Responses

Response body

object

bacen_response_time

date-time

Banco Central do Brasil (Central Bank of Brazil) response datetime. A RFC 3339 date-time value, i.e., "2023-04-12T23:20:50.52Z".

claim_id

string

Claim ID for key transfer. The Create key claim or Create DICT key claim endpoint returns this field.

claimer

object

document_number

string

required

length between 11 and 14

A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). Must be numeric with 11-14 digits.

name

string

required

length ≤ 100

Person's name

trade_name

string

length ≤ 100

Name under which the business operates. Not necessarily the same as the legal name.

type

string

required

Key claim type:

OWNERSHIP - Transfers key ownership between individuals in the same or another bank.
PORTABILITY- Transfers key ownership for the same individual to another bank.

OWNERSHIP PORTABILITY

claimer_account

object

account_number

string

required

length ≤ 20

Account number.

account_type

string

required

length ≤ 4

Account type:
CACC - Checking account
SVGS - Savings account
TRAN - Transactional account (Brazil only). Also known as "conta corrente" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking.
SLRY - Salary account. Employer deposits a fixed amount every month.

CACC SLRY SVGS TRAN

branch

string

required

Bank-assigned branch ID or ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.

participant

string

length ≤ 8

Participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.

opening_datetime

date-time

required

Opening date time. A RFC 3339 date-time value, i.e., "2023-04-12T23:20:50.52Z".

completion_period_end_datetime

date-time

Completion period end for claim. Present for claim type OWNERSHIP. ISO 8601 format.

correlation_id

string

The correlation identifier is used to link related API requests and events. The Pismo engineering team can use this to track everything related to a call. If one is not passed, it is automatically generated and returned to the client in a response header.

donor_participant

string

length ≤ 8

Donor participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.

key

string

length ≤ 77

Value, based on a key's type, used to encrypt Pix key.

key_type

string

User information that can be used to create a Pix key:

CPF - Cadastro de Pessoas Fisicas (Indiviual Taxpayer Registry) number. Similar to a Social Security number in the US.
CNPJ - Cadastro Nacional de Pessoa Juridica (National Registry of Legal Entities) number. Unique ID for legal entities, such as companies and organizations, in Brazil
EMAIL - Email
PHONE - Phone number
EVP - Endereco de pagamento virtual (virtual payment address). A randomly-generated UUID number.

CPF CNPJ PHONE EMAIL EVP

last_modified_datetime

date-time

Last modified datetime. A RFC 3339 date-time value, i.e., "2023-04-12T23:20:50.52Z".

resolution_period_end_datetime

date-time

Resolution period end for claim. ISO 8601 format.

status

string

Claim status

OPEN WAITING_RESOLUTION CONFIRMED CANCELLED COMPLETED

type

string

Key claim type:

OWNERSHIP - Transfers key ownership between individuals in the same or another bank.
PORTABILITY- Transfers key ownership for the same individual to another bank.

OWNERSHIP PORTABILITY

Headers

object

x-cid

string

Request tracking identifier.

Language

Credentials

Bearer

JWT


xxxxxxxxxx
13
1
curl --request POST \
2
     --url https://api-sandbox.pismolabs.io/pix-dict/v2/pix/claims \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "claimer_account": {
8
    "account_type": "CACC"
9
  },
10
  "key_type": "CPF",
11
  "type": "OWNERSHIP"
12
}
13
'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

Create key claim

Changelog

Support

Pismo is here to help

200Claim registered

202Accepted

400Bad Request

401Unauthorized

403Forbidden

404Not Found

500Internal server errpr

502Bad Gateway

504Gateway Timeout