v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB

DICT proxy claims

Acknowledge DICT proxy claim

Donor acknowledges receipt of an open proxy claim, transitioning it from open to pending_acknowledgment. Only applicable when role = donor — requests against claimer-side rows return 400.

The provider call is synchronous against the simulator; on success the response returns status = pending_acknowledgment and the claim is finalised to waiting_resolution asynchronously by the inbound proxy_claim.acknowledgment_completed event. On provider rejection the response returns 200 with status = acknowledgment_rejected and a populated status_details (rejections are stored business states, not HTTP errors).

post/proxy_services/dict/proxy_claims/{id}/acknowledge

Path parameters

idstring uuid required

ID of the proxy claim to acknowledge.

Response

Proxy claim acknowledged (or acknowledgment rejected by the provider).

idstring uuid required

Unique identifier of the proxy claim.

object'proxy_claim' required

Object type label.

schemestring required

The directory scheme this claim belongs to.

type'ownership' | 'portability' required

Claim type.

role'claimer' | 'donor' required

Whether our customer is opening the claim (claimer) or receiving it (donor).

Current state of the claim.

pending_creation — creation submitted to DICT; awaiting the scheme to finalise it (async). Flipped to open by proxy_claim.creation_completed or to creation_rejected by proxy_claim.creation_rejected.
open — DICT accepted the claim creation, awaiting donor response.
creation_rejected — DICT rejected the creation request (e.g. key not found or key type not claimable).
pending_acknowledgment — donor acknowledged the claim; awaiting the scheme to finalise it (async). Flipped to waiting_resolution by proxy_claim.acknowledgment_completed.
waiting_resolution — the donor's acknowledgment was finalised; waiting for the resolution period to complete.
acknowledgment_rejected — DICT rejected the donor's acknowledgment; status_details contains the rejection reason.
pending_confirmation — a confirm was requested; awaiting the scheme to finalise it (async). Flipped to confirmed by proxy_claim.confirmation_completed, which also releases the bound proxy key.
confirmed — donor confirmed the claim; the bound proxy key is released (status = disabled, status_reason = released_via_claim).
confirmation_rejected — DICT rejected the donor's confirmation; status_details contains the rejection reason.
pending_cancellation — a cancel was requested; awaiting the scheme to finalise it (async). Flipped to cancelled by proxy_claim.cancellation_completed. scheme_data.cancel_reason / scheme_data.cancelled_by are already populated.
cancelled — claim was cancelled; scheme_data.cancel_reason and scheme_data.cancelled_by are populated.
cancellation_rejected — DICT rejected the cancellation; status_details contains the rejection reason.
pending_completion — claimer requested completion; awaiting the scheme to finalise it (async). Flipped to completed by proxy_claim.completion_completed.
completed — claimer successfully completed the claim; proxy_key_id is populated with the new key.
completion_rejected — DICT rejected the completion request; status_details contains the rejection reason.

status_detailsstring nullable required

Additional information about the current status, populated when the claim is rejected.

proxy_type'phone' | 'email' | 'tax_id' | 'organisation' | 'random_alias' required

The category of the claimed proxy identifier.

proxy_type_codestring nullable required

The scheme-specific sub-type code of the claimed proxy.

proxy_identificationstring required

The proxy identifier value being claimed.

claimer_namestring required

Full name of the claimer.

claimer_account_identificationstring required

Account number at the claiming institution.

claimer_account_type'CACC' | 'SVGS' | 'SLRY' | 'TRAN' | 'null' nullable required

ISO 20022 account type code at the claiming institution.

claimer_account_issuerstring nullable required

Identifier of the institution that issued the claimer's account.

claimer_servicerstring required

ISPB of the claiming institution.

donor_servicerstring nullable required

ISPB of the institution currently holding the key. Populated once DICT resolves the donor.

connected_account_idstring uuid required

ID of the Mambu Payments connected account associated with this claim.

internal_account_idstring uuid nullable required

ID of the Mambu Payments internal account linked to this claim, if any.

proxy_key_idstring uuid nullable required

ID of the proxy key created upon successful completion of the claim. Null until the claim reaches completed status.

resolution_period_endstring date-time nullable required

Deadline by which the donor must respond. Null when status is creation_rejected.

completion_period_endstring date-time nullable required

Deadline by which the claim must reach a terminal state. Null when status is creation_rejected.

metadataobject required

Customer-defined key/value pairs.

created_atstring date-time required

UTC timestamp when the claim was created.

updated_atstring date-time nullable required

UTC timestamp of the last status update.

Example response

{
  "id": "e5f6a7b8-c9d0-1234-efff-123456789012",
  "object": "proxy_claim",
  "scheme": "dict",
  "type": "portability",
  "role": "claimer",
  "status": "open",
  "proxy_type": "tax_id",
  "proxy_type_code": "cpf",
  "proxy_identification": "12345678901",
  "claimer_name": "Maria Silva",
  "claimer_account_identification": "0001234-5",
  "claimer_account_type": "CACC",
  "claimer_account_issuer": "12345678",
  "claimer_servicer": "12345678",
  "connected_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "resolution_period_end": "2026-01-08T12:00:00Z",
  "completion_period_end": "2026-01-15T12:00:00Z",
  "scheme_data": {
    "claim_id": "claim-bacen-uuid-001",
    "claimer_tax_identification_number": "12345678901",
    "claimer_owner_type": "individual",
    "claimer_opening_date": "2020-01-01T00:00:00Z"
  },
  "metadata": {},
  "created_at": "2026-01-01T12:00:00Z"
}