Sign in

v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB
DICT proxy keys

Update DICT proxy key

Partially update an active DICT proxy key. Only fields present in the request body are updated; omitted fields are left unchanged.

owner_name and account_identification changes are forwarded to the DICT provider before the record is persisted — a provider failure leaves the key unchanged.

Returns 400 if the key is not currently active. An empty request body is valid — the current key is returned with 200.

post/proxy_services/dict/proxy_keys/{id}

Path parameters

idstring uuid required

ID of the proxy key to update.

Request body

owner_namestring

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

account_identificationstring

Account number associated with this proxy key.

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

ISO 20022 account type code. Pass null to clear the existing value.

account_issuerstring nullable

Identifier of the institution that issued the account. Pass null to clear the existing value.

servicerstring

Identifier of the financial institution servicing the account.

metadataobject

Shallow key/value patch applied to the existing metadata: keys present in the patch overwrite existing values; setting a key to null removes it from the stored metadata; keys absent from the patch are preserved.

Example request

{
  "owner_name": "João Santos",
  "account_identification": "0009876-5",
  "account_type": "CACC",
  "account_issuer": "12345678",
  "servicer": "12345678",
  "metadata": {
    "customer_ref": "cust-002"
  }
}

Response

Proxy key successfully updated.

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"
}