PIpismo
Claims

Create key claim

Register a DICT claim for a key.

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 <a href="https://developers.pismo.io/events/docs/pix-dict-claim-status-change-1" >Pix key claim status changed</a> event.

For more information, refer to Pix key transfer (key claim).

post/v2/pix/claims

Request

  • Base URL
    https://sandbox.pismolabs.io/pix-dict
  • URL
    https://sandbox.pismolabs.io/pix-dict/v2/pix/claims
  • Auth
    HTTP bearer

Headers

Authorizationstring required
Example:Bearer eyJhbGci...IUzUx

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

Idempotency-Keystring 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.

Request body

keystring required

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

key_type'CPF' | 'CNPJ' | 'PHONE' | 'EMAIL' | 'EVP' 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'OWNERSHIP' | 'PORTABILITY' 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'REGISTRATION_NAME' | 'SOCIAL_NAME'

Name type:

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

Example request

{
  "claimer_account": {
    "account_number": "98765432",
    "account_type": "TRAN",
    "branch": "011",
    "participant": "00115678",
    "opening_datetime": "2020-08-13T13:49:03Z"
  },
  "key": "al_fresco@bourdain.com",
  "key_type": "EMAIL",
  "type": "OWNERSHIP",
  "name_type": "SOCIAL_NAME"
}

Response

Claim registered

bacen_response_timestring date-time

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

claim_idstring

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

completion_period_end_datetimestring date-time

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

correlation_idstring uuid

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_participantstring

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

keystring

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

key_type'CPF' | 'CNPJ' | 'PHONE' | 'EMAIL' | 'EVP'

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.
last_modified_datetimestring date-time

Last modified datetime. A RFC 3339 date-time value. For example - 2023-04-12T23:20:50.52Z.

resolution_period_end_datetimestring date-time

Resolution period end for claim. ISO 8601 format.

status'OPEN' | 'WAITING_RESOLUTION' | 'CONFIRMED' | 'CANCELLED' | 'COMPLETED'

Claim status

type'OWNERSHIP' | 'PORTABILITY'

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.

Example response

{
  "bacen_response_time": "2020-08-13T13:49:03Z",
  "claim_id": "123e4567-e89b-12d3-a456-426655440000",
  "claimer": {
    "document_number": "123412341234",
    "name": "Jerry Atrick",
    "type": "OWNERSHIP",
    "trade_name": "Acme Widgets"
  },
  "claimer_account": {
    "account_number": "98765432",
    "account_type": "TRAN",
    "branch": "011",
    "participant": "00115678",
    "opening_datetime": "2020-08-13T13:49:03Z"
  },
  "completion_period_end_datetime": "2020-01-24T10:00:00Z",
  "correlation_id": "ea8bc045-9ff7-439f-a318-2e6f974707a5",
  "donor_participant": "99999011",
  "key": "al_fresco@bourdain.com",
  "key_type": "EMAIL",
  "last_modified_datetime": "2020-08-13T13:49:03Z",
  "resolution_period_end_datetime": "2020-01-17T10:00:00Z",
  "status": "OPEN",
  "type": "OWNERSHIP"
}

Changes

No recorded changes to this operation across all 1 revision of this API.