Collections

Collections allow you to receive funds into your Maraboo wallet from external sources. This guide covers how to set up and manage inbound payments.

Overview

Maraboo supports multiple collection methods:

1. Deposit Transactions: Direct deposits to your wallet
2. Billpay Collections: Accept payments through bill payment providers
3. Account Enquiry: Verify account details before receiving funds

Deposit Transactions

When to Use

• Add funds to your wallet for operations
• Receive payments from customers
• Top up balance for payouts
• Fund multi-currency wallets

Supported Payin Methods

Canada - CAD

• interac_request: Interac Request for deposits
• direct_debit: Pre-authorized direct debits

West Africa (WAEMU) - XOF

• bank_transfer: Local bank transfers
• direct_debit: Direct debit payments

United States - USD (Coming Soon)

• swift: SWIFT international transfers
• fednow: FedNow instant payments

Creating a Deposit

Step 1: Get Deposit Quote

Calculate deposit fees and final amount:

const quoteResponse = await fetch('https://sandbox.mara.boo/api-access/calculators/deposit', {
  method: 'POST',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api',
    'X-Timestamp': new Date().toISOString(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10000,
    payin_country: 'ca',
    payin_method: 'interac_request'
  })
});

const quote = await quoteResponse.json();
const quote_id = quote.data.quote_id;

View calculator endpoint →

Step 2: Create Deposit Transaction

const depositResponse = await fetch('https://sandbox.mara.boo/api-access/transactions/client/sessions/deposit', {
  method: 'POST',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api',
    'X-Timestamp': new Date().toISOString(),
    'X-Idempotency-Key': `deposit-${Date.now()}-${quote_id}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    description: 'Wallet top-up',
    quote_id: quote_id,
    wallet_id: 'wallet-456',
    transaction: {
      amount: 10000,
      payin_country: 'ca',
      payin_method: 'interac_request'
    },
    metadata: {
      customer_id: 'CUST-123',
      purpose: 'top-up'
    },
    account_name: 'Business Account'
  })
});

const deposit = await depositResponse.json();
console.log('Transaction ID:', deposit.data.transaction_id);
console.log('Payment Link:', deposit.data.payment_link); // If applicable
console.log('Session ID:', deposit.data.session_id);

View full API reference →

Step 3: Complete Payment

Depending on the payment method:

1. Interac Send: Customer receives email/SMS with instructions
2. Bank Transfer: Use provided account details
3. Mobile Money: USSD prompt or app notification
4. Payment Link: Redirect customer to payment_link URL

Step 4: Track Deposit Status

Monitor the deposit status:

const sessionId = deposit.data.session_id;
const statusResponse = await fetch(`https://sandbox.mara.boo/api-access/transactions/client/sessions/${sessionId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api',
    'X-Timestamp': new Date().toISOString(),
    'Content-Type': 'application/json'
  }
});

const status = await statusResponse.json();
console.log('Status:', status.data.status);

View endpoint →

Direct Debit Collections

For recurring collections, you can set up direct debit profiles:

When to Use

• Subscription billing
• Recurring payments
• Automated top-ups
• Regular invoice collections

Setting Up Direct Debit

// 1. Create direct debit profile
const profileResponse = await fetch('https://sandbox.mara.boo/api-access/collections/client/direct-debit-profile', {
  method: 'POST',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api',
    'X-Timestamp': new Date().toISOString(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: 'CUST-123',
    bank_account: {
      account_number: '1234567',
      institution_number: '001',
      transit_number: '12345'
    },
    mandate_reference: 'MANDATE-456'
  })
});

const profile = await profileResponse.json();
const direct_debit_token = profile.data.token;

// 2. Use token for deposits
const depositResponse = await fetch('https://sandbox.mara.boo/api-access/transactions/client/sessions/deposit', {
  method: 'POST',
  headers: { /* auth headers */ },
  body: JSON.stringify({
    wallet_id: 'wallet-456',
    direct_debit_token: direct_debit_token,
    transaction: {
      amount: 5000,
      payin_country: 'ca',
      payin_method: 'direct_debit'
    }
  })
});

