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_pendingandRetry-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, andmessagecarries 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
accountId
Account identifier.
Headers
X-Tenant-Id
Tenant context used for authorization and routing.
Idempotency-Key
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.
beneficiaryId
Settlement-bank beneficiary id.
identifier
Beneficiary identifier.
status
Beneficiary status.
Allowed values:
relationshipStatus
Relationship with the settlement bank.
Allowed values:
relationshipActive
True when the relationship is active.
personType
Allowed values:
taxNumber
name
legalName
tradeName
relationshipStartDate
relationshipClosedAt
email
phone
representativeName
representativeEmail
representativePhone
alertOriginators
ISPBs of institutions that raised alerts about this beneficiary.
updated
accountId
Present on the tenant list, when the tax number matches an account.
lastEvent
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