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

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
Staging	https://api-direct-debit.aptpay-staging.teamapt.com	Sandbox testing
Production	https://api.aptpay-direct-debit.teamapt.com	Live environment

The Direct Debit Workflow

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

Obtain an Access Token
Authenticate your API requests to our Authentication API using your Client ID and Secret to obtain your access token.
Initiate Mandate
Send a request to our Initiate Mandate API. Depending on your request type, the response will include an activation link if the mandate is initiated with without account number.
If an account number is provided, the mandate will be return a reference number instead.
Check Activation Status
Using the reference Id gotten in the previous step, send a request to our Check Mandate Status API to get the mandate activation status and url.
You can skip this step if your mandate was initiated without an account number and activationUrl was provided in the previous step.
Customer Authorization
Redirect the customer to the activationUrl to review and approve the mandate.
Process a Debit
Send a request to Process Debit API to initiate a debit on your active mandate.
Monitor Transactions
Track payment outcomes using our Transaction Status API and reconcile results.

Quick Example: End-to-End API Flow

Step 1. Get Access Token

Authentication request sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'POST',
5  url: 'https://cosmos-direct-debit.aptpay-staging.teamapt.com/oauth/token?grant_type=client_credentials',
6  headers: {
7    Authorization: 'Basic MDAwMDFGOmI0NDNlNDM2YTZiNTRhZWRhMTBmOWQ1NmI2YWFjZTNm'  // MDAwMDFGOmI0NDNlNDM2YTZiNTRhZWRhMTBmOWQ1NmI2YWFjZTNm should be replaced with base64 encoded string of your 'ClientID:ClientSecret'
8  }
9
10};
11
12try {
13  const { data } = await axios.request(options);
14  console.log(data);
15} catch (error) {
16  console.error(error);
17}

Authentication 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 a Mandate

Payment Facilitators and Merchants have the option of initiating a mandate with Account number or without Account number.

Intiating a Merchant with Account Number Sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'POST',
5  url: 'https://direct-debit-mandate-service.staging.teamapt.com/api/v1/debit-mandate/initiate',
6  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
7  data: {
8  "mandateName": "Mandate for Loan repayment",
9  "merchantId": "XTRA",
10  "totalAmount": 1000000,
11  "transactionAmount": null,
12  "maxAmountWithinFrequency": 250000,
13  "isSingleTransactionAmountFixed": false,
14  "totalDebitCount": 4,
15  "durationInDays": 200,
16  "canCustomerCancel": false,
17  "merchantLogo": "https://www.examplemerchant.com/logo.png",
18  "redirectUrl": "https://www.google.com",
19  "minimumMultipleAccountPercentage": null,
20  "paymentFacilitatorReference": "PayFac_Ref_98765",
21  "transactionsCategory": "ELE14",
22  "merchantLocation": "123 Tech Avenue, Lagos, Nigeria",
23  "customerEmail": "firstname.lastname@teamapt.com",
24  "frequency": "ANY",
25  "notificationUrl": "https://webhook.site/1a1c581a-7029-413d-9d24-2a1433fc12f6",
26  "accountNumbers": [
27    {
28      "accountNumber": "0123456789",
29      "bankCode": "070"
30    }
31  ]
32}
33};
34
35try {
36  const { data } = await axios.request(options);
37  console.log(data);
38} catch (error) {
39  console.error(error);
40}

Mandate with Account Provided Response Sample

1{
2    "success": true,
3    "message": "Success",
4    "response": {
5        "paymentFacilitatorReference": "PayFac_Ref_98765",
6        "reference": "TDD12348CSue129303MALNH3HWI",
7        "activationUrl": null,
8        "expiryTime": "2025-12-22T08:12:59Z",
9        "status": "PENDING",
10        "state": "Initiated",
11        "description": "Mandate creation request has been received and being validated",
12        "sessionKey": "5244c9e6cff24ab2ab8a8498d4f7b8b0"
13    },
14    "responseCode": "00"
15}

Mandate without Account Number Sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'POST',
5  url: 'https://direct-debit-mandate-service.staging.teamapt.com/api/v1/debit-mandate/initiate',
6  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
7  data: {
8  "mandateName": "Loan for Bicycle 3",
9  "merchantId": "XTRA",
10  "totalAmount": 100000,
11  "transactionAmount": null,
12  "maxAmountWithinFrequency": 250000,
13  "isSingleTransactionAmountFixed": true,
14  "totalDebitCount": 3,
15  "durationInDays": 365,
16  "canCustomerCancel": true,
17  "merchantLogo": "https://www.examplemerchant.com/logo.png",
18  "redirectUrl": "https://www.google.com",
19  "minimumMultipleAccountPercentage": null,
20  "paymentFacilitatorReference": "PayFac_Ref_98765",
21  "transactionsCategory": "ELE14",
22  "merchantLocation": "123 Tech Avenue, Lagos, Nigeria",
23  "customerEmail": "firstname.lastname@teamapt.com",
24  "frequency": "ANY",
25  "notificationUrl": "https://webhook.site/1a1c581a-7029-413d-9d24-2a1433fc12f6",
26  "mandateClassification": "SINGLE_ACCOUNT"
27}
28};
29
30try {
31  const { data } = await axios.request(options);
32  console.log(data);
33} catch (error) {
34  console.error(error);
35}

