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

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

Integration quick start

Precium API Quick Start GuideCopy Anchor Link

PrerequisitesCopy Anchor Link

Step 1: Test Your API ConnectionCopy Anchor Link

Step 2: Create Your First PaymentCopy Anchor Link

Option A: Payment Link (Simplest)Copy Anchor Link

Option B: Redirect Flow (E-commerce)Copy Anchor Link

Step 3: Complete a Test PaymentCopy Anchor Link

Step 4: Verify Payment StatusCopy Anchor Link

Step 5: Set Up Webhooks (Recommended)Copy Anchor Link

Create Webhook SubscriptionCopy Anchor Link

Handle WebhookCopy Anchor Link

Quick ReferenceCopy Anchor Link

Purchase StatusesCopy Anchor Link

Essential EndpointsCopy Anchor Link

Test CardsCopy Anchor Link

Common IssuesCopy Anchor Link

"Invalid brand_id"Copy Anchor Link

"Unauthorized"Copy Anchor Link

Checkout not loadingCopy Anchor Link

Next StepsCopy Anchor Link

Complete Example: E-commerce CheckoutCopy Anchor Link

On this page

Integration quick start

Precium API Quick Start GuideCopy Anchor Link

PrerequisitesCopy Anchor Link

Step 1: Test Your API ConnectionCopy Anchor Link

Step 2: Create Your First PaymentCopy Anchor Link

Option A: Payment Link (Simplest)Copy Anchor Link

Option B: Redirect Flow (E-commerce)Copy Anchor Link

Step 3: Complete a Test PaymentCopy Anchor Link

Step 4: Verify Payment StatusCopy Anchor Link

Step 5: Set Up Webhooks (Recommended)Copy Anchor Link

Create Webhook SubscriptionCopy Anchor Link

Handle WebhookCopy Anchor Link

Quick ReferenceCopy Anchor Link

Purchase StatusesCopy Anchor Link

Essential EndpointsCopy Anchor Link

Test CardsCopy Anchor Link

Common IssuesCopy Anchor Link

"Invalid brand_id"Copy Anchor Link

"Unauthorized"Copy Anchor Link

Checkout not loadingCopy Anchor Link

Next StepsCopy Anchor Link

Complete Example: E-commerce CheckoutCopy Anchor Link

On this page

Precium API Quick Start Guide

Prerequisites

Step 1: Test Your API Connection

Step 2: Create Your First Payment

Option A: Payment Link (Simplest)

Option B: Redirect Flow (E-commerce)

Step 3: Complete a Test Payment

Step 4: Verify Payment Status

Step 5: Set Up Webhooks (Recommended)

Create Webhook Subscription

Handle Webhook

Quick Reference

Purchase Statuses

Essential Endpoints

Test Cards

Common Issues

"Invalid brand_id"

"Unauthorized"

Checkout not loading

Next Steps

Complete Example: E-commerce Checkout

Precium API Quick Start Guide

Prerequisites

Step 1: Test Your API Connection

Step 2: Create Your First Payment

Option A: Payment Link (Simplest)

Option B: Redirect Flow (E-commerce)

Step 3: Complete a Test Payment

Step 4: Verify Payment Status

Step 5: Set Up Webhooks (Recommended)

Create Webhook Subscription

Handle Webhook

Quick Reference

Purchase Statuses

Essential Endpoints

Test Cards

Common Issues

"Invalid brand_id"

"Unauthorized"

Checkout not loading

Next Steps

Complete Example: E-commerce Checkout