API Use Cases & Integration Guide

Getting Started

Two environments, one simple API format

Sandbox (Testing)

https://sandboxportal.tib.finance

Get free sandbox credentials →

Production (Live)

https://portal.tib.finance

Create a live account →

Every API call uses the same format: POST [BaseURL]/Data/[MethodName]

The API uses Rijndael (AES-256) encryption for all payloads. Our SDKs handle encryption automatically — the cURL examples below show the decrypted JSON structure for clarity.

// Your first call: CreateSession
POST https://sandboxportal.tib.finance/Data/CreateSession

// Request:
{
  "ClientId": "YOUR_CLIENT_ID",
  "Username": "YOUR_USERNAME",
  "Password": "YOUR_PASSWORD"
}

// Response:
{
  "SessionId": "46a84f3f-c4fb-4d00-b3ff-caf6c85d06d4",
  "HasError": false,
  "Messages": ""
}
            

Tip: The SessionId is used in all subsequent API calls. SDKs for .NET, PHP, Python, Node.js, JavaScript handle encryption and session management automatically.

Complete Integration Lifecycle

Follow the 8 steps from authentication to payment confirmation

Authenticate

Your Software

ClientId, Username, Password

CreateSession

TIB Finance API

SessionId (GUID)

All subsequent calls require this SessionId as a header.

Your Software

CustomerName, ExternalId

CreateCustomer

TIB Finance API

CustomerId (GUID)

Store the CustomerId — you'll reuse it for all this customer's payments.

Add Payment Method

Your Software

Bank account or Credit card details

CreateDirectAccount…

TIB Finance API

PaymentMethodId (GUID)

Full method: CreateDirectAccountPaymentMethod

Create Invoice

Your Software

MerchantId, Amount, Currency, CustomerId

CreateBill

TIB Finance API

BillId (GUID)

The bill represents the invoice; the payment is a separate step.

Process Payment

Your Software

BillId, PaymentFlow: 5

CreatePayment

TIB Finance API

PaymentId + auto-processed

Flow 5 = fully automated. The payment is charged immediately.

Monitor Status

Your Software

MerchantId, DateRange

ListExecutedOperations

TIB Finance API

TransferStatus + BankResultCode

Poll this endpoint or use webhooks to track settlement progress.

How Processing Works

Each money transfer generates a minimum of 3 operations, each with up to 4 transactions.

Collection Flow (Collecting from customer)

1. Collect funds from customer payment method
2. Deposit funds into merchant account
3. Collect fees (grouped on the 5th of next month)

Deposit Flow (Sending to customer)

1. Collect funds from merchant account
2. Deposit funds into customer payment method
3. Collect fees (grouped on the 5th of next month)

Each Operation Has 4 Transaction Steps

1. Validation — verify parameters
2. Transmit — send collection/deposit to bank
3. Check Status — waiting & verification
4. Check Payback — NSF & opposition check

To get the full transfer status, verify all sub-transaction statuses across all operations.

Verify Result

Your Software

Decision branch — check BankResultCode

BankResultCode

Result Codes

1 = Confirmed 3 = NSF 4 = Error 5 = Opposition

Code 1 means funds settled. Any other code requires action in your system.

Easy Error Handling

Check each transaction status using this simple approach:

Status 0 Still waiting for process execution.
Note: payback check can stay in this status for up to 3 months.

Status 1 TIB Validation — TIB confirms the transaction is valid and accepted.

Status 2 Banking Network — The banking network has confirmed the transaction.

Status 3 Funds Settled — Funds have been successfully deposited.

Status 4 Process Complete — Full process completed, including payback verification.

All transactions have a status and a detailed description. Verify all sub-transaction statuses to determine the overall process status.

Refund (Optional)

Your Software

TransferId

RevertTransfer

TIB Finance API

Reversal confirmation

Only available for confirmed transfers. Initiates a credit back to the customer.

Interac Variant — Alternative to Steps 3–5

Your Software

Email or Phone, Amount

CreateDirectInterac…

TIB Finance API

Interac transaction created — customer receives email/SMS

Full method: CreateDirectInteracTransaction — replaces steps 3, 4, and 5 in a single call. Canada only.

Use Case 1

Collect a Payment Automatically

Charge a known customer with a registered payment method. No customer interaction — the payment processes automatically using Payment Flow 5.

CreateSession → CreateCustomer → CreateDirectAccountPaymentMethod → CreateBill → CreatePayment (Flow 5)

// Step 1: Create Session (see Getting Started above)

