Direct Debit API

Paga's Direct Debit feature allows businesses to securely debit customer bank accounts without cards. Using the Collect API, you can tokenize accounts and automate charges. It is perfect for recurring billing (e.g., subscriptions).

Prerequisites

Before integrating:

You must have a verified Paga Business Account → Sign up or log in.
You need your:
- Public Key
- Secret Key
- HMAC (hash key)
  from your business account.
Your business must be whitelisted to access the Collect API.

Base URLs

Environment	URL
Live	`https://collect.paga.com`
Test	`https://beta-collect.paga.com`

Important Notes

All operations are asynchronous, rely on callback notifications to avoid unnecessary polling and rate limits.
The accountReference serves as your token identifier. Ensure it is properly mapped to your account information.

API Endpoints

1. Tokenization (Direct Debit Authorization)

Endpoint:
POST /paymentRequest

This endpoint initiates the bank account tokenization process. Merchants must provide all required parameters to identify the bank account for tokenization.

Required Parameters

Parameter	Description
`referenceNumber`	Unique transaction ID
`amount`	Tokenization amount (e.g., `6600.0`)
`currency`	ISO currency code (`"NGN"`)
`payer.phoneNumber`	Customer's phone
`payer.email`	Customer's email
`payer.address`	Registered address (with bank)
`payer.bankId`	Customer’s bank UUID (from `getBank` endpoint)
`payer.bankAccountNumber`	NUBAN
`payer.accountReference`	Your internal ID for customer
`payee.name`	Your business name (e.g., "Spotify")
`expiryDateTimeUTC`	The expiry timestamp of the payment request in UTC.
`callBackUrl`	Notification URL
`paymentMethods`	Always set as `["DIRECT_DEBIT"]`

Hash Format

SHA-512(referenceNumber + amount + currency + payer.phoneNumber + payer.email + hashKey)

Sample Request

POST /paymentRequest HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: "Basic base64(public Key:secret Key)"
hash: SHA-512(referenceNumber + amount + currency + payer.phoneNumber + payer.email + hashkey)

{
"referenceNumber": "2353464564565",
"amount": 6600.0,
"currency": "NGN",
"payer": {
 "name": "Payer One",
 "phoneNumber": "08011111111",
 "email": "[email protected]",
 "bankId": "40090E2F-7446-4217-9345-7BBAB7043C4C",
 "bankAccountNumber": "0000000000",
 "address": "176 Herbert Macualey Yaba",
 "accountReference":"00203028083802029"
 },
 "payee": {
  "name": "Spotify"

  },
  "expiryDateTimeUTC": "2021-04-15T00:00:00",
  "callBackUrl": "https://globalpayment.com/payment/callback",
  "paymentMethods:["DIRECT_DEBIT"]
}

Sample Response

{
"referenceNumber": "00000007000076",
"statusCode": "0",
"statusMessage": "success",
"requestAmount": 6600.0,
"totalPaymentAmount": 6600.0,
"paymentMethods": [
{
    "name": "DIRECT_DEBIT",
    "accountReference":"00203028083802028",
    "properties": {
      "bankName": "FIDELITY",
      "AccountNumber": "3075917286",
      "amount": 50,
     }
 	},
 ],
"expiryDateTimeUTC": "2025-02-22T22:50:33"
}

Post-Tokenization Steps

The response includes an account number.
Customer must transfer ₦50 from the registered bank account.
Once received, the customer’s bank activates the token.
A callback notification will be sent to the merchant confirming token approval for charge requests.

Sample Callback

{
  "statusCode": "0",
  "statusMessage": "approved",
  "productName": "Spotify Subscription",
  "accountReference": "00203028083802028",
  "hash": "d6ec130666a76c8e9b72c01ee066518daa6a59c136ef5f13043d05a78bd90c35974eac42834fc8b225a59ba393624a7ae16325658d4af03fde30f2dcd4d8ab95"
}

2. Charge (Direct Debit Charge)

Endpoint:
POST /charge

This endpoint debits a customer’s bank account after tokenization has been approved. It is used for recurring or one-time charges on a tokenized account.

Required Parameters

Parameter	Description
`referenceNumber`	Unique transaction ID
`amount`	Amount to charge
`accountReference`	Token identifier for the customer’s account

Hash Format

SHA-512(referenceNumber + amount + accountReference + hashKey)

