Create a standing order

posthttps://api.tranzila.com/v2/sto/create

This is a paid module

Please contact sales to use this module.

Standing Order - Subscription Based Payments

Charge payments every week/month/year etc.

Prerequisites - Token Creation Workflow

Before creating a Standing Order, you must first generate a credit card token. Follow these steps:

Generate a Token - Use one of Tranzila's secure payment pages to tokenize the credit card:
- Iframe Integration - Embed a payment form in your page
- Hosted Fields - Customizable hosted input fields
Identify the Terminal - The My Billing module is typically configured on a TOK (Token) terminal. This terminal type does not require CVV for recurring charges, as per credit card company regulations.
Verify Terminal Configuration - Before creating an STO, confirm which terminal is configured with the My Billing module in your Tranzila account. Use this terminal name in your API requests.
Create the STO - Use the token received from step 1 along with the correct terminal name to create the Standing Order.

What's New in V2?

VAT Configuration You can now pass the vat_percent parameter to determine the VAT percentage that will appear in the STO Dashboard in my.tranzila.

Price Index Linkage V2 introduces support for linking standing order prices to the Consumer Price Index (CPI). This feature allows automatic price adjustments based on index changes published by the Central Bureau of Statistics (CBS).

When index_linked is set to "Y", the following parameters are required:

index_type - The CBS index code (currently supported: 120010 for Consumer Price Index)
base_month - The starting reference month for index calculation (format: YYYY-MM). This is the month from which the index comparison begins. The system compares the current month's index value against this base month's index value to calculate price adjustments.
min_price - Minimum price protection ("Y" or "N"). When set to "Y", prices will never decrease below the original base price, even if the index decreases. This protects against deflation scenarios.

Item-Level Index Linkage Price index linkage is configured per item in the items array. Each item can be individually linked to the index by setting index_link to "Y".

Important

When an item has index_link set to "Y":

The base_price field is required (this is the reference price for index calculations)
The unit_price field should not be sent (the price is calculated automatically based on the index)
Items without index_link: "Y" still require unit_price as usual

Code Examples

Basic Example With Card

JSON

{
  "terminal_name": "myterminal",
  "sto_payments_number": 12,
  "charge_frequency": "monthly",
  "first_charge_date": "2024-08-24",
  "charge_dom": 25,
  "vat_percent": 18,
  "created_by_user": "CRM A user",
  "response_language": "english",
  "items": [
    {
      "name": "HDMI Splitter",
      "unit_price": 10,
      "units_number": 2,
      "price_currency": "ILS",
      "price_type": "G"
    },
    {
      "name": "Desk Lamp",
      "unit_price": 30,
      "units_number": 1,
      "price_currency": "ILS",
      "price_type": "G"
    }
  ],
  "client": {
    "name": "John Smith",
    "id": "012345632",
    "email": "johnsmith@domain.com",
    "address": "15 Tamar Street, Apt. 4, Tel Aviv 678910, Israel",
    "phone_country_code": "972",
    "phone_area_code": "050",
    "phone_number": "5558965"
  },
  "card": {
    "token": "f12cF45cI7898t75548",
    "expire_month": 5,
    "expire_year": 2027,
    "card_holder_id": "012345632",
    "card_holder_name": "John Smith"
  }
}

Example With Price Index Linkage

JSON

{
  "terminal_name": "myterminal",
  "sto_payments_number": 12,
  "charge_frequency": "monthly",
  "first_charge_date": "2025-12-30",
  "charge_dom": 1,
  "currency_code": "ILS",
  "vat_percent": 18,
  "index_linked": "Y",
  "index_type": 120010,
  "base_month": "2021-12",
  "min_price": "Y",
  "card": {
    "token": "Z76f667a58a48581984",
    "expire_month": 2,
    "expire_year": 2025
  },
  "client": {
    "name": "Customer Name",
    "phone_area_code": "050",
    "phone_number": "5551234",
    "email": "customer@example.com"
  },
  "items": [
    {
      "code": "PROD001",
      "name": "Premium Service",
      "type": "I",
      "units_number": 3,
      "unit_type": 1,
      "price_type": "G",
      "index_link": "Y",
      "base_price": 10
    },
    {
      "code": "PROD002",
      "name": "Basic Service",
      "unit_price": 2,
      "type": "I",
      "units_number": 2,
      "unit_type": 1,
      "price_type": "G"
    }
  ]
}

Basic Example With Bank Account (MASAV)

JSON

{
  "terminal_name": "myterminal",
  "sto_payments_number": 12,
  "charge_frequency": "weekly",
  "first_charge_date": "2024-08-24",
  "charge_dom": 25,
  "items": [
    {
      "name": "HDMI Splitter",
      "unit_price": 10,
      "units_number": 2,
      "price_currency": "ILS",
      "price_type": "G"
    }
  ],
  "msv": {
    "bank_code": 12,
    "branch_code": "659",
    "account_number": "127963"
  }
}

Request

Headers

X-tranzila-api-request-timestringrequired

Request time sent in Unix format (large integer counting milliseconds from Jan 1st, 1970 00:00:00)

X-tranzila-api-app-keystringrequired

Application public key supplied by Tranzila

X-tranzila-api-noncestringrequired

A 40 bytes NONCE – unique random string generated with any random bytes function

X-tranzila-api-access-tokenstringrequired

hash_hmac using 'sha256' on application key with secret + request-time + nonce

Body

application/json

terminal_nameterminalNamerequired

sto_payments_numberintegerrequired

Total number of payments for this standing order

Example:12

charge_frequencystringrequired

How often to charge the customer

Allowed values:weeklymonthlyquarterlyhalf-yearlyyearly

Example:monthly

first_charge_datestring<date>

The date of the first charge (format YYYY-MM-DD)

Example:2024-08-24

charge_domintegerrequired

Day of month to charge (1-28)

Example:25

currency_codestring

Currency for the standing order

Allowed values:ILSUSDEUR

Example:ILS

vat_percentnumber

VAT percentage to apply. If omitted, current Bank of Israel VAT rate will be used

Example:18

index_linkedstring

Enable price index linkage for this standing order. When set to "Y", the following fields become required: `index_type`, `base_month`, `min_price`

Allowed values:YN

Example:Y

index_typeinteger

CBS (Central Bureau of Statistics) index code. Currently supported: `120010` (Consumer Price Index - CPI)

Example:120010

base_monthstring

Reference month for index calculation (format YYYY-MM)

Match pattern:^(19|20)\d\d[-](0[1-9]|1[012])$

Example:2021-12

min_pricestring

Minimum price protection. When set to "Y", prices will not decrease below the base price even if the index decreases

Allowed values:YN

Example:Y

clientSTOClient

itemsarray[STOItemV2]required

List of items to charge

cardtokenDetails

msvbankDetails

response_languageAPILanguage

created_by_userstring

Username or identifier of the user creating this STO

Example:CRM Admin

Responses

The response can be 200 with an Application error code:

Error Code	Description
20300	Too many payment methods
20301	Failed to insert STO
20302	Failed to retrieve STO
20303	No payment method
20304	Bad date
20305	Failed to create token

Response body

response.json

JSON

1{
2  "error_code": 0,
3  "message": "Success",
4  "sto_id": 189976
5}
6