API Processing Type
EBANX processes payments on two tenants — Cross-border and Local — and each tenant has its own base URL, as described in API Endpoints. The X-EBANX-API-Processing-Type header lets you process a request on the Local tenant while still sending it to the Cross-border base URL.
When to use it
Send the request to the Local base URL whenever you can: it is the explicit, recommended way to process on the Local tenant, and it keeps tenant selection visible in your integration.
Use the header when your integration must keep a single base URL for both tenants — for example, when the base URL is fixed by a platform, a connector, or an internal gateway you do not control, and only a per-request decision is available to you.
How it works
Send the header with the value local on a request to a Cross-border base URL, and EBANX processes it on the Local tenant:
curl -X POST \
--location 'https://sandbox.ebanxpay.com/ws/direct' \
--header 'Content-Type: application/json' \
--header 'X-EBANX-API-Processing-Type: local' \
--data '{
"integration_key": "{{integration_key}}",
"payment": {
"amount_total": 99.85,
"currency_code": "BRL",
"name": "John Doe",
"email": "john.doe@example.com",
"country": "br",
"payment_type_code": "pix",
"merchant_payment_code": "{{unique_merchant_code}}",
"document": "{{tax_id}}"
}
}'
The request above is equivalent to sending the same body, with no extra header, to the Local base URL:
curl -X POST \
--location 'https://sandbox-local-latam.ebanxpay.com/ws/direct' \
--header 'Content-Type: application/json' \
--data '{ ... }'
The method, path, query string, and body are preserved, and you receive the response produced by the Local tenant — including its error responses and any redirect it returns.
Behavior
| Request | Result |
|---|---|
Header value local on a Cross-border base URL | Processed on the Local tenant |
| Header absent, or any other value | Processed on the Cross-border tenant |
| Header on a Local base URL | Ignored — the request is already on the Local tenant |
The value is not case-sensitive: local and Local behave the same. The header applies per request, so you can mix Cross-border and Local traffic on the same base URL, except for the endpoints in Endpoint scope.
A request with this header is authenticated by the Local tenant, so the integration key you send must be active for your Local merchant account. Sending a key that only exists on the Cross-border tenant returns an authentication error. Contact your EBANX account manager to have your keys enabled on both tenants.
Payment method availability differs per country and tenant. Before switching a payment to the Local tenant, check the method in Payment Methods by Country. For a broader comparison of both models, see API Operability.
Endpoint scope
Some endpoints require you to call the base URL of the tenant that owns the resource, and the header does not change where they are processed. POST /ws/chargeback/send-evidence is one of them: its JWS kid is registered per tenant and environment, so submit dispute evidence directly to the base URL matching the chargeback's tenant and environment, as described in Chargeback Dispute.
Limits
Requests using the header depend on internal routing between tenants, which adds latency to the response and is subject to an internal timeout. If the Local tenant cannot be reached, the API returns HTTP 500 — retry the request with the same merchant_payment_code to avoid duplicate payments.
Environments are never mixed: a request to a sandbox base URL is processed on the Local sandbox, and a request to a production base URL is processed on Local production.