Skip to navigation

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.

HeaderWhat to sendLimit
X-Acting-IpThe user’s real IP, not your server’sIPv4 or IPv6
X-Acting-DocumentCPF of the person operating the payment11 digits
X-Acting-User-AgentUser-agent of the 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
curl -X POST "https://tenant.api.corpx.com/v1/accounts/acc-123/pix/payments" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: tenant-yourcompany" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "X-Acting-Document: 12345678909" \
-H "X-Acting-Ip: 200.10.20.30" \
-H "X-Acting-User-Agent: MyApp/4.2 (Android 14)" \
-H "X-Acting-Device-Id: dev_8f3a1c" \
-H "X-Acting-Session-Id: sess_19ab" \
-H "X-Acting-Geo: -22.9068,-43.1729" \
-H "Content-Type: application/json" \
-d '{ "pixKey": "customer@email.com", "amount": "150.00" }'

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_secret between 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: HMAC and verification of X-Signature over the raw body bytes. Re-serializing the JSON breaks the signature.
  • Allow only the delivery IPs listed on that page through your firewall.
  • Treat eventId as 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:

  1. Revoke the credential that may have leaked and issue another. While the old one is valid, whoever has it keeps operating.
  2. Tighten the outgoing policies: hours, amount and destination. That takes effect immediately and does not depend on anyone on the other side.
  3. Open a ticket at suporte@corpx.com with 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-Ip with 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_secret is 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-Key that the retry reuses.
  • Someone on the team knows how to revoke the credential and who to call if they suspect fraud.