Collect (Kenya M-Pesa)

Create one M-Pesa collection per API call. The payer approves on their phone. Live API keys only. Scope: payin:create.

Idempotency-Key is required (16–255 chars). Replaying the same key + same body returns the first response.

Limits: 20–145,000 KES.

Create collection

POST/v1/ke/collectspayin:create

Request fields

Field	Required	Notes
`amount`	yes	Decimal string, 20–145,000 KES
`accountNumber`	yes	Kenya MSISDN: `2547XXXXXXXX`, `07XXXXXXXX`, or `7XXXXXXXX`
`accountName`	yes	Payer name
`customerEmail`	no	Payer email
`merchantReference`	no	Your order / reference id
`description`	no	Shown in the collection flow when supported
`metadata`	no	Opaque JSON stored on the transaction

Request


{
  "amount": "500",
  "accountNumber": "254712345678",
  "accountName": "Jane Doe",
  "customerEmail": "payer@example.com",
  "merchantReference": "order-42",
  "description": "Invoice 42",
  "metadata": { "orderId": "42" }
}

cURL

curl -X POST https://api.transacty.ai/v1/ke/collects \
  -H "X-Transacty-Key: $TRANSACTY_KEY" \
  -H "X-Transacty-Timestamp: $TS" \
  -H "X-Transacty-Signature: $SIG" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "500",
  "accountNumber": "254712345678",
  "accountName": "Jane Doe",
  "customerEmail": "payer@example.com",
  "merchantReference": "order-42",
  "description": "Invoice 42",
  "metadata": {
    "orderId": "42"
  }
}'

Response


{
  "transactionId": "…",
  "reference": "…",
  "status": "pending",
  "amount": "500",
  "currency": "KES",
  "settlementCurrency": "KES",
  "paymentInstructions": {
    "type": "mpesa",
    "msisdn": "254712345678",
    "network": "MPESA"
  },
  "expiresAt": "2026-10-10T12:00:00.000Z",
  "environment": "live"
}

Store transactionId. Prompt the payer to approve the M-Pesa request on their phone.

Settlement is KES only. There is no FX swap to USDC/USDT on this rail.

Poll status

GET/v1/ke/collects/:transactionIdpayin:create

No body. Sign with {timestamp}..

curl -X GET https://api.transacty.ai/v1/ke/collects/{transactionId} \
  -H "X-Transacty-Key: $TRANSACTY_KEY" \
  -H "X-Transacty-Timestamp: $TS" \
  -H "X-Transacty-Signature: $SIG" \
  -H "Content-Type: application/json"

Poll until status is terminal (success / failed), or rely on payin.completed / payin.failed.