Sandbox and Testing

UrbanPayX provides a full sandbox environment for testing your integration before going live. The sandbox behaves identically to production with a few key differences that make testing faster and easier.

Sandbox vs. production

	Sandbox	Production
Base URL	`api-sandbox.urbanpayx.com`	`api.urbanpayx.com`
OpCo approval time	Minutes	3-5 business days
Real money	No — test transactions only	Yes
Bank connections	Test bank accounts	Real bank accounts
KYC verification	Test mode (simulated)	Full identity verification
Rate limits	Same as production	Same as sandbox
API behavior	Identical	Identical

The sandbox uses the same API endpoints, authentication, and business logic as production. The only differences are the base URL, approval speed, and the fact that no real money moves.

Getting started with sandbox

1. Get your credentials

Your sandbox API key and secret are available in the UrbanPayX dashboard. If you do not have an account yet, contact the UrbanPayX team to get one provisioned.

2. Authenticate

POST https://api-sandbox.urbanpayx.com/api/v1/auth/api-token
Content-Type: application/json

{
  "api_key": "your-sandbox-api-key",
  "api_secret": "your-sandbox-api-secret"
}

3. Follow the Getting Started guide

The Getting Started guide walks you through the full flow — creating an OpCo, setting up a Project, adding a User, and generating your first payment link. In sandbox, the entire flow can be completed in about 15 minutes.

Testing the full payment flow

Step-by-step test scenario

Create and submit an OpCo — In sandbox, approval takes minutes. Poll the status or listen for the opco.status_changed webhook.
Create a Project under your activated OpCo.
Create a User and complete verification:
- For urbanpayx_kyc mode: Initiate verification and complete the hosted flow with test documents
- For external_attestation mode: Set the status to verified via the API
Set your callback URL — PUT /auth/client/settings with a URL where users will be redirected after checkout.
Generate a payment link — POST /checkout/paylink with amount, currency (EUR), user_id, and project_id. Include an X-Idempotency-Key header.
Open the checkout URL — The response includes a checkout_url. Open it in a browser to see the payment flow.
Complete the payment — Use the sandbox test bank to authorize the payment.
Verify the webhook — Your webhook endpoint should receive a payment.status_changed event with current_status: success.

Test bank credentials

In sandbox, the checkout page connects to test banks. Use these credentials to simulate different scenarios:

Sandbox Test Bank:

Available in the bank selection screen during checkout
Select the sandbox/test bank option
Follow the prompts to authorize the test payment

The sandbox bank simulates the full open banking flow including bank selection, authentication, and payment authorization — without moving real money.

Testing webhooks

Send a test event

You can trigger a test webhook at any time to verify your endpoint is configured correctly:

POST /api/v1/webhooks/subscription/test
Authorization: Bearer YOUR_ACCESS_TOKEN

This sends a webhook.test event to your configured webhook URL. The response includes an event_id you can use to track delivery.

Required role: OWNER or DEVELOPER

Webhook event types

Event	When it fires
`payment.status_changed`	Transaction status changes (pending to processing to success/failed/expired/canceled)
`kyc.status_changed`	User KYC status changes (none to pending to approved/rejected)
`opco.status_changed`	OpCo status changes (draft to awaiting_approval to activated/rejected)
`project.frozen_changed`	Project freeze status changes
`webhook.test`	When you call the test endpoint

Verifying webhook signatures

Every webhook includes security headers for verification:

Header	Description
`X-UPX-Signature`	HMAC-SHA256 signature of the payload
`X-UPX-Timestamp`	Unix timestamp when the event was sent

Verify the signature by computing HMAC-SHA256(payload_body, your_webhook_secret) and comparing it to the X-UPX-Signature header value. This ensures the event genuinely came from UrbanPayX and was not tampered with.

Your webhook secret is available in your webhook subscription settings. You can rotate it at any time via POST /webhooks/subscription/rotate-secret.

Webhook delivery and retries

If your endpoint does not return a 2xx response, UrbanPayX retries delivery with exponential backoff:

Max attempts: 8
Max backoff: 1 hour between retries
Deduplication: Each event has a unique key — duplicate deliveries are prevented at the database level

Simulating transaction outcomes

In sandbox, transaction outcomes depend on the test bank behavior during checkout:

To simulate	What to do
Success	Complete the full checkout flow — select bank, authenticate, authorize payment
Failed	Reject or cancel the payment during bank authentication
Expired	Generate a payment link and let it expire without completing checkout
Canceled	Start checkout but abandon before authorizing

Checking transaction status

You can check the current status of any transaction:

GET /api/v1/transactions/{transaction_id}
Authorization: Bearer YOUR_ACCESS_TOKEN

Or force a status refresh from the payment provider:

POST /api/v1/transactions/{transaction_id}/refresh-status
Authorization: Bearer YOUR_ACCESS_TOKEN

The refresh endpoint is rate-limited — if you call it too frequently, you will receive a 429 with a retry-after value. Use webhooks as your primary mechanism and reserve polling for edge cases.

Testing OpCo approval

In sandbox, OpCo approval is handled through the same polling mechanism as production, but the approval process is faster:

Submit your OpCo via PATCH /opcos/{opco_id}/submit
The system polls the upstream provider for status updates
First poll happens after 30 seconds
In sandbox, approval typically completes within a few minutes

You can monitor progress via:

The opco.status_changed webhook event
Polling GET /opcos/{opco_id} to check the status field

Testing KYC verification

UrbanPayX KYC mode

In sandbox, the hosted verification page accepts test documents. The verification provider operates in test mode, so:

Use any government ID document image for the document upload step
The liveness check is simplified in test mode
Approval/rejection is processed faster than in production

External attestation mode

No difference between sandbox and production — you control the verification status directly via the API:

POST /api/v1/kyc/external/status/{user_id}
{
  "status": "verified",
  "provider": "test",
  "reference": "test-ref-001"
}

Rate limits

Rate limits are the same in sandbox and production:

Scope	Limit	Lockout
Login attempts (per email)	5 failures	5-minute lockout
API key auth attempts	5 failures	5-minute lockout
OTP resend	1 per 60 seconds	60-second cooldown
Transaction refresh	Per-transaction cooldown	Varies (check `429` response)

Checklist before going to production

Before switching from sandbox to production, verify:

Related guides

Getting Started — Complete the full flow in 15 minutes
Transaction Lifecycle — Understand payment statuses and webhooks
Authentication Guide — Token management for your integration
Error Reference — Troubleshoot common errors