# Integration quick start (/docs/payment-orchestration/integration-quick-start)

## Precium API Quick Start Guide [#precium-api-quick-start-guide]

Get your first payment working in under 10 minutes.

## Prerequisites [#prerequisites]

Before you begin, ensure you have:

- Precium account with API access
- API Key (Bearer Token) from your dashboard
- Brand ID from your dashboard. Your brand might need to be approved by [support@precium.com](mailto:support@precium.com) before you can utilise it for live transactions


## Step 1: Test Your API Connection [step] [#step-1-test-your-api-connection-step]

Verify your credentials work:

```bash
curl -X GET "https://gate.reviopay.com/api/v1/clients/" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Expected Response:**

```json
{
  "results": [],
  "next": null,
  "previous": null
}
```

If you receive a `401 Unauthorized` error, check your API key.

## Step 2: Create Your First Payment [step] [#step-2-create-your-first-payment-step]

### Option A: Payment Link (Simplest) [step] [#option-a-payment-link-simplest-step]

Create a payment with minimal parameters:

```bash
curl -X POST "https://gate.reviopay.com/api/v1/purchases/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client": {
      "email": "customer@example.com"
    },
    "purchase": {
      "currency": "ZAR",
      "products": [
        {
          "name": "Test Product",
          "price": 10000
        }
      ]
    },
    "brand_id": "YOUR_BRAND_ID"
  }'
```

**Response:**

```json
{
  "id": "pur_abc123...",
  "checkout_url": "https://gate.reviopay.com/p/abc123.../",
  "status": "created",
  "purchase": {
    "currency": "ZAR",
    "total": 10000,
    "products": [...]
  }
}
```

Open the `checkout_url` in your browser to see the hosted checkout page.

### Option B: Redirect Flow (E-commerce) [step] [#option-b-redirect-flow-e-commerce-step]

For e-commerce with a redirect back to your site:

```bash
curl -X POST "https://gate.reviopay.com/api/v1/purchases/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client": {
      "email": "customer@example.com"
    },
    "purchase": {
      "currency": "ZAR",
      "products": [
        {
          "name": "Test Product",
          "price": 10000
        }
      ]
    },
    "brand_id": "YOUR_BRAND_ID",
    "success_redirect": "https://www.example.com/payment/success",
    "failure_redirect": "https://www.example.com/payment/failure",
    "cancel_redirect": "https://www.example.com/payment/cancel"
  }'
```

After payment:

- **Success** — Customer redirected to `success_redirect`
- **Failure** — Customer redirected to `failure_redirect`
- **Cancel** — Customer redirected to `cancel_redirect`

## Step 3: Complete a Test Payment [step] [#step-3-complete-a-test-payment-step]

1. Open the `checkout_url` from the response
2. Enter test card details:

| Field | Value |
|---|---|
| Card Number | `4444 3333 2222 1111` |
| Expiry | `12/28` (any future date) |
| CVC | `123` |
| Name | `Test User` |

1. Complete 3D Secure if prompted
2. Observe the redirect to your success URL
3. Remember to make use of your testing API credentials

## Step 4: Verify Payment Status [step] [#step-4-verify-payment-status-step]

Check the purchase status:

```bash
curl -X GET "https://gate.reviopay.com/api/v1/purchases/PURCHASE_ID/" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Successful Payment Response:**

```json
{
  "id": "pur_abc123...",
  "status": "paid",
  "purchase": {
    "total": 10000,
    "currency": "ZAR"
  },
  "payment_method_details": {
    "card": {
      "brand": "visa",
      "last4": "1111"
    }
  }
}
```

## Step 5: Set Up Webhooks (Recommended) [step] [#step-5-set-up-webhooks-recommended-step]

Don't rely solely on redirects. Set up webhooks for reliable payment notifications.

### Create Webhook Subscription [step] [#create-webhook-subscription-step]

Via Dashboard:

1. Navigate to Settings — Webhooks
2. Add webhook URL
3. Select events: `purchase.paid`, `purchase.payment_failure`

Via API:

```bash
curl -X POST "https://gate.reviopay.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/webhooks/precium",
    "events": ["purchase.paid", "purchase.payment_failure"]
  }'
```

