Test scenarios

Comprehensive test scenarios and sandbox testing instructions for the Precium Payment API. Contact your account manager to gain access to more advanced testing scenarios if required. Especially for s2s integrations.

‍

Sandbox Environment

Sandbox Configuration

|Setting|Value| |---|---| |Base URL|`https://gate.reviopay.com/api/v1/`| |API Key|Your sandbox API key from dashboard| |Brand ID|Your sandbox brand ID|

‍

Note: Sandbox and production use the same base URL but different credentials. Always verify you're using sandbox credentials when testing.

‍

Test Card Numbers

Successful Payments

|Card Number|Brand|3DS|Behavior| |---|---|---|---| |`4444 3333 2222 1111`|Visa|Yes|Success| |`5555 5555 5555 4444`|Mastercard|Yes|Success| |`4000 0000 0000 0077`|Visa|No|Success (no 3DS)|

‍

Test Card Details

|Field|Value| |---|---| |Expiry Date|Any future date (e.g., `12/28`)| |CVC|`123`| |Cardholder Name|Any Latin characters|

‍

Failed Payments

Use these card numbers to simulate failures:

‍

|Card Number|Error Type| |---|---| |Invalid card number|Card declined| |Invalid CVC|Validation error| |Past expiry date|Expired card|

‍

Test Scenarios

Category 1: Basic Payment Flow

TC-1.1: Create Payment Link

‍

Objective: Verify payment link creation with minimal parameters

‍

Steps:

POST to /purchases/ with client email, product, and brand_id
Verify response contains checkout_url
Open checkout_url in browser
Verify the checkout page loads correctly

‍

Request:

JSON

{
  "client": {"email": "test@example.com"},
  "purchase": {
    "currency": "ZAR",
    "products": [{"name": "Test Product", "price": 10000}]
  },
  "brand_id": "YOUR_BRAND_ID"
}

‍

Expected: HTTP 201, response contains checkout_url and id

‍

TC-1.2: Complete Card Payment

‍

Objective: End-to-end card payment flow

‍

Steps:

Create a purchase with redirect URLs
Navigate to checkout_url
Enter test card details
Complete 3DS if prompted
Verify the redirect to success_redirect
GET purchase to confirm the status is paid

‍

Request:

JSON

{
  "client": {"email": "test@example.com"},
  "purchase": {
    "currency": "ZAR",
    "products": [{"name": "Test Product", "price": 10000}]
  },
  "brand_id": "YOUR_BRAND_ID",
  "success_redirect": "https://example.com/success",
  "failure_redirect": "https://example.com/failure"
}

‍

Expected:

Payment completes
Redirected to the success URL
Purchase status is paid

‍

TC-1.3: Payment with Multiple Products

‍

Objective: Verify the correct total calculation

‍

Steps:

Create a purchase with multiple products
Verify purchase.total equals the sum of all product prices
Complete payment
Verify the amount charged matches the total

‍

Request:

JSON

{
  "client": {"email": "test@example.com"},
  "purchase": {
    "currency": "ZAR",
    "products": [
      {"name": "Product A", "price": 5000, "quantity": "2"},
      {"name": "Product B", "price": 3000},
      {"name": "Shipping", "price": 2000}
    ]
  },
  "brand_id": "YOUR_BRAND_ID"
}

‍

Expected: Total should be 15000 (5000Ã2 + 3000 + 2000)

‍

Category 2: Payment Method Restrictions

TC-2.1: Whitelist Card Only

‍

Objective: Verify that only whitelisted methods appear

‍

Steps:

Create a purchase with payment_method_whitelist: ["visa", "mastercard"]
Open checkout page
Verify that only Visa and Mastercard options appear
Verify EFT options are not available

‍

Request:

JSON

{
  "client": {"email": "test@example.com"},
  "purchase": {
    "currency": "ZAR",
    "products": [{"name": "Test", "price": 10000}]
  },
  "brand_id": "YOUR_BRAND_ID",
  "payment_method_whitelist": ["visa", "mastercard"]
}