Sample Request

POST /charge HTTP/1.1
Host: collect.paga.com
Authorization: Basic base64(publicKey:secretKey)
hash: <sha512_hash>
Content-Type: application/json

{
  "referenceNumber": "2353464564565",
  "amount": 600.0,
  "accountReference": "00203028083802028"
}

Sample Response

{
  "referenceNumber": "2353464564565",
  "statusCode": "3",
  "statusMessage": "pending"
}

Post-Charge Notification

Once the charge is processed, a callback notification will confirm the status of the charge.

Sample Callback

{
  "event": "PAYMENT_COMPLETE",
  "notificationId": "e68545b8-358c-4b72-9ac1-0471008617e7",
  "statusCode": "0",
  "statusMessage": "Charge has been authorized",
  "externalReferenceNumber": "2353464564565",
  "state": "CONSUMED",
  "paymentAmount": 6600.00,
  "cumulativePaymentAmount": 7048.38,
  "collectionFee": 1000.75,
  "fundingDetails": {
    "paymentReferenceNumber": "0000000010244242242442211424232",
    "payerName": "Feranmi Zubair",
    "payerBankName": "Access Bank",
    "payerBankAccountNumber": "0000000000"
  },
  "hash": "e1f12b4dfcc399eb17fad29e676914c0d7f15420e82a384de2676cf473aa9e27aa744fbd2aa2bb2ff33b615ff38d4f6e970ad12648cf67ec613d0ec81fad9f1f"
}

3. Check Transaction Status

Refer to Paga’s transaction status endpoint documentation for details on how to verify charge status.

4. Check Mandate Status

Request URL
https://collect.paga.com/status

This endpoint is used to check the status of the mandate using the original referenceNumber.

Request Parameter

Parameter	Description	Required
`referenceNumber`	Unique reference from tokenization request	Yes
`accountReference`	Your internal ID for mandate	Yes

Response Parameter

Field	Description
`referenceNumber`	Reference ID for the status request
`statusCode`	Status code of the overall request (e.g., `"0"` = success)
`statusMessage`	Message describing the status (e.g., `"success"`)
`data.referenceNumber`	Original tokenization reference number
`data.statusCode`	Status of the tokenization request
`data.statusMessage`	Message for the tokenization request status
`data.requestAmount`	Original amount set during tokenization. This is the maximum single transaction amount you can charge.
`data.totalPaymentAmount`	Total expected payment amount (with fees)
`data.expiryDateTimeUTC`	Expiration time of the mandate/token
`data.mandate.statusCode`	Mandate-specific status code (e.g., `"0"` = success, `1` = pending, `-3` = request_cancelled)
`data.mandate.statusMessage`	Mandate-specific status message (e.g., `"success"`)
`data.mandate.accountReference`	Your internal ID for mandate
`data.mandate.createdDateTimeUTC`	Date and time when the mandate was created

POST /status HTTP/1.1
Host: collect.paga.com
Authorization: Basic base64(publicKey:secretKey)
hash: SHA-512(referenceNumber + hashKey)
Content-Type: application/json

{
  "referenceNumber": "ed0952c6-da54-402d-830d-97b49f083159",
	"accountReference":"00203028083802029"
}

{
  "referenceNumber": "ed0952c6-da54-402d-830d-97b49f083159",
  "statusCode": "0",
  "statusMessage": "success",
  "data": {
    "referenceNumber": "ed0952c6-da54-402d-830d-97b49f083159",
    "statusCode": "0",
    "statusMessage": "success",
    "requestAmount": 500.0,
    "totalPaymentAmount": 514.78,
    "expiryDateTimeUTC": "2025-04-12T11:24:00",
    "mandate": {
      "statusCode": "0",
      "statusMessage": "success",
      "accountReference": "00203028083802029",
      "createdDateTimeUTC": "2025-04-12T11:24:00"
    }
  }
}

This endpoint is essential for confirming whether a customer's mandate has been successfully created and is valid before initiating a charge.

The data.mandate.statusCode indicates the mandate's state: "0" means the mandate is active and approved for use, "1" indicates it is pending, and "-3" means the means the request was cancelled.

Only proceed with charging when the mandate status is "0" (success).

Additionally, always verify the expiryDateTimeUTC to ensure the mandate has not expired, as expired or inactive mandates will result in failed transactions.