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

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

1. Create and submit an OpCo — In sandbox, approval takes minutes. Poll the status or listen for the opco.status_changed webhook.

2. Create a Project under your activated OpCo.

3. 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

4. Set your callback URL — PUT /auth/client/settings with a URL where users will be redirected after checkout.

5. Generate a payment link — POST /checkout/paylink with amount, currency (EUR), user_id, and project_id. Include an X-Idempotency-Key header.

6. Open the checkout URL — The response includes a checkout_url. Open it in a browser to see the payment flow.

7. Complete the payment — Use the sandbox test bank to authorize the payment.

8. 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

Verifying webhook signatures

Every webhook includes security headers for verification:

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:

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:

1. Submit your OpCo via PATCH /opcos/{opco_id}/submit
2. The system polls the upstream provider for status updates
3. First poll happens after 30 seconds
4. 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:

Checklist before going to production

Before switching from sandbox to production, verify:

• Your OpCo is submitted and activated in production (not just sandbox)
• You are using production API credentials (not sandbox)
• Your webhook endpoint is configured and receiving events
• Webhook signature verification is implemented
• Your callback URL is set and accessible
• Token refresh logic handles expiration gracefully
• Error handling covers all status codes (see Error Reference)
• Idempotency keys are implemented for payment creation
• All terminal transaction statuses are handled (success, failed, expired, canceled)
• KYC verification flow is tested end-to-end

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