Takbull API

Every request must include API_Key and API_Secret in the HTTP headers. Contact Takbull support to obtain sandbox credentials at app.takbull.co.il.

1. Send order details → receive a unique order ID (uniqId)
2. Redirect user or open an iFrame at
   https://api.takbull.co.il/PaymentGateway?orderUniqId={uniqId}
3. On payment submit, customer is redirected to your RedirectAddress
4. Provide a IPNAddress callback that listens for payment notifications
5. On IPN receipt, call the Validation API to confirm order/transaction/invoice data

{
  "order_reference": "A11A234",
  "OrderTotalSum": 150.77,
  "RedirectAddress": "https://someurl.com/processSuccess?ordeid=1da23a"
}

{
  "responseCode": 0,
  "uniqId": "89fd6612-2c4b-4a7b-91a3-dd9bdf0ee26a"
}

statusCode=0 means success. On failure, statusDescription contains the reason.

To charge with Bit, send PaymentMethodType=21 in the create-order request.

1. Detect whether the customer is browsing from a mobile device. If so, send IsMobile=true in the request. This tells the gateway to return a deep link that can open the Bit application directly.
2. In the response you will receive a url parameter. This is the link that opens the Bit application.
3. Navigate the customer to that URL — for example window.open(url) (or set window.location.href = url) — so the Bit app is launched to complete the payment.

On init you receive a message from the iframe containing the height of the iframe so you can adjust the iframe height accordingly.

{
  "id": 3067,
  "transactionId": "000000164",
  "tranProviderId": "82965",
  "amount": 210.10,
  "transactionType": 10,
  "currency": "ILS",
  "paymentMethod": 3,
  "numberOfPayments": 1,
  "cardToken": "xxxxxxxxxxx",
  "cardTokenExpirationMonth": 3,
  "cardTokenExpirationYear": 25,
  "last4DigitsCardNumber": "0000",
  "dealType": 1,
  "clearer": "LMI",
  "cardCompanyTtype": "CAL",
  "cardtype": "VI",
  "status": 1,
  "statusCode": 0,
  "transactionDate": "2023-05-20T23:42:25.9201733",
  "customerFullName": "test",
  "isDocumentCreated": true,
  "invoiceId": 4158,
  "invoiceUniqId": "6fcab03f-39de-45df-9fed-80784e1ab9fd",
  "documentNumber": 40101
}

Several response fields are returned as numeric codes. Use the tables below to interpret them.

Double-check order status after IPN receipt.

{ "uniqId": "89fd6612-2c4b-4a7b-91a3-dd9bdf0ee26a" }

{
  "orderId": 0,
  "internalCode": 1400101,
  "internalDescription": "INVALID",
  "providerCode": 0,
  "doNotRetry": false,
  "isSubscriptionPayment": false,
  "saveToken": false,
  "documentId": 0,
  "amount": 0.0,
  "dealType": 0,
  "orderStatus": 0,
  "tranSactionStatus": 0
}

Takbull calls your IPNAddress to guarantee delivery of payment results even when redirects fail.

Charge a saved card token without showing the payment form.

{
  "order_reference": 219,
  "IPNAddress": "https://yourdomain.com/ipn",
  "RedirectAddress": "https://yourdomain.com/thank-you",
  "CancelReturnAddress": "https://yourdomain.com/cart",
  "Products": [
    {
      "SKU": "22",
      "Description": "Polo",
      "Price": "20.00",
      "Quantity": 1,
      "TaxAmount": "0.00",
      "IsTaxteble": false,
      "Discount": "0.00"
    }
  ],
  "Currency": "USD",
  "CustomerFullName": "John Smith",
  "Customer": {
    "CustomerFullName": "John Smith",
    "Email": "john@example.com",
    "PhoneNumber": "1234567890",
    "Address": { "Address1": "123 Main St", "City": "New York", "Country": "US", "Zip": "10001" }
  },
  "OrderTotalSum": "74.00",
  "Language": "en",
  "CreateDocument": true,
  "MaxNumberOfPayments": 1,
  "CreditCard": {
    "CardExternalToken": "828e8373-76f0-4bad-b397-abcdd08a226a"
  }
}

{
  "orderId": 0,
  "internalCode": 0,
  "internalDescription": "OK",
  "providerCode": 0,
  "doNotRetry": false,
  "orderStatus": 0,
  "tranSactionStatus": 0
}

