Sign in

v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB
DICT proxy keys

Create DICT proxy key

Register a proxy key in the DICT directory for a connected account.

post/proxy_services/dict/proxy_keys

Request body

owner_type'individual' | 'legal_entity' required

Whether the proxy key owner is an individual or a legal entity.

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

The category of proxy identifier (phone number, email, tax ID, etc.).

proxy_type_code'cpf' | 'cnpj' | 'abn' | 'teli' | 'emal' | 'aubn' | 'orgn' | 'evp'

The scheme-specific sub-type code for the proxy. For DICT: cpf (individual) or cnpj (legal entity).

proxy_identificationstring required

The proxy identifier value (e.g. the CPF number, email address, or phone number).

owner_namestring required

Full name of the proxy key owner. Maximum 140 characters.

account_identificationstring required

Account number associated with this proxy key.

account_type'CACC' | 'SVGS' | 'SLRY' | 'TRAN'

ISO 20022 account type code.

account_issuerstring

Identifier of the institution that issued the account (e.g. ISPB code for DICT).

servicerstring required

Identifier of the financial institution servicing the account (e.g. ISPB for DICT).

connected_account_idstring uuid required

ID of the Mambu Payments connected account to register this proxy key against.

internal_account_idstring uuid

Optional ID of an internal account in Mambu Payments linked to this proxy key.

metadataobject

Customer-defined key/value pairs passed through as-is.

Example request

{
  "owner_type": "individual",
  "proxy_type": "tax_id",
  "proxy_type_code": "cpf",
  "proxy_identification": "12345678901",
  "owner_name": "Maria Silva",
  "account_identification": "0001234-5",
  "account_type": "CACC",
  "account_issuer": "12345678",
  "servicer": "12345678",
  "connected_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "internal_account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "scheme_data": {
    "reason": "USER_REQUESTED",
    "tax_identification_number": "12345678901"
  },
  "metadata": {
    "customer_ref": "cust-001"
  }
}

Response

Successfully created proxy key

idstring uuid required

Unique identifier of the proxy key.

object'proxy_key' required

Object type label.

schemestring required

The directory scheme this proxy key is registered in.

owner_type'individual' | 'legal_entity' required

Whether the owner is an individual or a legal entity.

owner_namestring required

Full name of the proxy key owner.

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

The category of proxy identifier.

proxy_type_code'cpf' | 'cnpj' | 'abn' | 'teli' | 'emal' | 'aubn' | 'orgn' | 'evp' | 'null' nullable required

The scheme-specific sub-type code for the proxy.

proxy_identificationstring required

The proxy identifier value.

status'pending_registration' | 'registration_failed' | 'active' | 'disabled' required

Current status of the proxy key. A newly created key is pending_registration until the scheme accepts the registration, at which point it becomes active. If the scheme refuses the registration the key becomes registration_failed.

status_detailsstring nullable required

Additional information about the current status.

status_reason'released_via_claim' | 'null' nullable required

Machine-readable reason the key reached its current status. released_via_claim when disabled by a confirmed donor-side claim.

account_identificationstring required

Account number associated with this proxy key.

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

ISO 20022 account type code.

account_issuerstring nullable required

Identifier of the institution that issued the account.

connected_account_idstring uuid required

ID of the Mambu Payments connected account this proxy key is registered against.

internal_account_idstring uuid nullable required

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

servicerstring required

Identifier of the financial institution servicing the account.

metadataobject required

Customer-defined key/value pairs.

created_atstring date-time required

UTC timestamp when the proxy key was created.

disabled_atstring date-time nullable required

UTC timestamp when the proxy key was disabled, if applicable.

enabled_atstring date-time nullable required

UTC timestamp when the proxy key was last enabled, if applicable.

Example response

{
  "id": "c39d1eff-c5ed-4197-8f24-28a68bd0eee6",
  "object": "proxy_key",
  "scheme": "dict",
  "owner_type": "individual",
  "owner_name": "Maria Silva",
  "proxy_type": "tax_id",
  "proxy_type_code": "cpf",
  "proxy_identification": "12345678901",
  "status": "active",
  "account_identification": "0001234-5",
  "account_type": "CACC",
  "account_issuer": "12345678",
  "connected_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "servicer": "12345678",
  "scheme_data": {
    "reason": "USER_REQUESTED",
    "tax_identification_number": "12345678901",
    "directory_entry_id": "dict-entry-abc123"
  },
  "metadata": {
    "customer_ref": "cust-001"
  },
  "created_at": "2025-01-01T12:00:00Z"
}