Skip to main content

Claim

The following set of endpoints is responsible for managing Claims.


Create Claim​

Endpoint to create a new claim.

This operation is performed by the claiming participant at the request of the end user. The current link remains unchanged until confirmation by the donating PSP.

Not all key types can be claimed or ported. The table below defines the possibilities:

compatible?OWNERSHIPPORTABILITY
CPF✓
CNPJ✓
PHONE✓✓
EMAIL✓
EVP

Claims the ownership of a Pix key. This claim has two types: OWNERSHIP or PORTABILITY.

In OWNERSHIP, the claimant requests the change of a key that is in another user's possession, which can only be of type email or phone.

In PORTABILITY, the claimant requests the change of a key that is in their possession but at another PSP, which can be CPF, CNPJ, Email, or phone.

POST /dict/claims
Requires authorization for the scope: claim.ind.write


Request

{
  "type": "OWNERSHIP",
  "key": "+5561988887777",
  "keyType": "PHONE",
  "claimer": {
    "name": "João Silva",
    "taxIdNumber": "11122233300",
    "type": "NATURAL_PERSON"
  },
  "claimerAccount": {
    "accountNumber": "0007654321",
    "accountType": "CACC",
    "branch": "0001",
    "openingDate": "2010-01-10T03:00:00Z"
  }
}

Responses

The responses below represent Success(201) from the consumption.

{
  "claim": {
    "claimer": {
      "name": "João Silva",
      "taxIdNumber": "11122233300",
      "type": "NATURAL_PERSON"
    },
    "claimerAccount": {
      "accountNumber": "0007654321",
      "accountType": "CACC",
      "branch": "0001",
      "openingDate": "2010-01-10T03:00:00.000Z"
    },
    "completionPeriodEnd": "2020-01-17T10:00:00.000Z",
    "donorParticipant": "87654321",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "key": "+5561988887777",
    "keyType": "PHONE",
    "lastModified": "2020-01-10T10:00:00.000Z",
    "resolutionPeriodEnd": "2020-01-17T10:00:00.000Z",
    "status": "OPEN",
    "type": "OWNERSHIP"
  },
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "responseTime": 500
}

Confirm Claim​

Endpoint to confirm the claim operation. As a result, the key's link with the donating participant is removed.

Status must be WAITING_RESOLUTION.

For ownership claims, if the reason is DEFAULT_OPERATION, the resolution period (ResolutionPeriodEnd) must have passed. If the reason provided is USER_REQUESTED, the completion period (CompletionPeriodEnd) will be advanced to allow immediate closure by the claimant.

The table below defines, depending on the reason and type, who can confirm.

OWNERSHIPPORTABILITY
REASONDONORCLAIMANTDONORCLAIMANT
USER_REQUESTED✓✓
ACCOUNT_CLOSURE✓
DEFAULT_OPERATION✓

Idempotency

The operation is idempotent. If the claim has already been confirmed with the same parameters and is still in CONFIRMED status, the response will be equivalent to the first request.

Confirms a Pix key claim process created by another PSP.

The status must necessarily be WAITING_RESOLUTION.

POST /dict/claims/:claimId/confirm
Requires authorization for the scope: claim.ind.write


Request

{
  "claimId": "123e4567-e89b-12d3-a456-426655440000",
  "reason": "user_requested"
}

Responses

The responses below represent Success(200) from the consumption.

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "claim": {
    "type": "ownership",
    "key": "+5561988887777",
    "keyType": "phone",
    "claimerAccount": {
      "participant": "12345678",
      "branch": "0001",
      "accountNumber": "0007654321",
      "accountType": "CACC",
      "openingDate": "2010-01-10T03:00:00.000Z"
    },
    "claimer": {
      "type": "natural_person",
      "taxIdNumber": "11122233300",
      "name": "João Silva",
    },
    "donorParticipant": "87654321",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "status": "CONFIRMED",
    "resolutionPeriodEnd": "2020-01-17T10:00:00.000Z",
    "completionPeriodEnd": "2020-01-17T10:00:00.000Z",
    "lastModified": "2020-01-10T10:00:00.000Z",
    "confirmReason": "user_requested"
  }
}

