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:

‍

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

Option A: Payment Link (Simplest)

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)

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

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

‍

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

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)

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

‍

Create Webhook Subscription

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

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

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.

‍

Essential Endpoints

‍

Test Cards

‍

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:

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

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