# Pull Transactions

Retrieve your PesaWay collection or payment transactions for a date range, with an optional transaction status filter. Only transactions belonging to the authenticated merchant are returned.

Endpoint: POST

https://api.sandbox.pesaway.com/api/v1/mobile-money/pull-transactions/

# Request Sample

To retrieve failed payouts:

{
  "StartDate": "2026-09-01T00:00:00+03:00",
  "EndDate": "2026-09-02T00:00:00+03:00",
  "TransType": "Payment",
  "OffsetValue": 0,
  "Status": "Failed"
}

Omit Status to retrieve only Complete transactions, as before. Set TransType to Collection to retrieve payins.

TIP

Always include the X-Region header on all requests. The appropriate X-Region can be found on the Supported Regions / Countries menu.

# Request Parameters

Parameter	Required	Description
StartDate	Yes	Inclusive start of the date range. Use a timestamp such as `2026-09-01T00:00:00+03:00`.
EndDate	Yes	Exclusive end of the date range. Use a timestamp such as `2026-09-02T00:00:00+03:00`.
TransType	Yes	`Collection` for payins, `Payment` for payouts, or `Refund` for collection refunds.
OffsetValue	Yes	Row offset, starting at `0`. Increase by `100` to request the next page.
Status	No	One transaction lifecycle status. Defaults to `Complete` when omitted. Values are case-insensitive and surrounding whitespace is ignored.

# Supported Status Values

Processing, Complete, Failed, and Rejected for payments and collections. Internal processing states such as Active, Disburse, and Fraud Review are not accepted. Refund listings use the separate values described under Pull refunds.

For example, "Status": "failed" and "Status": "Failed" select the same transactions. An explicit null, empty string, non-string value, or unsupported status returns code 403.003 with an Invalid Status message listing the supported values.

The status filter applies before pagination. Each request returns at most 100 transactions, ordered by creation date, within the requested date range and transaction type.

# Response Sample

{
  "code": "200.001",
  "data": [
    {
      "Reference": "nZ84WxLx8p1",
      "Receipt": null,
      "TransactionDate": "2026-09-01T10:13:00Z",
      "Recipient": "72200000 - John Doe",
      "ExternalReference": "UAT2",
      "TransactionType": "Payment",
      "Amount": "876.00"
    }
  ],
  "status": "success"
}

The top-level lowercase status describes the outcome of the API request. A successful lookup returns "status": "success" even when requesting failed transactions. It is distinct from the capitalized Status request filter. A successful lookup with no matches returns an empty data array.

# Response Parameters

Parameter	Description
code	API result code. `200.001` indicates a successful lookup.
status	Outcome of the API request, rather than the status of the returned transactions.
data	Array of matching transactions. Each item contains the fields below.

Transaction Field	Description
Reference	PesaWay's unique internal transaction reference.
Receipt	Third-party receipt, such as an M-Pesa receipt. May be null if unavailable.
TransactionDate	Transaction creation timestamp.
Recipient	Details of the transaction recipient.
ExternalReference	The merchant's own transaction reference.
TransactionType	`Collection` (payin) or `Payment` (payout).
Amount	Transaction amount.

# Pull refunds

Set TransType to Refund. Refund filters accept Status of Complete (default), Processing, Failed, or All, ignoring case and surrounding whitespace. All is supported for refund listings only. Refund rows include OriginalReference, Status, Stage, Currency, and completion timestamps. See Refunds for creation, signing, and lifecycle details.

← Airtime Refunds →