Cas d’utilisation API & Guide d’intégration | Documentation développeur TIB Finance

Pour commencer

Deux environnements, un format API simple

Bac à sable (Test)

https://sandboxportal.tib.finance

Obtenir des identifiants bac à sable gratuits →

Production (En direct)

https://portal.tib.finance

Créer un compte en direct →

Chaque appel API utilise le même format : POST [BaseURL]/Data/[MethodName]

L'API utilise le chiffrement Rijndael (AES-256) pour toutes les données. Nos SDKs gèrent le chiffrement automatiquement — les exemples cURL ci-dessous montrent la structure JSON déchiffrée pour plus de clarté.

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

Astuce : Le SessionId est utilisé dans tous les appels API suivants. Les SDKs pour .NET, PHP, Python, Node.js, JavaScript gèrent le chiffrement et la gestion des sessions automatiquement.

Cycle de vie complet de l'intégration

Suivez les 8 étapes de l'authentification à la confirmation de paiement

Authentifier

Votre logiciel

ClientId, Username, Password

CreateSession

API TIB Finance

SessionId (GUID)

Tous les appels suivants nécessitent ce SessionId comme en-tête.

Enregistrer le client

Votre logiciel

CustomerName, ExternalId

CreateCustomer

API TIB Finance

CustomerId (GUID)

Conservez le CustomerId — vous le réutiliserez pour tous les paiements de ce client.

Ajouter un mode de paiement

Votre logiciel

Compte bancaire ou Détails de carte de crédit

CreateDirectAccount…

API TIB Finance

PaymentMethodId (GUID)

Méthode complète : CreateDirectAccountPaymentMethod

Créer une facture

Votre logiciel

MerchantId, Amount, Currency, CustomerId

CreateBill

API TIB Finance

BillId (GUID)

La facture représente la facturation ; le paiement est une étape séparée.

Traiter le paiement

Votre logiciel

BillId, PaymentFlow: 5

CreatePayment

API TIB Finance

PaymentId + traité automatiquement

Flux 5 = entièrement automatisé. Le paiement est débité immédiatement.

Surveiller le statut

Votre logiciel

MerchantId, DateRange

ListExecutedOperations

API TIB Finance

TransferStatus + BankResultCode

Interrogez ce point d'accès ou utilisez des webhooks pour suivre la progression du règlement.

Fonctionnement du traitement

Chaque transfert génère un minimum de 3 opérations, chacune avec jusqu'à 4 transactions.

Flux d'encaissement (Collecter du client)

1. Collecter les fonds du mode de paiement du client
2. Déposer les fonds dans le compte du marchand
3. Percevoir les frais (regroupés le 5 du mois suivant)

Flux de dépôt (Envoyer au client)

1. Collecter les fonds du compte du marchand
2. Déposer les fonds dans le mode de paiement du client
3. Percevoir les frais (regroupés le 5 du mois suivant)

Chaque opération a 4 étapes de transaction

1. Validation — vérifier les paramètres
2. Transmission — envoyer la collecte/dépôt à la banque
3. Vérification du statut — attente et vérification
4. Vérification du retour — NSF et opposition

Pour obtenir le statut complet du transfert, vérifiez tous les statuts de sous-transactions de toutes les opérations.

Vérifier le résultat

Votre logiciel

Branche de décision — vérifier BankResultCode

BankResultCode

Codes de résultat

1 = Confirmé 3 = NSF 4 = Erreur 5 = Opposition

Le code 1 signifie que les fonds sont réglés. Tout autre code nécessite une action dans votre système.

Gestion simplifiée des erreurs

Vérifiez le statut de chaque transaction avec cette approche simple :

Statut 0 En attente d'exécution.
Note : la vérification de retour peut rester à ce statut jusqu'à 3 mois.

Statut 1 Validation TIB — TIB confirme que la transaction est valide et acceptée.

Statut 2 Réseau bancaire — Le réseau bancaire a confirmé la transaction.

Statut 3 Fonds déposés — Les fonds ont été déposés avec succès.

Statut 4 Processus terminé — Processus complet, incluant la vérification de retour.

Toutes les transactions ont un statut et une description détaillée. Vérifiez tous les statuts de sous-transactions pour déterminer le statut global.

Remboursement (Optionnel)

Votre logiciel

TransferId

RevertTransfer