‍

Expected: Only card payment options visible on checkout

‍

TC-2.2: Whitelist EFT Only

‍

Objective: Verify non-card methods work

‍

Steps:

Create a purchase with payment_method_whitelist: ["ozow"]
Open checkout page
Verify that only Ozow option appears
Verify card options are not available

‍

Expected: Only Ozow payment option visible

‍

Category 3: Pre-Authorization (Hold Funds)

TC-3.1: Create Pre-Authorization

‍

Objective: Reserve funds without capture

‍

Steps:

Create a purchase with skip_capture: true
Complete payment
Verify the status is hold (not paid)
Verify funds are reserved on the test card

‍

Request:

JSON

{
  "client_id": "CLIENT_UUID",
  "purchase": {
    "currency": "ZAR",
    "products": [{"name": "Hotel Deposit", "price": 500000}]
  },
  "brand_id": "YOUR_BRAND_ID",
  "skip_capture": true,
  "success_redirect": "https://example.com/success",
  "failure_redirect": "https://example.com/failure"
}

‍

Expected: Status hold after payment completion

‍

TC-3.2: Capture Pre-Authorization (Full)

‍

Objective: Capture the full held amount

‍

Steps:

Create pre-auth purchase (TC-3.1)
Complete payment
POST to /purchases/{id}/capture/ with full amount
Verify status changes to paid

‍

Request:

BASH

POST /purchases/{id}/capture/
{"amount": 500000}

‍

Expected: Status changes to paid

‍

TC-3.3: Capture Pre-Authorization (Partial)

‍

Objective: Capture less than held amount

‍

Steps:

Create pre-auth for 500000 cents
Complete payment
Capture only 300000 cents
Verify capture succeeds
Verify the remaining 200000 is released

‍

Request:

BASH

POST /purchases/{id}/capture/
{"amount": 300000}

‍

Expected: Capture succeeds with a partial amount

‍

TC-3.4: Release Pre-Authorization

‍

Objective: Release held funds without capture

‍

Steps:

Create a pre-auth purchase
Complete payment (status = hold)
POST to /purchases/{id}/release/
Verify status changes to released
Verify funds are released on the test card

‍

Expected: Status released, funds returned

‍

Category 4: Refunds

TC-4.1: Full Refund

‍

Objective: Refund the entire payment

‍

Steps:

Create and complete a payment
Verify the status is paid
POST to /purchases/{id}/refund/ with an empty body
Verify the refund is processed
Check the purchase for refund status

‍

Request:

‍

bash

‍

BASH

POST /purchases/{id}/refund/
{}

‍

Expected: Refund processed, status updated

‍

TC-4.2: Partial Refund

‍

Objective: Refund portion of payment

‍

Steps:

Complete payment for 10000 cents
POST refund for 3000 cents
Verify partial refund succeeds
Verify the remaining balance is 7000

‍

Request:

BASH

POST /purchases/{id}/refund/
{"amount": 3000}

‍

Expected: Partial refund of 3000 cents processed

‍

TC-4.3: Multiple Partial Refunds

‍

Objective: Issue multiple refunds on the same purchase

‍

Steps:

Complete payment for 10000 cents
Refund 3000 cents (success)
Refund another 4000 cents (success)
Verify the total refunded is 7000
Verify the remaining is 3000

‍

Expected: Multiple refunds succeed up to the original amount

‍

TC-4.4: Refund Exceeds Amount

‍

Objective: Verify refund limit enforcement

‍

Steps:

Complete payment for 10000 cents
Attempt to refund 15000 cents
Verify request fails with appropriate error

‍

Expected: HTTP 400, error refund_exceeds_amount

‍

Category 5: Recurring Payments

TC-5.1: Tokenize Card

‍

Objective: Save card for future payments

‍

Steps:

Create a purchase with force_recurring: true
Complete payment
GET /clients/{id}/recurring_tokens/
Verify the token is created

