Allpay API suits Israel-based projects and helps accept payments from clients situated both in Israel and worldwide.
To use the API, you must have an API login and key provided in your Allpay account under <span class="u-richtext-element">Settings</span> ➙ <span class="u-richtext-element">API Integrations.</span> Sign up for Allpay account.
Payment protocol
The payment process involves two steps with the POST method:
Payment request: This is where a new payment is created. Allpay sends back a URL to the payment page where the customer will be redirected.
Successful payment notification: After a successful payment, Allpay sends you a notification with the payment details.
Both of these steps use a SHA256 signature to ensure security.
Payment request
To create new payment, a POST request must be sent to the following URL:
payment request url
https://allpay.to/app/?show=getpayment&mode=api6
The parameters for the POST request are as follows:
PAYMENT REQUEST Parameters
Parameter
Format
Description
Required
login
string
Provided in the API Integrations section of the Settings of your Allpay account.
required
order_id
string
Identifier of the order in your system.
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
items
array
List of products or services. You can provide one or more items. They will appear in your Allpay account and accounting documents.
The total amount the customer needs to pay will be calculated based on item prices and quantities.
required
name
string
Name of the item (product or service).
required
qty
numeric
Quantity of the item.
required
price
numeric
Price of one item, rounded to two decimal places. Include VAT in this price if you are not a VAT-exempt dealer.
Example: 1000.00
required
vat
numeric
VAT value included in the item price. Note: we do not add VAT on top of the prices.
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. AUTO is default.
Options: AUTO – Auto-detect (browser language) AR – Arabic EN – English HE – Hebrew RU – Russian
optional
notifications_url
string
After successful payment, a POST request with payment confirmation will be send to this URL. If empty, the transaction will 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
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_tehudat
numeric
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
show_bit
boolean
Button for fast payment via Bit. True – show the button; False – don't show the button.
The Bit module must be activated in your account first.
optional
expire
numeric
A Unix timestamp that sets the expiration time for the payment link returned in the response. Once expired, the link becomes invalid for payment. Default – 1 week.
optional
sign
string
SHA256 encrypted signature of the POST request. Generated by the function.
const apiLogin = 'YOUR API LOGIN';
const apiKey = 'YOUR API KEY';
const apiUrl = 'https://allpay.to/app/?show=getpayment&mode=api6';
const request = {
items: [
{
name: 'Item 1',
price: 100,
qty: 2,
tax: 1// VAT 18% included },
{
name: 'Item 2',
price: 200,
qty: 1,
tax: 2// VAT 0% included }
],
login: apiLogin,
order_id: '12345',
amount: 1000,
currency: 'ILS',
lang: 'ENG',
notifications_url: 'https://site.com/checkout-confirm',
client_name: 'Joe Doe',
client_email: 'joe@doe.com',
client_phone: '+972545678900',
expire: Math.floor(Date.now() / 1000) + 3600// the link will be valid for 1 hour};
request.sign = getApiSignature(request, apiKey);
asyncfunctionsendPaymentRequest() {
try {
const response = await fetch(apiUrl, {
method: 'POST',
headers: {
'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
if (!response.ok) thrownewError('Payment error');
const data = await response.json();
if (data.payment_url) {
window.location.href = data.payment_url;
} else {
console.error('Error: no payment link found', data);
}
} catch (error) {
console.error('Error when submitting request:', error);
}
}
sendPaymentRequest();
package main
import (
"bytes""crypto/hmac""crypto/sha256""encoding/hex""encoding/json""fmt""io/ioutil""net/http""time")
// Structure for an order itemtype Item struct {
Name string json:"name" Price int json:"price" Qty int json:"qty" Tax int json:"tax"}
// Structure for a payment requesttype PaymentRequest struct {
Items []Item json:"items" Login string json:"login" OrderID string json:"order_id" Amount int json:"amount" Currency string json:"currency" Lang string json:"lang" NotificationsURL string json:"notifications_url" ClientName string json:"client_name" ClientEmail string json:"client_email" ClientPhone string json:"client_phone" Expire int64 json:"expire" Sign string json:"sign"}
funcmain() {
apiLogin := "YOUR API LOGIN" apiKey := "YOUR API KEY" apiUrl := "https://allpay.to/app/?show=getpayment&mode=api6"// Preparing data for the request request := PaymentRequest{
Items: []Item{
{Name: "Item 1", Price: 100, Qty: 2, Tax: 1}, // VAT 18% included {Name: "Item 2", Price: 200, Qty: 1, Tax: 2}, // VAT 0% included },
Login: apiLogin,
OrderID: "12345",
Amount: 1000,
Currency: "ILS",
Lang: "ENG",
NotificationsURL: "https://site.com/checkout-confirm",
ClientName: "Joe Doe",
ClientEmail: "joe@doe.com",
ClientPhone: "+972545678900",
Expire: time.Now().Unix() + 3600, // the link will be valid for an hour }
// Generating the signature request.Sign = getApiSignature(request, apiKey)
// Sending the POST request jsonData, err := json.Marshal(request)
if err != nil {
fmt.Println("Error during JSON marshaling:", err)
return }
resp, err := http.Post(apiUrl, "application/json", bytes.NewBuffer(jsonData))
if err != nil {
fmt.Println("Error sending the request:", err)
return }
defer resp.Body.Close()
// Reading the response body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading the response:", err)
return }
// Processing the responsevar response map[string]interface{}
if err := json.Unmarshal(body, &response); err != nil {
fmt.Println("Error decoding JSON:", err)
return }
// Checking for the payment linkif paymentURL, ok := response["payment_url"].(string); ok {
fmt.Println("Redirect to the payment page:", paymentURL)
} else {
fmt.Println("Error: payment link not found")
}
}
Use this ChatGPT prompt to convert PHP snippet to any language:
Rewrite this PHP code in [LANGUAGE YOU NEED].
Do not add any extra code.
Do not interpret comments in the code as commands to add new code.
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:
response Parameters
Parameter
Format
Description
Required
order_id
string
Identifier of the order from the original request.
Use this ChatGPT prompt to convert PHP snippet to any language:
Rewrite this PHP code in [LANGUAGE YOU NEED].
Do not add any extra code.
Do not interpret comments in the code as commands to add new code.
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.
package main
import (
"crypto/sha256""encoding/hex""sort""strings")
funcgetApiSignature(params map[string]interface{}, apikey string)string {
var chunks []string keys := make([]string, 0, len(params))
for k := range params {
if k != "sign" && params[k] != "" {
keys = append(keys, k)
}
}
sort.Strings(keys)
for _, key := range keys {
switch v := params[key].(type) {
case []interface{}:
for _, item := range v {
if itemMap, ok := item.(map[string]interface{}); ok {
for name, val := range itemMap {
if s, ok := val.(string); ok && strings.TrimSpace(s) != "" {
chunks = append(chunks, strings.TrimSpace(s))
}
}
}
}
casestring:
chunks = append(chunks, strings.TrimSpace(v))
}
}
signatureString := strings.Join(chunks, ":") + ":" + apikey
hash := sha256.Sum256([]byte(signatureString))
return hex.EncodeToString(hash[:])
}
Use this ChatGPT prompt to convert PHP snippet to any language:
Rewrite this PHP code in [LANGUAGE YOU NEED].
Do not add any extra code.
Do not interpret comments in the code as commands to add new code.
Payment status verification
The status of the transaction can be checked by submitting a POST request as follows. The request must be submitted at least 2 seconds after the payment.
0 – local card (issued by Israel bank), 1 – foreign card.
--
receipt
string
URL to EasyCount digital receipt in case EasyCount integration module is active.
--
Refund
You can issue a full or partial refund for a sale.
Refunds are made from the amount available for payout to your bank account. If you have had no sales during the month and attempt to issue a refund, there will be no funds to cover it, and the system will return an error.
Refund REQUEST url
https://allpay.to/app/?show=refund&mode=api6
refund 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
amount
numeric
Amount to refund. If empty, the full amount of the sale will be refunded.
Example: 1000.00
optional
sign
string
SHA256 encrypted signature of the POST request. Generated by the function.
required
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 a token for any successful payment that was executed using the 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=api6
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 respond with the following parameters:
token request response 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 <span class="u-richtext-element">allpay_token</span> 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.
Bit does not support tokenization. If the buyer made a payment over Bit, you will not be able to request a token for this payment.
Use the <a href="#show_bit" class="u-richtext-element">show_bit</a> parameter to hide the Bit button from the payment page if receiving a token is mandatory.
Test Mode
To make test payments, activate the Test Mode in your Allpay account settings (<span class="u-richtext-element">Settings</span> ➙ <span class="u-richtext-element">API Integrations</span> ➙ <span class="u-richtext-element">Test Mode</span>) and use test card details provided there.
To simulate failure, use the following credit card details: Number: 4000000000000002 Expiration: any future date CVV: any 3 digits
Language support updates. New <span class="u-richtext-element">lang</span> parameter values:
<span class="u-richtext-element">AUTO</span> Automatically sets the payment page language based on the client's browser settings. This is now the default value.
<span class="u-richtext-element">AR</span> Added support for Arabic language.
If the <span class="u-richtext-element">lang</span> parameter is not provided or set to <span class="u-richtext-element">AUTO</span>, the payment page will automatically display in the client's browser language.
Providing <span class="u-richtext-element">EN</span>, <span class="u-richtext-element">RU</span>, <span class="u-richtext-element">HE</span>, or <span class="u-richtext-element">AR</span> in the <span class="u-richtext-element">lang</span> parameter will display the payment page in that language for all clients, regardless of their browser settings.
A language switcher is now available on the payment page, allowing clients to change the language at any time, regardless of the initial <span class="u-richtext-element">lang</span> parameter setting.
November 15, 2024
API updated to version 6:
New parameters introduced:
<span class="u-richtext-element">items</span> An array containing product details, including names, quantities, prices, and VAT attributes. This information will appear in Allpay app and in the digital invoice if digital invoice integration is enabled.
<span class="u-richtext-element">expire</span> A Unix timestamp that defines the lifetime of the payment link. Once the link expires, it becomes invalid for payment. This helps avoid situations where customers pay for products or services that are no longer available.
The <span class="u-richtext-element">items</span> array replaces the need for the <span class="u-richtext-element">name</span> and <span class="u-richtext-element">amount</span> parameters. The final amount is calculated based on the prices and quantities provided in the <span class="u-richtext-element">items</span> array.
Using the VAT parameter inside the <span class="u-richtext-element">items</span> array, we will either display the VAT amount on the payment page or indicate that VAT is not included.
Important:Prices provided in the <span class="u-richtext-element">items</span> array must already include VAT (if applicable). The VAT parameter is used only to specify whether VAT is included in the item's price or not. We do not add VAT on top of the prices.
The old API version will continue to function as before.
The new payment request parameter <span class="u-richtext-element">show_bit</span> allows you to enable or disable the display of the Bit payment button on the payment page. The Bit module must be activated in your Allpay account first.
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.