Integration quick start

Precium API Quick Start Guide

Get your first payment working in under 10 minutes.

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 before you can utilise it for live transactions

Step 1: Test Your API Connection

Verify your credentials work:


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

Expected Response:


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

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

Step 2: Create Your First Payment

Option A: Payment Link (Simplest)

Create a payment with minimal parameters:


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:


{
  "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)

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


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

Open the checkout_url from the response
Enter test card details:

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

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

Step 4: Verify Payment Status

Check the purchase status:


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

Successful Payment Response:


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

Step 5: Set Up Webhooks (Recommended)

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

Create Webhook Subscription

Via Dashboard:

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

Via API:


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


// 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

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

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

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

Use CVC 123 and any future expiry date.

Common Issues

“Invalid brand_id”

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

“Unauthorized”

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

Checkout not loading

Verify success_redirect and failure_redirect are valid URLs
Ensure the purchase hasn’t expired

Next Steps

Now that you’ve processed your first payment:

Integration Guide — Learn about all payment scenarios
Code Examples — Production-ready code samples
Testing Guide — Complete test scenarios

Complete Example: E-commerce Checkout


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']}")