Latest Update : 2018-30-6
API Version : 1.4

Introduction

PayPax offers a simple yet powerful and flexible API for developers. We use REST and JSON architecture to make it easier for developers to understand and develop. All the requests are encrypted carried out through the secure HTTPS protocol.

One of the services that is offered to customers and developers through the API is the multi-purpose payment gateway for creating gift cards, increase account balance with gift cards, sales statistics, etc.

In addition, to make it fast and easy to develop, PayPax offers two modes of accounts which are Test and Live accounts. There is no need to switch between the two modes as there are two separate API keys for each gateway.

To stay tuned with the latest API updates and other news and tutorials, make sure to subscribe to PayPax developers newsletter.

Workflow :
  1. The customer chooses the product/service from your website.
  2. The customer clicks on the pay with PayPax button.
  3. Customer's data and the product/service data is sent to PayPax API from your website.
  4. The customer is transferred to the payment page and chooses one of the payments methods available.
  5. The customer enters credit card information and clicks to make the payment.
  6. Whether the payment was successful or unsuccessful will be sent to the callback URL that you have defined. You can examine the received data and in case the payment was successful, you can provide the customer with the product/service and in case the payment was unsuccessful, the invoice will be displayed to the customer so they can make the payment again.

Getting Started

Force HTTPS

The encryption within HTTPS is intended to provide benefits like confidentiality, integrity and identity. Your customer information remains confidential from prying eyes because only customer browser and the server can decrypt the traffic. Integrity protects the data from being modified without your knowledge.

All submissions of payment info in PayPax are made via a secure HTTPS connection

API KEY

For all the requests, PayPax needs a token or the API key. If this parameter is not taken into account or an unverified key is used, PayPax will reject all your requests. You need to register to get the API key (here).

Each user account has two modes which are Test and Live API. The Test mode is used for developing and integrating with PayPax and on the final steps of releasing the app/website, you need to use the Live mode for making real payments.


Quick Start

  1. Sign up to create an account
  2. Go to Merchant > Stores and choose Add Store and fill in the requested fields and wait for your payment to be verified. After verification, the API key will be sent to you.
  3. Use prepared codes to connect to the checkout API
Create Checkout Request (PHP)
                                    
                                        // prepare data to send
$RequestData = [
    'api_key' => 'ZmYxZTc0ODljYzU2YmM1MTlkNzk5NTE4OGZhYWM1NDk=',
    'amount' => 152.85,
    'currency'   => 'usd',
    'callback'   => 'https://example.com/callback',
    'invoice_data'=> [
            ['name'=>'product license','count'=>2,'amount'=>75],
            ['name'=>'tax','count'=>1,'amount'=>2.85],
    ],
    'logo_url'=>'https://example.com/logo.png',
    'company_name'=> 'Example Co'
];
// start curl request
$ch = curl_init('https://paypax.net/cp/api/checkout/create');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($RequestData));
$response = curl_exec($ch);
curl_close($ch);
// decode response
$response = json_decode($response);
// check is response ok
if($response->code == 200){
    /*
     * Do this:
     * Store $response->token at table
     * and redirect user to $response->url
     */
    header("Location:$response->url");
}else{
    /*

     * fix error
     */
}

                                    
                                
Complete Checkout Request (PHP)
                                    
// prepare data to send
$RequestData = [
    'api_key' => 'ZmYxZTc0ODljYzU2YmM1MTlkNzk5NTE4OGZhYWM1NDk=',
    'reference' => '4b886befa9667c4d26418baed6201830',
];
// start curl request
$ch = curl_init('https://paypax.net/cp/api/checkout/verify');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($RequestData));
$response = curl_exec($ch);
curl_close($ch);
// decode response
$response = json_decode($response);
// check is response ok
if($response->code == 200){
    if($response->data->status == 'PAYED'){
        // do sth after successful payment and store data
        $method = $response->data->payment_method;
        $data = $response->data->date;
        $amount = $response->data->amount;
        $currency = $response->data->currency;
        $currency = $response->data->currency;
    }elseif ($response->data->status == 'CANCELED'){
        // Show Cancel message or use $response->data->message
    }elseif($response->data->status == 'NOT PAYED'){
        // pars error message with following function
        $message = ShowErrorMessage($response->data->code);
    }
}else{
    /*
     * fix error
     */
}

