Getting Started with Payments

Maraboo's payment system enables you to send and receive funds across multiple currencies and payment channels. This guide covers the fundamentals of working with payments in the Maraboo ecosystem.

Payment Types

Maraboo supports several types of payment operations:

1. Deposit Transactions

Add funds to your wallet from external sources.

• Use case: Fund your Maraboo wallet to enable payments
• Payment methods: Interac, bank transfers, mobile money
• Endpoint: POST /api/v1/transactions/sessions/deposit

Learn more about deposits →

2. Payment Transactions

Send funds to recipients (individuals or businesses).

• Use case: Pay suppliers, send money to individuals
• Payment channels: Mobile money, bank transfers, Interac
• Supports: Multiple currencies (XOF, CAD, etc.)
• Endpoint: POST /api/v1/transactions/sessions/payment

Learn more about payments →

3. Withdrawal Transactions

Transfer funds from your wallet to your own pre-configured accounts.

• Use case: Move funds to your bank account
• Methods: EFT, ACH, Interac
• Endpoint: POST /api/v1/transactions/sessions/withdrawal

Learn more about withdrawals →

4. Swap Transactions

Exchange currency between wallets or swap and send to recipients.

• Swap types:
  • SWAP: Currency exchange between your own wallets
  • SWAP_SEND: Exchange currency and send to a recipient in one transaction
• Endpoint: POST /api/v1/transactions/sessions/swap

Learn more about swaps →

Payment Lifecycle

Understanding the payment lifecycle helps you track and manage transactions effectively.

Transaction Statuses

Status	Description
pending	Transaction has been created and is awaiting processing
processing	Transaction is being processed by the payment provider
completed	Transaction has been successfully completed
failed	Transaction has failed (see failure_reason for details)

Typical Payment Flow

1. Get a Quote: Use calculator endpoints to get exchange rates and fees
2. Create Transaction: Submit transaction with quote ID
3. Track Status: Monitor transaction status via webhooks or polling
4. Handle Result: Process completion or handle failures

Before You Start

Prerequisites

Before making payment transactions, ensure you have:

1. Active Maraboo Account: Sign up at the Maraboo portal
2. API Credentials: Generate your Public and Private keys
3. Funded Wallet: For payment and withdrawal transactions
4. Recipient Information: Valid recipient details for payments

Authentication

All payment endpoints require HMAC-SHA256 authentication:

Authorization: HMAC-SHA256 PUBLIC_KEY:PRIVATE_KEY
X-Origin: third-party-api.mara.boo
X-Timestamp: 2025-10-12T14:30:00.000Z
X-Idempotency-Key: unique-transaction-id
Content-Type: application/json

Required Headers:

• Authorization: HMAC-SHA256 authentication
• X-Origin: Must be third-party-api.mara.boo
• X-Timestamp: Current timestamp in ISO 8601 format
• X-Idempotency-Key: Unique identifier to prevent duplicate transactions
• Content-Type: Must be application/json

Learn more about authentication →Learn more about idempotency →

Payment Calculators

Before creating transactions, use calculator endpoints to get accurate quotes:

Calculator	Purpose	Endpoint
Deposit Calculator	Calculate deposit fees and amounts	POST /api/v1/mb-api/calculator/deposit-calculator
Payment Calculator	Get payment quotes with fees	POST /api/v1/mb-api/calculator/payment-calculator
Swap Calculator	Calculate currency exchange rates	POST /api/v1/mb-api/calculator/swap-calculator
Swap and Send Calculator	Quote for swap + payment	POST /api/v1/mb-api/calculator/swap-and-send-calculator

View all calculators →

Common Payment Patterns

Pattern 1: Simple Payment

// 1. Get a quote
const quoteResponse = await fetch('https://sandbox-gateway.mara.boo/api/v1/mb-api/calculator/payment-calculator', {
  method: 'POST',
  headers: { /* auth headers */ },
  body: JSON.stringify({
    amount: 5000,
    country: 'bj',
    channel: 'mobile_money',
    currency: 'xof'
  })
});

const { quote_id } = await quoteResponse.json();

