> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lux-core.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Guide

> Test your integration before going live

# Testing Guide

LuxCore provides a test mode that allows you to simulate transactions without processing real money. This guide covers how to use test mode effectively.

## Test vs Production Mode

<Info>
  Test and production use the **same API endpoint**. The environment is determined by your API key prefix.
</Info>

| Key Prefix     | Environment | Behavior                                 |
| -------------- | ----------- | ---------------------------------------- |
| `qp_test_sk_*` | Test        | Simulated transactions, no real money    |
| `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:

1. Log in to your [Merchant Dashboard](https://admin.lux-core.io)
2. Navigate to **Settings → API Keys**
3. Copy your test API key (starts with `qp_test_sk_`)

<Info>
  Contact [developers@lux-core.io](mailto:developers@lux-core.io) if you need test API keys.
</Info>

## Test Mode Behavior

### Payments

* Payments are created and go through normal status transitions
* No actual bank transfers or card charges occur
* Webhooks are delivered normally
* All API responses mirror production behavior

### Balance

* Test mode uses a separate test balance
* Initial test balance may be pre-funded for testing
* Balance changes reflect test transactions only

### Webhooks

* Webhooks are delivered to your configured endpoints
* Use webhook testing to verify your integration
* Same signature verification as production

## Simulating Payment Scenarios

### Successful Deposit

Create a deposit payment - it will transition to `completed` status:

```bash theme={null}
curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key" \
  -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:

```bash theme={null}
curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key" \
  -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

Create a withdrawal payment (requires sufficient test balance):

```bash theme={null}
curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key" \
  -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:

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

### Local Development

For local development, use a tunneling service like [ngrok](https://ngrok.com) to expose your local server:

```bash theme={null}
# 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:

<AccordionGroup>
  <Accordion title="Payment Creation">
    * [ ] Create deposit payments successfully
    * [ ] Create withdrawal payments successfully
    * [ ] Handle validation errors gracefully
    * [ ] Store transaction IDs for tracking
  </Accordion>

  <Accordion title="Payment Status">
    * [ ] Retrieve payment status by ID
    * [ ] List payments with filters
    * [ ] Cancel pending payments
  </Accordion>

  <Accordion title="Webhooks">
    * [ ] Receive webhook notifications
    * [ ] Verify webhook signatures
    * [ ] Handle `payment.completed` events
    * [ ] Handle `payment.failed` events
    * [ ] Process events idempotently
  </Accordion>

  <Accordion title="Error Handling">
    * [ ] Handle 401 (unauthorized) errors
    * [ ] Handle 400 (bad request) errors
    * [ ] Handle 429 (rate limit) errors
    * [ ] Handle network timeouts
  </Accordion>

  <Accordion title="Balance">
    * [ ] Check balance before withdrawals
    * [ ] Handle insufficient balance errors
  </Accordion>
</AccordionGroup>

## Going Live

<Steps>
  <Step title="Complete Testing">
    Ensure all checklist items pass in test mode
  </Step>

  <Step title="Request Live API Key">
    Contact your LuxCore account manager or [developers@lux-core.io](mailto:developers@lux-core.io) to request production credentials
  </Step>

  <Step title="Update Configuration">
    Replace test API key with live API key in your production environment
  </Step>

  <Step title="Update Webhook URLs">
    Ensure webhooks point to your production server
  </Step>

  <Step title="Monitor">
    Watch the dashboard for your first live transactions
  </Step>
</Steps>

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

## Common Testing Mistakes

<CardGroup cols={2}>
  <Card title="Using Live Keys in Dev" icon="triangle-exclamation">
    Always use test keys (`qp_test_sk_*`) in development
  </Card>

  <Card title="Skipping Webhook Verification" icon="shield-xmark">
    Always verify signatures, even in test mode
  </Card>

  <Card title="Not Testing Errors" icon="bug">
    Test error scenarios, not just happy paths
  </Card>

  <Card title="Hardcoding Keys" icon="key">
    Use environment variables for API keys
  </Card>
</CardGroup>

## Need Help?

<Card title="Developer Support" icon="envelope" href="mailto:developers@lux-core.io">
  Contact our team if you have questions about testing
</Card>