Monnify Adaptor Specification

Request

We want to build a basic adaptor to integrate with the REST API for Monnify, a Nigerian payment gateway that enables businesses to accept payments from customers via bank transfers, cards, and USSD. Monnify is a product of Moniepoint (formerly TeamApt) and provides comprehensive payment solutions including collections, disbursements, invoicing, reserved accounts, and verification services.

To start, this adaptor should:

1. Handle authentication via OAuth 2.0 (Basic Auth to generate Bearer tokens)
2. Include generic HTTP helpers (GET, POST, PUT, DELETE) for interacting with Monnify endpoints
3. Make it easy to create reserved accounts for customers
4. Make it easy to initiate single transfers/disbursements
5. Make it easy to verify bank accounts and retrieve transaction status
6. Return results in JSON format

Credentials

• Login credentials: Users should sign up at https://app.monnify.com to get their own credentials. Public sandbox credentials are available for quick testing at: https://teamapt.atlassian.net/wiki/spaces/MON/pages/212008611/Monnify+Collections (click "view the public sandbox credentials")

• Test environment:

  • Sandbox Base URL: https://sandbox.monnify.com
  • Live Base URL: https://api.monnify.com
  • Users can toggle between test and live modes in their dashboard under Settings > API Keys & Webhooks

• Test record(s): After signing up, users will have access to a test environment with sample data for testing collections, disbursements, and other features without using real money.

• Authentication method(s):

  • OAuth 2.0 with Basic Authentication: The adaptor uses a two-step authentication process:

    1. First, encode API Key and Secret Key as base64(ApiKey:SecretKey) and send with Basic Auth header
    2. Make POST request to /api/v1/auth/login to obtain access token
    3. Use the Bearer token for all subsequent API calls (token expires in 3599 seconds/~1 hour)

  • Example credentials format:

    API Key: MK_TEST_SAF7HR5F3F
    Secret Key: 4SY6TNL8CK3VPRSBTHTRG2N8XXEGC6NL
    Contract Code: (provided in dashboard)
    

  • API Documentation: https://developers.monnify.com/api

  • Authentication Details: https://teamapt.atlassian.net/wiki/spaces/MON/pages/212008633/Authentication

Sample Code

// Initialize and authenticate (this would be handled internally by the adaptor)
// POST /api/v1/auth/login with Basic Auth header

// Create a reserved account for a customer
post('/api/v1/bank-transfer/reserved-accounts', {
  body: {
    accountReference: "abc123",
    accountName: "John Doe",
    currencyCode: "NGN",
    contractCode: "2917634883",
    customerEmail: "[email protected]",
    customerName: "John Doe",
    getAllAvailableBanks: false,
    preferredBanks: ["035"]
  }
});

// Initiate a single transfer/disbursement
post('/api/v2/disbursements/single', {
  body: {
    amount: 5000,
    reference: "transfer_123",
    narration: "Payment for services",
    destinationBankCode: "058",
    destinationAccountNumber: "0123456789",
    currency: "NGN",
    sourceAccountNumber: "1234567890"
  }
});

// Verify a bank account
get('/api/v1/disbursements/account/validate', {
  query: {
    accountNumber: "0123456789",
    bankCode: "058"
  }
});

// Get transaction status
get('/api/v2/transactions/:transactionReference');

// Get all transactions with pagination
get('/api/v1/transactions/search', {
  query: {
    page: 1,
    size: 10
  }
});

// Get wallet balance
get('/api/v1/disbursements/wallet-balance/:walletAccountNumber');

Resources

API Documentation

• Main API Reference: https://developers.monnify.com/api
• Developer Documentation Home: https://developers.monnify.com/
• Authentication Guide: https://teamapt.atlassian.net/wiki/spaces/MON/pages/212008633/Authentication
• Collections Documentation: https://teamapt.atlassian.net/wiki/spaces/MON/pages/212008611/Monnify+Collections
• Disbursements/Transfers Guide: https://developers.monnify.com/docs/disbursements/single-transfers
• Integration Tools (Verification): https://developers.monnify.com/docs/integration-tools/
• Going Live Guide: https://monnify-docs.playground.monnify.com/docs/live

Key API Endpoints

Authentication:

• POST /api/v1/auth/login - Generate access token

Collections:

• POST /api/v1/bank-transfer/reserved-accounts - Create reserved account
• POST /api/v1/merchant/transactions/init-transaction - Initialize transaction
• GET /api/v2/transactions/:transactionReference - Get transaction status
• GET /api/v1/transactions/search - Search transactions

Disbursements:

• POST /api/v2/disbursements/single - Initiate single transfer
• POST /api/v2/disbursements/single/validate-otp - Authorize transfer with OTP
• GET /api/v2/disbursements/single/summary - Get transfer status
• GET /api/v1/disbursements/search-transactions - Search disbursement transactions
• GET /api/v1/disbursements/wallet-balance/:accountNumber - Get wallet balance

Sub-Accounts:

• POST /api/v1/sub-accounts - Create sub-account for payment splitting
• PUT /api/v1/sub-accounts - Update sub-account
• DELETE /api/v1/sub-accounts/:subAccountCode - Delete sub-account
• GET /api/v1/sub-accounts - Get all sub-accounts

Verification:

• GET /api/v1/disbursements/account/validate - Validate bank account
• POST /api/v1/vas/bvn-details-match - Verify BVN information

Invoicing:

• POST /api/v1/invoice/create - Create invoice
• GET /api/v1/invoice/:invoiceReference - Get invoice details

Response Format

All Monnify API responses follow this structure:

{
  "requestSuccessful": true,
  "responseMessage": "success",
  "responseCode": "0",
  "responseBody": {
    // Response data here
  }
}

Common Response Codes

• 0 - Success
• 99 - Unexpected error (re-query recommended)
• D01 - Transaction processing failed
• D04 - Insufficient wallet balance
• D05 - Duplicate reference

Additional Resources

• Postman Collection: https://www.postman.com/monnifyteam/monnify-public-apis
• Node.js Library Example: https://www.npmjs.com/package/monnify-nodejs-lib
• Python Library Example: https://github.com/samkayz/teamapt-monnify
• Developer Community (Slack): https://slack.monnify.com/

Logo Links

• Official Website: https://monnify.com/
• Brandfetch (Logo Assets): https://brandfetch.com/monnify.com

Note: Monnify logo files in PNG and SVG formats can be obtained from the Brandfetch page or by contacting Monnify support. For adaptor assets, you'll need:

• Rectangle logo: 512x190px with transparent background
• Square logo: 256x256px with transparent background

Toggle

Under SS project

###Test cases:
https://claude.ai/share/72199b44-dca7-48bd-8de5-e2822b07b77e