Skip to navigation

Account Security

Three controls the account holder configures and the API then enforces on every attempt to move money out: cashout locks, transaction PIN and visibility of who else has access to the account.

They exist for the scenario where the integrator’s credential and token are correct — and it is the account holder’s session that was taken over. Nothing here is opt-out per request: what the holder configured applies even to the credential that configured it.

Nothing changes if you do not use it

Every account starts with no lock and no PIN, and behaves exactly as it does today. The controls only apply once configured.

Cashout locks

account security locks are three independent limits:

FieldEffect
cashoutBlockedtrue rejects every outgoing payment from the account
cashoutHoursOnly allows outgoing payments inside the window (HH:MM, 24h, with timezone)
cashoutSourceIpsOnly allows outgoing payments from declared IPs/CIDRs

In P2P Crypto, an account that advertises buying has the order amount held from its own balance. So cashoutBlocked pauses its active buy ads, and outside cashoutHours they leave the book until the window opens. See Ads.

Read

curl "https://tenant.api.corpx.com/v1/accounts/acc-123/security/locks" \
-H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany"
{
"accountId": "acc-123",
"current": {
"cashoutBlocked": false,
"cashoutHours": { "start": "08:00", "end": "18:00", "timezone": "America/Sao_Paulo" },
"cashoutSourceIps": ["200.10.20.30/32"]
},
"updatedAt": "2026-09-19T12:00:00Z"
}

Write

PUT takes the whole desired document (scope security_locks.manage):

curl -X PUT "https://tenant.api.corpx.com/v1/accounts/acc-123/security/locks" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: tenant-yourcompany" \
-H "X-Acting-Document: 12345678909" \
-H "X-Acting-Ip: 200.10.20.30" \
-H "Content-Type: application/json" \
-d '{
"cashoutBlocked": false,
"cashoutHours": { "start": "08:00", "end": "18:00", "timezone": "America/Sao_Paulo" },
"cashoutSourceIps": ["200.10.20.30/32"]
}'

Tightening applies now; loosening waits 6 hours

This is the part that changes your flow, so it is worth reading closely: the decision is made field by field.

ChangeWhen it applies
Turning cashoutBlocked onImmediately
Turning cashoutBlocked off+6h
Narrowing cashoutHours, or adding a windowImmediately
Widening or removing cashoutHours+6h
Removing an IP from cashoutSourceIpsImmediately
Adding an IP, or removing the whole list+6h

Someone who turns the block on and widens the window in the same call gets the block now and the window later. The response says exactly that:

{
"accountId": "acc-123",
"current": { "cashoutBlocked": true, "cashoutHours": { "start": "08:00", "end": "18:00" } },
"pending": { "cashoutBlocked": true, "cashoutHours": { "start": "00:00", "end": "23:59" } },
"pendingEffectiveAt": "2026-09-19T18:00:00Z",
"pendingReason": "relaxing_security_requires_grace"
}

The asymmetry is the whole design: whoever took over the account wants to turn off the block, widen the window, add their own IP — never to tighten. A symmetric grace period would protect the attacker and punish the holder who is reacting to fraud in progress.

Cancelling or bringing forward the loosening

# Cancel: discards the pending change, current keeps applying. Immediate.
curl -X DELETE ".../v1/accounts/acc-123/security/locks/pending" ...
# Bring forward: promotes the pending change now. REQUIRES the operator's PIN.
curl -X POST ".../v1/accounts/acc-123/security/locks/pending/approve" \
-H "X-Acting-Document: 12345678909" \
-H "X-Transaction-Pin: 918273" ...

Bringing it forward is the only path that shortens the grace period, which is why it costs the one thing whoever hijacked the session does not have: the PIN. Without this endpoint, the legitimate holder who wants their own cashout back would have to wait 6h with no alternative.

X-Acting-Ip

When the call comes from a server of yours on the account holder’s behalf (the internet banking case), the connection IP is your server’s, not the end user’s. cashoutSourceIps would be useless. Pass the user’s real IP in X-Acting-Ip — that is the one the lock evaluates.

The header is only accepted from integrator credentials. A delegated credential is used directly by its owner, so the connection IP is already the right one and X-Acting-Ip is ignored.

