Call any endpoint with your API keys — no Postman required. Open API playground

Senegal Guide

Collect and send money in Senegal using Orange and Free on the same MarzPay APIs. Use country: "SN", XOF amounts, and +221 phones.

Before you start

  1. Create API keys in the dashboard. Authenticate with HTTP Basic: Authorization: Basic base64(api_key:api_secret). See Getting Started.
  2. Ask a superadmin to enable the Senegal wallet for your business.
  3. Subscribe to Senegal Orange and Free collection and/or disbursement services in the marketplace.
  4. Set a webhook URL (or pass callback_url on each request). Final status is completed or failed only.

Senegal essentials

  • Always send country: "SN" so the Senegal wallet is used
  • Use amounts in XOF. Optional currency: "XOF" is accepted
  • Phones must be E.164: Orange +22177… / +22178… or Free +22176…
  • Same endpoints: POST /collect-money and POST /send-money
  • reference must be a UUID you generate
  • Provider is auto-detected from the phone (Orange and Free). Webhooks use that network name (e.g. orange), not a gateway name
  • Typical minimums start around XOF 100 (confirm your business limits)

XOF is also used by Benin and Côte d'Ivoire — always send country: "SN" so the Senegal wallet is used.

Pricing

Fees come from the public pricing page. Custom business rates may differ.

Network Collections Disbursements
Orange 3% Successful collections only 2.8% Successful payouts only
Free Money 3% Successful collections only 2.5% Successful payouts only

See full Senegal pricing →

Collect money (Senegal)

Request payment from a customer’s Orange and Free wallet. The customer approves on their phone; you receive a webhook when the collection completes or fails.

  1. POST /collect-money with amount, +221 phone, country: "SN", UUID reference
  2. Transaction starts as pending / processing
  3. Customer authorises the PIN prompt
  4. Webhook/callback settles to completed or failed
  5. Optional: poll GET /collect-money/{uuid} if you need a status safety net

Optional metadata — send up to 10 objects. Echoed on create (data.collection.metadata) and on webhooks (top-level metadata).

"metadata": [
  { "orderId": "ORD-123456789" },
  { "customerId": "customer@email.com", "isPII": true }
]

Example request

curl --location 'https://wallet.wearemarz.com/api/v1/collect-money' \
--header 'Authorization: Basic YOUR_API_CREDENTIALS' \
--form 'phone_number="+221771234567"' \
--form 'amount="1000"' \
--form 'country="SN"' \
--form 'currency="XOF"' \
--form 'reference="123e4567-e89b-12d3-a456-426614174000"' \
--form 'description="Payment for services"' \
--form 'callback_url="https://your-app.com/webhook"' \
--form 'metadata=[{"orderId":"ORD-123456789"},{"customerId":"customer@email.com","isPII":true}]'

Example response

{
  "status": "success",
  "message": "Collection initiated successfully.",
  "data": {
    "transaction": {
      "uuid": "4e7fb3fa-c13a-4b05-8acd-cf60ff68cb94",
      "reference": "123e4567-e89b-12d3-a456-426614174000",
      "status": "processing",
      "provider_reference": null
    },
    "collection": {
      "amount": {
        "formatted": "1000.00",
        "raw": 1000,
        "currency": "XOF"
      },
      "provider": "orange",
      "phone_number": "+221771234567",
      "mode": "live"
    }
  }
}

Send money (Senegal)

Disburse to a Orange and Free wallet. You receive a webhook when the payout completes or fails.

  1. POST /send-money with amount, +221 phone, country: "SN", UUID reference
  2. The network pays the recipient
  3. Webhook settles to completed or failed
  4. Optional: poll GET /send-money/{uuid}

Example request

curl --location 'https://wallet.wearemarz.com/api/v1/send-money' \
--header 'Authorization: Basic YOUR_API_CREDENTIALS' \
--form 'phone_number="+221771234567"' \
--form 'amount="1000"' \
--form 'country="SN"' \
--form 'currency="XOF"' \
--form 'description="Payout to customer"' \
--form 'callback_url="https://your-app.com/webhook"' \
--form 'reference="123e4567-e89b-12d3-a456-426614174001"' \
--form 'metadata=[{"orderId":"ORD-123456789"},{"customerId":"customer@email.com","isPII":true}]'

Example response

{
  "status": "success",
  "message": "Send money initiated successfully.",
  "data": {
    "transaction": {
      "uuid": "4e7fb3fa-c13a-4b05-8acd-cf60ff68cb94",
      "reference": "123e4567-e89b-12d3-a456-426614174001",
      "status": "processing"
    },
    "disbursement": {
      "amount": {
        "formatted": "1000.00",
        "raw": 1000,
        "currency": "XOF"
      },
      "provider": "orange",
      "phone_number": "+221771234567",
      "mode": "live"
    }
  }
}

Payment links (Senegal)

Create a shareable /pay/{uuid} page. Customers enter a local Senegal number and approve the PIN prompt. Same webhook shape as collect-money. 

curl --location 'https://wallet.wearemarz.com/api/v1/payment-links' \
--header 'Authorization: Basic YOUR_API_CREDENTIALS' \
--header 'Content-Type: application/json' \
--data '{
  "title": "Senegal payment",
  "amount": 1000,
  "country": "SN",
  "currency": "XOF",
  "is_fixed": true,
  "callback_url": "https://your-app.com/webhook"
}'

Share data.payment_url. Full fields: Payment Links API.

Webhooks

Senegal uses the same webhook envelope as Uganda and Kenya. Currency is XOF. Provider is the network (orange), not a gateway name. Match your order with transaction.reference (the UUID you sent).

Collection completed

{
  "event_type": "collection.completed",
  "transaction": {
    "uuid": "transaction-uuid",
    "reference": "123e4567-e89b-12d3-a456-426614174000",
    "status": "completed",
    "amount": { "formatted": "1000.00", "raw": 1000, "currency": "XOF" },
    "provider": "orange",
    "phone_number": "+221771234567"
  },
  "collection": {
    "provider": "orange",
    "phone_number": "+221771234567",
    "amount": { "formatted": "1000.00", "raw": 1000, "currency": "XOF" },
    "mode": "live",
    "provider_transaction_id": "ABC123"
  },
  "metadata": [
    { "orderId": "ORD-123456789" }
  ]
}

Send money completed

{
  "event_type": "disbursement.completed",
  "transaction": {
    "uuid": "transaction-uuid",
    "reference": "123e4567-e89b-12d3-a456-426614174001",
    "status": "completed",
    "amount": { "formatted": "1000.00", "raw": 1000, "currency": "XOF" },
    "provider": "orange",
    "phone_number": "+221771234567"
  },
  "disbursement": {
    "provider": "orange",
    "phone_number": "+221771234567",
    "amount": { "formatted": "1000.00", "raw": 1000, "currency": "XOF" },
    "mode": "live",
    "provider_transaction_id": "ABC123"
  }
}

Failed outcomes use collection.failed / disbursement.failed with the same envelope. Signing and more examples: Webhooks guide.

Check status

Callbacks are primary. To poll MarzPay (not the network directly):

  • GET https://wallet.wearemarz.com/api/v1/collect-money/{uuid}
  • GET https://wallet.wearemarz.com/api/v1/send-money/{uuid}

Those endpoints return the local MarzPay transaction. Status updates when the webhook arrives.

Not available for Senegal yet

These products remain Uganda-focused:

Related guides

→ All West & Central Africa markets → Benin → Côte d'Ivoire → Gabon → Congo-Brazzaville → Sierra Leone → Collections → Send Money → Payment Links → Webhooks → Getting Started
Chat on WhatsApp