Getting Started

Enable your merchants to collect payments seamlessly with TeamApt’s Direct Debit Network. This guide covers everything you need to start: setting up your environment, obtaining access credentials, understanding the workflow, and processing your first payment.

What is Direct Debit?

TeamApt Direct Debit provides a secure, automated way for merchants to collect payments directly from customers’ bank accounts with prior authorization. It simplifies recurring and one-time collections, reduces payment friction, and ensures faster settlement.

Direct Debit is built around mandates, which are digital authorizations that allow an approved merchant to debit a customer’s bank account via a payment facilitator.

Key Benefits

Feature	Description
Streamlined Merchant Onboarding	Easily register and manage merchants with intuitive APIs
Flexible Mandate Options	Support for one-time, recurring, partial, and multi-account debits to meet diverse merchant requirements
Enhanced Customer Experience	Offer seamless mandate creation and payment processing via web, mobile, or POS terminals
Scalable Infrastructure	Build robust systems to accommodate various mandate classes and transaction types
Future-Ready Features	Upcoming Escrow Debits functionality to expand service offerings
Secure and Compliant	Built with industry-standard security protocols to ensure trust and reliability

How It Works

The Direct Debit process involves four main steps:

Mandate Creation: The merchant sets up the direct debit using the customer's details.
Customer Activation: The customer reviews and authorizes via an activation link or email.
Tokenization: The authorized account is converted into a reusable token for future debits.
Debit Execution: Once activated, the merchant initiates transactions using the Transaction APIs.

Each debit action is fully traceable, with APIs available for mandate status checks, transaction verification, and cancellations.

Before You Integrate

To begin integration, the following steps must be completed with support from the TeamApt onboarding team:

Staging Environment Setup
TeamApt personnel will assist in configuring your Payment Facilitator profile within the staging environment.
Generate Integration Credentials
Onboarded users can log into the Direct Debit Portal to generate their Client ID and Client Secret.
IP Whitelisting
The IP addresses of your servers must be whitelisted by TeamApt to allow secure API access. Provide your static outbound IPs during onboarding.

Environments

Environment	Base URL	Purpose
Development	https://direct-debit-mandate-service.development.teamapt.com/api/v1	Internal testing
Staging	https://api-direct-debit.aptpay-staging.teamapt.com	Sandbox testing
Production	https://api.aptpay-direct-debit.teamapt.com	Live environment
Portal (Staging)	https://direct-debit-consolidated-portal.aptpay-staging.teamapt.com/	Manage test credentials

The Direct Debit Workflow

Follow these steps to integrate and process payments through the API:

Obtain an Access Token
Authenticate with /auth/oauth/token using your Client ID and Secret.
Initiate or Create Mandate
Send a request to /mandate/api/v1/debit-mandate/initiate or /mandate/api/v1/debit-mandate/create. The response includes an activation link for the customer.
Customer Authorization
Redirect the customer to the activationUrl to review and approve the mandate.
Check Activation Status
Send a request to /api/v1/debit-mandate/status/{reference} to verify activation.
Process a Debit
Send a request to /transaction/api/v1/transaction/process-payment to initiate a debit.
Monitor Transactions
Track payment outcomes using /transaction/api/v1/transaction/status and reconcile results.

Going Live

Once sandbox testing is complete:

Submit a Go Live Request through your TeamApt Dashboard.
Upload required compliance and KYC documents.
Wait for review and approval (typically 2–5 business days).
Switch your API base URL to the production environment.

After approval, you can process real transactions using live API keys.

Quick Example: End-to-End API Flow

Step 1. Get Access Token

Request Sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'POST',
5  url: 'https://direct-debit-bank-integration-service.development.teamapt.com/oauth/token',
6  headers: {'Content-Type': 'application/json'},
7  data: {username: '24598D', password: 'dabf9ec190f742168ecfbbeb06e9071f'}
8};
9
10try {
11  const { data } = await axios.request(options);
12  console.log(data);
13} catch (error) {
14  console.error(error);
15}

Response Sample

1{
2  "success": true,
3  "result": {
4    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTYyNzQwNjYwM30.7",
5    "token_type": "Bearer",
6    "scope": "profile",
7    "jti": "ceea8fb7-3782-4de0-99b5-aebfqi920b55",
8    "expiresIn": 3600
9  },
10  "errors": []
11}

Step 2. Initiate or Create Mandate

