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.
For technical support, log a ticket at https://support.paga.com.
For business-related inquiries, contact the Paga Business Team at [email protected].

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`	Token expiry (e.g., `"2025-02-22T22:50:33"`)
`callBackUrl`	Notification URL
`paymentMethods`	Always set as `["BANK_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", //Expiration of the Mandate Code
  "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": "BANK_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.