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
Every payment you asked for, including failed ones	Payment requests
Only the money that moved in and out of your balance	Transactions

Payment status

GEThttps://api.payd.money/api/v2/payments/{reference}/status

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

cURL

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

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

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

{
  "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.
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.

POSThttps://api.payd.money/api/v2/transaction-requests/search

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. 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.

{
  "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:

GEThttps://api.payd.money/api/v2/transaction-requests/{reference}

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_.

POSThttps://api.payd.money/api/v2/transactions/search

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.

{
  "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:

GEThttps://api.payd.money/api/v2/transactions/{code}

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