create a credit card transaction

Recommended Integration Workflow

Tranzila supports two ways to submit card details for a credit card transaction:

• Token-based integration — recommended for most integrations.
• Full card number integration — permitted only for PCI DSS-certified integrations.

For non-PCI DSS-certified integrations, do not send the full card number directly to Tranzila through this API. Instead, first tokenize the card using one of Tranzila's secure payment pages, such as an iframe or hosted fields.

A Tranzila token replaces only the full card number. It does not include the card expiry date, CVV, cardholder details, or any other customer data. When required, those values must still be sent together with the token.

Recommended flow:

1. Tokenize the card using a Tranzila payment page, iframe, or hosted fields.
2. Tranzila securely captures the card details and returns a reusable card token.
3. Submit the transaction using the token in the card_number field.
4. Send the card expiry date, and CVV where required, alongside the token.

This flow keeps the full card number outside your servers while allowing you to continue using the same card_number field in the transaction request.

This endpoint can also be used with an express terminal.

Transaction Types (txn_type)

Use the txn_type parameter to define the type of transaction to perform.

• debit — Charges the card and deducts the transaction amount from the cardholder's account.
• credit — Credits funds back to the cardholder, typically for a refund or adjustment.
• verify — Performs a verification transaction. Used together with the verify_mode parameter. 3DS is supported.
  • 2 — J2 verification. Checks the card without capturing funds.
  • 5 — J5 authorization. Reserves credit for the specified amount. The actual charge is later performed using txn_type=force.
  • 6 — Initializes a standing order (sto). Use the verification response when submitting the later sto transaction.
• sto — Performs a standing order charge. A standing order must first be initialized using txn_type=verify. When submitting the sto transaction, pass the related verification transaction reference in reference_txn_id.
• cancel — Cancels a debit or credit transaction.
• reversal — Releases a reserved credit amount from a J5 authorization transaction (verify_mode=5).

Prevent Duplicate Transactions (DCdisable)

The DCdisable parameter helps prevent duplicate charges by using a unique value for each transaction.

When enabled, Tranzila checks whether the same DCdisable value was already used for a successful transaction. If the value was already used, no additional charge will be created.

Requirements and behavior:

• In the my.tranzila system, go to Terminal Settings > Additional Fields for Transaction.
• Define field 20 only as the field used for DCdisable duplicate charge detection.
• Send the DCdisable parameter with a unique value for each transaction.
• The duplicate check is performed up to 24 hours back.
• The check is performed at the parent terminal level.
• If parent and child terminals are used, define the parameter in both the parent and child terminals.
• If the original transaction failed, DCdisable will not prevent a retry because no successful duplicate transaction exists.
• The recommended value is a long, complex, unique string.
• The maximum length for the DCdisable value is 254 characters.

If a duplicate transaction is detected, one of the following messages may be returned:

• "This payment has already been made, please contact the business"
• "This payment has already been paid. Please contact customer service."

Visit this page for a code example.

Allocation Number (מספר הקצאה)

For tax invoices on transactions above ₪5,000, the Israel Tax Authority requires an Allocation Number for the amount to be tax-deductible. The Allocation Number is issued based on the customer's registered business ID, registered under their personal ID, or their ח.פ. for a registered company.

If the ID number already sent for card verification (card_holder_id) matches the customer's registered business ID, the Allocation Number is issued automatically. Otherwise, for example, a registered company, or a cardholder paying on behalf of the business send the correct business ID separately via user_defined_fields, using the name business_id. business_id does not replace card_holder_id; both may be sent, and can hold the same value.

You must log into the my.tranzila system and go to the "Additional Fields for Transaction" screen, located under the terminal settings menu, and define a field named business_id.

If neither card_holder_id nor business_id contains the customer's correct registered business ID, the transaction still completes successfully, but no Allocation Number will be issued for the automatic invoice.

Attaching End-Customer Details to a Transaction

When charging via the API, any end-customer identifying information you want to see on the transaction itself, company name, contact person, email, external CRM ID, etc. — must be sent through user_defined_fields, not through the client object. client fields are not surfaced on the transaction record or in reports; user_defined_fields are.

Setup (one-time, per terminal):

1. In my.tranzila, go to your terminal settings → Additional Fields for Transaction, and define a name for each field you want to send (up to 25 slots: user_defined_1–user_defined_25).
2. In your API request, send a user_defined_fields array with {name, value} objects, where name matches the field name you configured.

"user_defined_fields": [
  { "name": "company", "value": "Acme Ltd" },
  { "name": "contact", "value": "Israel Israeli" },
  { "name": "email", "value": "contact@acme.com" }
]

Once configured, these values appear on the transaction and can be filtered on via ufields in the Transaction Reports API.

Card Entry Mode (pan_entry_mode)

Use the pan_entry_mode parameter to indicate how the card details were provided.

• 50 — Transaction by phone. The card was not physically present.
• 51 — Manually entered card details.
• 52 — Online transaction.

Installments (payment_plan)

