API Reference

Complete reference for the Danipa Fintech API — transfers, wallets, exchange rates, KYC, payment requests, MTN MoMo integration, bill payments, savings, loans, invoices, POS, payroll, and more.

Base URL

All API requests use the following base URL:

https://api.danipa.com/ms/v1

The OpenAPI specification version is 3.1.0. For the full machine-readable spec, see openapi.json.

Authentication

The API uses two authentication schemes depending on the endpoint type:

Bearer Token (JWT) — App Users

Most endpoints require a JWT Bearer token obtained after user registration and login via Keycloak:

Authorization: Bearer <jwt_token>

HTTP Basic — MoMo API Operations

MTN Mobile Money endpoints (Collection, Disbursement, Remittance) use HTTP Basic authentication with your API user ID as the username and API key as the password, Base64-encoded:

Authorization: Basic <base64(apiUserId:apiKey)>

Common Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <token>` or `Basic <credentials>`
`Content-Type`	Yes (POST/PUT)	`application/json`
`Ocp-Apim-Subscription-Key`	Yes	Your subscription key from the API Manager portal
`X-Target-Environment`	Yes	`sandbox` or `production`
`X-Correlation-ID`	Yes	UUID for request tracing across distributed systems
`Cache-Control`	No	Cache directive (e.g. `no-cache`)

1. Authentication

User registration and account recovery.

Method	Path	Description
`POST`	`/auth/register`	Register a new user (creates Keycloak account + wallet)
`POST`	`/auth/forgot-password`	Request a password reset email

Register

POST /ms/v1/auth/register

Request Body:

Field	Type	Required	Description
`firstName`	string	Yes	First name (1-100 chars)
`lastName`	string	Yes	Last name (1-100 chars)
`email`	string	Yes	Email address
`phone`	string	Yes	Phone number (E.164, 7-15 digits)
`password`	string	Yes	Password (12-128 chars)
`country`	string	Yes	Country code (2-3 chars, e.g. `GH`, `CA`)

2. Transfers

Create and track money transfers to saved recipients.

Method	Path	Description
`POST`	`/transactions`	Create a new transfer
`GET`	`/transactions`	List transfers (paginated)
`GET`	`/transactions/{id}`	Get transfer detail

Create Transfer

POST /ms/v1/transactions

Request Body:

Field	Type	Required	Description
`recipientId`	string	Yes	ID of a saved recipient
`amount`	number	Yes	Amount to send (min 0.01)
`sendCurrency`	string	Yes	Send currency (3 chars, e.g. `CAD`)
`receiveCurrency`	string	Yes	Receive currency (3 chars, e.g. `GHS`)
`speedTier`	string	Yes	`express` or `economy`
`quoteId`	string	No	Locked FX quote ID (from `/fx/quotes`)

Example:

curl -X POST https://api.danipa.com/ms/v1/transactions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "recipientId": "rec_8f3a2b1c",
    "amount": 250.00,
    "sendCurrency": "CAD",
    "receiveCurrency": "GHS",
    "speedTier": "express",
    "quoteId": "qt_x7k9m2p4"
  }'

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "dd657f12-49c7-4e30-8f57-5b2fa13a4865",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "id": "txn_r7kj2m9x",
    "type": "REMITTANCE",
    "status": "PENDING",
    "sendAmount": 250.00,
    "sendCurrency": "CAD",
    "receiveAmount": 1980.28,
    "receiveCurrency": "GHS",
    "fee": 1.49,
    "exchangeRate": 7.9211,
    "speedTier": "express",
    "providerRefId": "momo-ref-abc123",
    "createdAt": "2026-03-13T14:22:00Z",
    "events": []
  }
}

List Transfers

GET /ms/v1/transactions?page=0&size=20

Parameter	Type	Default	Description
`page`	integer	0	Page number (zero-based)
`size`	integer	20	Results per page

3. Recipients

Manage saved transfer recipients.

Method	Path	Description
`POST`	`/recipients`	Create a new recipient
`GET`	`/recipients`	List all recipients (sorted by most recently used)
`PUT`	`/recipients/{id}`	Update a recipient
`DELETE`	`/recipients/{id}`	Delete a recipient

4. Exchange Rates

Get live FX rates and fee calculations for the send money flow.

Method	Path	Description
`GET`	`/exchange-rates`	Get exchange rate and fee for a currency pair

Get Exchange Rate

GET /ms/v1/exchange-rates?from=CAD&to=GHS&amount=250&speed=express

Parameter	Type	Required	Default	Description
`from`	string	Yes	--	Send currency (e.g. `CAD`, `USD`, `GBP`)
`to`	string	Yes	--	Receive currency (e.g. `GHS`)
`amount`	number	No	100	Send amount for fee calculation (min 0.01)
`speed`	string	No	`express`	Speed tier: `express` or `economy`

Example:

curl "https://api.danipa.com/ms/v1/exchange-rates?from=CAD&to=GHS&amount=250&speed=express" \
  -H "Authorization: Bearer <token>" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)"

5. FX Quotes

Lock an exchange rate for a configurable window before creating a transfer.

Method	Path	Description
`POST`	`/fx/quotes`	Create a locked FX quote
`GET`	`/fx/quotes/{quoteId}`	Retrieve a quote by ID

The quoteId returned from POST /fx/quotes can be passed to POST /transactions to guarantee the quoted rate.

6. Wallet

Digital wallet with multi-currency accounts, peer-to-peer transfers, and MoMo integration.

Method	Path	Description
`POST`	`/wallets`	Create wallet (one per user, default GHS account)
`GET`	`/wallets/me`	Get wallet details
`GET`	`/wallets/me/balances`	Get all currency balances
`GET`	`/wallets/me/balances/{currency}`	Get balance for a specific currency
`POST`	`/wallets/me/transfer`	P2P transfer to another wallet
`POST`	`/wallets/me/fund-in`	Fund wallet via MoMo
`POST`	`/wallets/me/cash-out`	Cash out to MoMo
`POST`	`/wallets/me/refund`	Request a refund
`PUT`	`/wallets/me/accounts/{currency}`	Add a currency account
`DELETE`	`/wallets/me/accounts/{currency}`	Remove a currency account
`GET`	`/wallets/me/transactions/{currency}`	Get transaction history by currency
`GET`	`/wallets/me/fund-ins`	List fund-in requests
`GET`	`/wallets/me/cash-outs`	List cash-out requests

Create Wallet

POST /ms/v1/wallets

No request body required. Creates a wallet with a default GHS account.

Example:

curl -X POST https://api.danipa.com/ms/v1/wallets \
  -H "Authorization: Bearer <token>" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)"

7. KYC (Know Your Customer)

Document upload, verification status, and tier upgrades.

Method	Path	Description
`POST`	`/kyc/documents`	Upload a KYC document
`GET`	`/kyc/status`	Get current KYC verification status
`GET`	`/kyc/tiers`	List available KYC tiers and requirements
`POST`	`/kyc/upgrade`	Request upgrade to a higher KYC tier

8. Payment Requests

Request money from other Danipa users. Requests expire after 7 days.

Method	Path	Description
`POST`	`/payment-requests`	Create a payment request
`POST`	`/payment-requests/{id}/accept`	Accept a payment request
`POST`	`/payment-requests/{id}/reject`	Reject a payment request
`POST`	`/payment-requests/{id}/cancel`	Cancel a sent payment request
`GET`	`/payment-requests/sent`	List sent payment requests
`GET`	`/payment-requests/received`	List received payment requests

9. Payment Methods (Stripe)

Manage saved payment methods for card-based funding.

Method	Path	Description
`GET`	`/payment-methods`	List saved payment methods
`POST`	`/payment-methods/sync`	Sync payment methods from Stripe
`POST`	`/payment-methods/setup-intent`	Create a Stripe setup intent for adding a new card
`PUT`	`/payment-methods/default`	Set a payment method as default
`DELETE`	`/payment-methods/{paymentMethodId}`	Remove a payment method

10. Collection -- MTN Mobile Money (MoMo)

Request payments from MoMo account holders. All collection endpoints use HTTP Basic authentication and return 202 Accepted for async processing.

Method	Path	Description
`POST`	`/collection/payment/request`	Request to pay (initiate payment from payer)
`GET`	`/collection/payment/request/{referenceId}/status`	Get request-to-pay status
`POST`	`/collection/payment`	Initiate payment via partner gateway
`GET`	`/collection/payment/{X-Reference-Id}/status`	Get payment status
`PUT`	`/collection/payment/withdraw`	Initiate a withdrawal (cash-out) from payer
`GET`	`/collection/payment/withdraw/{referenceId}/status`	Get withdrawal status
`POST`	`/collection/invoice`	Create an invoice
`GET`	`/collection/invoice/{X-Reference-Id}/status`	Get invoice status
`DELETE`	`/collection/invoice/{referenceId}/cancel`	Cancel an invoice
`POST`	`/collection/preapproval`	Create a pre-approval
`GET`	`/collection/preapproval/{referenceId}/status`	Get pre-approval status
`DELETE`	`/collection/preapproval/{preApprovalId}/cancel`	Cancel a pre-approval

Additional endpoints exist for account balance, account holder status, OAuth token management, and consent. See the full OpenAPI spec for details.

11. Disbursement -- MTN Mobile Money (MoMo)

Transfer funds to MoMo account holders. All disbursement endpoints use HTTP Basic authentication and return 202 Accepted for async processing.

Method	Path	Description
`POST`	`/disbursement/transfer`	Transfer funds to a payee
`GET`	`/disbursement/transfer/{referenceId}/status`	Get transfer status
`POST`	`/disbursement/deposit`	Deposit to a payee account
`GET`	`/disbursement/deposit/{referenceId}/status`	Get deposit status
`POST`	`/disbursement/refund`	Refund a completed transaction
`GET`	`/disbursement/refund/{referenceId}/status`	Get refund status

Additional endpoints exist for account balance, account holder info/status, OAuth tokens, and consent. See the full OpenAPI spec for details.

12. Remittance -- MTN Mobile Money (MoMo)

Cross-border transfers via MoMo. All remittance endpoints use HTTP Basic authentication and return 202 Accepted for async processing.

Method	Path	Description
`POST`	`/remittance/transfer`	Transfer funds to a recipient
`GET`	`/remittance/transfer/{referenceId}/status`	Get transfer status
`POST`	`/remittance/cash/transfer`	Cash transfer to a payee
`GET`	`/remittance/cash/transfer/{referenceId}/status`	Get cash transfer status

Additional endpoints exist for account balance, account holder info/status, OAuth tokens, and consent. See the full OpenAPI spec for details.

User Profile

Method	Path	Description
`GET`	`/users/me`	Get current user profile
`PUT`	`/users/me`	Update current user profile
`POST`	`/users/me/logout-all`	Sign out all devices

💳 Bill Payments

Pay utility bills, airtime top-ups, and other services through integrated bill payment providers.

Method	Path	Description
`GET`	`/v1/bills/providers`	List bill payment providers (filter by category, country)
`POST`	`/v1/bills/pay`	Pay a bill
`GET`	`/v1/bills/history`	Bill payment history
`POST`	`/v1/bills/saved-billers`	Save a biller for quick access
`GET`	`/v1/bills/saved-billers`	List saved billers
`POST`	`/v1/bills/scheduled`	Create a scheduled bill payment
`GET`	`/v1/bills/scheduled`	List scheduled bill payments

Pay a Bill

POST /ms/v1/bills/pay

Request Body:

Field	Type	Required	Description
`providerId`	string	Yes	Bill provider ID (from `/bills/providers`)
`accountNumber`	string	Yes	Customer account or meter number
`amount`	number	Yes	Payment amount (min 0.01)
`currency`	string	Yes	Currency code (3 chars, e.g. `GHS`)

Example:

curl -X POST https://api.danipa.com/ms/v1/bills/pay \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "providerId": "bp_ecg_gh",
    "accountNumber": "0112345678",
    "amount": 150.00,
    "currency": "GHS"
  }'

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "id": "bill_x9k2m4p7",
    "providerId": "bp_ecg_gh",
    "providerName": "ECG Prepaid",
    "accountNumber": "0112345678",
    "amount": 150.00,
    "currency": "GHS",
    "status": "COMPLETED",
    "receiptNumber": "RCP-20260324-001",
    "token": "4567-8901-2345-6789",
    "paidAt": "2026-03-24T10:15:00Z"
  }
}

🎯 Savings Goals

Create and manage savings goals with target amounts and deadlines. Deposit or withdraw funds at any time.

Method	Path	Description
`POST`	`/v1/savings/goals`	Create a savings goal
`GET`	`/v1/savings/goals`	List all savings goals
`GET`	`/v1/savings/goals/{id}`	Get savings goal detail
`POST`	`/v1/savings/goals/{id}/deposit`	Deposit into a savings goal
`POST`	`/v1/savings/goals/{id}/withdraw`	Withdraw from a savings goal

Create Savings Goal

POST /ms/v1/savings/goals

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Goal name (1-100 chars)
`targetAmount`	number	Yes	Target amount (min 1.00)
`currency`	string	Yes	Currency code (3 chars, e.g. `GHS`)
`targetDate`	string	No	Target date (ISO 8601, e.g. `2026-12-31`)

Example:

curl -X POST https://api.danipa.com/ms/v1/savings/goals \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "name": "New Laptop",
    "targetAmount": 5000.00,
    "currency": "GHS",
    "targetDate": "2026-12-31"
  }'

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "id": "goal_m3k7p2x9",
    "name": "New Laptop",
    "targetAmount": 5000.00,
    "savedAmount": 0.00,
    "currency": "GHS",
    "progress": 0.0,
    "targetDate": "2026-12-31",
    "status": "ACTIVE",
    "createdAt": "2026-03-24T10:20:00Z"
  }
}

🔄 Savings Plans

Set up automated recurring deposits into your savings goals.

Method	Path	Description
`POST`	`/v1/savings/plans`	Create an auto-save plan
`GET`	`/v1/savings/plans`	List all savings plans
`PUT`	`/v1/savings/plans/{id}/pause`	Pause a savings plan
`PUT`	`/v1/savings/plans/{id}/resume`	Resume a paused savings plan

Create Auto-Save Plan

POST /ms/v1/savings/plans

Request Body:

Field	Type	Required	Description
`goalId`	string	Yes	Savings goal to fund
`amount`	number	Yes	Recurring deposit amount (min 1.00)
`frequency`	string	Yes	`daily`, `weekly`, or `monthly`
`startDate`	string	Yes	Start date (ISO 8601)

Example:

curl -X POST https://api.danipa.com/ms/v1/savings/plans \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "goalId": "goal_m3k7p2x9",
    "amount": 200.00,
    "frequency": "weekly",
    "startDate": "2026-04-01"
  }'

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "id": "plan_j4n8r2v6",
    "goalId": "goal_m3k7p2x9",
    "amount": 200.00,
    "frequency": "weekly",
    "nextDebitDate": "2026-04-01",
    "status": "ACTIVE",
    "createdAt": "2026-03-24T10:25:00Z"
  }
}

🏦 Loans

Browse loan products, apply for loans, and manage repayments.

Method	Path	Description
`GET`	`/v1/loans/products`	List available loan products
`POST`	`/v1/loans/apply`	Apply for a loan
`GET`	`/v1/loans`	List user's loans
`GET`	`/v1/loans/{id}`	Get loan detail with repayment schedule
`POST`	`/v1/loans/{id}/repay`	Make a loan repayment

Apply for a Loan

POST /ms/v1/loans/apply

Request Body:

Field	Type	Required	Description
`productId`	string	Yes	Loan product ID (from `/loans/products`)
`amount`	number	Yes	Requested loan amount
`currency`	string	Yes	Currency code (3 chars, e.g. `GHS`)
`termMonths`	integer	Yes	Loan term in months
`purpose`	string	No	Purpose of the loan

Example:

curl -X POST https://api.danipa.com/ms/v1/loans/apply \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "productId": "lp_personal_standard",
    "amount": 10000.00,
    "currency": "GHS",
    "termMonths": 12,
    "purpose": "Business expansion"
  }'

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "id": "loan_k5p9t3w7",
    "productId": "lp_personal_standard",
    "principalAmount": 10000.00,
    "currency": "GHS",
    "interestRate": 18.5,
    "termMonths": 12,
    "monthlyPayment": 916.80,
    "status": "PENDING_APPROVAL",
    "appliedAt": "2026-03-24T10:30:00Z"
  }
}

📊 Credit Score

Check your credit score, view score history, and determine loan eligibility.

Method	Path	Description
`GET`	`/v1/credit/score`	Get current credit score and grade
`GET`	`/v1/credit/history`	Get credit score history over time
`GET`	`/v1/credit/eligibility`	Check loan eligibility based on credit profile

Get Credit Score

GET /ms/v1/credit/score

Example:

curl "https://api.danipa.com/ms/v1/credit/score" \
  -H "Authorization: Bearer <token>" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)"

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "score": 720,
    "grade": "A",
    "maxScore": 850,
    "factors": [
      "Consistent on-time repayments",
      "Low credit utilization",
      "Active savings history"
    ],
    "lastUpdated": "2026-03-24T00:00:00Z"
  }
}

🧾 Invoices

Create and manage invoices for merchant transactions.

Method	Path	Description
`POST`	`/v1/merchants/me/invoices`	Create a new invoice
`GET`	`/v1/merchants/me/invoices`	List all invoices
`GET`	`/v1/merchants/me/invoices/{id}`	Get invoice detail
`POST`	`/v1/merchants/me/invoices/{id}/void`	Void an invoice

Create Invoice

POST /ms/v1/merchants/me/invoices

Request Body:

Field	Type	Required	Description
`customerEmail`	string	Yes	Customer email address
`items`	array	Yes	Line items (see below)
`currency`	string	Yes	Currency code (3 chars, e.g. `GHS`)
`dueDate`	string	No	Payment due date (ISO 8601)
`notes`	string	No	Additional notes

Line item fields:

Field	Type	Required	Description
`description`	string	Yes	Item description
`quantity`	integer	Yes	Quantity
`unitPrice`	number	Yes	Price per unit

Example:

curl -X POST https://api.danipa.com/ms/v1/merchants/me/invoices \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "customerEmail": "customer@example.com",
    "items": [
      { "description": "Web Design Service", "quantity": 1, "unitPrice": 3500.00 },
      { "description": "Domain Registration", "quantity": 2, "unitPrice": 120.00 }
    ],
    "currency": "GHS",
    "dueDate": "2026-04-15",
    "notes": "Payment due within 30 days"
  }'

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "id": "inv_n6q0u4y8",
    "invoiceNumber": "INV-2026-0042",
    "customerEmail": "customer@example.com",
    "items": [
      { "description": "Web Design Service", "quantity": 1, "unitPrice": 3500.00, "total": 3500.00 },
      { "description": "Domain Registration", "quantity": 2, "unitPrice": 120.00, "total": 240.00 }
    ],
    "subtotal": 3740.00,
    "currency": "GHS",
    "status": "SENT",
    "dueDate": "2026-04-15",
    "createdAt": "2026-03-24T10:35:00Z"
  }
}

🤝 Referrals

Invite friends to Danipa and earn rewards when they sign up and transact.

Method	Path	Description
`GET`	`/v1/referrals/code`	Get your unique referral code
`GET`	`/v1/referrals`	List all referrals and their status
`GET`	`/v1/referrals/rewards`	Get referral reward history

Get Referral Code

GET /ms/v1/referrals/code

Example:

curl "https://api.danipa.com/ms/v1/referrals/code" \
  -H "Authorization: Bearer <token>" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)"

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "a7b8c9d0-e1f2-3456-abcd-567890123456",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "code": "DANIPA-PK7X9M",
    "shareUrl": "https://danipa.com/join?ref=DANIPA-PK7X9M",
    "totalReferrals": 12,
    "completedReferrals": 8,
    "totalRewardsEarned": 240.00,
    "rewardCurrency": "GHS"
  }
}

⚖️ Disputes

File and track disputes for transactions that require investigation or resolution.

Method	Path	Description
`POST`	`/v1/disputes`	File a new dispute
`GET`	`/v1/disputes`	List all disputes
`GET`	`/v1/disputes/{id}`	Get dispute detail
`POST`	`/v1/disputes/{id}/comments`	Add a comment to a dispute

File a Dispute

POST /ms/v1/disputes

Request Body:

Field	Type	Required	Description
`transactionId`	string	Yes	ID of the disputed transaction
`reason`	string	Yes	`unauthorized`, `duplicate`, `not_received`, `incorrect_amount`, or `other`
`description`	string	Yes	Detailed description (10-1000 chars)
`evidence`	array	No	Array of evidence file URLs

Example:

curl -X POST https://api.danipa.com/ms/v1/disputes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "transactionId": "txn_r7kj2m9x",
    "reason": "not_received",
    "description": "Recipient has not received the funds after 48 hours. MoMo confirmation was received but balance not credited."
  }'

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "b8c9d0e1-f2a3-4567-bcde-678901234567",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "id": "dsp_p8s2v6z0",
    "transactionId": "txn_r7kj2m9x",
    "reason": "not_received",
    "description": "Recipient has not received the funds after 48 hours. MoMo confirmation was received but balance not credited.",
    "status": "OPEN",
    "priority": "MEDIUM",
    "createdAt": "2026-03-24T10:40:00Z",
    "expectedResolutionDate": "2026-03-31T23:59:59Z"
  }
}

🔔 Notifications

Manage notification preferences for email, SMS, and push notifications.

Method	Path	Description
`GET`	`/v1/notifications/preferences`	Get current notification preferences
`PUT`	`/v1/notifications/preferences`	Update notification preferences

Update Notification Preferences

PUT /ms/v1/notifications/preferences

Request Body:

Field	Type	Required	Description
`email`	object	No	Email notification settings
`sms`	object	No	SMS notification settings
`push`	object	No	Push notification settings

Each channel object supports these boolean fields: transactions, promotions, security, reminders.

Example:

curl -X PUT https://api.danipa.com/ms/v1/notifications/preferences \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "email": { "transactions": true, "promotions": false, "security": true, "reminders": true },
    "sms": { "transactions": true, "promotions": false, "security": true, "reminders": false },
    "push": { "transactions": true, "promotions": true, "security": true, "reminders": true }
  }'

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "c9d0e1f2-a3b4-5678-cdef-789012345678",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "email": { "transactions": true, "promotions": false, "security": true, "reminders": true },
    "sms": { "transactions": true, "promotions": false, "security": true, "reminders": false },
    "push": { "transactions": true, "promotions": true, "security": true, "reminders": true },
    "updatedAt": "2026-03-24T10:45:00Z"
  }
}

🏪 POS (Point of Sale)

Process in-person sales and refunds, manage product catalogs, and view daily reports for merchant locations.

Method	Path	Description
`POST`	`/v1/pos/sales`	Process a sale
`POST`	`/v1/pos/refunds`	Process a refund
`GET`	`/v1/pos/catalog`	List catalog items
`GET`	`/v1/pos/reports/daily`	Get daily sales report

Process a Sale

POST /ms/v1/pos/sales

Request Body:

Field	Type	Required	Description
`items`	array	Yes	Array of sale items
`paymentMethod`	string	Yes	`momo`, `card`, or `cash`
`currency`	string	Yes	Currency code (3 chars, e.g. `GHS`)
`customerPhone`	string	No	Customer phone for receipt delivery

Sale item fields:

Field	Type	Required	Description
`catalogItemId`	string	No	Catalog item ID (if from catalog)
`description`	string	Yes	Item description
`quantity`	integer	Yes	Quantity
`unitPrice`	number	Yes	Price per unit

Example:

curl -X POST https://api.danipa.com/ms/v1/pos/sales \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "items": [
      { "catalogItemId": "cat_001", "description": "Wireless Mouse", "quantity": 2, "unitPrice": 85.00 },
      { "description": "USB Cable", "quantity": 1, "unitPrice": 25.00 }
    ],
    "paymentMethod": "momo",
    "currency": "GHS",
    "customerPhone": "+233241234567"
  }'

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "d0e1f2a3-b4c5-6789-defa-890123456789",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "id": "sale_q9t3w7a1",
    "receiptNumber": "POS-20260324-0017",
    "items": [
      { "description": "Wireless Mouse", "quantity": 2, "unitPrice": 85.00, "total": 170.00 },
      { "description": "USB Cable", "quantity": 1, "unitPrice": 25.00, "total": 25.00 }
    ],
    "subtotal": 195.00,
    "currency": "GHS",
    "paymentMethod": "momo",
    "status": "COMPLETED",
    "createdAt": "2026-03-24T10:50:00Z"
  }
}

💰 Payroll

Create and process payroll batches for bulk salary disbursements to employees via MoMo.

Method	Path	Description
`POST`	`/v1/payroll/batches`	Create a payroll batch
`GET`	`/v1/payroll/batches`	List payroll batches
`POST`	`/v1/payroll/batches/{id}/process`	Process a payroll batch
`GET`	`/v1/payroll/templates`	List payroll templates

Create Payroll Batch

POST /ms/v1/payroll/batches

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Batch name (e.g. `March 2026 Salaries`)
`currency`	string	Yes	Currency code (3 chars, e.g. `GHS`)
`templateId`	string	No	Payroll template ID to pre-fill employees
`employees`	array	Yes	Array of employee payment entries

Employee entry fields:

Field	Type	Required	Description
`name`	string	Yes	Employee name
`phone`	string	Yes	MoMo phone number (E.164)
`amount`	number	Yes	Payment amount
`reference`	string	No	Internal reference

Example:

curl -X POST https://api.danipa.com/ms/v1/payroll/batches \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <your-key>" \
  -H "X-Target-Environment: production" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "name": "March 2026 Salaries",
    "currency": "GHS",
    "employees": [
      { "name": "Kwame Asante", "phone": "+233241000001", "amount": 4500.00, "reference": "EMP-001" },
      { "name": "Ama Mensah", "phone": "+233241000002", "amount": 3800.00, "reference": "EMP-002" },
      { "name": "Yaw Boateng", "phone": "+233241000003", "amount": 5200.00, "reference": "EMP-003" }
    ]
  }'

Response (200 OK):

{
  "timeStamp": 1754347579330,
  "correlationId": "e1f2a3b4-c5d6-7890-efab-901234567890",
  "serverStatusCode": "200",
  "severity": "INFO",
  "data": {
    "id": "batch_r0u4x8b2",
    "name": "March 2026 Salaries",
    "currency": "GHS",
    "totalEmployees": 3,
    "totalAmount": 13500.00,
    "status": "DRAFT",
    "createdAt": "2026-03-24T10:55:00Z"
  }
}

Response Format

All responses follow a consistent envelope structure:

{
  "timeStamp": 1754347579330,
  "correlationId": "96e6837a-150c-4883-bf22-90664184e60b",
  "serverStatusCode": "200",
  "severity": "INFO",
  "details": {
    "code": "SUCCESS",
    "severity": "INFO",
    "description": "Operation completed successfully."
  },
  "data": { }
}

Error Response

{
  "timeStamp": 1754347579330,
  "correlationId": "96e6837a-150c-4883-bf22-90664184e60b",
  "serverStatusCode": "400",
  "severity": "ERROR",
  "details": {
    "code": "BAD_REQUEST",
    "severity": "ERROR",
    "description": "The request could not be understood or was missing required parameters."
  }
}

HTTP Status Codes

Code	Description
`200`	Success
`202`	Accepted (async MoMo operations)
`400`	Bad request / validation error
`401`	Unauthorized (missing or invalid credentials)
`403`	Forbidden (insufficient permissions)
`404`	Resource not found
`409`	Conflict (duplicate or stale resource)
`500`	Internal server error
`502`	Bad gateway (upstream provider error)
`503`	Service unavailable (temporary overload)

Webhooks

The API delivers async transaction results via webhooks. Callbacks are HMAC-SHA256 signed via the X-Danipa-Signature header and include an X-Danipa-Timestamp for replay protection (300-second window). Each delivery is identified by a unique X-Danipa-Delivery UUID.

Webhook	Description
MoMo Transfer Callback	Fired when a disbursement or remittance transfer completes or fails
MoMo Payment Callback	Fired when a collection request-to-pay completes or fails

Rate Limits

Plan	Requests/minute	Requests/day
Sandbox	60	10,000
Starter	120	50,000
Business	600	500,000
Enterprise	Custom	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1710165060

Full OpenAPI Specification

The complete machine-readable API specification (OpenAPI 3.1.0) is available at /docs/openapi.json. It includes all endpoints, request/response schemas, and examples -- including admin endpoints not covered in this reference.