Skip to navigation

Register the account as a boleto beneficiary

Registers this account’s holder as a boleto beneficiary using the account’s own data. Send an empty body, {} or null. Any other JSON returns 400 invalid_payload. Scope boleto_charge.manage. Requires boleto_charge.

  • Holder not registered, or the relationship is closed: 202 boleto_charge_beneficiary_pending and Retry-After: 300.
  • Already pending: the same 202, with no second registration.
  • Eligible with an active relationship: 200 with the current beneficiary.
  • Ineligible or under review: 422 boleto_charge_beneficiary_ineligible.
  • The settlement bank refused: 502 boleto_charge_beneficiary_registration_failed, and message carries the partner’s reason.
  • A registration was rejected in the last 24 hours: this call registers again anyway. It is how you re-register after fixing the account data; only automatic re-registration by issuance waits for the 24 hours.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringOptional

Optional client-generated idempotency token (recommended for safe retries).

Request

Empty. The account supplies the beneficiary data.

Response

Already eligible. Body is the current beneficiary.
beneficiaryIdstringOptional

Settlement-bank beneficiary id.

identifierstringOptional
Beneficiary identifier.
statusenumOptional
Beneficiary status.
Allowed values:
relationshipStatusenumOptional
Relationship with the settlement bank.
Allowed values:
relationshipActivebooleanOptional
True when the relationship is active.
personTypeenumOptional
Allowed values:
taxNumberstringOptional
namestringOptional
legalNamestringOptional
tradeNamestringOptional
socialNamestringOptional
relationshipStartDatedateOptional
relationshipClosedAtdatetimeOptional
emailstringOptional
phonestringOptional
representativeNamestringOptional
representativeEmailstringOptional
representativePhonestringOptional
alertOriginatorslist of stringsOptional
ISPBs of institutions that raised alerts about this beneficiary.
updateddatetimeOptional
accountIdstringOptional
Present on the tenant list, when the tax number matches an account.
lastEventobjectOptional

Latest notice from the settlement bank about this account’s beneficiary. Same data as the boleto.charge.beneficiary.* webhooks. Absent until the first notice.

Errors

400
Bad Request Error
403
Forbidden Error
422
Unprocessable Entity Error
502
Bad Gateway Error