Takbull API

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",
    "email": "muhammad@example.com",
    "phoneNumber": "+972501234567",
    "identityNumber": "123456789",
    "address": {
      "address1": "street 16",
      "address2": "Apartment 5",
      "city": "TLV",
      "country": "ISRAEL",
      "zipCode": "12345"
    }
  },
  "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.

The flow depends on the package (PackageUniqId) and on who pays for it (SubscriptionPayer):

In every case the child's login is created with the given Email/Password and needs no email verification. In the child-pays case the login stays disabled until the payment completes.

{
  "Email": "child@example.com",
  "Password": "SecurePass123!",
  "FirstName": "John",
  "LastName": "Doe",
  "Phone": "0501234567",
  "PackageUniqId": "pkg_basic_001",
  "SubscriptionPayer": "Parent",
  "MerchantDetails": {
    "Name": "Child Business Ltd.",
    "NameEn": "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,
    "FirstName": "John",
    "LastName": "Doe",
    "IdentityNumber": "203458101",
    "IdentitycreationDate": "2015-04-12",
    "IncorporationDate": "2015-01-01",
    "Sex": "M",
    "DateOfBirth": "1985-06-20",
    "BirthCountry": "Israel",
    "bankcode": "12",
    "branchcode": "345",
    "accountnumber": "123456",
    "BusinessDomainDescription": "6012"
  }
}

When the assigned package includes a Upay clearing/provider module, the fields below are forwarded to Upay's FULLCREATEACCOUNT request. Provide them inside the MerchantDetails object.

If the merchant already has a Upay account, send the fields below inside MerchantDetails instead of the account-opening fields above. The account is linked to the new merchant rather than opened. The credentials are verified before any payment is taken, and the package is charged in full, clearing setup fee included.

The Mcc field inside MerchantDetails is a standard ISO 18245 merchant category code describing the merchant's line of business. Send the numeric code that best matches the merchant's activity. Common values are listed below; if none apply, use 5999 (miscellaneous retail).

Use this flow when the new merchant pays Takbull for its own subscription. Your system (the parent) opens the account, the child pays on a Takbull-hosted page, and you are notified of the result.

1. Call CreateAccount with SubscriptionPayer: "Child", a paid PackageUniqId, RedirectUrl and (recommended) IpnUrl.
2. The response has ErrorCode 600113, PaymentRedirectUrl, OrderUniqId and AffiliationId. Save AffiliationId — it identifies this account in the redirect and in the IPN. Send the child to PaymentRedirectUrl.
3. The child enters card details on the Takbull payment page. The card is saved for the subscription.
4. Takbull then creates the child merchant, assigns the package, charges the package (setup + first period) to the child's card, opens the monthly subscription on the same card, issues API credentials (if the package includes API / clearing) and enables the login.
5. The child's browser is redirected to RedirectUrl with the query parameters below.
6. A server-to-server POST (JSON) is sent to IpnUrl with the final result and the child account details.

{
  "Email": "child@example.com",
  "Password": "SecurePass123!",
  "FirstName": "John",
  "LastName": "Doe",
  "Phone": "0501234567",
  "PackageUniqId": "pkg_basic_001",
  "SubscriptionPayer": "Child",
  "RedirectUrl": "https://parent.example.com/takbull/child-account/return",
  "IpnUrl": "https://parent.example.com/takbull/child-account/ipn",
  "MerchantDetails": { "Name": "Child Business Ltd.", "BusinessNumber": "123456789" }
}

{
  "Success": true,
  "ErrorCode": 600113,
  "ErrorMessage": "Payment is required to activate this child account. Please complete the payment process.",
  "UserId": 1042,
  "MerchantId": null,
  "Email": "child@example.com",
  "ParentMerchantId": "MID_parent456",
  "AffiliationId": 7,
  "SubscriptionPayer": "Child",
  "PaymentRedirectUrl": "https://api.takbull.co.il/PaymentGateway?orderUniqId=3f0b1c2e-...",
  "OrderUniqId": "3f0b1c2e-...",
  "ApiKey": null,
  "ApiSecret": null
}

MerchantId and the API credentials are not available yet — they are delivered in the IPN once the payment completes.

Example: https://parent.example.com/takbull/child-account/return?status=activated&statusCode=0&affiliationId=7&childMid=MID_abc123

Use the redirect only to show the child a result page. It is not signed, the child may close the browser before it arrives, and processing means the activation had not finished yet — update your records from the IPN.

Sent as POST with Content-Type: application/json and User-Agent: TakbullIPNAgent, once the activation has finished (successfully or not).

{
  "Status": "Activated",
  "StatusCode": 0,
  "StatusDescription": "Child account activated",
  "AffiliationId": 7,
  "ParentMerchantId": "MID_parent456",
  "MerchantId": "MID_abc123",
  "UserId": 1042,
  "Email": "child@example.com",
  "PackageUniqId": "pkg_basic_001",
  "OrderUniqId": "3f0b1c2e-...",
  "ApiKey": "5c2a493c-1a92-4222-9a4d-b50340757cf8",
  "ApiSecret": "8e2e4556-7d59-4476-833c-471f4bf6a605"
}

• Respond with any 2xx status to acknowledge. Any other status, or no response, is retried — up to 3 attempts, 15 minutes apart.
• Make your handler idempotent: the same IPN may arrive more than once. Match it by AffiliationId.
• The IPN carries the child's ApiSecret — use an https IpnUrl and store the credentials securely.
• If the payment is abandoned no IPN is sent. You may call CreateAccount again with the same Email: the previous pending request is cancelled and a new payment link is returned.
• On Failed after the payment (e.g. the package charge was declined), contact Takbull support — the email cannot be reused automatically.

{
  "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"
}

Reads / updates the document (invoice & receipt) settings of the authenticated merchant, or of one of its active affiliated child merchants when ChildMid is given. On update only the fields sent are changed; the response returns the full settings after the change.

• Right after CreateAccount (or after the Activated IPN in the child-pays flow), to set up how the new child's documents look and are sent — default document type, VAT handling, email subject/body, SMS text, etc.
• At any later time, to keep a child's document settings in sync with your system, without the child logging in.
• Without ChildMid, to manage your own document settings.

Settings are kept per language: he (Hebrew documents, default) and en (English documents) are separate sets — update each one you use. If a merchant has no settings yet for the language, defaults are created from the merchant profile on the first call. A child can be managed only while its affiliation is Active.

Recommended: call GetDocumentSettings first, then send only the fields you want to change.

The response has the same structure as the UpdateDocumentSettings response below.

{
  "ChildMid": "MID_abc123",
  "Language": "he",
  "Settings": {
    "DefaultDocumentType": 320,
    "IsItemIncludeTax": true,
    "EmailFromDisplayName": "Child Business Ltd.",
    "EmaiSubjectMsg": "Your document from Child Business",
    "EmailDocumentToMerchantAsCopy": true,
    "MerchantEmailToSendCopy": "child@example.com",
    "AddPaymentLink": false,
    "HideUnits": true,
    "DocumentNumbering": [
      { "DocumentType": 320, "Count": 1000 },
      { "DocumentType": 400, "Count": 2000 }
    ]
  }
}

{
  "Success": true,
  "ErrorCode": 0,
  "ErrorMessage": null,
  "Mid": "MID_abc123",
  "Language": "he",
  "Settings": {
    "DefaultDocumentType": 320,
    "IsItemIncludeTax": true,
    "DocumentNumbering": [ { "DocumentType": 320, "Count": 1000 } ],
    "...": "..."
  }
}

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