// Step 2: Create Customer
POST /Data/CreateCustomer
{
  "SessionToken": "session-guid",
  "ServiceId": "your-service-id",
  "Customer": {
    "CustomerName": "John Smith",
    "CustomerExternalId": "CUST-001",
    "Language": 2
  }
}
// Response: { "CustomerId": "customer-guid" }

// Step 3: Add Bank Account (set as default)
POST /Data/CreateDirectAccountPaymentMethod
{
  "SessionToken": "session-guid",
  "CustomerId": "customer-guid",
  "IsCustomerAutomaticPaymentMethod": true,
  "Account": {
    "Owner": "John Smith",
    "AccountName": "Main checking",
    "BankNumber": "003",
    "InstitutionNumber": "12345",
    "AccountNumber": "9876543"
  }
}
// Response: { "PaymentMethodId": "pm-guid" }

// Step 4: Create Bill
POST /Data/CreateBill
{
  "SessionToken": "session-guid",
  "BreakIfMerchantNeverBeenAuthorized": true,
  "BillData": {
    "MerchantId": "your-merchant-id",
    "BillTitle": "Invoice #1001",
    "BillDescription": "Monthly service fee",
    "BillAmount": 99.99,
    "BillCurrency": 1,
    "Language": 2,
    "RelatedCustomerId": "customer-guid"
  }
}
// Response: { "BillId": "bill-guid" }

// Step 5: Create Payment (Flow 5 = automatic)
POST /Data/CreatePayment
{
  "SessionToken": "session-guid",
  "BillId": "bill-guid",
  "SetPaymentCustomerFromBill": true,
  "PaymentInfo": {
    "PaymentFlow": 5
  }
}
// Response: { "PaymentId": "pay-guid", "PaymentFlowParsingResult": 1 }
        

Important: IsCustomerAutomaticPaymentMethod: true makes this the default method — required for Flow 5. PaymentFlowParsingResult: 1 means success. Steps 2-3 only need to be done once per customer — reuse CustomerId for future bills.

Use Case 3

Recurring Monthly Payments

Set up automatic monthly collection for subscriptions, rent, memberships. Same as Use Case 1 but with TransferFrequency: 4 (Monthly).

CreateSession → CreateCustomer → CreatePaymentMethod → CreateBill → CreatePayment (Monthly)

// Steps 1-4: Same as Use Case 1 (Session, Customer, PaymentMethod, Bill)

// Step 5: Create RECURRING Payment
POST /Data/CreatePayment
{
  "SessionToken": "session-guid",
  "BillId": "bill-guid",
  "SetPaymentCustomerFromBill": true,
  "PaymentInfo": {
    "PaymentFlow": 5,
    "TransferFrequency": 4
  }
}
// The payment repeats every month automatically!

// List active recurring transfers
POST /Data/GetRecuringTransfers
{
  "SessionToken": "session-guid",
  "ServiceId": "your-service-id"
}

// Cancel a recurring transfer
POST /Data/DeleteRecuringTransfer
{
  "SessionToken": "session-guid",
  "RecuringTransferId": "recurring-guid"
}
        

Frequencies: 0=Once, 1=Daily, 2=Weekly, 3=Every 2 Weeks, 4=Monthly, 5=Trimester, 6=Bi-Annual, 7=Annual

Use Case 5

Interac e-Transfer

Send or request money via Interac e-Transfer using an email or phone number. Only 2 API calls.

CreateSession → CreateDirectInteracTransaction

// Send money (Deposit) via Interac
POST /Data/CreateDirectInteracTransaction
{
  "SessionToken": "session-guid",
  "MerchantId": "your-merchant-id",
  "InteracInformation": {
    "Description": "Freelancer payment",
    "Owner": "Kelly Freelancer",
    "TargetEmailAddress": "[email protected]",
    "InteracQuestion": "What is your pet name?",
    "InteracAnswer": "Buddy"
  },
  "TransferDirection": 2,
  "Amount": 500.00,
  "Currency": 1,
  "Language": 2
}

// Request money (Collect) via Interac
POST /Data/CreateDirectInteracTransaction
{
  "SessionToken": "session-guid",
  "MerchantId": "your-merchant-id",
  "InteracInformation": {
    "Description": "Invoice #3001",
    "Owner": "Customer Name",
    "TargetEmailAddress": "[email protected]"
  },
  "TransferDirection": 1,
  "Amount": 150.00,
  "Currency": 1
}
        

Key: TransferDirection: 1 = Collect (request money), 2 = Deposit (send money). InteracQuestion and InteracAnswer are required for deposits. Either TargetEmailAddress or TargetMobilePhoneNumber must be provided.

Use Case 7

Accept Credit Card Payments