API TIB Finance

Confirmation d'annulation

Disponible uniquement pour les transferts confirmés. Initie un crédit au client.

Variante Interac — Alternative aux étapes 3–5

Votre logiciel

Email or Phone, Amount

CreateDirectInterac…

API TIB Finance

Transaction Interac créée — le client reçoit un courriel/SMS

Méthode complète : CreateDirectInteracTransaction — remplace les étapes 3, 4 et 5 en un seul appel. Canada seulement.

Cas d'utilisation 1

Percevoir un paiement automatiquement

Débitez un client connu avec un mode de paiement enregistré. Aucune interaction client — le paiement est traité automatiquement en utilisant le Flux de paiement 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 en fait le mode par défaut — requis pour le Flux 5. PaymentFlowParsingResult: 1 signifie succès. Les étapes 2-3 ne doivent être effectuées qu'une fois par client — réutilisez CustomerId pour les factures futures.

Cas d'utilisation 3

Paiements récurrents mensuels

Configurez la perception mensuelle automatique pour les abonnements, loyers, adhésions. Même procédure que le Cas d'utilisation 1 mais avec TransferFrequency: 4 (Mensuel).

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

Fréquences : 0=Une fois, 1=Quotidien, 2=Hebdomadaire, 3=Aux 2 semaines, 4=Mensuel, 5=Trimestriel, 6=Semestriel, 7=Annuel

Cas d'utilisation 5

Virement Interac

Envoyez ou demandez de l'argent via virement Interac en utilisant un courriel ou un numéro de téléphone. Seulement 2 appels API.

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
}
        

Clé : TransferDirection: 1 = Percevoir (demander de l'argent), 2 = Déposer (envoyer de l'argent). InteracQuestion et InteracAnswer sont requis pour les dépôts. TargetEmailAddress ou TargetMobilePhoneNumber doit être fourni.

Cas d'utilisation 7

Accepter les paiements par carte de crédit

Acceptez Visa, Mastercard et Amex à travers l'Amérique du Nord. Enregistrez une carte de crédit comme mode de paiement et débitez-la automatiquement en utilisant le Flux de paiement 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
        