‍

Request:

JSON

{
  "client_id": "CLIENT_UUID",
  "purchase": {
    "currency": "ZAR",
    "products": [{"name": "Subscription", "price": 29900}]
  },
  "brand_id": "YOUR_BRAND_ID",
  "force_recurring": true,
  "success_redirect": "https://example.com/success",
  "failure_redirect": "https://example.com/failure"
}

‍

Expected: Recurring token created after payment

‍

TC-5.2: Zero-Amount Tokenization

‍

Objective: Save the card without charging

‍

Steps:

Create a purchase with price: 0 and skip_capture: true
Complete checkout (no charge)
Verify that the token is created
Use the token for subsequent charges

‍

Request:

JSON

{
  "client_id": "CLIENT_UUID",
  "purchase": {
    "currency": "ZAR",
    "products": [{"name": "Card Authorization", "price": 0}]
  },
  "brand_id": "YOUR_BRAND_ID",
  "skip_capture": true,
  "force_recurring": true,
  "success_redirect": "https://example.com/success",
  "failure_redirect": "https://example.com/failure"
}

‍

Expected: Token created, no charge to card

‍

TC-5.3: Charge with Token

‍

Objective: Process payment using saved token

‍

Steps:

Complete tokenization (TC-5.1)
Create a new purchase for the same client
POST to /purchases/{id}/charge/ with recurring_token
Verify payment succeeds without customer interaction

‍

Request:

BASH

POST /purchases/{new_id}/charge/
{"recurring_token": "ORIGINAL_PURCHASE_ID"}

‍

Expected: Payment succeeds, status paid

‍

TC-5.4: Charge with Invalid Token

‍

Objective: Verify invalid token handling

‍

Steps:

Create purchase
Attempt charge with non-existent token ID
Verify the appropriate error returned

‍

Expected: HTTP 404, error recurring_token_not_found

‍

Category 6: Billing Templates (Subscriptions)

TC-6.1: Create Subscription Plan

‍

Objective: Create a monthly subscription template

‍

Steps:

POST to /billing_templates/
Verify template created
Check subscription settings are correct

‍

Request:

JSON

{
  "title": "Monthly Premium",
  "purchase": {
    "currency": "ZAR",
    "products": [{"name": "Premium Plan", "price": 29900}]
  },
  "brand_id": "YOUR_BRAND_ID",
  "is_subscription": true,
  "subscription_active": true,
  "subscription_period": 1,
  "subscription_period_units": "months",
  "force_recurring": true
}

‍

Expected: Template created with subscription configuration

‍

TC-6.2: Add Subscriber

‍

Objective: Subscribe the client to a plan

‍

Steps:

Attempt to create another with the same email

‍

TC-6.3: Add Subscriber with Override

‍

Objective: Subscribe with custom pricing

‍

Steps:

Create a template with a standard price
Add subscriber with override price
Verify the subscriber has a custom price
Complete payment
Verify the charged amount matches the override

‍

Request:

JSON

{
  "client_id": "CLIENT_UUID",
  "override": {
    "products": [{"name": "Discounted Plan", "price": 19900}]
  }
}

‍

Expected: Subscription uses override pricing

‍

Category 7: Client Management

TC-7.1: Create Client

‍

Objective: Create a new client record

‍

Steps:

POST to /clients/ with email and details
Verify client created
Verify all fields are saved correctly

‍

Request:

JSON

{
  "email": "test@example.com",
  "full_name": "Test User",
  "phone": "+27821234567"
}

‍

Expected: HTTP 201, client ID returned

‍

TC-7.2: Search Client

‍

Objective: Find a client by email

‍

Steps:

Create client
GET /clients/?email=test@example.com
Verify the client found in the results

‍

Expected: Client returned in search results

‍

TC-7.3: Duplicate Client Prevention

‍

Objective: Verify duplicate email handling

‍

Steps:

Create a client with an email
Attempt to create another with the same email
Verify the appropriate error