Accept Visa, Mastercard, and Amex across North America. Register a credit card as a payment method and charge it automatically using Payment Flow 5.

CreateSession → CreateCustomer → CreateCreditCardPaymentMethod → CreateBill → CreatePayment (Flow 5)

// Steps 1-2: CreateSession + CreateCustomer (same as Use Case 1)

// Step 3: Register Credit Card
POST /Data/CreateCreditCardPaymentMethod
{
  "SessionToken": "session-guid",
  "CustomerId": "customer-guid",
  "IsCustomerAutomaticPaymentMethod": true,
  "CreditCard": {
    "Pan": 4242424242424242,
    "Cvd": 123,
    "ExpirationMonth": 12,
    "ExpirationYear": 27,
    "CardOwner": "John Smith"
  },
  "CreditCardRegisteredAddress": {
    "CivicNumber": "360",
    "Street": "Rue Saint-Jacques",
    "City": "Montreal",
    "Province": "QC",
    "Country": "CA",
    "PostalCode": "H2Y1P5"
  }
}
// Response: { "PaymentMethodId": "pm-guid" }

// Steps 4-5: CreateBill + CreatePayment (Flow 5) — same as Use Case 1
        

Tip: CreditCardRegisteredAddress is optional but recommended for AVS (Address Verification System) which reduces fraud. Pan accepts Visa (4xxx), Mastercard (5xxx), and Amex (3xxx). In sandbox, use test card number 4242424242424242.

Use Case 8

Quick Collection Without a Bill

Collect money directly without creating an invoice or bill. Uses CreateFreeOperation with TransferType: 3 (FreeCollection). Ideal for tips, micro-payments, and adjustments.

CreateSession → CreateFreeOperation (Type 3)

// Step 1: CreateSession (see Getting Started)

// Step 2: Free Collection — collect without a bill
POST /Data/CreateFreeOperation
{
  "SessionToken": "session-guid",
  "MerchantId": "your-merchant-id",
  "PaymentMethodId": "customer-pm-guid",
  "TransferType": 3,
  "Amount": 25.00,
  "Currency": 1,
  "Language": 2,
  "ReferenceNumber": "TIP-001"
}
        

Tip: TransferType: 3 = FreeCollection (collect money), TransferType: 2 = FreeDeposit (send money). The PaymentMethodId must belong to an existing customer. This bypasses the full bill workflow — perfect for streamlining operations.

Use Case 10

Multi-Tenant Platform (Sub-Clients)

Build your own payment platform. Each sub-client gets their own isolated environment with dedicated merchants, customers, and payment methods. Used by SaaS platforms, property management companies, and financial institutions across North America.

CreateSession → CreateSubClient → SetClientSettings → Normal payment flow per sub-client

// Step 1: CreateSession (see Getting Started)

// Step 2: Create a Sub-Client
POST /Data/CreateSubClient
{
  "SessionToken": "session-guid",
  "ClientName": "Acme Property Management",
  "ClientLanguage": 2
}
// Response: { "ServiceId": "new-service-guid" }

// Step 3: Configure the Sub-Client
POST /Data/SetClientSettings
{
  "SessionToken": "session-guid",
  "ServiceId": "new-service-guid",
  "Settings": {
    "AllowCreditCard": true,
    "AllowDirectDebit": true,
    "AllowInterac": true
  }
}

// Read the Sub-Client configuration
POST /Data/GetClientSettings
{
  "SessionToken": "session-guid",
  "ServiceId": "new-service-guid"
}

// Now use the ServiceId in all subsequent calls for this sub-client
// CreateCustomer, CreateBill, CreatePayment, etc. all scoped to this sub-client
        

Enterprise: Each sub-client is completely isolated. You can configure fee settings per sub-client using SetClientDefaultServiceFeeSettings. The ServiceId returned by CreateSubClient replaces your own ServiceId in all API calls for that sub-client.

Use Case 11

White-Label Your Payment Pages

Your brand, our infrastructure. Customize payment pages with your colors, logo, and style. Your customers never see TIB — they see YOU.

CreateSession → SetWhiteLabeling

// Step 1: CreateSession (see Getting Started)

// Step 2: Set White-Labeling (Merchant level)
POST /Data/SetWhiteLabeling
{
  "SessionToken": "session-guid",
  "WhiteLabelingLevel": 1,
  "WhiteLabelingLevelId": "your-merchant-id",
  "CssProperties": {
    "background-color": "#1a1a2e",
    "color": "#ffffff",
    "font-family": "Inter, sans-serif",
    "button-background": "#e94560"
  }
}

