Initiate collection - MarzPay Docs

curl --request POST \
  --url https://wallet.wearemarz.com/api/v1/collect-money \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 5000,
  "phone_number": "+256712345678",
  "reference": "c97fae8b-9b7f-4192-9f72-6f0859d33e67",
  "country": "UG",
  "description": "Order payment",
  "callback_url": "https://your-app.com/webhooks/marzpay",
  "metadata": [
    {
      "orderId": "ORD-123456789"
    },
    {
      "customerId": "customer@email.com",
      "isPII": true
    }
  ]
}
'

{
  "status": "error",
  "message": "<string>",
  "error_code": "VALIDATION_ERROR",
  "errors": {}
}

POST

/

collect-money

curl --request POST \
  --url https://wallet.wearemarz.com/api/v1/collect-money \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 5000,
  "phone_number": "+256712345678",
  "reference": "c97fae8b-9b7f-4192-9f72-6f0859d33e67",
  "country": "UG",
  "description": "Order payment",
  "callback_url": "https://your-app.com/webhooks/marzpay",
  "metadata": [
    {
      "orderId": "ORD-123456789"
    },
    {
      "customerId": "customer@email.com",
      "isPII": true
    }
  ]
}
'

{
  "status": "error",
  "message": "<string>",
  "error_code": "VALIDATION_ERROR",
  "errors": {}
}

Authorizations

Authorization

string

header

required

base64(api_key:api_secret)

Body

application/json

amount

number

required

Required range: 500 <= x <= 10000000

Example:

5000

reference

string<uuid>

required

Example:

"c97fae8b-9b7f-4192-9f72-6f0859d33e67"

country

enum<string>

required

UG (UGX), KE (KES), RW (RWF), CD (CDF/USD), ZM (ZMW), CM/GA/CG (XAF), BJ/CI/SN (XOF), or SL (SLE)

Available options:

UG,

KE,

RW,

CD,

ZM,

CM,

BJ,

CI,

GA,

CG,

SN,

SL

phone_number

string

Required for mobile money; omit for card. E.164 — Uganda +256…, Kenya +254…, Rwanda +250…, DRC +243…, Zambia +260…, Cameroon +237…, Benin +229…, Côte d'Ivoire +225…, Gabon +241…, Congo-Brazzaville +242…, Senegal +221…, Sierra Leone +232…

Pattern: ^\+[0-9]{10,15}$

Example:

"+256712345678"

currency

enum<string>

Optional. For DRC (CD), use CDF (default) or USD for dual wallets.

Available options:

UGX,

KES,

RWF,

CDF,

USD,

ZMW,

XAF,

XOF,

SLE

method

enum<string>

default:mobile_money

Available options:

mobile_money,

card

description

string

Maximum string length: 255

callback_url

string<uri>

metadata

object[]

Optional. Array of objects echoed on create (data.collection.metadata) and webhooks (top-level metadata). Each item has exactly one field name + string/number value, plus optional isPII: true.

Maximum array length: 10

Example:

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

Response

Collection initiated