external-id

Unique identifier for your app installation at a store. It ties every call originating from the end customer's browser (CDN, tokenization, Apple Pay) to the correct merchant on Appmax.

This page is the central reference. Other pages link here instead of repeating the content.

external-id vs external_id convention

The same identifier appears with two spellings throughout the docs — it is the same value, in different formats:

Spelling	Where it appears
external_id	JSON body of the health check ({ "external_id": "..." }), field stored in your database.
external-id	Name of the HTTP header sent on CDN calls to the payment gateway.

This follows standard HTTP conventions (headers in kebab-case, JSON in snake_case). Mentally treat it as the same value — the string is identical between formats.

What it is

The external-id is an identifier, not a secret. It identifies the pair (installed app + store) to the platform. When your front-end calls the payment gateway, Appmax uses the external-id to identify the store and run the operation in the correct context.

Key points:

• It is not a credential. It does not authenticate the call. Authentication of the gateway route is handled by Appmax (internal gateway), not by the integrator.
• You are the one who generates it. The value originates on your side during installation — Appmax only persists and validates it.
• It is not sensitive enough to require a vault, but treat it as store configuration: persisted in your database, linked to the merchant, read on every checkout page render.

The lifecycle of the external_id is:

The external_id is generated by the integrator during the health check. Appmax only persists and validates — it does not invent this value. The same UUID that originates on your side in step 6 comes back in step 11 as the CDN header.

What counts is the value you responded with

Appmax persists the external_id that came in your health check response body. That one, and only that one, is what it recognizes afterwards — in the header of CDN calls and in Appmax JS's init().

Two practical consequences:

• Don't store a value different from the one you returned. The most common mistake is generating a UUID, responding with it, and persisting a different one in your own database. The two sides diverge from then on, and the checkout fails with 404 Merchant not found.
• Don't regenerate the value later. The external_id identifies that installation for as long as it exists: it is the same value on every checkout render, until the merchant reinstalls the app (see When external_id changes).

The uniqueness requirement is per installation: the value must not already be bound to another installation on the partner's account.

Where it comes from

The external_id is defined during the app's installation at a store. The flow:

1. You start the installation by calling POST /app/authorize.
2. The merchant authorizes in the Appmax panel and is redirected to your url_callback with a token.
3. You exchange the token for credentials by calling POST /app/client/generate.
4. While processing that call, Appmax performs a server-to-server health check against the validation URL configured in your app panel.
5. Your validation URL responds with HTTP 200 and a JSON body containing external_id (UUID).
6. Appmax internally persists the binding between that external_id and the store.

The external_id you return in this health check is the same value you must send as the external-id header on every subsequent CDN call for that store.

Format details (UUID v1-v5, uniqueness, validation) in Health check.

Persist it at generation time

When your callback handler generates the external_id to answer the health check, store that value in your database linked to the merchant. You will need it on every checkout render for that merchant. See Automating credential creation.

Where it is used

You consume external_id through the public methods of Appmax JS — the script wraps the HTTP transport to Appmax and propagates the identifier wherever needed. Contexts where it shows up:

1. Script initialization — AppmaxScripts.init

At the merchant's checkout, externalId is one of the init options:

window.AppmaxScripts.init({ externalId, onIp, onTokenize, onError });

// Positional form, kept for backward compatibility:
window.AppmaxScripts.init(onSuccess, onError, externalId, onUpdate, onAuthorize);

Without it, card tokenization fails with MISSING_EXTERNAL_ID in onError, and Apple Pay initialization throws synchronously — in both cases before any HTTP call is made.

2. Card form submit — data-appmax-checkout

Any <form data-appmax-checkout> in the DOM triggers card tokenization through the CDN on submit. The script reuses the externalId provided in init — you don't need to repeat it or touch the HTTP headers.

<form data-appmax-checkout>
  <input name="card_number" />
  <input name="card_cvv" />
  ...
</form>

The card token arrives back in your code via the onTokenize({ token }) callback — see Appmax JS.

3. Apple Pay — onAuthorize

When the user taps the Apple Pay button, the script opens Safari's PaymentSheet, runs Apple's merchant validation (using externalId under the hood) and delivers the appleToken via the onAuthorize callback you set on init. You don't call any endpoint yourself — just take the token and send it to POST /v1/payments/apple-pay from your backend.

You typically don't write any HTTP call to scripts.appmax.com.br manually — appmax.js does it for you. The Tokenization and Apple Pay merchant session pages exist for advanced cases (custom implementation without the script) and for debugging.

When NOT to use external-id

external-id belongs exclusively to calls originating from the browser via Appmax JS. Everywhere else — especially on your backend — it has no role.

Do not send external-id on server-to-server calls made by your backend to api.appmax.com.br (creating a customer, creating an order, payment, recurring billing, split, etc.). Those calls use Authorization: Bearer with the merchant token obtained via /oauth2/token — the store context comes from the JWT itself.

Summary:

Call origin	How to authenticate	Where does external_id go?
Backend → api.appmax.com.br (transactional)	Authorization: Bearer <merchant_token>	Not sent — context comes from JWT.
Browser → Appmax JS (AppmaxScripts.init, data-appmax-checkout form, Apple Pay)	Configured once in init	The script propagates internally; you don't touch headers or body.

When external_id changes

The external_id is stable while the installation is active. However:

• Reinstalling the app at the same store generates a new external_id. This holds both when the merchant removes and reinstalls your application and when they reinstall without removing, picking the same store on the authorization screen (see Reusing an existing store on installation). In both cases the old value stops working and the front-end must be updated with the new one.
• Different stores of the same merchant have different external_id values. Each (installed app, store) pair has its own — they cannot be shared across stores.

Recommendation: treat the external_id as live data. Do not hardcode it in code or in environment variables — read it from your database on every checkout render, keyed by the merchant.

Common errors and diagnosis

Response	Where it appears	Likely cause	How to fix
401 Missing Authorization token	HTTP response from the gateway	The call reached the gateway without the external-id header and without Authorization.	Confirm the CDN script was initialized with the correct externalId before the form submit.
404 Merchant not found	HTTP response from the gateway	The value sent in external-id does not match any active installation.	Verify the front-end is using this store's external_id, not another's. Confirm the installation is active.
404 Client id not found	HTTP response from the gateway	The external_id exists, but the store's credential binding is incomplete.	Open a support ticket. This usually indicates a half-finished installation.
MISSING_EXTERNAL_ID (in onError) / External ID is required (synchronous throw in the Apple Pay flow)	Script error in the browser	AppmaxScripts.init(...) was called without externalId, or with an empty value.	Make sure your template renders the store's externalId before calling init.

Best practices

• Persist the external_id in your database alongside the merchant's client_id and client_secret. See the example in Automating credential creation.
• Never hardcode the value. There is no "default" or "test" value — each installation has its own.
• Read it from the database on every checkout render. If you cache in session state, invalidate when the merchant reinstalls the app.
• Do not expose the external_id unnecessarily in public logs or third-party trackers. It is not a secret, but it is installation data — keep basic data hygiene.
• Handle front-end script errors: if onError receives MISSING_EXTERNAL_ID, log the error and show the user a "checkout temporarily unavailable, please try again" message — do not let the submit silently break.

See also

• App installation — full flow where the external_id is generated.
• Installation callback — redirect handler that receives the token.
• Automating credential creation — tutorial that persists credentials and the external_id.
• Appmax JS — CDN script that consumes externalId in init.
• Apple Pay payment — using externalId in the Apple Pay session.