### Handle Webhook [step] [#handle-webhook-step]

```jsx
// Express.js example
app.post('/webhooks/precium', (req, res) => {
  const event = req.body;

  switch (event.event_type) {
    case 'purchase.paid':
      // Fulfill order
      console.log('Payment received:', event.data.id);
      break;
    case 'purchase.payment_failure':
      // Handle failure
      console.log('Payment failed:', event.data.id);
      break;
  }

  res.status(200).send('OK');
});
```


## Quick Reference [#quick-reference]

### Purchase Statuses [#purchase-statuses]

The ones you will meet most often. Note there is no bare `pending` status — the in-flight states are named for the operation.

| Status | Meaning |
|---|---|
| `created` | Created, awaiting payment |
| `sent` / `viewed` | Invoice sent / checkout opened |
| `pending_charge` | Authorisation in flight |
| `hold` | Funds reserved, awaiting capture or release |
| `preauthorized` | Card verified, no money moved |
| `pending_capture` / `pending_release` / `pending_refund` | Operation accepted, acquirer still processing |
| `paid` | Captured and complete |
| `released` | Hold released without capture |
| `refunded` | Refunded in full |
| `cancelled` | Cancelled before payment |
| `chargeback` | Disputed by the cardholder |
| `expired` / `overdue` | Payment window elapsed / past due date |
| `error` | Failed — read `transaction_data.attempts[]`, newest first |

### Essential Endpoints [#essential-endpoints]

| Action | Method | Endpoint |
|---|---|---|
| Create purchase | POST | `/purchases/` |
| Get purchase | GET | `/purchases/{id}/` |
| Refund purchase | POST | `/purchases/{id}/refund/` |
| Create client | POST | `/clients/` |
| Get client | GET | `/clients/{id}/` |

### Test Cards [#test-cards]

| Card Number | Behavior |
|---|---|
| `4444 3333 2222 1111` | Success |
| `5555 5555 5555 4444` | Success (Mastercard) |

Use CVC `123` and any future expiry date.

## Common Issues [#common-issues]

### "Invalid brand_id" [#invalid-brand_id]

- Verify your brand_id in the dashboard
- Ensure you're using the correct environment credentials

### "Unauthorized" [#unauthorized]

- Check that your API key is correct
- Ensure the Authorization header format: `Bearer YOUR_API_KEY`

### Checkout not loading [#checkout-not-loading]

- Verify `success_redirect` and `failure_redirect` are valid URLs
- Ensure the purchase hasn't expired

## Next Steps [#next-steps]

Now that you've processed your first payment:

1. **Integration Guide** — Learn about all payment scenarios
2. **Code Examples** — Production-ready code samples
3. **Testing Guide** — Complete test scenarios

## Complete Example: E-commerce Checkout [#complete-example-e-commerce-checkout]

```python
import requests

API_KEY = "your_api_key"
BRAND_ID = "your_brand_id"
BASE_URL = "https://gate.reviopay.com/api/v1"

def create_checkout(customer_email, amount_cents, product_name, order_id):
    """Create a checkout and return the redirect URL"""

    response = requests.post(
        f"{BASE_URL}/purchases/",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "client": {
                "email": customer_email
            },
            "purchase": {
                "currency": "ZAR",
                "products": [{
                    "name": product_name,
                    "price": amount_cents
                }]
            },
            "brand_id": BRAND_ID,
            "reference": order_id,
            "success_redirect": f"https://www.example.com/orders/{order_id}/success",
            "failure_redirect": f"https://www.example.com/orders/{order_id}/failure",
            "cancel_redirect": f"https://www.example.com/orders/{order_id}/cancel"
        }
    )

    data = response.json()
    return {
        "purchase_id": data["id"],
        "checkout_url": data["checkout_url"]
    }

# Usage
checkout = create_checkout(
    customer_email='customer@example.com',
    amount_cents=29900,  # R299.00
    product_name='Premium Subscription',
    order_id='ORD-12345'
)

print(f"Redirect customer to: {checkout['checkout_url']}")
```