> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# 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.

| Header                | What to send                                                  | Limit          |
| --------------------- | ------------------------------------------------------------- | -------------- |
| `X-Acting-Ip`         | The user's real IP, not your server's                         | IPv4 or IPv6   |
| `X-Acting-Document`   | CPF of the person operating the payment                       | 11 digits      |
| `X-Acting-User-Agent` | User-agent of the browser or app                              | 512 characters |
| `X-Acting-Device-Id`  | Device identifier from your system                            | 128 characters |
| `X-Acting-Session-Id` | The user's session in your system                             | 128 characters |
| `X-Acting-Geo`        | `latitude,longitude` in decimal degrees (`-22.9068,-43.1729`) | valid range    |

```bash
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](/baas/guias/autenticacao/oauth2) 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](/baas/guias/autenticacao/politicas) are yours: PIX out maximum, operating hours, blocked destinations, key-lookup limits. A rule that refuses at the edge never debits. Account [amount limits](/baas/guias/pagar/limites) 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](/baas/guias/conta/webhooks) 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](/baas/guias/comece-aqui/idempotencia) 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](/baas/guias/autenticacao/politicas): 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](/baas/guias/pagar/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.