function ShowErrorMessage($code){
    switch ($code){
        case 11:
            return 'Payment canceled';
            break;
        case 12:
            return 'unauthorized user';
            break;
        case 13:
            return 'card/user has no money';
            break;
        case 14:
            return 'card expired';
            break;
        case 15:
            return 'card/user not supported';
            break;
        default:
            return 'unknown error';
            break;
    }
}
                                    
                                

Checkout

Create Checkout

In order for a customer to be able to purchase a desired product, a checkout must be created. The checkout can be updated at any time with the information provided by the customer.

The Checkout API is an integration method implemented within PayPax Payment Gateway. It is useful for any online merchant who currently does not have a checkout page or the ability to get customer payments details.

Endpoint : https://paypax.net/cp/api/checkout/create
Method : POST
Required Paramters
Name Type Description
api_key STRING The unique vendor key which has been created in the Store section of the system.
amount FLOAT Total invoice amount
currency STRING Currency only including (eur - usd)
callback STRING Callback URL to the host site
(e.g.  https://example.com/callback)
Optional Parameters
Name Type Description
invoice_data ARRAY of ARRAYS Payment invoice details including   [ [name: (string),count : (int), amount: (float)] ]
billing_data ARRAY [ Email: (string), Name: (string), Mobile: (int), ]
shipping_data ARRAY [ Country : (string(ex:usa)), City: (string), Address : (string) ]
logo_url STRING Your logo address (The URL must be HTTPS)
company_name STRING Your website or company name of at most 20 characters
short_desc STRING A brief description of your company in at most 120 characters
recurring_data ARRAY To renew payment, you can use these parameters (fully described in the below table)
Recurring Data Object (Optional)

If you would like to renew this payment, you can use recurring_data parameter, otherwise, the payment will be done once.

Name Data Type Description Required?
period INTEGER The time intervals for renewing payments are on monthly basis and between 1 to 12 (default: 1). No
amount FLOAT If the renew amount is different for each month, you can send the amount. No
callback STRING the response url after each renewal. e.g., https://example.com/renew-callback?id=10001 Yes
Response

You might receive one of the below responses. It must be mention that based on the response that you receive, you must take below actions.

If the code is 200, you can use the URL amount to refer the users to it and you can keep the token amount to synchronize your table with the payment gateway.
Otherwise, you can troubleshoot by taking the descriptions and the text of the message into consideration.

Code Status Parameters Description
200 true token url The request was submitted successfully. You can now proceed to next steps.
400 false message The required data is not send or is invalid (for example, tr is not a currency)
401 false message The sent key (api_key) is not correct
403 false message Your payment gateway is not active or is not verified yet
409 false message Referrer domain is different from the domain specified for this gateway
Example :
                                    
{

    "status":true,
    "code":200,
    "token":"21697e559b6d7de1ace67dcfdab4d917",
    "url":"http://paypax.net/cp/cgi/go?reference=21697e559b6d7de1ace67dcfdab4d917"

}
                                    
                                

Complete Checkout

After creating a checkout request and referring the customer to the payment page, the customer will enter the payment data and the reference token will be sent to the callback URL that you have defined.

On this step, to complete and confirm the payment, the complete payment request must be sent as follows:

Endpoint : https://paypax.net/cp/api/checkout/update
Method : POST
Required Paramters
Name Data Type Description
api_key STRING The unique vendor key which has been created in the Store section of the system.
reference STRING This parameter is sent to the callback_url you have defined before (Method:GET)
Response
Code Status Parameters Description
200 true data Includes a group of data which is fully described in the below table
400 false message The required data is not send or is invalid (for example, tr is not a currency)
401 false message The sent key (api_key) is not correct
403 false message Your payment gateway is not active or is not verified yet
409 false message Referrer domain is different from the domain specified for this gateway
Data Object Parameters
Name Values Description
payment_status PAYED | CANCELED | PENDING PAYED means the payment has successful.
CANCELED means the customer has clicked the button to cancel the transaction and has discontinued the payment.
PENDING means the customer is still in the process of making the payment and the process is not complete yet.
currency eur | usd The currency that was requested at the checkout
amount FLOAT The amount that was requested at the checkout
payment_method paypal | credit | skrill | paypax The method that the user has chosen for the payment
payment_date Date/Time(Timestamp) The exact date at which the user has made the payment which is in timestamp format
code Error Code 11 -> Canceled transaction
12 -> Unauthorized user
13 -> Insufficient funds
14 -> Credit card has been expired
15 -> Credit card not supported
19 -> Unknown error
Example :
                                    
{
   "status":true,
   "code":200,
   "data":{
      "status":"PAYED",
      "amount":30,
      "currency":"usd",
      "date":1528210282,
      "payment_method":"PayPax"
   }
}
                                    
                                

Gift Card

Generate Gift Card

By using this method you can create gift cards automatically. You can also choose the number and amount for creating bulk gift cards.

Endpoint : https://paypax.net/cp/api/giftcard/redeem
Method : POST
Required Parameters
Name Data Type Description
api_key STRING The unique vendor key which has been created in the Store section of the system.
amount FLOAT Amount of each gift card
currency STRING Currency only including
Currency of each gift card usd | eur
Optional Parameters
Name Data Type Description
count INT Integer number greater than zero (if not sent, it will be considered 1)
recipient STRING Email or wallet ID of the person who is receiving the gift card. ( If this field is left blank, gift cards will be sent to the vendor’s account)
Response
Code Status Parameters Description
200 true data Includes the following array [ [serial:’’,code:’’] ]
400 false message The required data is not send or is invalid (for example, tr is not a currency)
401 false message The sent key (api_key) is not correct
403 false message Your payment gateway is not active or is not verified yet
409 false message Referrer domain is different from the domain specified for this gateway
Example :
                                    
{
   "status":true,
   "code":200,
   "data":{
      "serial":"KQ-233300",
      "code":"1T7MQWTVEEAB4TEI"
   }
}
                                    
                                

Redeem Gift Card

By using this method you can create gift cards automatically. You can also choose the number and amount for creating bulk gift cards.

Endpoint : https://paypax.net/cp/api/giftcard/update
Method : POST
Required Parameters
Name Data Type Description
api_key STRING The unique vendor key which has been created in the Store section of the system.
code STRING Gift card code to redeem
Response
Code Status Parameters Description
200 true data Includes an array containing the redeemed gift card data:
Amount: Gift card amount
Currency: Gift card currency
Serial: Gift card serial number
Text: Text displayed to the user
401 false message The sent key (api_key) is not correct
403 false message Your payment gateway is not active or is not verified yet
409 false message Referrer domain is different from the domain specified for this gateway
Example :
                                        
{

    "status":true,
    "code":200,
    "data":{
        "amount":30.00,
        "currency":"usd",
        "serial":"KQ-233300",
        "text":"Gift Card with serial number KQ-233300 and 30.00 $ value redeemed"
    }

}
                                        
                                    

Wallet

Send Money

By using this feature, you can transfer a prticular amount from one of your wallets to other PayPax users' wallet easily and automatically. To provide you with more security and avoiding anonymous requests, we offer you the security code feature.

Endpoint : https://paypax.net/cp/api/wallet/transfer
Method : POST
Required Parameters
Name Type Description
api_key STRING The unique vendor key which has been created in the Store section of the system.
amount FLOAT Total invoice amount
currency STRING Currency only including  (eur – usd )
sender STRING Your wallet Sender String, e.g. PX-123456
recipient STRING Recipient wallet, e.g. PX-98546
Optional Parameters
Name Type Description
secret STRING Security code for transaction
description STRING Notes and description
Response
Code Status Parameters Description
200 true message Transfer details
400 false message The required data is not send or is invalid (for example, tr is not a currency)
401 false message The sent key (api_key) is not correct
402 false message Wallet balance is less than the requested amount
403 false message Your payment gateway is not active or is not verified yet
404 false message Recipient wallet is incorrect
409 false message Referrer domain is different from the domain specified for this gateway
415 false message Transferring to the sender account is not possible
Example :
                                            
                                                {
   "status":true,
   "code":200,
   "message":"Your 30.00 $ transfer successfully submitted to user John Doe and wallet ID PX-88527111 This transaction security code is W$64a"
}
                                            
                                        

Trial payment through Sandbox

Sandbox allows developers to examine their API in a test environment.

Through Sandbox payment path and offered credit cards, you can make a trial payment and test the payment and service delivery on your website.

To use Sandbox, just add "sandbox" parameter before the API path. For example, you can use the below URL to make a trial transaction in sandbox:

Endpoint : https://paypax.net/cp/sandbox/api/checkout/create

Accepted credit cards:
4111111111111111, // Visa
4222222222222, // Visa
5555555555554444, // MasterCard
6011111111111117, // Discover
378282246310005, // American Express