End-user context

An integrator credential may also send the end user’s context. Every header is optional, feeds risk analysis, and never blocks the payment: an invalid or oversized value is dropped and the call continues.

HeaderWhat it isLimit
X-Acting-User-AgentUser-agent of the user’s browser or app512 characters
X-Acting-Device-IdDevice identifier from your system128 characters
X-Acting-Session-IdThe user’s session in your system128 characters
X-Acting-Geolatitude,longitude in decimal degrees (-22.9068,-43.1729)valid range

A delegated credential ignores these headers: the caller is the owner, and the connection IP is already theirs.

Errors

CodeHTTPWhen
cashout_locked423cashoutBlocked: true
cashout_outside_hours403Outside cashoutHours. The message states the window
cashout_source_ip_not_allowed403Source IP outside cashoutSourceIps
invalid_cashout_hours422Invalid HH:MM, start == end, or unknown timezone
no_pending_change404DELETE/approve with no scheduled loosening

Transaction PIN

The PIN belongs to the person (CPF in X-Acting-Document) inside the tenant, not to the account. Two accounts of the same CPF share the PIN and the failure counter. The new family is /v1/people/pin (the CPF is a header, not a path segment). The /v1/accounts/{accountId}/security/pin routes keep working, with the same JSON, and write that same PIN.

It is only required when the caller’s credential is marked for it — in practice, the internet banking credential, where a single credential serves many account holders and the token alone cannot tell who is on the other side of the screen.

Register and change

curl -X PUT "https://tenant.api.corpx.com/v1/accounts/acc-123/security/pin" \
-H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany" \
-H "Content-Type: application/json" \
-d '{ "actingDocument": "12345678909", "pin": "918273" }'
{ "accountId": "acc-123", "actingDocument": "123.***.***-09", "status": "created" }

Changing an existing PIN requires the current one in the same body (currentPin). Without that, whoever hijacked the session would simply change the PIN and the PIN would stop protecting anything.

The scope is pin.manage. The PIN never appears in a log or a response — it is stored as an argon2id hash and the clear value is discarded.

When reset on the CorpX page is enabled, a PUT without currentPin for a PIN that already exists returns 403 pin_change_disabled. Sending the correct currentPin still replaces the PIN while the page is on. The first enrollment does not send currentPin.

PIN rules

RuleValue
Length6 to 12 digits
Digits onlyYes
RejectedAll digits equal (111111), sequences including wrap-around (123456, 654321, 890123), short-period patterns (121212, 123123) and a PIN contained in the holder’s birth date or document

A rejected PIN returns 422 weak_pin with the reason named.

Use

On cashout routes (PIX out, TED, boleto, internal transfer), when the credential requires a PIN:

curl -X POST ".../v1/accounts/acc-123/pix/payments" \
-H "X-Acting-Document: 12345678909" \
-H "X-Transaction-Pin: 918273" ...

Missing either one returns 428 pin_required.

Lockout

Wrong attemptsEffect
315 minute lock (429 pin_temporarily_locked, with the Retry-After header)
6Locked until reset (423 pin_locked)

A correct PIN resets the counter. DELETE does not remove the row: it hard-locks the person’s PIN (423 pin_locked on cashout) and they stay enrolled, so the reset request below still works. The facial page also clears the lock.

curl -X DELETE "https://tenant.api.corpx.com/v1/people/pin" \
-H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany" \
-H "X-Acting-Document: 12345678909"

The alias DELETE /v1/accounts/{accountId}/security/pin/{document} applies the same lock. With the page turned off, a PUT without currentPin after that DELETE re-enrolls — that is the reset internet banking already does.

Reset on the CorpX page

curl -X POST "https://tenant.api.corpx.com/v1/accounts/acc-123/security/pin/reset-request" \
-H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany" \
-H "Content-Type: application/json" \
-d '{ "actingDocument": "52998224725", "displayMessage": "Confirm your face to choose a new PIN." }'
{
"resetId": "pinrst_8c1f6a2e-4d3b-4b9a-9f0e-1a2b3c4d5e6f",
"resetUrl": "https://tenant.api.corpx.com/v1/security/pin-reset#…",
"expiresAt": "2026-09-27T18:00:00Z"
}

