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.