# Testing in staging (/testing-in-staging) Use separate staging accounts and credentials to test e-Próspera API, OAuth, and payments. Voucher API1234 covers every product; Stripe test card ACCT-000015. ## Base URLs [#base-urls] | Environment | Base URL | | ----------- | ---------------------------------- | | Production | `https://portal.eprospera.com` | | Staging | `https://stg.portal.eprospera.com` | 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 [#getting-access] Create or sign in to your account in the [staging portal](https://stg.portal.eprospera.com), then open [Developer](https://stg.portal.eprospera.com/developer) to create a [standard API key](/standard-keys) or an [Agent Key](/agent-keys). 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](https://help.eprospera.com/en/chat). ## Making requests [#making-requests] For API-key requests with the CLI, select staging and the preferred API hostname: ```bash export EPROSPERA_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: ```bash curl -X POST https://stg.portal.eprospera.com/api/v1/verify_rpn \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"rpn": "80000000000012"}' ``` See the [quickstart](/getting-started) for more details. ## OAuth in staging [#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](/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](https://stg.portal.eprospera.com/developer). To test with a partner application running locally, register the complete callback it listens on. For example: ```text http://127.0.0.1:3001/auth/oauth2/callback/prospera ``` Staging accepts HTTP callbacks only when they use one of these loopback hosts: ```text http://127.0.0.1:/ http://[::1]:/ http://localhost:/ ``` Prefer `127.0.0.1` or `[::1]` for new integrations. Load the staging issuer's discovery document: ```text 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. The loopback HTTP exception is available only in development and staging. Production rejects `http://127.0.0.1`, `http://[::1]`, and `http://localhost`, even if an older HTTP callback remains stored. Register the partner application's deployed HTTPS callback before testing against production. ## Testing payments [#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 [#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: ```text API1234 ``` Enter it on the checkout **Have a discount code or voucher?** field, or send it on the voucher endpoints: ```bash EPROSPERA_ENV=staging eprospera --json --yes application pay --voucher API1234 ``` ```bash curl -X POST https://stg.portal.eprospera.com/api/v1/legal_entity_applications//pay/voucher \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"voucherCode": "API1234"}' ``` Partner integrations use the same code on [`POST /api/v1/partner/residency_applications/{id}/pay/voucher`](/reference/post-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 [#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](https://docs.stripe.com/testing#cards): | Field | Value | | ----------------- | --------------- | | Card number | `ACCT-000015` | | Expiry | Any future date | | CVC | Any 3 digits | | ZIP / postal code | Any value | 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](https://docs.stripe.com/testing#cards) for declines, 3D Secure, and other cases. ## Partner Keys in staging [#partner-keys-in-staging] Partner Keys are not self-service in staging either. Request a staging integration and key through the [Help Center chat](https://help.eprospera.com/en/chat) as described in [Partner onboarding](/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](/partner-embed), 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](/partner-onboarding#before-a-production-key-is-issued) against staging before requesting a production key. ## Filings and documents [#filings-and-documents] Use the [amendments and certificates walkthrough](/entity-filings) 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.