Transactions

Once a mandate is created and activated, transactions can be created automatically according to the mandate’s authorization and limits. This guide covers how transactions work, the end-to-end flow from creation to completion, and how to interpret transaction statuses and responses.

What is a Transaction?

A transaction is a debit request initiated by a merchant against a customer’s authorized mandate. Each transaction includes the amount, currency, frequency, and mandate reference to ensure accuracy and traceability. Transactions can be one-time, recurring, or flexible depending on the mandate configuration.

Transaction Types

TeamApt supports multiple transaction types to handle different payment scenarios and merchant use cases.

Transaction Type	Description
One-Time Debits	Used for single, immediate payments such as one-off purchases or service fees. The transaction is authorized once and debit is completed
Recurring Debits	Automates regular payments (daily, weekly, or monthly) for subscriptions, loans, or installment plans
Multi-Account Debits	Allows funds to be debited from multiple customer accounts under one mandate, improving debit success rates and reducing failed payments
Partial Debits	Enables merchants to debit smaller amounts in multiple installments within a mandate’s total limit. Useful for flexible repayment or pay-as-you-go models
Escrow Debits (Coming Soon)	Holds funds securely in escrow for conditional or staged payments, released when specific criteria are met. Ideal for marketplaces or escrow-based services

Working with Transactions

Verify Mandate
Query /api/v1/debit-mandate/status/{reference} to confirm the mandate's current status and verify that it is ACTIVE before processing any debit.
Debit Mandate
Once the mandate is active, use /transaction/api/v1/transaction/process-payment to process a debit.
Bank Processing
Once submitted, the debit request is routed to the customer’s bank. The bank validates the mandate, checks funds, and processes the settlement according to the mandate rules.
Transaction Update
Use /transaction/api/v1/transaction/status to check transaction outcomes, or receive real-time updates via the notificationUrl webhook configured during debit processing.
Reconciliation
Reconcile your internal records by matching API responses and response codes against your transaction reference IDs. See Response Codes for descriptions of all possible API message statuses and codes.

Add illustration here

Transaction Statuses

Transactions can return one of the following statuses during their lifecycle:

Status	Description
PENDING	The transaction has been received and is awaiting bank processing
SUCCESSFUL	The debit was processed and confirmed by the customer’s bank
FAILED	The debit was not processed. Check the responseCode for the failure reason

Got Questions

Reach out to us at support@teamapt.com if you have any questions as regards integrating with the TeamApt API.

TeamApt Tutorial Videos

Check out Our Youtube channel for tutorials on how to integrate the TeamApt API.

Join Our Slack Community

Click here to join the TeamApt Slack community.