# 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://staging-portal.eprospera.com` |

## Getting access [#getting-access]

Create or sign in to your account in the [staging portal](https://staging-portal.eprospera.com), then open [Developer](https://staging-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]

With the CLI, set `EPROSPERA_ENV=staging`:

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

For direct HTTP, use the staging base URL:

```bash
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](/getting-started) for more details.

## OAuth in staging [#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](/oauth-overview) for the full flow.

After the staging client is provisioned, its owner can add redirect URIs from
[Developer](https://staging-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:<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:

| Purpose       | Endpoint                                                   |
| ------------- | ---------------------------------------------------------- |
| Authorization | `https://staging-portal.eprospera.com/api/oauth/authorize` |
| Token         | `https://staging-portal.eprospera.com/api/oauth/token`     |

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.

<Callout title="Production remains HTTPS-only" type="warn">
  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.
</Callout>

## 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 &#x2A;*Have a discount code or voucher?** field, or send it on the voucher endpoints:

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

```bash
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`](/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.