Skip to main content

Testing

Use PayConnect's sandbox environment to build and test your integration before going live.

Sandbox Environment​

SandboxProduction
Base URLhttps://dev.payconnect.us/apihttps://my.payconnect.us/api
API KeySandbox API keyProduction API key
PaymentsSimulated (no real charges)Real charges
DataIsolated test dataLive customer data
warning

Sandbox and production use separate API keys. Never use your production API key for testing, and never use your sandbox key in production.

Getting Started​

  1. Request sandbox credentials — contact [email protected] for a sandbox API key
  2. Create a session token — exchange your sandbox API key for a session token
  3. Make test API calls — all sandbox calls behave identically to production (without real charges)
# Create session token in sandbox
curl -X POST https://dev.payconnect.us/api/auth/session \
  -H "Authorization: Api-Key YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json"

Test Workflows​

Invoice Flow​

  1. Create a customer
  2. Create an invoice for the customer
  3. Retrieve the invoice to confirm it was created
  4. Send the invoice email
  5. Verify the postback notification is received
# Step 1: Create customer
curl -X POST https://dev.payconnect.us/api/customers \
  -H "x-session-token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Test",
    "lastName": "Customer"
  }'

# Step 2: Create invoice
curl -X POST https://dev.payconnect.us/api/invoices \
  -H "x-session-token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUSTOMER_ID",
    "description": "Test invoice",
    "amount": 61,
    "dueDate": "2026-12-31"
  }'

# Step 3: Verify
curl -X GET https://dev.payconnect.us/api/invoices/INVOICE_ID \
  -H "x-session-token: YOUR_SESSION_TOKEN"

Transaction Flow​

  1. Create a hosted payment page to collect a payment method
  2. Process a test payment
  3. Verify the transaction status
  4. Test a refund
# Process a payment using a stored payment method
curl -X POST https://dev.payconnect.us/api/trx/payment \
  -H "Authorization: Api-Key YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_api_id": "CONTACT_ID",
    "transaction_amount": 10,
    "order_id": "TEST-001",
    "account_vault_id": "VAULT_ID",
    "type": "av"
  }'

# Verify the transaction
curl -X GET https://dev.payconnect.us/api/trx/order/TEST-001 \
  -H "Authorization: Api-Key YOUR_SANDBOX_API_KEY"

Subscription Flow​

  1. Create a subscription plan
  2. Create a subscription for a customer
  3. Verify the subscription status
  4. Test cancel operations
# Create a plan
curl -X POST https://dev.payconnect.us/api/subscriptions/v2/plans \
  -H "x-session-token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Plan",
    "price": 9.99,
    "billingCycle": "monthly"
  }'

# Create a subscription
curl -X POST https://dev.payconnect.us/api/subscriptions/v2 \
  -H "x-session-token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUSTOMER_ID",
    "planId": "PLAN_ID",
    "startDate": "2026-04-01"
  }'

Testing Postbacks​

To test postback notifications in your sandbox:

  1. Set up a postback receiver — use a tool like webhook.site or a local tunnel for development
  2. Configure your postback URL — contact support to set your sandbox postback URL
  3. Trigger events — create invoices, process payments, etc.
  4. Verify payloads — check that your endpoint receives and processes the notifications correctly

See the Postbacks guide for payload format and best practices.

Testing Checklist​

Before going live, verify the following in your sandbox:

Authentication​

  • Successfully create session tokens
  • Handle expired tokens gracefully (re-authenticate on 401)
  • API key is stored securely (not in client-side code)

Invoices​

  • Create invoices with all required fields
  • Handle validation errors for missing/invalid fields
  • Verify invoice emails are sent
  • Test the hosted payment page flow

Transactions​

  • Process payments using stored payment methods
  • Handle declined transactions
  • Process full and partial refunds
  • Test authorize-and-capture flow

Subscriptions​

  • Create subscription plans
  • Create subscriptions with different billing cycles
  • Test cancel operations
  • Verify payment method management

Postbacks​

  • Receive and acknowledge postback notifications
  • Verify the API key in postback headers
  • Handle duplicate notifications (idempotency)
  • Process postback data correctly

Error Handling​

  • Handle all HTTP error codes
  • Implement retry logic with exponential backoff
  • Respect rate limits (25 req/sec sustained, 50 burst, 2,000,000/month)

Going Live​

When your integration passes all sandbox tests:

  1. Request production credentials — contact [email protected]
  2. Update your base URL — switch from dev.payconnect.us to my.payconnect.us
  3. Update your API key — use your production API key
  4. Configure production postbacks — set your production postback URL
  5. Monitor — watch for errors in your first production transactions
tip

Use environment variables to switch between sandbox and production configurations. This makes it easy to test in sandbox and deploy to production without code changes.

Next Steps​