API Reference

Example H2
Example H3
Example H4
Example H5
Example H6
Telegram logo
Track API Changelog

Requirements

Allpay API suites Israel-based projects and helps to accept payments from clients situated both in Israel and worldwide.

To use API you must have API login and key provided in your Allpay account (Settings ➙ API Integrations). Sign up for Allpay account.

Payment protocol

Payment is executed using POST method in two steps:

  1. Request to Allpay to create a new payment. In response Allpay will return URL to redirect the customer to the payment page.
  2. After the successful payment, Allpay will return you a confirmation.

Both POST requests are SHA256 signed.

Payment request

To create new payment, a POST request must be send to the URL https://allpay.to/app/?show=getpayment&mode=api1.

payment request url

https://allpay.to/app/?show=getpayment&mode=api1

The POST request parameters are the following:

PAYMENT REQUEST Parameters

Parameter
Format
Description
Required
name
string
Name of the order or payment. Under this name the transaction will appear in your Allpay account.

Example: "Order #123456" or "Payment for delivery"
required
login
string
Your login provided in API Integrations section of the Setting of your Allpay account.
required
order_id
string
Identifier of the order in your system.
required
amount
numeric
Payment amount. Number rounded to hundredths.

Example: 1000.00
required
currency
string
Billing currency. ILS is default. When account has no permission for USD or EUR transactions, the value will be converted to ILS according to the Google Finance rates.

Options: ILS, USD, EUR
optional
lang
string
Language of the payment page where the customer enters his bank card details. ENG is default.

Options: ENG, HEB
optional
notifications_url
string
After successful payment, a POST request with payment confirmation will be send to this URL. If empty, the transaction we be displayed in your Allpay account only.
optional
success_url
string
Customer will be redirected to this URL after successful payment. If empty, the customer will be redirected to the default Allpay success page.
optional
fail_url
string
Customer will be redirected to this URL if payment error occurs. If empty, the customer will be redirected to the default Allpay error page.
optional
tash
numeric
The maximum allowed number of installment payments that customer will be proposed to choose on the payment page.

Options: Up to 12.
optional
tash_first_payment
numeric
Amount of the first installment payment. Customer will not be able to change it.

Example: 500.00
optional
tash_fixed
numeric
Makes the number of installment payments fixed so the customer can not change it.
0 (default) – the customer will be able to select the number of payments in the range from 1 to the value of the tash parameter;
1 - the number of payments will be fixed and equal to the value of the tash parameter.

Options: 0 or 1
optional
allpay_token
string
Makes payment using token without need for the customer to enter bank card details again. See Tokens section.
optional
client_name
string
Customer name in any language.
required
client_email
string
Customer e-mail. Used to send invoice if a digital invoices service integrated with your Allpay account.
required
client_phone
string
Customer phone number.
optional
add_field_1
string
Any additional data on the order or the customer. Will be returned unchanged to the notifications_url.
optional
add_field_2
string
Any additional data on the order or the customer. Will be returned unchanged to the notifications_url.
optional
sign
string
SHA256 encrypted signature of the POST request. Generated by the function.
required

Here is the example of a POST payment request:

payment request (php)


    $api_login = 'YOUR API LOGIN';
    $api_key = 'YOUR API KEY';
    $api_url = 'https://allpay.to/app/?show=getpayment&mode=api1';

    $request = [
        'name' => 'Payment for order #12345 on site.com',
        'login' => $api_login,
        'order_id' => '12345',
        'amount' => 1000.00,
        'currency' => 'ILS',
        'lang' => 'ENG',
        'notifications_url' => 'https://site.com/checkout-confirm',        
        'client_name' => 'Joe Doe',
        'client_email' => 'joe@doe.com',
        'client_phone' => '+972545678900'        
    ];
    
    $sign = getApiSignature($request, $api_key);
    $request['sign'] = $sign;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_url);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $request); 
    $result = curl_exec($ch); 
    curl_close($ch);
    $data = json_decode($result, true);
    header('Location: ' . $data['payment_url']);

In response to the request, Allpay will return URL to route the customer to the payment page. When the payment is made Allpay will send you either success or error message.

