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.