Pycue is a payment gateway providing a unified API for mobile money collections and disbursements in Ghana. It handles MoMo collections (deposits), MoMo transfers (withdrawals), SMS messaging, OTP verification, airtime, and MoMo-funded data bundles.

All organization-facing API requests require an API key via the Authorization header.

Authorization: Bearer gw_live_4f8a2b3c...

Keys are issued by the platform admin. The raw key (gw_live_* or gw_test_*) is shown only once at creation. Only the SHA-256 hash is stored server-side.

Initiate a MoMo collection (push payment) from a user's mobile money wallet. The user receives a USSD prompt on their phone to approve the payment.

curl -X POST /api/v1/deposits \
  -H "Authorization: Bearer gw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_12345",
    "amount": "10.50",
    "phoneNumber": "0541234567",
    "network": "MTN",
    "clientReference": "order-42-deposit"
  }'

{
  "success": true,
  "data": {
    "transaction": {
      "id": "a1b2c3d4-...",
      "type": "DEPOSIT",
      "status": "PENDING",
      "amount": "10.50",
      "currency": "GHS",
      "externalUserId": "user_12345",
      "clientReference": "order-42-deposit",
      "providerReference": "903434548908798123",
      "providerTransactionId": "561338065478",
      "createdAt": "2026-08-26T10:00:00.000Z",
      "updatedAt": "2026-08-26T10:00:00.000Z"
    }
  }
}

Send a Kakosino-authorized payout directly to the recipient's MoMo wallet. Kakosino owns user eligibility and transaction rules; Pycue records the organization transaction, checks the organization vault, and submits the MoMo transfer. Pycue does not maintain a user withdrawal reserve or financial queue.

curl -X POST /api/v1/withdrawals \
  -H "Authorization: Bearer gw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_12345",
    "amount": "5.00",
    "accountNumber": "0549876543",
    "channel": "MTN",
    "accountName": "Kwame Asante",
    "clientReference": "payout-99-withdraw"
  }'

{
  "success": true,
  "data": {
    "transaction": {
      "id": "e5f6g7h8-...",
      "type": "ORG_TRANSFER",
      "status": "SUCCESS",
      "amount": "5.00",
      "currency": "GHS",
      "externalUserId": "user_12345",
      "clientReference": "payout-99-withdraw",
      "providerReference": "payout-99-withdraw",
      "providerTransactionId": "305243536672",
      "createdAt": "2026-08-26T10:05:00.000Z",
      "updatedAt": "2026-08-26T10:05:00.000Z"
    }
  }
}

Transfer funds directly from the organization's vault to an external MoMo account. Unlike user withdrawals, no externalUserIdis involved — money comes from the organization's vault position.

Use this for organizations whose users only deposit (e.g. e-commerce) and the org admin needs to withdraw accumulated funds.

curl -X POST /api/v1/org-transfers \
  -H "Authorization: Bearer gw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500.00",
    "accountNumber": "0244123456",
    "channel": "MTN",
    "accountName": "Acme Corp Payout",
    "clientReference": "org-payout-jan-12"
  }'

{
  "success": true,
  "data": {
    "transactionId": "f8a9b0c1-...",
    "duplicate": false,
    "status": "SUCCESS"
  }
}

Each organization has a configurable daily withdrawal limit that applies across all withdrawal types (user withdrawals and org transfers). The limit resets at midnight UTC.

Organization Vault

{
  "success": true,
  "data": {
    "currency": "GHS",
    "vaultPosition": "1250.00"
  }
}

User Balance

{
  "success": true,
  "data": {
    "externalUserId": "user_12345",
    "currency": "GHS",
    "availableBalance": "50.00",
    "reservedBalance": "10.00"
  }
}

List Transactions

{
  "success": true,
  "data": {
    "transactions": [ { "id": "...", "type": "DEPOSIT", "status": "SUCCESS", ... } ],
    "pagination": {
      "hasMore": true,
      "nextCursor": "a1b2c3d4-...",
      "limit": 20
    }
  }
}

Get Transaction

Returns a single transaction. If the transaction is still PENDING, PROCESSING, or an ambiguous RESERVED transfer, a best-effort reconciliation check runs first. Normal accepted transfers are finalized immediately.

