API Reference βeta

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

The payment process happens in two steps using the POST method:

‍Payment request: This is where a new payment is created. Allpay sends back a URL for the payment page where the customer will be redirected.
‍Successful payment notification: After a successful payment, Allpay submits you a notification with the payment details.

Both of these steps use SHA256 signature to ensure security.

Payment request

To create new payment, a POST request must be send to the following URL:

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

The POST request parameters are the following:

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

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. ENG is default.

Options: ENG, HEB, RUS

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

backlink_url

string

URL for "Return to site" button on the bottom of the payment page.

Note: We don't have a fail URL because payment errors are displayed directly on the payment page, prompting the customer to make a new payment attempt.

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_tehudat

number

Social ID Number (Teudat Zehut) for private customers or Company Number (Mispar Het Pey) for companies. Submit 000000000 for non-Israeli citizens/companies. If not provided, it will be requested on the payment page as required by law.

optional

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:


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

    $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']);

Response

When a payment request is initiated, Allpay will return a URL (payment_url) to direct the customer to the payment page.

Upon completing the payment, if the transaction is successful, Allpay will redirect the customer to the success_url. However, in the event of a failed payment, the customer will remain on the payment page where an error message will be displayed, along with an option to attempt another payment.

Payment notification

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

Parameter

Format

Description

Required

order_id

string

Identifier of the order from the original request.

amount

numeric

Payment amount.

currency

string

Billing currency.

Options: ILS, USD, EUR

status

numeric

0 – payment failed or wasn't conducted,
1 – successful payment,
3 – refunded.

card_mask

string

Example: 465901******7049

card_brand

string

Visa, Mastercard, AmEx, Diners etc.

foreign_card

numeric

0 - card local (issued by Israel bank), 1 - card foreign.

receipt

string

URL to EasyCount digital receipt in case EasyCount integration module is active.

add_field_1

string

Unchanged as was provided in the request.

add_field_2

string

Unchanged as was provided in the request.

sign

string

SHA256 encrypted signature of the response.

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

Code example to verify that the payment was successful:


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

Signature

Payment requests to Allpay and notifications returned from Allpay includes the 'sign' parameter which represents request signature. The signature is generated with the 'getApiSignature' function.

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.


  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;  
    }

Payment status verification

Status of transaction can be checked by submitting POST request as follows. The request must be submitted with a minimum delay of 2 seconds after the payment.

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

Parameter

Format

Description

Required

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:

Parameter

Format

Description

Required

order_id

string

Identifier of the order from the original request.

status

numeric

0 – payment failed or wasn't conducted,
1 – successful payment,
3 – refunded.

amount

numeric

Payment amount.

currency

string

Billing currency.

Options: ILS, USD, EUR

card_mask

string

Example: 465901******7049

card_brand

string

Visa, Mastercard, AmEx, Diners etc.

foreign_card

numeric

0 - card local (issued by Israel bank), 1 - card foreign,

receipt

string

URL to EasyCount digital receipt in case EasyCount integration module is active.

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.

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

Parameter

Format

Description

Required

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:

Parameter

Format

Description

Required

order_id

string

Identifier of the order from the original request.

card_mask

string

Example: 465901******7049

card_brand

string

Visa, Mastercard, AmEx, Diners etc.

foreign_card

numeric

0 - card local (issued by Israel bank), 1 - card foreign,

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:

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

March 14, 2024:

The receipt parameter is included in both payment notification and payment verification response. This parameter provides the URL to the digital receipt, which is generated by the EasyCount module when the module is activated in the account settings.

Please note, that the request URL changed to...api4.

‍

February 09, 2024:

Added new optional parameter for Payment Request: client_tehudat, representing the client's Social ID Number (Teudat Zehut). If provided, Allpay won't prompt the client for manual entry. If not provided, it will be requested on the payment page, as required by law. For non-Israeli citizens, submit 000000000.

December 24, 2023:

fail_url parameter will not be longer applied because payment errors are displayed directly on the payment page, prompting the customer to make a new payment attempt.

New parameter added: backlink_url, which is a URL for the new "Return to site" button on the bottom of the payment page.

December 21, 2023:

New parameters added in the responses for payment protocol, status verification and token requests: card_mask (example: 465901******7049), card_brand (example: visa, mastercard etc.) and foreign_card (issued in Israel or abroad).

Request URLs changed from ...api1 to ...api2. Example: https://allpay.to/app/?show=getpayment&mode=api1 (before) vs. https://allpay.to/app/?show=getpayment&mode=api2 (now).

September 09, 2023:

Added endpoint for creating and using tokens.

‍June 30, 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.

February 09, 2024:

December 24, 2023:

fail_url parameter will not be longer applied because payment errors are displayed directly on the payment page, prompting the customer to make a new payment attempt.

New parameter added: backlink_url, which is a URL for the new "Return to site" button on the bottom of the payment page.

December 21, 2023:

Request URLs changed from ...api1 to ...api2. Example: https://allpay.to/app/?show=getpayment&mode=api1 (before) vs. https://allpay.to/app/?show=getpayment&mode=api2 (now).

September 09, 2023:

Added endpoint for creating and using tokens.

‍June 30, 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.

API Reference βeta

Requirements

Payment protocol

Payment request

payment request url

PAYMENT REQUEST Parameters

payment request (php)

Response

Payment notification

response Parameters

payment verification (php)

Signature

SHA256 signature function (php)

Payment status verification

payment verification url

PAYMENT verification REQUEST Parameters

response Parameters

Tokens

TOKEN REQUEST url

token REQUEST Parameters

token request response Parameters

token payment response Parameters

Test Mode

Support

Changelog