// Read white-labeling data
POST /Data/GetWhiteLabelingData
{
  "SessionToken": "session-guid",
  "WhiteLabelingLevel": 1,
  "WhiteLabelingLevelId": "your-merchant-id"
}

// Update or delete white-labeling
// POST /Data/UpdateWhiteLabelingData
// POST /Data/DeleteWhiteLabeling
        

Levels: 1 = Merchant level, 2 = Service level, 3 = Client level. You can apply different branding at each level. Use GetListWhiteLabelingData to list all white-labeling configurations.

Use Case 12

Charge a Specific Payment Method (Flow 6)

Full control over which payment method to charge. Instead of using the customer's default, specify exactly which card or bank account to use via Payment Flow 6.

CreateSession → CreateCustomer → CreatePaymentMethod → CreateBill → CreatePayment (Flow 6)

// Steps 1-4: CreateSession, CreateCustomer, CreatePaymentMethod, CreateBill
// (same as Use Case 1 — customer may have multiple payment methods)

// Step 5: Create Payment with FORCED method
POST /Data/CreatePayment
{
  "SessionToken": "session-guid",
  "BillId": "bill-guid",
  "SetPaymentCustomerFromBill": true,
  "PaymentInfo": {
    "PaymentFlow": 6,
    "ForcedCustomerPaymentMethodId": "specific-pm-guid"
  }
}
// Charges the exact payment method you specified, not the default
        

Tip: Use ListPaymentMethods to get all payment methods for a customer, then pass the desired PaymentMethodId as ForcedCustomerPaymentMethodId. This is ideal when a customer has multiple cards and you want to charge a specific one (e.g., a backup card after the primary fails).

Enterprise & Multinational Features

Built for scale. Trusted by businesses processing $600M+ annually.

North American Coverage

Process payments in Canada (EFT, Interac, credit cards) and the United States (ACH, credit cards). Multi-currency support in CAD and USD from a single integration.

Customer & Data Management

Full CRUD operations: GetCustomer, SaveCustomer, DeleteCustomer, GetCustomersByExternalId, ListCustomers, ListPaymentMethods, ListBills. Your data, your control.

Advanced Reporting

ListExecutedOperations with filters by date range, merchant, transfer type, and group. Track every transaction across your entire organization in real-time.

Category	Methods
Session	`CreateSession`
Customers	`CreateCustomer` `SaveCustomer` `GetCustomer` `GetCustomersByExternalId` `DeleteCustomer` `ListCustomers`
Payment Methods	`CreateDirectAccountPaymentMethod` `CreateCreditCardPaymentMethod` `CreateInteracPaymentMethod` `GetPaymentMethod` `ListPaymentMethods` `DeletePaymentMethod` `SetDefaultPaymentMethod` `ChangeInteracPaymentMethodQuestionAndAnswer`
Bills	`CreateBill` `GetBill` `DeleteBill` `ListBills`
Payments	`CreatePayment` (9 flows) `DeletePayment` `RevertTransfer`
Direct Operations	`CreateDirectDeposit` `CreateDirectInteracTransaction` `CreateFreeOperation`
Batch	`CreateTransactionFromRaw`
Recurring	`GetRecuringTransfers` `DeleteRecuringTransfer`
Reporting	`ListExecutedOperations`
Sub-Clients	`CreateSubClient` `SetClientSettings` `GetClientSettings` `SetClientDefaultServiceFeeSettings`
White-Labeling	`SetWhiteLabeling` `GetWhiteLabelingData` `UpdateWhiteLabelingData` `GetListWhiteLabelingData` `DeleteWhiteLabeling`

Payment Flow Reference

Choose the right flow for your scenario

Flow	Name	Customer Known?	Has Payment Method?	Automatic?	Best For
`1`	Anonymous	No	No	No	One-time invoices, new customers
`2`	Known - Existing Methods	Yes	Yes	No	Customer chooses from saved methods
`3`	Known - Can Add Methods	Yes	Optional	No	Customer can add new payment method
`4`	Known - Full Management	Yes	Optional	No	Customer manages all methods + default
`5`	Automatic (Default)	Yes	Yes (default set)	Yes	Most common: subscriptions, recurring
`6`	Automatic (Forced)	Yes	Yes (specific)	Yes	Charge a specific payment method
`7`	Auto Select	Any	Any	Depends	Let the API choose the best flow
`8`	Auto Select (Non-Automatic)	Any	Any	Never	Auto-select but require customer action
`9`	Anonymous with Consent	No	No	No	Anonymous with consent capture

Quick Object Reference

Key data structures used in the TIB API

Customer Object

