Testing in staging

Base 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

With the CLI, set EPROSPERA_ENV=staging:

export EPROSPERA_API_KEY="<your-staging-api-key>"
EPROSPERA_ENV=staging eprospera --json entity verify 80000000000012

For direct HTTP, use the staging base URL:

curl -X POST https://staging-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 at the staging base URL, but it requires a separately provisioned staging client. See the OAuth overview for the full flow.

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. Then use the staging OAuth endpoints throughout the flow:

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://staging-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.