# Payment status and lookups

Use these endpoints to confirm a payment before you act on it, to find a payment after a timeout, and to reconcile your records.

| You want | Use |
| --- | --- |
| The current state of one payment | [Payment status](#payment-status) |
| Every payment you asked for, including failed ones | [Payment requests](#search-payment-requests) |
| Only the money that moved in and out of your balance | [Transactions](#transactions) |

## Payment status

<div class="endpoint"><span class="method get">GET</span><code>https://api.payd.money/api/v2/payments/{reference}/status</code></div>

`reference` is the Payd reference from `gateway_response.merchant_reference`, such as `9BD103350408eR`.

::: code-group

```bash [cURL]
curl https://api.payd.money/api/v2/payments/9BD103350408eR/status \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD"
```

```js [Node.js]
const auth = Buffer.from(
  `${process.env.PAYD_API_USERNAME}:${process.env.PAYD_API_PASSWORD}`,
).toString('base64')

const status = await fetch('https://api.payd.money/api/v2/payments/9BD103350408eR/status', {
  headers: { Authorization: `Basic ${auth}` },
}).then((r) => r.json())

if (status.status === 'success') {
  // fulfil the order
}
```

```python [Python]
import os
import requests

status = requests.get(
    "https://api.payd.money/api/v2/payments/9BD103350408eR/status",
    auth=(os.environ["PAYD_API_USERNAME"], os.environ["PAYD_API_PASSWORD"]),
    timeout=15,
).json()

if status["status"] == "success":
    pass  # fulfil the order
```

:::

```json
{
  "success": true,
  "status": "success",
  "transaction_ref": "9BD103350408eR",
  "transaction_id": "7c1e9a52d4b8",
  "amount": 1500,
  "currency": "KES",
  "message": "Order 8842"
}
```

| Field | Meaning |
| --- | --- |
| `status` | `pending`, `processing`, `success` or `failed`. See [statuses](./core-concepts.md#statuses). |
| `success` | `true` only when `status` is `success`. |
| `transaction_ref` | The Payd reference you asked about. |
| `transaction_id` | The network's id for the payment, the same as `checkout_request_id` in the payin or payout response. |
| `amount`, `currency` | The amount you asked for. |
| `message` | The `remark` you sent with the payment. |

A `404` means Payd has no payment with that reference for your account. Check that you are using the Payd reference and the key for the right account.

### How often to check

- Collections: wait for the webhook. If none arrives within two minutes, check the status, then every few minutes for up to an hour.
- Payouts: check after 15 seconds, then every 15 seconds for two minutes, then every few minutes until the payout is final.
- Stop as soon as the status is `success` or `failed`.

## Search payment requests

A payment request is Payd's record of every payin and payout you sent, from the moment Payd accepted it. Failed and pending payments are included. Use search after a timeout, to find a payment by phone number or by the network's id.

<div class="endpoint"><span class="method post">POST</span><code>https://api.payd.money/api/v2/transaction-requests/search</code></div>

```bash
curl https://api.payd.money/api/v2/transaction-requests/search \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "account_id": "4f28836c-2f1e-4d9b-9a51-6f3c2b1d8e70",
      "term": "254712345678",
      "from": "2026-10-16T11:30:00Z",
      "page": 1,
      "per": 25
    }
  }'
```

| Filter | Meaning |
| --- | --- |
| `account_id` | Your [account id](./authentication.md#find-your-account-id). Send it on every search. |
| `term` | Matches part of the Payd reference, the phone number or the network's id. |
| `status` | `pending`, `processing`, `success` or `failed`. |
| `transaction_type` | `receipt` for collections, `withdrawal` for payouts. |
| `from`, `to` | Created between these times, in RFC 3339. |
| `page`, `per` | Page number, from 1, and page size. `per` defaults to 25 and goes up to 200. |

`term` matches parts of values, so check each result's `reference` before you act on it.

```json
{
  "transaction_requests": [
    {
      "reference": "9BD103350408eR",
      "status": "failed",
      "transaction_type": "receipt",
      "description": "Order 8842",
      "callback_url": "https://example.com/webhooks/payd",
      "country_code": "KE",
      "amounts": {
        "requested": { "amount": 1500, "currency": "KES" },
        "charges": { "amount": 22.5, "currency": "KES" },
        "billed": { "amount": 11.61, "currency": "USD" }
      },
      "counterparty": { "name": "Amina Wanjiru", "phone_number": "254712345678" },
      "provider_details": { "checkout_request_id": "7c1e9a52d4b8", "third_party_reference": "" },
      "created_at": "2026-10-16T11:42:03Z",
      "updated_at": "2026-10-16T11:43:10Z"
    }
  ],
  "pagination": { "count": "1", "page": "1", "per": "25", "num_pages": "1", "next_page": "0", "prev_page": "0" }
}
```

| Field | Meaning |
| --- | --- |
| `reference` | The Payd reference. |
| `status` | The state of the payment. |
| `amounts.requested` | The amount you sent, in your currency. |
| `amounts.charges` | Payd's fee, in the same currency. |
| `amounts.billed` | The amount in US dollars that moved on your balance. |
| `counterparty` | The customer or recipient. |
| `provider_details.checkout_request_id` | The network's id for the payment. |
| `provider_details.third_party_reference` | The network's receipt number, such as the M-Pesa confirmation code, once the payment succeeds. |
| `pagination.next_page` | The next page number, or `"0"` on the last page. |

Get one payment request by its Payd reference:

<div class="endpoint"><span class="method get">GET</span><code>https://api.payd.money/api/v2/transaction-requests/{reference}</code></div>

```bash
curl https://api.payd.money/api/v2/transaction-requests/9BD103350408eR \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD"
```

The response wraps the same object: `{ "transaction_request": { ... } }`.

## Transactions

A transaction is money that moved on your balance. Payd writes one when a payment succeeds, with the same code as the payment's Payd reference. Fees appear as their own transactions, with codes that start with `cost_`.

<div class="endpoint"><span class="method post">POST</span><code>https://api.payd.money/api/v2/transactions/search</code></div>

```bash
curl https://api.payd.money/api/v2/transactions/search \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "account_id": "4f28836c-2f1e-4d9b-9a51-6f3c2b1d8e70",
      "transaction_type": "receipt",
      "from": "2026-10-01T00:00:00Z",
      "to": "2026-10-31T23:59:59Z",
      "page": 1,
      "per": 100
    }
  }'
```

Filters work as for payment requests. `term` matches part of the transaction code or phone number.

```json
{
  "transactions": [
    {
      "code": "9BD103350408eR",
      "status": "success",
      "transaction_type": "receipt",
      "amounts": {
        "requested": { "amount": 1500, "currency": "KES" },
        "billed": { "amount": 11.61, "currency": "USD" },
        "conversion_rate": 0.00774
      },
      "balance_after": 418.32,
      "counterparty": { "phone_number": "254712345678" },
      "processed_at": "2026-10-16T11:43:10Z",
      "created_at": "2026-10-16T11:43:10Z"
    }
  ],
  "pagination": { "count": "1", "page": "1", "per": "100", "num_pages": "1", "next_page": "0", "prev_page": "0" }
}
```

| Field | Meaning |
| --- | --- |
| `code` | The Payd reference of the payment, or `cost_` plus that reference for its fee. |
| `amounts.billed` | The amount in US dollars that moved on your balance. |
| `amounts.requested` | The amount in the payment's own currency. |
| `balance_after` | Your balance in US dollars after this transaction. |
| `processed_at` | When the money moved. |

Get one transaction by its code:

<div class="endpoint"><span class="method get">GET</span><code>https://api.payd.money/api/v2/transactions/{code}</code></div>

The response wraps the same object: `{ "transaction": { ... } }`.