Gateway identity migration: legacy ids to Vector, Harbor and Plaza

Documentation index · Español

This release separates Payment Emulator's product identity from the third-party APIs it emulates. The emulator-owned gateway names are now Vector, Harbor and Plaza. Stripe, PayPal and Mercado Pago remain compatibility targets and source-provenance names only.

This is a breaking identity/URL migration for installations created before the independent gateway profiles were introduced. Wire contracts are deliberately kept compatible.

#Mapping

#Emulator-owned namespaces

These are emulator-owned prefixes. Provider protocol paths inside them do not change. For example, the compatible operations remain /v1/payment_intents, /v2/checkout/orders and /v1/orders. Prefixless SDK-compatible routing continues to resolve the gateway from the credential.

#Hosted checkout URLs

Generated persisted Vector and Harbor links are migrated automatically. Free-form caller metadata is never searched/replaced.

#Scenario and contract namespaces

Scenario keys move by prefix:

stripe/<scenario>       -> vector/<scenario>
paypal/<scenario>       -> harbor/<scenario>
mercadopago/<scenario>  -> plaza/<scenario>

Contract storage moves with the independent profile identity:

contracts/stripe/       -> contracts/vector/
contracts/paypal/       -> contracts/harbor/
contracts/mercadopago/  -> contracts/plaza/

The files may still name the real compatibility target in source attribution. That provenance must not be rewritten.

#Environment variable

One compatibility-contract setting was renamed:

MERCADOPAGO_CONTRACT_URL
    -> PLAZA_COMPATIBILITY_CONTRACT_URL

Update local env files, deployment secrets and CI variables before starting the new release. There are no permanent public aliases for the legacy gateway ids.

#What the database migration changes

Migration20260930210000 migrates:

• gateway ids;
• applications.provider and bound scenario keys;
• scenario provider/key/definition;
• payment intents, provider resources, traces and webhook event provider ids;
• provider-owned clearing and fee ledger account codes/names;
• emulator-generated Vector redirect URLs;
• emulator-generated Harbor HATEOAS links in provider resources and idempotent replay bodies.

It intentionally does not rewrite arbitrary metadata or historical trace payloads. Operator-created ledger account names are changed only when their account code proves they are provider-owned accounts.

The migration has a matching down() path and is covered by the branding migration semantic certification.

#What does not change

• provider wire API shapes;
• provider-specific HTTP headers;
• official SDK vocabulary and compatibility tests;
• official contract source attribution;
• canonical money, ledger, idempotency and webhook architecture;
• the rule that the emulator never calls a real provider API at runtime.

Third-party names therefore remain where they describe a real external contract. They are no longer the emulator's gateway identity.

#Upgrade procedure

1. Back up the database. For a PostgreSQL installation with DATABASE_URL available:

   bash Copy

   pg_dump "$DATABASE_URL" > payment-emulator-before-gateway-identity.sql
   

   Use your normal managed-database snapshot procedure instead when applicable.

2. Record the current application release and keep the previous build available for rollback.

3. Rename configuration from MERCADOPAGO_CONTRACT_URL to PLAZA_COMPATIBILITY_CONTRACT_URL wherever it is set.

4. Deploy the new code and run the normal migration command. The project setup/update tooling already runs database migrations; a manual deployment can run the existing API migration CLI used by that environment.

5. Update clients that use emulator-owned prefixed URLs to /vector, /harbor or /plaza. Integrations using an official SDK against the prefixless compatibility surface do not need to rename provider protocol paths.

6. Update saved checkout links, scenario names and local contract tooling if they were hard-coded outside the database.

7. Restart API, worker, Console and Checkout using the normal deployment procedure.

#Post-upgrade validation

Run the repository gates:

npm ci
npm run docs:check
npm run brand:check
npm run typecheck
npm run lint
npm test
npm run test:checkout
npm run test:cli
npm run test:docs
npm run build
npm run certify:branding-migration --workspace @payment-emulator/api
npm run smoke

For a production-like acceptance run, also execute the Docker Compose CI path or the equivalent deployment health checks. Confirm that Console and Checkout show Vector, Harbor and Plaza, and that no application configuration still contains the old runtime ids.

#Rollback

If rollback is required before accepting new traffic:

1. stop application processes;
2. deploy the previous application release;
3. run the matching migration down() path, or restore the pre-upgrade database backup/snapshot;
4. restore the legacy environment variable name expected by that release;
5. restart and run its health/smoke checks.

Prefer restoring the database backup if other incompatible schema changes were deployed at the same time. This identity migration itself supports semantic up -> down -> up certification, including provider-owned ledger identifiers and generated replay URLs.

#Compatibility policy after this migration

Legacy ids are migration inputs, not permanent runtime aliases. Do not re-add stripe, paypal or mercadopago as product ids, public gateway names or emulator-owned route namespaces. If a third-party name is required by an SDK, header, wire field or source document, keep it there and describe it explicitly as compatibility.