The operator opens resetUrl, completes the facial check and, if it is approved, chooses the new PIN on that same page. The integrator never sees or chooses the value — this request body does not accept pin. displayMessage is optional plain text and is shown on the page as sent.

The page uses the tenant’s brand: the name, logo and colors configured for it, or the tenant’s registered name when no brand is set. CorpX appears only in the footer. The field accepts exactly 6 digits, the length the internet banking PIN keypad enters; PUT still accepts 6 to 12.

An existing PIN is required, including a PIN invalidated by DELETE. With none, the response is 409 pin_reset_not_enrolled and the first enrollment stays on PUT. When the page is not enabled for the tenant, the response is 403 feature_disabled. The link lasts 30 minutes. The fifth request for the same person in the same hour returns 429 pin_reset_rate_limited — the quota is per person, summed across accounts and across the alias. A new request expires earlier open links. The same request exists at POST /v1/people/pin/reset-request, with the CPF in X-Acting-Document.

Verify before building the payment

curl -X POST ".../v1/accounts/acc-123/security/pin/verify" \
-H "Content-Type: application/json" \
-d '{ "actingDocument": "12345678909", "pin": "918273" }'

This exists so the UI can confirm the PIN before the payment form. Without it, the user would only find out the PIN was wrong at the end of the flow — and each mistake would burn one of the 3 attempts. A wrong attempt here counts the same: the endpoint is not a free oracle.

Operator status

curl ".../v1/accounts/acc-123/security/pin/status" ...
{
"accountId": "acc-123",
"items": [
{ "actingDocument": "123.***.***-09", "failedAttempts": 0, "locked": false,
"setAt": "2026-09-19T12:00:00Z", "updatedAt": "2026-09-19T12:00:00Z" },
{ "actingDocument": "987.***.***-21", "failedAttempts": 6, "locked": true,
"lockedUntil": null, "requiresReset": true,
"setAt": "2026-09-01T10:00:00Z", "updatedAt": "2026-09-19T14:22:00Z" }
],
"policy": { "minLength": 6, "maxLength": 12, "softLockAfter": 3,
"softLockMinutes": 15, "hardLockAfter": 6,
"digitsOnly": true, "rejectsSequential": true }
}

Documents come back masked. lockedUntil: null with requiresReset: true is the hard lock — the way out is resetting, not waiting.

Errors

CodeHTTPWhen
pin_required428Cashout route without X-Acting-Document / X-Transaction-Pin
pin_invalid403Wrong PIN. The attempt was counted
pin_not_set403That person has no PIN in this tenant
pin_temporarily_locked4293 mistakes. Wait out the 15 minutes
pin_locked4236 mistakes, or a PIN invalidated by DELETE
weak_pin422PIN outside the policy
pin_not_found404DELETE for a person with no PIN
pin_change_disabled403Replacement without currentPin while hosted reset is on
pin_reset_not_enrolled409Reset requested for a person with no PIN
pin_reset_rate_limited429More than five requests for the same person in the last hour

Shared access

The same bank account can be reached by more than one tenant — the account holder hired two systems, or migrated from one to another and the old one still has access. The holder is entitled to see that:

curl ".../v1/accounts/acc-123/shared-access" \
-H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany"
{
"accountId": "acc-123",
"items": [
{ "tenantId": "tenant-yourcompany", "displayName": "Your Company",
"status": "active", "since": "2026-01-15T10:00:00Z", "isCurrent": true },
{ "tenantId": "tenant-other", "displayName": "Other Integrator",
"status": "suspended", "since": "2025-08-02T09:30:00Z", "isCurrent": false }
]
}

Public metadata only: display name, state and since when. No credentials, volume, balance or configuration of the other tenants. status is the state of that tenant’s access to the account, not of the tenant itself — a suspended row shows up precisely so the holder can confirm a revocation took effect.

Read scope. Revoking access is a backoffice operation, not this route.

See also

  • Security recommendations — what we ask of integrators: user context, IP allowlist, credentials and webhooks
  • Cashout — the outgoing routes where locks and PIN apply
  • Request Signing — the other half of the design: one credential per account
  • Errors — full catalog