Signature

The payment request to Allpay and the successful payment notification returned from Allpay contains the 'sign' parameter with the request signature. In the example above, the 'getApiSignature' function is used to generate the signature.

The 'getApiSignature' function sorts the request parameters (except for the 'sign' parameter and parameters with empty values) and use their values and the ":" (colon) separator to create the string. API Key is added to the end of the string. Then the string is hashed with SHA256 algorithm.

SHA256 signature function (php)


  function getApiSignature($params, $apikey) { 
        ksort($params);
        $chunks = [];
        foreach($params as $k => $v) {
            $v = trim($v);
            if ($v !== '' && $k != 'sign') {
                $chunks[] = $v;
            }  
        }
        $signature = implode(':', $chunks) . ':' . $apikey;
        $signature = hash('sha256', $signature);
        return $signature;  
    }

Request response

After successful payment, Allpay will submit a POST request to the 'notifications_url' with the following parameters:

response Parameters

Parameter
Format
Description
Required
order_id
string
Identifier of the order from the original request.
required
amount
numeric
Payment amount.
required
status
numeric
0 - payment failed, 1 - successful payment.
required
add_field_1
string
Unchanged as was provided in the request.
optional
add_field_2
string
Unchanged as was provided in the request.
optional
sign
string
SHA256 encrypted signature of the response.
required

An order can be considered paid when the returned status is equal to 1 and the the signature is valid.

Code example to verify if the payment was successful:

payment verification (php)


$sign = getApiSignature($_POST, $api_key);
if($_POST['status'] == 1 && $_POST['sign'] == $sign) {
    // successful payment action
}

Payment status verification

Transaction status can be checked by submitting POST request as follows.

payment verification url

https://allpay.to/app/?show=paymentstatus&mode=api1

PAYMENT verification REQUEST Parameters

Parameter
Format
Description
Required
login
string
Your login provided in API Integrations section of your Allpay account Settings.
required
order_id
string
Identifier of the order in your system.
required
sign
string
SHA256 encrypted signature of the POST request. Generated by the function.
required

Allpay will response with the following parameters:

response Parameters

Parameter
Format
Description
Required
order_id
string
Identifier of the order from the original request.
--
status
numeric
0 – pending, 1 – successful payment.
--

Tokens

A token is a securely captured and encrypted representation of a customer's bank card that can be used to initiate new payments without the need for the customer to re-enter their card details.

You can request token for any successful payment that was executed using Payment protocol. To receive the token submit signed request with the order_id of the original payment.

TOKEN REQUEST url

https://allpay.to/app/?show=gettoken&mode=api1

token REQUEST Parameters

Parameter
Format
Description
Required
login
string
Your login provided in API Integrations section of your Allpay account Settings.
required
order_id
string
Identifier of the order in your system.
required
sign
string
SHA256 encrypted signature of the POST request. Generated by the function.
required

Allpay will response with the following parameters:

token request response Parameters

Parameter
Format
Description
Required
order_id
string
Identifier of the order from the original request.
--
allpay_token
string
Token for the customer's bank card.
--

Now you can use the token to initiate new payment request by submitting it with the allpay_token parameter.

The payment will be executed immediately and, instead of the payment page URL, Allpay will return the following parameters:

token payment response Parameters

Parameter
Format
Description
Required
order_id
string
Identifier of the order from the original request.
--
status
numeric
0 – pending, 1 – successful payment.
--

Test Mode

To make test payments, activate the Test Mode in your Allpay account settings (Settings ➙ API Integrations ➙ Test Mode) and use test card details provided there.

To simulate failure, use real credit card details.

Support

Please route support requests to support@allpay.co.il or Telegram: @allpay_israel

Track API updates in the Telegram channel: Allpay API Updates.

Changelog

September 09, 2023: Added endpoint for creating and using tokens.

‍June 29, 2023: When submitting currency parameter in USD or EUR, the amount will be auto-converted to ILS on the Allpay side. Exchange rates are taken in real time from Google Finance.

June 29, 2023: Added payment verification method to check transaction status.