// 2. Create payment
const paymentResponse = await fetch('https://sandbox-gateway.mara.boo/api/v1/transactions/sessions/payment', {
  method: 'POST',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api.mara.boo',
    'X-Timestamp': new Date().toISOString(),
    'X-Idempotency-Key': `payment-${Date.now()}-${quote_id}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    quote_id: quote_id,
    wallet_id: 'wallet-456',
    transaction: {
      amount: 5000,
      country: 'bj',
      channel: 'mobile_money',
      currency: 'xof'
    },
    recipient: {
      first_name: 'John',
      last_name: 'Doe',
      phone: '+22997123456',
      country: 'bj',
      transaction_type: 'mobile_money',
      provider: 'mtn',
      currency: 'xof'
    }
  })
});

Pattern 2: Currency Swap

// 1. Get swap quote
const swapQuote = await fetch('https://sandbox-gateway.mara.boo/api/v1/mb-api/calculator/swap-calculator', {
  method: 'POST',
  headers: { /* auth headers */ },
  body: JSON.stringify({
    amount: 50000,
    from_currency: 'xof',
    to_currency: 'cad',
    country: 'bf'
  })
});

const { quote_id } = await swapQuote.json();

// 2. Execute swap
const swapResponse = await fetch('https://sandbox-gateway.mara.boo/api/v1/transactions/sessions/swap', {
  method: 'POST',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api.mara.boo',
    'X-Timestamp': new Date().toISOString(),
    'X-Idempotency-Key': `swap-${Date.now()}-${quote_id}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    swap_quote_id: quote_id,
    source_wallet: 'wallet-xof-456',
    destination_wallet: 'wallet-cad-789',
    transaction: {
      amount: 50000,
      from_currency: 'xof',
      to_currency: 'cad',
      country: 'bf',
      payment_channel: 'bank_transfer'
    },
    session_type: 'swap_transaction',
    swap_type: 'SWAP'
  })
});

Tracking Transactions

Get Transaction Status

Retrieve specific transaction details:

GET /api/v1/transactions/sessions/{session_id}

List All Transactions

Filter and retrieve transaction history:

GET /api/v1/transactions/sessions?limit=20&status=completed

Available filters:

• status: Filter by transaction status
• start_date / end_date: Date range
• recipient_id: Filter by recipient
• type: Transaction type
• currency: Filter by currency
• wallet: Filter by wallet ID

View transaction endpoints →

Payment Channels

Maraboo supports multiple payment channels across different regions:

West Africa (WAEMU) - XOF

Payout Channels:

• mobile_money: MTN, Moov, Orange Money
• direct_deposit: Direct bank deposits
• xpresscash: Cash pickup
• credit_ecobank_account: Ecobank account credits
• billpay: Bill payment services

Payin Channels:

• bank_transfer: Bank transfers
• direct_debit: Direct debit payments

Countries: Benin (BJ), Burkina Faso (BF), Côte d'Ivoire (CI), Guinea-Bissau (GW), Mali (ML), Niger (NE), Senegal (SN), Togo (TG)

North America - CAD

Canada Channels:

• interac_send: Interac Send (payout)
• interac_request: Interac Request (payin)
• eft: Electronic Funds Transfer
• billpay: Bill payment

North America - USD

United States Channels (Coming Soon):

• swift: SWIFT transfers
• fednow: FedNow instant payments
• bank_transfer_ach: ACH bank transfers

View service inventory →

Recipients

Before making payments, you can pre-create recipients or provide recipient details inline:

Pre-create Recipients

POST /api/v1/mb-api/recipients

Benefits:

• Reuse recipient information
• Faster transaction creation
• Recipient validation upfront

Inline Recipients

Provide recipient details directly in payment requests. Useful for one-time payments.

Learn more about recipients →

Best Practices

1. Always Get Quotes First

Use calculator endpoints before transactions to ensure accurate fees and exchange rates.

2. Store Quote IDs

Quote IDs help track pricing and provide audit trails.

3. Handle Webhooks

Set up webhooks to receive real-time transaction status updates instead of polling.

Learn about webhooks →

4. Implement Idempotency

Use Idempotency-Key headers to prevent duplicate transactions.

Learn about idempotency →

5. Validate Recipients

Use the account enquiry endpoint to validate recipient details before large transfers.

View account enquiry →

6. Monitor Transaction Status

Track transactions through completion and handle failures gracefully with retry logic.

Error Handling

Common payment errors and solutions:

Error	Cause	Solution
400 Bad Request	Invalid parameters	Validate all required fields
401 Unauthorized	Invalid authentication	Check API credentials
422 Validation Error	Field validation failed	Review field requirements
insufficient_funds	Wallet balance too low	Fund wallet before payment
invalid_recipient	Recipient details incorrect	Validate recipient information

Next Steps

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