Security recommendations
What we ask of anyone integrating the API, and what each item prevents. Nothing here changes the contract: what is optional stays optional. What changes is how much risk analysis can see of each operation.
Send the user’s context on every outgoing payment
When the call leaves your server on the customer’s behalf, the connection IP is your server’s. Without anything else, every outgoing payment from every customer looks like the same origin, and the account’s cashoutSourceIps lock has nothing to evaluate either.
Send the context of the person on the other side of the screen. It applies to PIX out, TED, boleto, internal transfer and PIX batch, on an integrator credential.
None of these headers is required, and none of them rejects a payment. An invalid or oversized value is dropped and the operation proceeds. A delegated credential ignores all of them: the caller is the owner, and the connection IP is already theirs.
Two effects, both on your side:
- A legitimate customer sees fewer wrongful blocks. Risk is assessed per person, not per server that concentrates everyone.
- Account takeover and out-of-pattern behavior are caught earlier by our fraud monitoring. If your own system is compromised, the impact is smaller: even with the credential, an attacker arrives with an IP, device and session that do not match that customer’s history, and that is what lets us stop the payment before the account is emptied.
Restrict where the credential calls the API from
The tenant IP allowlist is what actually blocks traffic from an unknown origin. It is not a policy: it lives on the portal’s Security screen (/dashboard/ip-allowlist) or at PUT /v1/security/ip-allowlist. Writing it requires a portal user token. An M2M credential cannot edit its own allowlist.
A new tenant starts open: any IP is accepted until someone registers the first one. From then on, an origin outside the list gets 403 ip_not_allowed. CorpX egress addresses (backoffice and internet banking) are added on their own, show up as system and cannot be removed. A list that contains only those addresses counts as empty: the tenant goes back to open.
A tenant with delegated credentials cannot edit that list by hand (409 ip_allowlist_derived). The allowlist becomes per credential, at GET and PUT /v1/backoffice/tenants/{tenantId}/credentials/{clientId}/ip-allowlist. Adding an IP waits 18 hours; removing one takes effect immediately.
One credential per system
Ask only for the scopes the system uses. A credential that sends PIX, looks up DICT keys and opens accounts is a credential that, once leaked, does all three.
- Do not share the
client_secretbetween production and sandbox, or between systems. - Keep the secret in an environment variable or a vault, never in the customer app’s source.
- Reuse the token until close to expiry. One token per call is refused.
- When someone who had the secret leaves the team, revoke the credential and issue another. Changing the portal password does not invalidate an M2M credential.
Tenant policies and limits
Policies are yours: PIX out maximum, operating hours, blocked destinations, key-lookup limits. A rule that refuses at the edge never debits. Account amount limits are the second step, per operation and per day.
Without a policy, the only barrier on an outgoing payment is the balance and risk analysis. With a policy, a leaked credential still hits the cap and the hours you set.
Sign the webhook and accept only the right origin
Anyone who discovers the URL can forge an event. The webhook security section covers what we ask:
authType: HMACand verification ofX-Signatureover the raw body bytes. Re-serializing the JSON breaks the signature.- Allow only the delivery IPs listed on that page through your firewall.
- Treat
eventIdas an idempotency key: the same delivery can arrive more than once.
One key per payment
Resending the same outgoing payment without an Idempotency-Key creates another payment. Generate the key once, when the intent to pay is born, and reuse it on retry, on timeout and on a double click. The body’s identifier is the operation’s key in your system; together, they are what idempotency uses to return the original result instead of debiting again.
If you suspect fraud
In this order:
- Revoke the credential that may have leaked and issue another. While the old one is valid, whoever has it keeps operating.
- Tighten the outgoing policies: hours, amount and destination. That takes effect immediately and does not depend on anyone on the other side.
- Open a ticket at
suporte@corpx.comwith the time, the account and what you already blocked.
On our side, every outgoing payment goes through risk analysis before it leaves, and a received PIX under dispute follows MED.
Checklist
- Every outgoing payment sends
X-Acting-Ipwith the user’s IP, plus whatever else you have (X-Acting-Document, user-agent, device, session, geo). - The tenant IP allowlist is active, with your IPs and without leftovers from an old environment.
- Each system has its own credential, with the smallest scope that works.
- The
client_secretis not in the repository or in the customer app. - PIX out has a cap, operating hours and a key-lookup limit.
- The webhook endpoint validates HMAC on the raw body and accepts only the delivery IPs.
- Each payment is born with an
Idempotency-Keythat the retry reuses. - Someone on the team knows how to revoke the credential and who to call if they suspect fraud.