Introduction

Introduction

Welcome to the Precium Server-to-Server (S2S) Payment Integration documentation. This comprehensive guide provides everything needed to integrate Precium's payment processing directly from your server environment.

Who is this documentation for?

This documentation is designed for:

• Payment Service Providers (PSPs) building payment solutions for their merchant networks
• Enterprise Development Teams implementing custom checkout experiences
• Technical Integrators requiring direct API access with full control over the payment flow
• Platform Engineers embedding payments into SaaS applications, marketplaces, or mobile apps

Prerequisites

Before beginning your integration, ensure your organisation meets the following requirements:

Requirement	Description
PCI DSS Compliance	SAQ-D Level 1 certification required for handling card data
Technical Resources	Development team familiar with RESTful APIs and webhook handling
HTTPS Infrastructure	Secure endpoints for callbacks and webhook reception
API Credentials	Standard API Key and S2S API Key from your Precium dashboard

Documentation overview

This documentation suite consists of seven interconnected guides:

Core documentation

Document	Description
Quick Start Guide	Get up and running quickly with basic payment scenarios
S2S Integration Guide	Complete reference for all 12 payment scenarios including 3DS, pre-authorization, refunds, and webhooks
Error Codes Reference	Comprehensive catalog of 80+ error codes with causes, actions, and retry guidance
Code Examples	Production-ready examples in Python, Node.js, PHP, Ruby, Java, C#, and Go
Technical reference documentation	API reference and detailed postman recipes for key requests

Supporting documentation

Document	Description
Glossary	Definitions for payment industry terminology and Precium-specific concepts
Troubleshooting Guide	Solutions for common integration issues across all payment scenarios
Testing Checklist	65 test cases to validate your integration before going live

Supported payment scenarios

Precium S2S supports a wide range of payment scenarios to meet diverse business needs:

Customer-initiated transactions (CIT)

• Standard Payment with 3DS — Card-present transactions with Precium-managed 3D Secure authentication
• Zero Authorization — Validate cards without charging (card-on-file verification)
• Pre-Authorization — Reserve funds for later capture (hotels, car rentals, etc.)
• External 3DS (MPI) — Use your own 3D Secure provider with Precium processing

Merchant-initiated transactions (MIT)

• Recurring Payments — Subscription billing using stored tokens
• Instalment Payments — Split payments over time
• Unscheduled MIT — Variable-amount charges (usage-based billing)

Post-transaction operations

• Full and Partial Captures — Capture authorized funds in full or in parts
• Full and Partial Refunds — Return funds to customers
• Voids — Cancel transactions before settlement

Integration architecture

flowchart LR
    YS[Your Server] -->|API calls| PA[Precium API]
    PA -->|Routes| CN[Card Networks]
    YS <-->|3DS Flow| YF[Your Frontend]
    PA -->|Real-time events| WH[Webhooks]

Key integration points:

• Server-to-Server API — Create clients, purchases, and manage transactions
• Direct Post URL — Securely submit card data (PCI-compliant endpoint)
• 3DS Handling — Redirect customers for authentication challenges
• Webhooks — Receive real-time transaction status notifications

API quick reference

Endpoint	Method	Description
/api/v1/clients/	POST	Create a customer record
/api/v1/purchases/	POST	Initiate a new transaction
/api/v1/purchases/{id}/	GET	Retrieve transaction details
/api/v1/purchases/{id}/charge/	POST	Execute the payment
/api/v1/purchases/{id}/capture/	POST	Capture pre-authorized funds
/api/v1/purchases/{id}/refund/	POST	Process a refund
/api/v1/purchases/{id}/cancel/	POST	Void a transaction

Base URL: https://gate.reviopay.com/api/v1/

Authentication: Bearer token in the Authorization header.

bash

curl -X POST https://gate.reviopay.com/api/v1/purchases/ \
  -H "Authorization: Bearer $PRECIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client": "cl_7Fq2mXd91",
    "currency": "ZAR",
    "amount": 149900
  }'

Getting started

Recommended learning path

1. Start with the Quick Start Guide to complete your first test transaction
2. Review the S2S Integration Guide for your specific payment scenarios
3. Review technical reference documentation for easy evaluation of all core API requests
4. Implement webhook handling using the patterns in the Integration Guide
5. Reference Code Examples for production-ready implementations
6. Complete the Testing Checklist before going live

Sandbox environment

All development and testing should be performed in the sandbox environment using test card numbers.

Environment	Base URL
Sandbox	https://gate.reviopay.com/api/v1/
Production	https://gate.reviopay.com/api/v1/

Note: Sandbox and production use the same base URL but different API credentials.

Security considerations

Integrating with Precium S2S requires adherence to strict security standards:

• PCI DSS Compliance — Your organisation must maintain SAQ-D certification
• API Key Security — Never expose API keys in client-side code or logs
• Webhook Verification — Always validate webhook signatures in production
• HTTPS Only — All communication must use TLS 1.2 or higher
• Token Storage — Store payment tokens encrypted at rest with access controls

Support resources

Resource	Description
Technical Documentation	This documentation suite
API Reference	OpenAPI specification available in dashboard
Sandbox Testing	Full-featured test environment
Support Email	support@precium.com

Next steps

Ready to begin? Start with the Quick Start Guide to process your first test transaction in minutes.

For questions or support, contact us at support@precium.com.