API Reference

Launch Checklist

Everything to verify before going from sandbox to production.

Launch Checklist

Use this checklist to verify your integration is production-ready before switching from sandbox to live payments. Each item addresses a common cause of production incidents. For a product overview, visit urbanpayx.com .

Account and entity setup

  • Production OpCo is ACTIVATED — Sandbox and production are separate environments. Your sandbox OpCo does not carry over. Submit your OpCo in production and wait for activation (3-5 business days).
  • Production API credentials generated — Generate your production API key and secret. Store them securely (environment variables or a secrets manager, never in code).
  • Team roles assigned — Ensure the right team members have the right roles. API keys default to OPERATIONS; use dashboard login for OWNER or DEVELOPER actions.
  • Project created under activated OpCo — Your production project must be linked to your activated production OpCo.

Authentication and security

  • Token refresh logic implemented — Access tokens expire (2 hours for API key, 30 minutes for dashboard). Your integration must handle token expiration gracefully — detect 401 responses and re-authenticate or refresh.
  • Security challenge flow implemented — If your integration performs sensitive operations (team management, key rotation), implement the security code request and verification flow.
  • API credentials are not hardcoded — Credentials must be in environment variables or a secrets manager. Never commit them to version control.
  • MFA configured for team accounts — Enable MFA for all dashboard users, especially OWNER accounts.

Payment flow

  • Callback URL configured — Set your production callback_url via PUT /auth/client/settings. This is where users are redirected after checkout.
  • Idempotency keys implemented — Every POST /checkout/paylink request must include a unique X-Idempotency-Key header. Generate a new key per payment intent (e.g., order-{id}-attempt-{n}).
  • All terminal statuses handled — Your system must handle all four terminal statuses: success (deliver product/service), failed (offer retry), expired (offer new link), canceled (offer new link).
  • Do not rely on callback URL for payment confirmation — The callback is a user redirect, not a server notification. Users may close their browser before the redirect. Always use webhooks for server-side confirmation.

KYC verification

  • Verification flow tested end-to-end — Whether using UrbanPayX KYC or external attestation, verify that users reach the approved/verified status before attempting payment link generation.
  • Error handling for unverified users — If a user is not yet verified, the payment endpoint returns 400. Handle this gracefully and guide the user through verification.
  • Bulk operations tested (if applicable) — If using bulk user creation or bulk status updates, verify partial failure handling.

Webhooks

  • Webhook endpoint deployed and reachable — Your webhook URL must be publicly accessible over HTTPS.
  • Webhook signature verification implemented — Verify the X-UPX-Signature header on every incoming webhook using your webhook secret and HMAC-SHA256. Reject any webhook that fails verification.
  • Webhook secret stored securely — Like API credentials, your webhook signing secret belongs in environment variables.
  • Idempotent webhook handling — Your webhook handler should be idempotent. UrbanPayX may retry delivery (up to 8 attempts with exponential backoff), so the same event may arrive more than once.
  • All event types handled — Implement handlers for: payment.status_changed, kyc.status_changed, opco.status_changed, and project.frozen_changed.
  • Test webhook received — Use POST /webhooks/subscription/test to verify your endpoint is receiving and processing events correctly.

Error handling

  • All HTTP status codes handled — Your integration should handle: 400 (business rule), 401 (re-authenticate), 403 (wrong role), 404 (resource not found), 409 (idempotency conflict), 422 (validation), 429 (rate limit — wait and retry), 500/502/503 (retry with backoff).
  • Rate limit handling implemented — On 429 responses, read the response body for retry timing. Do not retry immediately in a tight loop.
  • Retry logic with backoff — For 500/502/503 errors, implement exponential backoff (e.g., 1s, 2s, 4s, 8s) with a maximum number of retries.

Monitoring and observability

  • Logging API responses — Log response status codes and error messages for debugging. Do not log access tokens or API secrets.
  • Alerting on payment failures — Set up alerts for elevated failed transaction rates or repeated error responses.
  • Webhook delivery monitoring — Check GET /webhooks/deliveries periodically to verify events are being delivered and acknowledged.

Final verification

  • Run a complete payment cycle in sandbox — Create OpCo, submit, activate, create project, create user, verify user, generate payment link, complete checkout, receive webhook. Every step should succeed without manual intervention.
  • Verify production base URL — Your integration points to api.urbanpayx.com, not api-sandbox.urbanpayx.com.
  • Review the Error Reference — Familiarize your team with common errors and their fixes so production issues can be resolved quickly.

Related guides

Updated 15 days ago

Updated 15 days ago