Property	Type	Required	Description
`CustomerName`	string	Yes	Full name (max 150 chars)
`CustomerExternalId`	string	No	Your internal customer ID (max 50)
`Language`	int	No	1 = French, 2 = English
`CustomerDescription`	string	No	Notes (max 250)

Bank Account Object

Property	Type	Required	Description
`Owner`	string	Yes	Account holder name (max 150)
`AccountName`	string	Yes	Account description (max 150)
`BankNumber`	string	Yes	Bank ID (3 digits)
`InstitutionNumber`	string	Yes	Transit number (5 digits)
`AccountNumber`	string	Yes	Account number (max 15)

Credit Card Object

Property	Type	Required	Description
`Pan`	number	Yes	Card number (14-16 digits)
`Cvd`	number	No	CVV code (3-4 digits)
`ExpirationMonth`	int	Yes	1-12
`ExpirationYear`	int	Yes	2-digit year (e.g. 26)
`CardOwner`	string	Yes	Name on card (max 150)

Bill Object

Property	Type	Required	Description
`MerchantId`	GUID	Yes	Merchant this bill belongs to
`BillTitle`	string	Yes	Title shown to customer (max 150)
`BillDescription`	string	Yes	Description (max 1000)
`BillAmount`	decimal	Yes	Amount: 0.01 to 50,000
`BillCurrency`	int	No	1 = CAD, 2 = USD
`RelatedCustomerId`	GUID	No	Customer paying this bill

Key Enumerations

Payment Method Types

`1`	CreditCard
`2`	DirectAccount (Bank)
`3`	Interac

Currencies

`1`	CAD (Canadian Dollar)
`2`	USD (US Dollar)

Languages

`1`	French
`2`	English

Transfer Direction

`1`	Collect (request money)
`2`	Deposit (send money)

Transfer Frequencies

`0`	Once
`1`	Daily
`2`	Weekly
`4`	Monthly
`7`	Annually

Error Handling

Understanding API responses

Response Structure

// Success
{
  "HasError": false,
  "Errors": [],
  "Messages": ""
}

// Error
{
  "HasError": true,
  "Errors": [{
    "ErrorMessage": "Bad Credentials",
    "ErrorCode": 403
  }]
}
            

PaymentFlowParsingResult

Value	Meaning
`1`	Success
`2`	Invalid Payment Flow
`3`	Bill not related to customer
`4`	Customer has no payment method
`5`	No default payment method set
`6`	Forced method ID needed (Flow 6)
`7`	Customer doesn't have specified method
`8`	Anonymous must have email (Flow 1/9)
`9`	PPA consent needed

Bank Operation Results

Value	Result	Description
`0`	No result yet	Still being processed
`1`	Confirmed	Transaction completed successfully
`2`	Other errors	Unspecified bank error
`3`	NSF	Non-Sufficient Funds
`4`	Account error	Invalid, closed, or frozen account
`5`	Opposition	Customer opposed the transaction
`6`	Interac Refused	Interac transfer was refused
`7`	Interac Failed	Interac transfer failed

Getting Started

Sandbox (Testing)

Production (Live)

Why Developers Choose TIB

One API, All Payments

Multi-Currency & Multi-Country

Enterprise Multi-Tenant

Free Sandbox, No Risk

Complete Integration Lifecycle

How Processing Works

Collection Flow (Collecting from customer)

Deposit Flow (Sending to customer)

Each Operation Has 4 Transaction Steps

Easy Error Handling

13 Use Cases — From Simple to Enterprise

Collect a Payment Automatically

Send a Payment Link by Email

Recurring Monthly Payments

Direct Deposit to External Account

Interac e-Transfer

Batch Processing via ACP File

Accept Credit Card Payments

Quick Collection Without a Bill

Quick Deposit Without a Bill

Processing payments for businesses across Canada and the US

Multi-Tenant Platform (Sub-Clients)

White-Label Your Payment Pages

Charge a Specific Payment Method (Flow 6)

Refund / Revert a Transaction

Ready to scale your payment operations?

Enterprise & Multinational Features

North American Coverage

Customer & Data Management

Advanced Reporting

Complete API Method Reference

Ready to start building?

Payment Flow Reference

Quick Object Reference

Customer Object

Bank Account Object

Credit Card Object

Bill Object

Key Enumerations

Payment Method Types

Currencies

Languages

Transfer Direction

Transfer Frequencies

Error Handling

Response Structure

PaymentFlowParsingResult

Bank Operation Results

SDKs & Resources

.NET

PHP

JavaScript

Python

Sandbox

API Docs

Need help with integration?