Astuce : CreditCardRegisteredAddress est optionnel mais recommandé pour AVS (Système de vérification d'adresse) qui réduit la fraude. Pan accepte Visa (4xxx), Mastercard (5xxx), et Amex (3xxx). En bac à sable, utilisez le numéro de carte test 4242424242424242.

Cas d'utilisation 10

Plateforme multi-locataire (Sous-clients)

Construisez votre propre plateforme de paiement. Chaque sous-client obtient son propre environnement isolé avec des marchands, clients et modes de paiement dédiés. Utilisé par les plateformes SaaS, les sociétés de gestion immobilière et les institutions financières en Amérique du Nord.

CreateSession → CreateSubClient → SetClientSettings → Flux de paiement normal par sous-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
        

Entreprise : Chaque sous-client est complètement isolé. Vous pouvez configurer les paramètres de frais par sous-client en utilisant SetClientDefaultServiceFeeSettings. Le ServiceId retourné par CreateSubClient remplace votre propre ServiceId dans tous les appels API pour ce sous-client.

Cas d'utilisation 11

Personnalisez vos pages de paiement en marque blanche

Votre marque, notre infrastructure. Personnalisez les pages de paiement avec vos couleurs, logo et style. Vos clients ne voient jamais TIB — ils vous voient VOUS.

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
        

Niveaux : 1 = Niveau marchand, 2 = Niveau service, 3 = Niveau client. Vous pouvez appliquer différentes marques à chaque niveau. Utilisez GetListWhiteLabelingData pour lister toutes les configurations de marque blanche.

Cas d'utilisation 12

Débiter un mode de paiement spécifique (Flux 6)

Contrôle total sur le mode de paiement à débiter. Au lieu d'utiliser le mode par défaut du client, spécifiez exactement quelle carte ou quel compte bancaire utiliser via le Flux de paiement 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
        

Astuce : Utilisez ListPaymentMethods pour obtenir tous les modes de paiement d'un client, puis passez le PaymentMethodId souhaité comme ForcedCustomerPaymentMethodId. C'est idéal quand un client a plusieurs cartes et que vous voulez débiter une carte spécifique (ex. : une carte de secours après l'échec de la principale).

Fonctionnalités entreprise & multinationales

Conçu pour évoluer. La confiance des entreprises traitant plus de 600 M$ annuellement.

Couverture nord-américaine

Traitez les paiements au Canada (TEF, Interac, cartes de crédit) et aux États-Unis (ACH, cartes de crédit). Support multidevise en CAD et USD depuis une seule intégration.

Gestion des clients & données

Opérations CRUD complètes : GetCustomer, SaveCustomer, DeleteCustomer, GetCustomersByExternalId, ListCustomers, ListPaymentMethods, ListBills. Vos données, votre contrôle.

Rapports avancés

ListExecutedOperations avec des filtres par plage de dates, marchand, type de transfert et groupe. Suivez chaque transaction dans toute votre organisation en temps réel.

Catégorie	Méthodes
Session	`CreateSession`
Clients	`CreateCustomer` `SaveCustomer` `GetCustomer` `GetCustomersByExternalId` `DeleteCustomer` `ListCustomers`
Modes de paiement	`CreateDirectAccountPaymentMethod` `CreateCreditCardPaymentMethod` `CreateInteracPaymentMethod` `GetPaymentMethod` `ListPaymentMethods` `DeletePaymentMethod` `SetDefaultPaymentMethod` `ChangeInteracPaymentMethodQuestionAndAnswer`
Factures	`CreateBill` `GetBill` `DeleteBill` `ListBills`
Paiements	`CreatePayment` (9 flux) `DeletePayment` `RevertTransfer`
Opérations directes	`CreateDirectDeposit` `CreateDirectInteracTransaction` `CreateFreeOperation`
Lot	`CreateTransactionFromRaw`
Récurrent	`GetRecuringTransfers` `DeleteRecuringTransfer`
Rapports	`ListExecutedOperations`
Sous-clients	`CreateSubClient` `SetClientSettings` `GetClientSettings` `SetClientDefaultServiceFeeSettings`
Marque blanche	`SetWhiteLabeling` `GetWhiteLabelingData` `UpdateWhiteLabelingData` `GetListWhiteLabelingData` `DeleteWhiteLabeling`

Référence des flux de paiement

Choisissez le bon flux pour votre scénario

Flux	Nom	Client connu ?	A un mode de paiement ?	Automatique ?	Idéal pour
`1`	Anonyme	Non	Non	Non	Factures ponctuelles, nouveaux clients
`2`	Connu - Méthodes existantes	Oui	Oui	Non	Le client choisit parmi les méthodes enregistrées
`3`	Connu - Peut ajouter des méthodes	Oui	Optionnel	Non	Le client peut ajouter un nouveau mode de paiement
`4`	Connu - Gestion complète	Oui	Optionnel	Non	Le client gère toutes les méthodes + défaut
`5`	Automatique (Par défaut)	Oui	Oui (défaut défini)	Oui	Le plus courant : abonnements, récurrent
`6`	Automatique (Forcé)	Oui	Oui (spécifique)	Oui	Débiter un mode de paiement spécifique
`7`	Sélection automatique	Tout	Tout	Dépend	Laissez l'API choisir le meilleur flux
`8`	Sélection auto (Non-automatique)	Tout	Tout	Jamais	Sélection auto mais nécessite l'action du client
`9`	Anonyme avec consentement	Non	Non	Non	Anonyme avec capture de consentement

Référence rapide des objets

Structures de données clés utilisées dans l'API TIB

Objet Client

Propriété	Type	Requis	Description
`CustomerName`	string	Oui	Nom complet (max 150 caractères)
`CustomerExternalId`	string	Non	Votre identifiant client interne (max 50)
`Language`	int	Non	1 = Français, 2 = Anglais
`CustomerDescription`	string	Non	Notes (max 250)

Objet Compte bancaire

Propriété	Type	Requis	Description
`Owner`	string	Oui	Nom du titulaire du compte (max 150)
`AccountName`	string	Oui	Description du compte (max 150)
`BankNumber`	string	Oui	ID banque (3 chiffres)
`InstitutionNumber`	string	Oui	Numéro de transit (5 chiffres)
`AccountNumber`	string	Oui	Numéro de compte (max 15)

Objet Carte de crédit

Propriété	Type	Requis	Description
`Pan`	number	Oui	Numéro de carte (14-16 chiffres)
`Cvd`	number	Non	Code CVV (3-4 chiffres)
`ExpirationMonth`	int	Oui	1-12
`ExpirationYear`	int	Oui	Année à 2 chiffres (ex. 26)
`CardOwner`	string	Oui	Nom sur la carte (max 150)

Objet Facture

Propriété	Type	Requis	Description
`MerchantId`	GUID	Oui	Marchand auquel cette facture appartient
`BillTitle`	string	Oui	Titre affiché au client (max 150)
`BillDescription`	string	Oui	Description (max 1000)
`BillAmount`	decimal	Oui	Montant : 0,01 à 50 000
`BillCurrency`	int	Non	1 = CAD, 2 = USD
`RelatedCustomerId`	GUID	Non	Client payant cette facture

Énumérations clés

Types de modes de paiement

`1`	Carte de crédit
`2`	Compte direct (Banque)
`3`	Interac

Devises

`1`	CAD (Dollar canadien)
`2`	USD (Dollar américain)

Langues

`1`	Français
`2`	Anglais

Direction du transfert

`1`	Percevoir (demander de l'argent)
`2`	Déposer (envoyer de l'argent)

Fréquences de transfert

`0`	Une fois
`1`	Quotidien
`2`	Hebdomadaire
`4`	Mensuel
`7`	Annuel

Gestion des erreurs

Comprendre les réponses API

Structure de la réponse

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

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

PaymentFlowParsingResult

Valeur	Signification
`1`	Succès
`2`	Flux de paiement invalide
`3`	Facture non liée au client
`4`	Le client n'a pas de mode de paiement
`5`	Aucun mode de paiement par défaut défini
`6`	ID de méthode forcée requis (Flux 6)
`7`	Le client n'a pas la méthode spécifiée
`8`	Anonyme doit avoir un courriel (Flux 1/9)
`9`	Consentement PPA requis

Résultats des opérations bancaires

Valeur	Résultat	Description
`0`	Pas encore de résultat	Encore en cours de traitement
`1`	Confirmé	Transaction complétée avec succès
`2`	Autres erreurs	Erreur bancaire non spécifiée
`3`	NSF	Fonds insuffisants
`4`	Erreur de compte	Compte invalide, fermé ou gelé
`5`	Opposition	Le client s'est opposé à la transaction
`6`	Interac refusé	Le virement Interac a été refusé
`7`	Interac échoué	Le virement Interac a échoué

Cas d'utilisation API & Guide d'intégration

Pour commencer

Bac à sable (Test)

Production (En direct)

Pourquoi les développeurs choisissent TIB

Une API, tous les paiements

Multidevise & Multipays

Multi-locataire entreprise

Bac à sable gratuit, sans risque

Cycle de vie complet de l'intégration

Fonctionnement du traitement

Flux d'encaissement (Collecter du client)

Flux de dépôt (Envoyer au client)

Chaque opération a 4 étapes de transaction

Gestion simplifiée des erreurs

13 cas d'utilisation — Du simple à l'entreprise

Percevoir un paiement automatiquement

Envoyer un lien de paiement par courriel

Paiements récurrents mensuels

Dépôt direct vers un compte externe

Virement Interac

Traitement par lots via fichier ACP

Accepter les paiements par carte de crédit

Perception rapide sans facture

Dépôt rapide sans facture

Traitement des paiements pour les entreprises au Canada et aux États-Unis

Plateforme multi-locataire (Sous-clients)

Personnalisez vos pages de paiement en marque blanche

Débiter un mode de paiement spécifique (Flux 6)

Rembourser / Annuler une transaction

Prêt à élargir vos opérations de paiement ?

Fonctionnalités entreprise & multinationales

Couverture nord-américaine

Gestion des clients & données

Rapports avancés

Référence complète des méthodes API

Prêt à commencer à construire ?

Référence des flux de paiement

Référence rapide des objets

Objet Client

Objet Compte bancaire

Objet Carte de crédit

Objet Facture

Énumérations clés

Types de modes de paiement

Devises

Langues

Direction du transfert

Fréquences de transfert

Gestion des erreurs

Structure de la réponse

PaymentFlowParsingResult

Résultats des opérations bancaires

SDKs & Ressources

.NET

PHP

JavaScript

Python

Bac à sable

Docs API

Besoin d'aide avec l'intégration ?