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 and Secret Key. These keys should be kept secure and never exposed to the public.
Security Warning
Your Merchant Key and Secret Key are unique to your account. Never share them.
HMAC Signature
For enhanced security, all requests should be signed using HMAC-SHA256. The signature is calculated using your Secret Key.
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(
'MerchantKey' => 'YOUR_MERCHANT_KEY', // Merchant Key
'amount' => '19.99', // Amount to be paid
'currency' => 'EUR', // Currency (EUR or USD)
'RefOrder' => 'ORDER-', // Reference Order number (must be unique)
'Customer_Email' => 'jofhen785@gmail.com', // Customer's email
'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'
);
// Clone data BEFORE adding signature
$varsToSign = $MyVars;
// Secure signature
$secret_key = 'YOUR_SECRET_KEY'; // provided by Payblis server-side only
$signature = hash_hmac('sha256', json_encode($varsToSign), $secret_key);
// Add signature after calculation
$MyVars['signature'] = $signature;
// Encoding
$serializedData = serialize($MyVars);
$encoded = base64_encode($serializedData);
// Redirect to secure payment page
$paymentUrl = "https://pay.payblis.com/api/payment.php?token=" . $encoded;
header("Location: " . $paymentUrl);
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
IPN Security
All IPN notifications are signed with HMAC-SHA256 using your Secret Key. Verify the signature in the X-Payblis-Signature header to ensure the notification is authentic.
Parameters Reference
Required Parameters
Parameter | Type | Description | Required |
---|---|---|---|
MerchantKey | String | Your unique merchant identification key | Yes |
amount | String | Transaction amount (format: "XX.XX") | Yes |
currency | String | Currency (format: "EUR", "USD") | Yes (for new integrations) |
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 |
signature | String | HMAC-SHA256 signature of the request parameters | Yes (for new integrations) |
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 |
407 | Invalid signature | HMAC signature verification failed |
408 | Secret key not found | Merchant's secret key is not configured |
500 | Internal Server Error | Generic server error |
Test Cards
Important Note
Use sandbox 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.