Request Sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'POST',
5  url: 'https://direct-debit-bank-integration-service.development.teamapt.com/api/v1/debit-mandate/create',
6  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
7  data: {
8    mandateName: 'Monthly Subscription Service',
9    merchantId: 'MERCHANT001',
10    merchantName: 'Example Tech Inc.',
11    merchantCategoryCode: '5816',
12    accountNumber: '0123456789',
13    paymentFacilitatorReference: 'PAYFAC_REF_12345',
14    merchantLocation: '123 Tech Road, Lagos, NG',
15    paymentInterval: 'MONTHLY',
16    maxAmountPerFrequency: 500000,
17    durationInDays: 365,
18    transactionCategory: 'Subscription',
19    totalDebitAmount: 6000000,
20    totalDebitCount: 12,
21    transactionAmount: 500000,
22    fixedDebitAmount: true,
23    cancellationBy: 'CUSTOMER_OR_MERCHANT',
24    redirectPage: 'https://your-merchant-site.com/mandate-return',
25    bankCode: '058'
26  }
27};
28
29try {
30  const { data } = await axios.request(options);
31  console.log(data);
32} catch (error) {
33  console.error(error);
34}

Response Sample

1{
2  "activationUrl": "https://auth.provider.com/mandates?sessionId=abc-123",
3  "reference": "MNDT_f94afd5e7c4ad38354",
4  "message": "Mandate initiated successfully."
5}

Step 3. Check Mandate Activation

Request Sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'GET',
5  url: 'https://direct-debit-bank-integration-service.development.teamapt.com/api/v1/debit-mandate/status/12f94afd5e7c4ad3835442f45dc60b19',
6  headers: {Authorization: 'Bearer <token>'}
7};
8
9try {
10  const { data } = await axios.request(options);
11  console.log(data);
12} catch (error) {
13  console.error(error);
14}

Response Sample

1{
2  "statusCode": "string",
3  "comment": "string",
4  "reference": "string",
5  "activationUrl": "https://example.com",
6  "status": "string",
7  "token": {
8    "token": "string",
9    "totalAllowedDebitAmount": 1,
10    "successfulDebitAmount": 1,
11    "successfulDebitCount": 1,
12    "totalAllowedDebitCount": 1,
13    "expiryTime": "2025-12-07T19:29:30.009Z",
14    "reference": "string",
15    "name": "string",
16    "status": "ACTIVE"
17  }
18}

Step 4. Process Debit

Request Sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'POST',
5  url: 'https://direct-debit-bank-integration-service.development.teamapt.com/api/v1/transaction/process-payment',
6  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
7  data: {
8    currencyCode: 'NGN',
9    merchantId: 'MERCHANT001',
10    mandateReference: 'Hjw82hsjhuwherwh.',
11    paymentFacilitatorTransactionReference: 'MNFY_1010_01010',
12    token: 'aa8db96c37783fd48d709382a5a467fc',
13    transactionType: '00',
14    transactionCategory: 'Ads & Marketing',
15    amount: 10000,
16    narration: '058',
17    notificationUrl: 'https://your-merchant-site.com/transaction-notification'
18  }
19};
20
21try {
22  const { data } = await axios.request(options);
23  console.log(data);
24} catch (error) {
25  console.error(error);
26}

Response Sample

1{
2  "status": "Pending",
3  "transactionReference": "APT|MNFY|123456789",
4  "paymentFacilitatorTransactionReference": "MNFY_1010_01010",
5  "message": "Transaction initiated successfully.",
6  "timestamp": "2025-05-21T12:32:38Z"
7}

Step 5. Check Transaction Status

Request Sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'GET',
5  url: 'https://direct-debit-bank-integration-service.development.teamapt.com/api/v1/transaction/12f94afd5e7c4ad3835442f45dc60b19',
6  headers: {Authorization: 'Bearer <token>'}
7};
8
9try {
10  const { data } = await axios.request(options);
11  console.log(data);
12} catch (error) {
13  console.error(error);
14}

Response Sample

1{
2  "success": true,
3  "message": "Transaction details retrieved successfully",
4  "response": {
5    "transactionId": "APT|MNFY|123456789",
6    "transactionAmount": 10000,
7    "status": "SUCCESSFUL",
8    "createdAt": "2025-05-21T12:32:38Z",
9    "updatedAt": "2025-05-21T12:32:38Z",
10    "transactionType": "00",
11    "currency": "NGN"
12  },
13  "responseCode": "00"
14}