Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

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:

Shell
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:

Shell
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​

RequestResult
Header value local on a Cross-border base URLProcessed on the Local tenant
Header absent, or any other valueProcessed on the Cross-border tenant
Header on a Local base URLIgnored — 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.

Use credentials valid on the Local tenant

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.

Info

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.