{
  "invoiceItems": [
    {
      "rowId": 1,
      "description": "some product description",
      "isTaxteble": true,
      "unitPrice": 1000,
      "totalPrice": 1000,
      "quantity": 1
    }
  ],
  "customerVM": {
    "customerFullName": "Muhammad Waqas",
    "address": { "address1": "street 16", "city": "TLV", "country": "ISRAEL" }
  },
  "sendToCustomer": false,
  "documentDate": "Tue May 23 2023",
  "totalTaxAmount": 170,
  "taxtable": true,
  "totalTaxFree": 1000,
  "totalPriceWithTax": 1170,
  "isItemIncludeTax": true,
  "currency": "ILS",
  "language": "he",
  "documentType": 320,
  "totalSumPaidInCash": 500,
  "totalSumPaidInCheck": 670,
  "cashes": [{ "description": "מזומן", "amount": 500 }],
  "checks": [{ "checkDueDate": "Tue May 23 2023", "amount": 670 }],
  "wireTransfers": [],
  "customPayments": []
}

{
  "responseCode": 0,
  "documentNumber": 45325,
  "isOk": true,
  "errorList": [],
  "documentVM": {
    "id": 287727,
    "documentNumber": 45325,
    "documentType": 320,
    "totalPriceWithTax": 1170.0,
    "currency": "ILS",
    "uniqId": "3ab63741-fe90-49b7-9934-50105676b0cd"
  }
}

Cancels a recurring payment subscription. The uniqId is the original order ID from the Get Redirect URL call.

{
  "RefundType": 2,
  "RefundAmount": null,
  "TransactionInternalNumber": "00012547",
  "Comments": "No inventory"
}

{
  "orderId": 0,
  "internalCode": 0,
  "internalDescription": "OK",
  "providerCode": 0,
  "documentId": 0
}

Creates a child merchant account under the authenticated parent merchant (affiliate program). The parent merchant is always resolved from the API key — never from the request body.

{
  "Email": "child@example.com",
  "Password": "SecurePass123!",
  "FirstName": "John",
  "LastName": "Doe",
  "Phone": "0501234567",
  "PackageUniqId": "pkg_basic_001",
  "SubscriptionPayer": "Parent",
  "MerchantDetails": {
    "Name": "Child Business Ltd.",
    "BusinessNumber": "123456789",
    "BusinessType": 1,
    "BizRegiEmail": "child@example.com",
    "Address1": "רחוב הרצל 1",
    "City": "תל אביב",
    "Country": "Israel",
    "countryCode": 972,
    "Zip": "6120101",
    "PhoneNumber1": "0501234567",
    "WebSiteUrl": "https://childbusiness.com",
    "Mcc": 5999
  }
}

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorMessage": "Child account created successfully.",
  "UserId": 1042,
  "MerchantId": "MID_abc123",
  "Email": "child@example.com",
  "ParentMerchantId": "MID_parent456",
  "AffiliationId": 7,
  "SubscriptionPayer": "Parent",
  "PaymentRedirectUrl": null,
  "OrderUniqId": null,
  "ApiKey": "5c2a493c-1a92-4222-9a4d-b50340757cf8",
  "ApiSecret": "8e2e4556-7d59-4476-833c-471f4bf6a605"
}

Retrieves a single order by its unique identifier. The response includes full order details: customer info, payment sums, products, transactions, invoices, and shipping.

{
      "uniqId": "ord_abc123",
      "orderStatus": 2,
      "dealType": 1,
      "createDate": "2024-01-15T10:30:00",
      "language": "he",
      "orderTotalSum": 250.00,
      "currency": "ILS",
      "taxAmount": 39.57,
      "taxtable": true,
      "discount": 0,
      "discountType": 0,
      "paymentMethodType": 1,
      "numberOfPayments": 1,
      "paymentsCharged": 1,
      "firstPaymentamount": 250.00,
      "folowedPaymentamount": 0,
      "customerFullName": "John Doe",
      "customerFirstName": "John",
      "customerLastName": "Doe",
      "customerEmail": "john@example.com",
      "customerPhoneNumber": "0501234567",
      "city": "Tel Aviv",
      "country": "Israel",
      "order_reference": "EXT-REF-001",
      "IPNAddress": "https://yoursite.com/ipn",
      "comments": "Gift wrap please",
      "shippingAmount": 20.00,
      "shippingAddress1": "Herzl St 1",
      "shippingCity": "Tel Aviv",
      "shippingCountry": "Israel",
      "products": [
        { "name": "Widget", "quantity": 2, "price": 115.00, "currency": "ILS" }
      ],
      "transactions": [
        { "transactionId": "txn_xyz", "amount": 250.00, "status": 1 }
      ],
      "invoices": [],
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "phoneNumber": "0501234567",
        "externalCustomerId": "cust_001"
      }
    }