Testing in staging

Base URLs

New integrations should use stg.portal.eprospera.com.

Both legacy hostnames remain supported until their planned retirement in February 2027:

• Portal/API: staging-portal.eprospera.com.
• Auth0 browser login: auth.staging-portal.eprospera.com.

The exact cutoff day is still to be confirmed. The Auth0 login-domain migration is a separate cutover; continue using the configured login issuer until that cutover is announced.

For partner OAuth, use the issuer and endpoints returned by discovery; the token issuer may continue to advertise the legacy portal hostname during this transition. Do not infer the issuer from the API base URL or switch issuers midway through a session. Register exact callback URLs.

Getting access

Create or sign in to your account in the staging portal, then open Developer to create a standard API key or an Agent Key.

Staging mirrors the production API and OAuth behavior unless noted, but its accounts, data, credentials, and payment setup are separate. Create the key in the environment you want to test.

Some write operations require an active residency. You can apply for residency in the staging portal without affecting production.

OAuth clients are not self-service. If your integration needs OAuth / OIDC, request a staging client through the e-Próspera Help Center chat.

Making requests

For API-key requests with the CLI, select staging and the preferred API hostname:

export EPROSPERA_API_KEY="<your-staging-api-key>"
export EPROSPERA_BASE_URL=https://stg.portal.eprospera.com
EPROSPERA_ENV=staging eprospera --json entity verify 80000000000012

For direct HTTP, use the staging base URL:

curl -X POST https://stg.portal.eprospera.com/api/v1/verify_rpn \
  -H "Authorization: Bearer <your-staging-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"rpn": "80000000000012"}'

See the quickstart for more details.

OAuth in staging

OAuth uses the same authorization flow as production, but it requires a separately provisioned staging client and the staging issuer's discovery document. See the OAuth overview for the full flow. The published OpenAPI document targets production; selecting a different API base URL does not change its absolute OAuth URLs.

After the staging client is provisioned, its owner can add redirect URIs from Developer. To test with a partner application running locally, register the complete callback it listens on. For example:

http://127.0.0.1:3001/auth/oauth2/callback/prospera

Staging accepts HTTP callbacks only when they use one of these loopback hosts:

http://127.0.0.1:<port>/<callback-path>
http://[::1]:<port>/<callback-path>
http://localhost:<port>/<callback-path>

Prefer 127.0.0.1 or [::1] for new integrations. Load the staging issuer's discovery document:

https://staging-portal.eprospera.com/.well-known/openid-configuration

Use its issuer, authorization_endpoint, and token_endpoint values throughout the flow. The current staging issuer is https://staging-portal.eprospera.com; do not substitute the preferred API hostname into OAuth endpoint URLs.

The authorization and token requests must send the registered redirect_uri exactly, including its scheme, host, port, path, query, and trailing slash. Run the local application on the registered port before completing authorization in the browser.

Testing payments

Staging never charges a real card. Use the reusable voucher for a fully covering, no-cost payment, or complete hosted checkout with Stripe's test card.

Standard API keys and Partner Keys can test both voucher payment and hosted checkout. Agent Keys support voucher payment only.

Reusable voucher

API1234 applies to every product and unpaid invoice in staging — residency applications (portal and partner), entity incorporation, insurance, tax, and other portal purchases — not only LLC formation:

API1234

Enter it on the checkout Have a discount code or voucher? field, or send it on the voucher endpoints:

EPROSPERA_ENV=staging eprospera --json --yes application pay <id> --voucher API1234

curl -X POST https://stg.portal.eprospera.com/api/v1/legal_entity_applications/<id>/pay/voucher \
  -H "Authorization: Bearer <your-staging-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"voucherCode": "API1234"}'

Partner integrations use the same code on POST /api/v1/partner/residency_applications/{id}/pay/voucher. The voucher must still fully cover the invoice, and API voucher payment is limited to API-created Drafts.

Stripe test card

Hosted checkout in staging uses Stripe test mode. When the checkout page asks for a card, use Stripe's Visa test card:

This card never works in production. Do not use a real card in staging.

Create the session as usual with paymentProvider: "stripe" (or --provider stripe on the CLI), then complete the hosted page with the test card. Agent Keys cannot create checkout sessions; use API1234 instead.

See Stripe's test cards for declines, 3D Secure, and other cases.

Partner Keys in staging

Partner Keys are not self-service in staging either. Request a staging integration and key through the Help Center chat as described in Partner onboarding. Staging behaves like production with these differences:

• Application approval requires human review. Automatic resident and entity application approvals start paused in both staging and production. Submitted applications stay in Pending Review until reviewed. Coordinate an approval or rejection with the e-Próspera team when testing those outcomes.
• Real emails. The applicant claim-account email is sent to whatever address you submit. Use addresses you control, and use a fresh alias per run so you can observe the first-time claim behavior.
• Identity verification. In the hosted portal path, the applicant completes Veriff's test flow in the staging portal. In the embedded flow, staging simulates Veriff's decision: a submitted test session attached to an active embed is marked approved after a short delay, and the normal KYC_COMPLETED and APPLICATION_SUBMITTED events follow. Veriff's own dashboard may still show the session as submitted. Production always waits for Veriff's real signed decision.
• Payment. Use voucher API1234 on the partner voucher endpoint, or Stripe hosted checkout with the test card above. Blink and Solana Pay checkout are not exercised in staging tests.
• Embed origins. Staging accepts loopback HTTP embed and redirect origins such as http://localhost:3000 for local development. Production requires HTTPS.

Run the pre-production checklist against staging before requesting a production key.

Filings and documents

Use the amendments and certificates walkthrough to create a draft, complete hosted signing, pay with API1234, poll review, and retrieve generated PDFs. Test repeat payment and submission against the same ID. Confirm a removed representative, a revoked key, and an unrelated entity cannot read or mutate the filing. Test personal and partner applicant documents with their distinct credentials. A paid invoice alone does not mean a certificate or amendment document has been generated.