Introduction
Welcome to the Payblis Payment Gateway API documentation. This guide will help you integrate Payblis payment solutions into your applications.
Base URL
https://pay.payblis.com/api
Environments
Production URL
https://pay.payblis.com/api
Sandbox URL (Test Environment)
https://sandbox.payblis.com/api
Sandbox Usage
- Use this environment for testing your integration
- Test cards will only work in the sandbox environment
- No real transactions will be processed
- Same API structure and parameters as production
Authentication
Authentication is performed using your Merchant Key. This key should be kept secure and never exposed to the public.
Security Warning
Your Merchant Key is unique to your account. Never share it or expose it in client-side code.
Payment Integration
Initialize Transaction
To start a payment transaction, create a request with the required parameters and redirect to the payment page.
PHP Implementation Example
// Set up the request parameters
$MyVars = array(
'websitekey' => 'YOUR_MERCHANT_KEY', // Merchant Key
'amount' => '19.99', // Amount to be paid
'RefOrder' => 'ORDER-', // Reference Order number (must be unique)
'Customer_Email' => 'jofhen785@gmail.com', // Customer's email
'Customer_Phone' => '33625369364', // Customer's phone number
'Customer_Name' => 'Doe', // Customer's Last Name
'Customer_FirstName' => 'John', // Customer's First Name
'country' => 'France', // Customer's country
'userIP' => $_SERVER['REMOTE_ADDR'], // Customer's IP
'lang' => 'en', // Language
'store_name' => 'Example Store',
'urlOK' => 'https://your-domain.com/success',
'urlKO' => 'https://your-domain.com/failed',
'ipnURL' => 'https://your-domain.com/ipn',
);
// Serialize the data (convert array to string format)
$serializedData = serialize($MyVars);
// Base64 encode the serialized data directly (no URL encoding)
$encoded = base64_encode($serializedData);
// Prepare the subscription payment URL
$subscriptionPaymentUrl = "https://pay.payblis.com/api/payment.php?token=" . $encoded;
// Redirect the user to the payment page
header("Location: " . $subscriptionPaymentUrl);
exit;
Callbacks & IPN
Payblis provides three types of callbacks:
- Success URL (urlOK): Customer redirection after successful payment
- Failure URL (urlKO): Customer redirection after failed payment
- IPN URL (ipnURL): Server-to-server notification for payment confirmation
Recurring Payments
Initialize Subscription
To create a recurring payment, include subscription-specific parameters in your payment request.
PHP Implementation Example
// Set up the request parameters
$MyVars = array(
'websitekey' => 'YOUR_MERCHANT_KEY', // Merchant Key
'amount' => '19.99', // Amount to be paid
'RefOrder' => 'SUB-', // Reference Order number (must be unique)
'Customer_Email' => 'jofhen785@gmail.com', // Customer's email
'Customer_Phone' => '33625369364', // Customer's phone number
'Customer_Name' => 'Doe', // Customer's Last Name
'Customer_FirstName' => 'John', // Customer's First Name
'country' => 'France', // Customer's country
'userIP' => $_SERVER['REMOTE_ADDR'], // Customer's IP
'lang' => 'en', // Language
'store_name' => 'Example Store',
'urlOK' => 'https://your-domain.com/success',
'urlKO' => 'https://your-domain.com/failed',
'ipnURL' => 'https://your-domain.com/ipn',
// Subscription specific parameters
'interval_unit' => 'MONTH', // DAY, MONTH, YEAR
'interval_count' => 1, // Every 1 month
'iteration_count' => 12 // Total number of payments (12 months = 1 year)
);
// Serialize the data (convert array to string format)
$serializedData = serialize($MyVars);
// Base64 encode the serialized data directly (no URL encoding)
$encoded = base64_encode($serializedData);
// Prepare the subscription payment URL
$subscriptionPaymentUrl = "https://pay.payblis.com/api/subscription_payment.php?token=" . $encoded;
// Redirect the user to the subscription payment page
header("Location: " . $subscriptionPaymentUrl);
exit;
Parameters Reference
Required Parameters
Parameter | Type | Description | Required |
---|---|---|---|
MerchantKey | String | Your unique merchant identification key | Yes |
amount | String | Transaction amount (format: "XX.XX") | Yes |
RefOrder | String | Unique order reference | Yes |
Customer_Email | String | Customer's email address | Yes |
Customer_Name | String | Customer's name | Yes |
Customer_FirstName | String | Customer's first name | Yes |
store_name | String | Name of your store/business | Yes |
urlOK | String | Success callback URL | Yes |
urlKO | String | Failure callback URL | Yes |
ipnURL | String | IPN callback URL | Yes |
Subscription Parameters
Parameter | Type | Description | Required |
---|---|---|---|
interval_unit | String | Time unit for interval (DAY, MONTH, WEEK, YEAR) | Yes |
interval_count | Integer | Frequency of payments in the specified unit | Yes |
iteration_count | Integer | Total number of payments to be made | Yes |
Error Codes
API Error Codes
Code | Message | Description |
---|---|---|
400 | Invalid Request: Parameter is missing | Token parameter missing from URL |
401 | Invalid Data: Corrupt base64 string | Base64 decoding failed |
402 | Invalid Data: Unserialization failed | Data format incorrect |
403 | Authorization failed | Invalid MerchantKey |
404 | Missing fields | Required fields missing |
405 | Invalid Input | Missing/invalid form field |
406 | Transaction failed | Invalid transaction data |
500 | Internal Server Error | Generic server error |
Test Cards
Important Note
Activate test mode to use these cards
Brand | Number | Expire | CVV | 3D Secure | Status |
---|---|---|---|---|---|
VISA | 4556557955726624 | 12/2025 | 123 | 3DS Friction | APPROVED |
VISA | 4916994064252017 | 12/2025 | 123 | 3DS Challenge | APPROVED |
MASTERCARD | 5333259155643223 | 12/2025 | 123 | 3DS Friction | APPROVED |
MASTERCARD | 5306889942833340 | 12/2025 | 123 | 3DS Challenge | APPROVED |
VISA | 4929251897047956 | 12/2025 | 123 | 3DS Friction | DECLINED |
3D Secure Note: When challenge code is required, use '1234' for successful identification. Any other code will fail.