Initiate Mandate without Account Number Response Sample

1{
2    "success": true,
3    "message": "Success",
4    "response": {
5        "paymentFacilitatorReference": "PayFac_Ref_98765",
6        "reference": "TDD12348CSue12930KJTHZDCDXA",
7        "activationUrl": "https://mandate-verification.staging.teamapt.com?sessionId=efc4d16f9ad4404daed6ace1229d827d",
8        "expiryTime": "2025-12-19T14:47:37Z",
9        "status": "PENDING",
10        "state": "Initiated",
11        "description": "Mandate creation request has been received and being validated",
12        "sessionKey": "efc4d16f9ad4404daed6ace1229d827d"
13    },
14    "responseCode": "00"
15}

Step 3. Check Mandate Status

Check Mandate Status Request Sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'GET',
5  url: 'https://direct-debit-mandate-service.staging.teamapt.com/api/v1/debit-mandate/status?reference=TDD00001FQE5KDSBPD3RNU92QT6ZVQP',
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}

Check Mandate Status Response Sample

1{
2    "success": true,
3    "message": "Success",
4    "response": {
5        "paymentFacilitatorReference": "PayFac_Ref_98765",
6        "reference": "TDD00001FQE5KDSBPD3RNU92QT6ZVQP",
7        "status": "PENDING",
8        "state": "Awaiting Authorization",
9        "description": "Mandate is validated and the customer must authorize it via the activationURL",
10        "activationDetails": {
11            "activationUrl": "https://mandate-verification.aptpay-staging.teamapt.com?sessionId=780403e01b4c459e97a4719104983091",
12            "expiryTime": "2025-12-22T11:57:16Z"
13        },
14        "mandateSummary": null, //A mandateSummary is returned when mandate is activated
15        "tokenSummary": null //A token is returned when mandate is activated
16    },
17    "responseCode": "00"
18}

Step 4. Process Debit

Process Debit Request Sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'POST',
5  url: 'https://direct-debit-transaction-service.staging.teamapt.com/api/v1/transaction/process',
6  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
7  data: {
8    "amount": 10000,
9    "currencyCode": "NGN",
10    "merchantId": "XTRA",
11    "narration": "World without end, Amen",
12    "token": "wy82u92u382829382", //The tokenSummary value obtained during mandate activation
13    "transactionCategory": "ELE14",
14    "paymentFacilitatorTransactionReference": "PayFac_Ref_98765",
15    "transactionType": "00",
16    "mandateReference": "TDD00001FQE5KDSBPD3RNU92QT6ZVQP",
17    "notificationUrl": "https://webhook.site/bb33179d-01b3-4650-81b3-044a2372bb06"
18}
19};
20
21try {
22  const { data } = await axios.request(options);
23  console.log(data);
24} catch (error) {
25  console.error(error);
26}

Process Debit Response Sample

1{
2    "success": true,
3    "message": "Success",
4    "response": {
5      "status": "PENDING",
6      "comment": "Procesed via automation",
7      "transactionReference": "APTPAY2512221303505556",
8      "paymentFacilitatorTransactionReference": "PayFac_Ref_98765",
9      "timeStamp": "2025-12-22 13:03:50"
10    },
11    "responseCode": "00"
12  }

Step 5. Check Transaction Status

Check Transaction Request Sample

1const axios = require('axios').default;
2
3const options = {
4  method: 'GET',
5  url: 'https://direct-debit-transaction-service.staging.teamapt.com/api/v1/transaction/status/{{bankCode}}?transactionReference={{transactionReference}}',
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}

Transaction Status Response Sample

1{
2    "success": true,
3    "message": "Success",
4    "response": {
5        "status": "SUCCESSFUL",
6        "amount": 350000,
7        "responseCode": "00",
8        "comment": "Transaction is SUCCESSFUL",
9        "transactionReference": "APTPAY2512221303505556",
10        "paymentFacilitatorTransactionReference": "PayFac_Ref_98765",
11        "transactionTime": "2025-12-22T13:03:51",
12        "mandateReference": "TDD12348CSue12930OKZLZDZ95L",
13        "additionalParams": {}
14    },
15    "responseCode": "00"
16}