Billpay Collections

Accept payments through bill payment providers (utility companies, telecom, etc.):

Get Billpay Payees

Retrieve available billpay providers:

const payeesResponse = await fetch('https://sandbox.mara.boo/api-access/collections/client/billpay?payee=utility', {
  method: 'GET',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api',
    'X-Timestamp': new Date().toISOString(),
    'Content-Type': 'application/json'
  }
});

const payees = await payeesResponse.json();
console.log('Available payees:', payees.payees);
/*
[
  {
    "payee_name": "Electric Company",
    "payee_code": "ELEC-001"
  },
  {
    "payee_name": "Water Utility",
    "payee_code": "WATER-001"
  }
]
*/

View endpoint →

Accept Billpay Payments

Customers can pay through their bill payment portal using your payee code. The funds will be deposited to your wallet automatically.

Account Enquiry

Before accepting large deposits, verify account details:

const enquiryResponse = await fetch('https://sandbox.mara.boo/api-access/collections/client/ecobank/account-enquiry', {
  method: 'POST',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api',
    'X-Timestamp': new Date().toISOString(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    account_number: '1234567890'
  })
});

const result = await enquiryResponse.json();
console.log('Account Name:', result.account_name);
console.log('Account Status:', result.status); // ACTIVE
console.log('Message:', result.message);

View endpoint →

Collection Statuses

Understanding collection statuses:

Status	Description	Next Action
pending	Waiting for customer payment	Share payment details with customer
processing	Payment received, being processed	Wait for completion
completed	Funds deposited to wallet	Funds available for use
failed	Collection failed	Review failure reason, retry if needed

Webhook Notifications

Receive real-time updates on collection status:

{
  "event": "deposit.completed",
  "data": {
    "session_id": "session-123",
    "transaction_id": "txn-456",
    "status": "completed",
    "amount": 10000,
    "currency": "cad",
    "wallet_id": "wallet-456",
    "payin_method": "interac_request",
    "timestamp": "2025-10-12T14:30:00.000Z"
  }
}

Webhook Events

• deposit.pending: Deposit request created
• deposit.processing: Payment received, processing
• deposit.completed: Funds deposited successfully
• deposit.failed: Collection failed

Learn about webhooks →

Handling Collection Failures

Common Failure Reasons

Failure Reason	Description	Solution
payment_declined	Customer payment declined	Request alternative payment method
insufficient_funds	Customer account has insufficient funds	Retry after customer funds account
expired	Payment link expired	Generate new payment request
invalid_account	Account details incorrect	Verify account information

Retry Strategy

For failed collections:

1. Review failure reason
2. Contact customer if needed
3. Create new deposit request with corrected information
4. Set appropriate expiry times for payment links

## Testing Collections

### Sandbox Environment

Test collections without real funds:

Base URL: https://sandbox.mara.boo

### Test Scenarios

1. **Successful Deposit**: Complete deposit flow end-to-end
2. **Failed Payment**: Test customer payment failure
3. **Expired Link**: Test payment link expiry
4. **Webhook Delivery**: Verify webhook notifications

[Learn about sandbox testing →](/docs/environments)

## Multi-Currency Collections

Accept deposits in multiple currencies:

```javascript
// Create USD wallet deposit
const usdDeposit = await createDeposit({
  wallet_id: 'wallet-usd-123',
  transaction: {
    amount: 1000,
    payin_country: 'us',
    payin_method: 'ach'
  }
});

// Create CAD wallet deposit
const cadDeposit = await createDeposit({
  wallet_id: 'wallet-cad-456',
  transaction: {
    amount: 1500,
    payin_country: 'ca',
    payin_method: 'interac_request'
  }
});

Learn about multi-currency wallets →

Next Steps

• Learn about Payouts →
• Internal Transfers Guide →
• View Deposit API Reference →
• View Collections API Reference →