Cancel Claim​

Endpoint to cancel a portability or ownership claim. (Flow for Donor or Claimant)

Cancellation Rules:
PORTABILITY:
REASONDONORCLAIMANT
user_requested✓✓
account_closure✓
default_operation✓(after period)
fraud✓✓(even if CONFIRMED)

OWNERSHIP:
REASONDONORCLAIMANT
user_requested✓✓
default_operation✓(after period)
fraud✓✓
What happens:
  • 1. Status changes to CANCELED
  • 2. Process is closed
  • 3. Key remains with the original donor
  • 4. Both parties are notified
Important!

Cancellation is IRREVERSIBLE.

Once canceled, the claim cannot be reactivated.


The claimant is the one who can cancel an ownership claim. See exception below:

Exception: If the reason is FRAUD, the donor may also cancel the ownership claim.

Idempotency

The operation is idempotent. If the claim has already been canceled with the same parameters, the response will be equivalent to the first request.

Cancels a Pix key claim process created by the Indirect PSP. The table below defines, depending on the reason and type, who can cancel.

OWNERSHIPPORTABILITY
REASONDONORCLAIMANTDONORCLAIMANT
WAITING_RESOLUTIONCONFIRMED
USER_REQUESTED✓✓✓
ACCOUNT_CLOSURE✓✓
FRAUD✓✓✓✓✓
DEFAULT_OPERATION✓✓

POST /dict/claims/:claimId/cancel
Requires authorization for the scope: claim.ind.write


Request

{
  "claimId": "123e4567-e89b-12d3-a456-426655440000",
  "reason": "user_requested"
}

Responses

The responses below represent Success(201) from the consumption.

Portability
{
  "claim": {
    "claimer": {
      "name": "João Silva",
      "taxIdNumber": "11122233300",
      "type": "NATURAL_PERSON"
    },
    "claimerAccount": {
      "accountNumber": "0007654321",
      "accountType": "CACC",
      "branch": "0001",
      "openingDate": "2010-01-10T03:00:00.000Z",
      "participant": "12345678"
    },
    "completionPeriodEnd": "2020-01-17T10:00:00.000Z",
    "confirmReason": "USER_REQUESTED",
    "donorParticipant": "87654321",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "key": "+5561988887777",
    "keyType": "PHONE",
    "lastModified": "2020-01-10T10:00:00.000Z",
    "resolutionPeriodEnd": "2020-01-17T10:00:00.000Z",
    "status": "CANCELLED",
    "type": "PORTABILITY"
  },
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "responseTime": "2020-01-10T10:00:00.000Z"
}

Complete Claim​

Endpoint to complete a claim by the claimant. As a result, the key is linked to the claimant participant.

For ownership claims, the status must be CONFIRMED and the period defined by CompletionPeriodEnd must have passed.

For portability claims, the status must be CONFIRMED.

Idempotency

The claim completion operation is idempotent. The same considerations apply as described for the Create Link operation.

POST /dict/claims/:claimId/complete
Requires authorization for the scope: claim.ind.write


Request

The request sent to this endpoint does not require a body, only OAuth authorization headers, parameters, and the account certificate.

Responses

The responses below represent Success (200) and failures/errors of the consumption.

{
  "responseTime": 0,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "claim": {
    "type": "OWNERSHIP",
    "key": "+5561988887777",
    "keyType": "PHONE",
    "claimerAccount": {
      "participant": "12345678",
      "branch": "0001",
      "accountNumber": "0007654321",
      "accountType": "CACC",
      "openingDate": "2010-01-10T03:00:00.000Z"
    },
    "claimer": {
      "type": "NATURAL_PERSON",
      "taxIdNumber": "11122233300",
      "name": "João Silva"
    },
    "donorParticipant": "87654321",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "status": "CONFIRMED",
    "resolutionPeriodEnd": "2020-01-17T10:00:00.000Z",
    "completionPeriodEnd": "2020-01-17T10:00:00.000Z",
    "lastModified": "2020-01-10T10:00:00.000Z",
    "confirmReason": "USER_REQUESTED"
  }
}

Last updated on