Deliver airtime using either your organization vault balance or a MoMo payment prompt. MoMo-funded purchases remain PENDING or PROCESSING until Pycue confirms the provider payment, then airtime is sent.

curl -X POST /api/v1/airtime \
  -H "Authorization: Bearer gw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "0541008285",
    "phoneNumber": "0541008285",
    "network": "MTN",
    "amount": "10.00",
    "fundingSource": "MOMO",
    "clientReference": "airtime-order-42"
  }'

Poll this endpoint for MoMo-funded purchases. Once the status is SUCCESS, airtime delivery has been confirmed by Pycue.

Offer recipient-specific data bundles through a MoMo payment prompt. Pycue fetches the available services and packages live, starts the purchase, and lets you poll for the final status.

Returns the active data bundle services and their provider service IDs.

Returns the packages available for a service and recipient number. Use the returned package id, display name, and amount when starting a purchase.

This purchase flow is MoMo-funded. Pycue does not advertise a balance-funded data bundle flow.

curl -X POST /api/v1/data-bundles \
  -H "Authorization: Bearer gw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "0541008285",
    "network": "MTN",
    "serviceId": "service-id-from-services",
    "packageId": "package-id-from-offers",
    "packageName": "1GB",
    "amount": "10.00",
    "clientReference": "bundle-order-42"
  }'

Poll this endpoint after the MoMo prompt. The purchase becomes SUCCESS only after Pycue confirms the provider status.

Send SMS OTP

{
  "phoneNumber": "0541234567",
  "message": "Your verification code is <%%otp_code%%>. It expires in 5 minutes.",
  "expiry": 5,
  "length": 6
}

{
  "success": true,
  "data": {
    "requestId": "05dd890a-f560-45aa-9dc1-0ef0ea72757b",
    "prefix": "JQmr"
  }
}

Verify SMS OTP

Email OTP

Same flow as SMS OTP but for email addresses.

Pycue does not push completion events to you. A payout is only observable on your side through the response to your own request, or by polling. If your balance logic waits for an inbound callback, it will never fire.

The two supported paths

1. React to the response of your own request. POST /api/v1/withdrawals returns the final state for an accepted transfer. A 201 means the network accepted the payout.
2. Poll until the status is final. Query GET /api/v1/transactions/:id, or GET /api/v1/transactions?status=… to sweep. A payment is final when its status is SUCCESS, FAILED or CANCELLED.

Idempotent replays

clientReference is unique per organization at the database level. If you send the same key twice you receive the original transaction back with 200 and duplicate: true — never a second payout. The replayed response is also the authoritative record of that payout, so a client that discards a 200as “nothing to do” is dropping a real completion signal. Branch on duplicate, not on the HTTP status alone.

Pycue receives network callbacks for collections and direct MoMo transfers, and validates every payload before applying any financial transition. This is handled entirely on Pycue’s side: there is nothing for you to configure, and your application neither sends nor receives it.

Callbacks are never trusted at face value. The payload shape Pycue receives is:

Callback payload

{
  "amount": "10.50",
  "status": "success",
  "transaction_id": "903434548908798123",
  "ext_transaction_id": "561338065478",
  "phone_number": "0541234567"
}

Security Model

Network callbacks are not signed, so Pycue compensates with three guards:

1. transaction_id, client_reference, or ext_transaction_id must match a local provider or client reference. For transfers, providerReference is the exact bounded client_reference submitted for the payout.
2. The amount must match the stored transaction amount exactly.
3. Before crediting, Pycue re-verifies the status with an authoritative server-to-server call to GET /api/v1/payment-api/checkstatus/{transaction_id}.

Webhook Response

{
  "success": true,
  "data": {
    "received": true,
    "processed": true
  }
}

Possible reason values when processed: false:

All errors follow the standard envelope with an error.code and error.message:

Both deposits and withdrawals are idempotent via the clientReference field. Sending the same clientReference with the same externalUserId returns the original transaction without creating a new one.

// First call: creates a new deposit (201)
// Retry with same clientReference: returns existing (200)
{
  "externalUserId": "user_12345",
  "amount": "10.50",
  "phoneNumber": "0541234567",
  "network": "MTN",
  "clientReference": "order-42-deposit"
}