Testing Guide

Before running payment tests, arrange an isolated testing setup and approved recipient data with your account manager. A test-looking key prefix alone is not a guarantee that a request is simulated.

Test vs Production Mode

Test and production use the same API endpoint. Your account manager must confirm the environment and permitted test scenarios before you create payments.

Key Prefix	Environment	Behavior
`qp_test_sk_*`	Test	Credentials designated for an agreed testing setup
`qp_prod_sk_*`	Production	Real transactions, actual money movement

Getting Test API Keys

Test API keys are provided by the LuxCore team during onboarding. Once you have access:

Log in to your Merchant Dashboard
Navigate to Settings → API Keys
Copy your test API key (starts with qp_test_sk_)

Contact developers@lux-core.io if you need test API keys.

Confirm the Setup Before Testing

Confirm the endpoint, credentials, enabled currencies/methods, permitted recipients and expected statuses with your account manager. Only create payments after the isolated testing setup has been confirmed. Do not use live recipients or production credentials for example requests. Use the webhook test endpoint to test signature verification without creating a payment. Test notifications must not trigger order fulfilment or balance changes in your application; check X-Webhook-Test: true.

Agreed Payment Test Scenarios

Successful Deposit

In the confirmed testing setup, create a deposit and verify the expected status with your account manager:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "ARS",
    "method": "bank_transfer",
    "type": "deposit",
    "merchant_reference": "test_order_001",
    "customer": {
      "name": "Test Customer",
      "email": "test@example.com"
    }
  }'

Successful Deposit (AUD with PayID)

Create a deposit using PayID for near-instant processing:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "AUD",
    "method": "payid",
    "type": "deposit",
    "merchant_reference": "test_order_aud_001",
    "customer": {
      "name": "Test Customer",
      "email": "test@example.com"
    }
  }'

Successful Withdrawal

Use only the approved test recipient in the confirmed testing setup. Verify the required balance before submitting a withdrawal:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "ARS",
    "method": "bank_transfer",
    "type": "withdrawal",
    "merchant_reference": "test_payout_001",
    "customer": {
      "name": "Test Payout",
      "email": "payouts@example.com"
    },
    "payout": {
      "recipient_name": "Juan Perez",
      "bank_account": "0110012345678901234567"
    }
  }'

Testing Webhooks

Send Test Event

Use the test endpoint to send a test webhook to your server:

curl -X POST "https://api.lux-core.io/api/v1/webhooks/{webhook_id}/test" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "payment.completed"
  }'

Your server receives the same webhook envelope used by automatic payment webhooks:

{
  "id": "evt_1234567890",
  "created_at": "2025-01-21T10:30:00.000Z",
  "data": {
    "payment": {
      "id": "pay_1234567890_abcdefgh",
      "status": "completed",
      "amount": 100050,
      "currency": "MXN"
    }
  },
  "merchant_id": "42"
}

The response from the test API includes request.body and request.headers so you can compare the delivered payload and signature headers with what your endpoint logged.

Local Development

For local development, use a tunneling service like ngrok to expose your local server:

# Start ngrok
ngrok http 3000

# Use the ngrok URL for your webhook endpoint
# https://abc123.ngrok.io/webhooks/luxcore

Integration Checklist

Before going live, verify your integration handles these scenarios:

Payment Creation

Create deposit payments successfully
Create withdrawal payments successfully
Handle validation errors gracefully
Store transaction IDs for tracking

Payment Status

Retrieve payment status by ID
List payments with filters
Cancel pending payments

Webhooks

Receive webhook notifications
Verify webhook signatures
Handle payment.completed events
Handle payment.failed events
Process events idempotently

Error Handling

Handle 401 (unauthorized) errors
Handle 400 (bad request) errors
Handle 429 (rate limit) errors
Handle network timeouts

Balance

Check balance before withdrawals
Handle insufficient balance errors

Going Live

Complete Testing

Verify the agreed test scenarios and all checklist items

Request Live API Key

Contact your LuxCore account manager or developers@lux-core.io to request production credentials

Update Configuration

Replace test API key with live API key in your production environment

Update Webhook URLs

Ensure webhooks point to your production server

Monitor

Watch the dashboard for your first live transactions

Never use live API keys in development or testing environments. Always keep test and production credentials separate.

Common Testing Mistakes

Using Live Keys in Dev

Always use test keys (qp_test_sk_*) in development

Skipping Webhook Verification

Always verify signatures, even in test mode

Not Testing Errors

Test error scenarios, not just happy paths

Hardcoding Keys

Use environment variables for API keys

Need Help?

Developer Support

Contact our team if you have questions about testing

Getting Started

Guides

SDKs & Examples

Reference

Testing Guide

Testing Guide

Test vs Production Mode

Getting Test API Keys

Confirm the Setup Before Testing

Agreed Payment Test Scenarios

Successful Deposit

Successful Deposit (AUD with PayID)

Successful Withdrawal

Testing Webhooks

Send Test Event

Local Development

Integration Checklist

Going Live

Common Testing Mistakes

Using Live Keys in Dev

Skipping Webhook Verification

Not Testing Errors

Hardcoding Keys

Need Help?

Developer Support

​Testing Guide

​Test vs Production Mode

​Getting Test API Keys

​Confirm the Setup Before Testing

​Agreed Payment Test Scenarios

​Successful Deposit

​Successful Deposit (AUD with PayID)

​Successful Withdrawal

​Testing Webhooks

​Send Test Event

​Local Development

​Integration Checklist

​Going Live

​Common Testing Mistakes

Using Live Keys in Dev

Skipping Webhook Verification

Not Testing Errors

Hardcoding Keys

​Need Help?

Developer Support

Testing Guide

Test vs Production Mode

Getting Test API Keys

Confirm the Setup Before Testing

Agreed Payment Test Scenarios

Successful Deposit

Successful Deposit (AUD with PayID)

Successful Withdrawal

Testing Webhooks

Send Test Event

Local Development

Integration Checklist

Going Live

Common Testing Mistakes

Need Help?