Use the payment_plan parameter to define the payment structure.

• 1 — Default. A single regular payment.
• 6 — Credit installments. Used when the cardholder has an installment agreement with the credit card company. The merchant receives the full amount, while the cardholder pays in installments, usually with fees. Minimum: 3 payments.
• 8 — Regular installments.

Installment transactions should be used together with the relevant installment fields, including:

• installments_number
• first_installment_amount
• other_installments_amount

Code Examples

Required Fields Only

{
  "terminal_name": "myterminal",
  "expire_month": 7,
  "expire_year": 2025,
  "card_number": "O5d55d2922ca4021382",
  "cvv": "111",
  "items": [
    {
      "name": "Pen",
      "type": "I",
      "unit_price": 10.53,
      "units_number": 1
    }
  ]
}

Transaction Types (txn_type)

Debit (Default)

{
  "terminal_name": "myterminal",
  "txn_type": "debit",
  "expire_month": 7,
  "expire_year": 2025,
  "card_number": "O5d55d2922ca4021382",
  "cvv": "111",
  "items": [
    {
      "name": "Pen",
      "type": "I",
      "unit_price": 10.53,
      "units_number": 1
    }
  ]
}

Credit

{
  "terminal_name": "myterminal",
  "txn_type": "credit",
  "reference_txn_id": 12345,
  "authorization_number": "0587923",
  "expire_month": 7,
  "expire_year": 2025,
  "card_number": "O5d55d2922ca4021382",
  "cvv": "111",
  "items": [
    {
      "name": "Pen",
      "type": "I",
      "unit_price": 10.53,
      "units_number": 1
    }
  ]
}

Verify With verify_mode = 2

{
  "terminal_name": "myterminal",
  "txn_type": "verify",
  "expire_month": 7,
  "expire_year": 2025,
  "card_number": "O5d55d2922ca4021382",
  "cvv": "111",
  "items": [
    {
      "name": "Pen",
      "type": "I",
      "unit_price": 10.53,
      "units_number": 1
    }
  ],
  "verify_mode": 2
}

Verify With verify_mode = 5

{
  "terminal_name": "myterminal",
  "txn_type": "verify",
  "expire_month": 7,
  "expire_year": 2025,
  "card_number": "O5d55d2922ca4021382",
  "cvv": "111",
  "items": [
    {
      "name": "Pen",
      "type": "I",
      "unit_price": 10.53,
      "units_number": 1
    }
  ],
  "verify_mode": 5
}

reversal- release credit limit (j5 verify_mode=5)

{
  "terminal_name": "myterminal",
  "txn_type": "reversal",
  "reference_txn_id": 6769,
  "authorization_number": "0000000",
  "expire_month": 7,
  "expire_year": 2025,
  "card_number": "O5d55d2922ca4021382",
  "cvv": "111",
  "items": [
    {
      "name": "Pen",
      "type": "I",
      "unit_price": 10.53,
      "units_number": 1
    }
  ]
}

Charge With verify_mode = 5

{
  "terminal_name": "myterminal",
  "txn_type": "force",
  "reference_txn_id": 6769,
  "expire_month": 7,
  "expire_year": 2025,
  "card_number": "O5d55d2922ca4021382",
  "cvv": "111",
  "items": [
    {
      "name": "Pen",
      "type": "I",
      "unit_price": 10.53,
      "units_number": 1
    }
  ]
}

Verify With verify_mode = 6

{
  "terminal_name": "myterminal",
  "txn_type": "verify",
  "expire_month": 7,
  "expire_year": 2025,
  "card_number": "O5d55d2922ca4021382",
  "cvv": "111",
  "items": [
    {
      "name": "Pen",
      "type": "I",
      "unit_price": 10.53,
      "units_number": 1
    }
  ],
  "verify_mode": 6
}

Charge With verify_mode = 6

{
  "terminal_name": "myterminal",
  "txn_type": "sto",
  "reference_txn_id": 6967,
  "expire_month": 7,
  "expire_year": 2025,
  "card_number": "O5d55d2922ca4021382",
  "cvv": "111",
  "items": [
    {
      "name": "Pen",
      "type": "I",
      "unit_price": 10.53,
      "units_number": 1
    }
  ]
}

cancel transaction example

{
  "terminal_name": "myterminal",
  "txn_type": "cancel",
  "reference_txn_id": 123,
  "authorization_number": "0000000"
}

Dcdisable and business_id enabled example

{
  "terminal_name": "myterminal",
  "txn_type": "sto",
  "reference_txn_id": 6967,
  "expire_month": 7,
  "expire_year": 2025,
  "card_number": "O5d55d2922ca4021382",
  "cvv": "111",
  "items": [
    {
      "name": "Pen",
      "type": "I",
      "unit_price": 10.53,
      "units_number": 1
    }
  ],
   "user_defined_fields": [
    {
      "name": "DCdisable",
      "value": "your_generated_unique_value"
    },
    {
      "name": "business_id",
      "value": "515123456"
    }
  ]
}