Payments

Retrieve transactions

List transactions or fetch one by reference, HPN code, or client reference.

Scope: transactions:read

List

Bash

GET /v1/transactions

Param	Type	Default	Description
`page`	integer	`1`
`per_page`	integer	`50`	Max `100`
`status`	string	—	Filter by status
`from`	string	—	ISO 8601
`to`	string	—	ISO 8601
`phone_number`	string	—	Filter by payer phone

Bash

curl "https://api.harpoonsms.com/v1/transactions?status=SUCCESS&per_page=10" 
  -H "Authorization: Bearer hpn_live_sk_xxxxxxxxxxxxx"

JSON

{
  "success": true,
  "data": [
    {
      "reference": "hpn_trx_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "hpn_code": "K7M3F6",
      "status": "SUCCESS",
      "expected_amount": "150.00",
      "actual_amount": "150.00",
      "difference": null,
      "difference_type": "EXACT",
      "currency": "GHS",
      "payer_phone": "0244123456",
      "payer_name": "JOHN DOE",
      "created_at": "2026-04-29T12:00:00Z",
      "completed_at": "2026-04-29T12:05:32Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 156,
    "total_pages": 16,
    "has_next": true,
    "has_prev": false
  }
}

Get by reference

Bash

GET /v1/transactions/{reference}

JSON

{
  "success": true,
  "data": {
    "reference": "hpn_trx_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "hpn_code": "K7M3F6",
    "status": "SUCCESS",
    "expected_amount": "150.00",
    "actual_amount": "150.00",
    "difference": null,
    "difference_type": "EXACT",
    "currency": "GHS",
    "payer": {
      "phone_number": "0244123456",
      "name": "JOHN DOE"
    },
    "telco": {
      "provider": "mtn",
      "transaction_id": "73012849466",
      "timestamp": "2026-04-29T12:05:30Z"
    },
    "meta": { "order_id": "1234" },
    "timeline": {
      "created_at": "2026-04-29T12:00:00Z",
      "pending_at": "2026-04-29T12:00:01Z",
      "processing_at": "2026-04-29T12:05:30Z",
      "completed_at": "2026-04-29T12:05:32Z"
    },
    "processing_time_ms": 2000,
    "client_reference": "order_1234"
  }
}

Get by HPN code

Bash

GET /v1/transactions/by-hpn/{hpn_code}

Same response shape as Get by reference.

Get by client reference

Bash

GET /v1/transactions/by-client-ref/{client_ref}

Same response shape. Use this when you’d rather look up by your own ID.

Manual reconciliation →

Reference

Cancel a payment →