‍

Expected: HTTP 409, error duplicate_client

‍

Category 8: Webhooks

TC-8.1: Payment Success Webhook

‍

Objective: Verify webhook delivery on payment

‍

Steps:

Configure the webhook for purchase.paid
Create and complete a payment
Verify the webhook was received
Verify payload contains purchase data

‍

Expected: Webhook delivered with correct event type

‍

TC-8.2: Payment Failure Webhook

‍

Objective: Verify the webhook on failed payment

‍

Steps:

Configure the webhook for purchase.payment_failure
Create purchase
Attempt payment with an invalid card
Verify failure webhook received

‍

Expected: Webhook delivered with failure details

‍

TC-8.3: Webhook Signature Verification

‍

Objective: Verify webhook authenticity

‍

Steps:

Receive webhook
Extract signature header
Calculate the expected signature using the secret
Verify signatures match

‍

Expected: Calculated signature matches header

‍

Category 9: Error Handling

TC-9.1: Invalid API Key

‍

Objective: Verify authentication error

‍

Steps:

Make a request with an invalid API key
Verify HTTP 401 returned
Verify the error message is clear

‍

Expected: HTTP 401, invalid_token error

‍

TC-9.2: Missing Required Field

‍

Objective: Verify validation error

‍

Steps:

POST purchase without brand_id
Verify HTTP 400 returned
Verify field-specific error message

‍

Expected: HTTP 400, required error for brand_id

‍

TC-9.3: Invalid UUID

‍

Objective: Verify UUID validation

‍

Steps:

GET /purchases/invalid-uuid/
Verify the appropriate error

‍

Expected: HTTP 400 or 404 with clear error

‍

TC-9.4: Rate Limiting

‍

Objective: Verify rate limit handling

‍

Steps:

Make requests rapidly (>100/minute)
Observe rate limit response
Verify the retry-after information provided

‍

Expected: HTTP 429 after limit exceeded

‍

Test Checklist

Pre-Integration Checklist

Sandbox API key obtained
Brand ID configured
Webhook endpoint ready
Test card numbers available

‍

Basic Flow Tests

TC-1.1: Create payment link
TC-1.2: Complete card payment
TC-1.3: Multiple products
TC-2.1: Payment method whitelist

‍

Advanced Flow Tests

TC-3.1: Pre-authorization
TC-3.2: Full capture
TC-3.3: Partial capture
TC-3.4: Release hold
TC-4.1: Full refund
TC-4.2: Partial refund
TC-5.1: Card tokenization
TC-5.3: Token charge
TC-6.1: Create subscription
TC-6.2: Add subscriber

‍

Error Handling Tests

TC-9.1: Invalid API key
TC-9.2: Validation errors
TC-9.3: Invalid UUID
TC-9.4: Rate limiting

‍

Production Readiness

Webhook handling implemented
Error handling complete
Idempotency implemented
Logging configured
Production credentials ready

‍

Go-Live Checklist

Before going live:

Credentials

Production API key configured
Production brand ID configured
Sandbox credentials removed from production

Webhooks

Production webhook URL configured
Webhook signature verification implemented
All relevant events subscribed

Error Handling

All error codes handled gracefully
User-friendly error messages displayed
Errors logged for debugging

Security

API keys stored securely (not in code)
HTTPS enforced
Webhook signatures verified

Testing

End-to-end test in production sandbox
Small live transaction tested
Refund tested

Table of contents

Test scenarios

Sandbox Environment

Sandbox Configuration

Test Card Numbers

Successful Payments

Test Card Details

Failed Payments

Test Scenarios

Category 1: Basic Payment Flow

Category 2: Payment Method Restrictions

Category 3: Pre-Authorization (Hold Funds)

Category 4: Refunds

Category 5: Recurring Payments

Category 6: Billing Templates (Subscriptions)

Category 7: Client Management

Category 8: Webhooks

Category 9: Error Handling

Test Checklist

Go-Live Checklist