Skip to navigation
API Internet BankingPeople

Set or change a person's transaction PIN

The PIN belongs to the person (X-Acting-Document) inside the tenant, and is the same PIN on every account that person operates. Requires scope pin.manage. The CPF is a header, not a path segment: API Gateway access logs store the path.

The first enrollment does not send currentPin. Replacing an existing PIN requires currentPin. When hosted reset is on, a replacement without currentPin returns 403 pin_change_disabled; a replacement with the correct currentPin succeeds. After DELETE, a PUT without currentPin re-enrolls only while hosted reset is off.

Authentication

AuthorizationBearer

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

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
X-Acting-DocumentstringRequired
CPF of the person, 11 digits.
Idempotency-KeystringOptional

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

X-Request-TimestampstringRequired

Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

X-Request-SignaturestringRequired

Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.

Request

This endpoint expects an object.
pinstringRequired6-12 characters
currentPinstringOptional
Required when replacing an existing PIN.

Response

PIN created, replaced or re-enrolled.

documentstringOptional
Masked CPF.
statusenumOptional
Allowed values:

Errors

403
Forbidden Error
422
Unprocessable Entity Error
423
Locked Error