Payments

Initialize a payment

Create a payment request and receive an HPN code.

Bash

POST /v1/transactions/initialize

Scope: transactions:write or transactions:initialize

Request

Field	Type	Required	Description
`amount`	string	Yes	Amount, e.g. `"150.00"`
`phone_number`	string	Yes	Customer’s phone (local or E.164)
`currency`	string	No	Default `"GHS"`
`customer_name`	string	No	Customer’s name
`description`	string	No	Transaction description
`webhook_url`	string	No	Override default webhook (secret keys only)
`redirect_url`	string	No	Where to send the customer after hosted checkout
`idempotency_key`	string	No	Dedup key (24h window). Header `Idempotency-Key` works too.
`client_reference`	string	No	Your own ID (e.g. order ID). Max 100 chars.
`meta`	object	No	Arbitrary JSON, max 4 KB
`expires_in_hours`	integer	No	Expiry in hours, 1–24. Default `24`.
`expected_telco_transaction_id`	string	No	Match a specific transaction ID — same-network only
`expected_payer_phone`	string	No	Anti-spoofing. Payments from other numbers go to manual review.
`send_sms_to_payer`	boolean	No	SMS the HPN code to the customer once verified. Default `true`.

Example

Bash

curl -X POST https://api.harpoonsms.com/v1/transactions/initialize 
  -H "Authorization: Bearer hpn_live_sk_xxxxxxxxxxxxx" 
  -H "Content-Type: application/json" 
  -d '{
    "amount": "150.00",
    "phone_number": "0244123456",
    "customer_name": "John Doe",
    "description": "Order #1234",
    "client_reference": "order_1234"
  }'

Response

JSON

{
  "success": true,
  "data": {
    "reference": "hpn_trx_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "hpn_code": "K7M3F6",
    "public_slug": "a1b2c3d4e5f6a7b8",
    "amount": "150.00",
    "currency": "GHS",
    "status": "PENDING",
    "expires_at": "2026-04-30T12:00:00Z",
    "created_at": "2026-04-29T12:00:00Z",
    "payer_sms_sent": false,
    "checkout_url": "https://harpoonsms.com/pay/a1b2c3d4e5f6a7b8",
    "client_reference": "order_1234"
  },
  "meta": {
    "request_id": "req_c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
    "idempotency_key": null
  }
}

Field	Description
`reference`	Stable Harpoon ID for the payment request
`hpn_code`	What the customer types in the MoMo reference field
`public_slug`	Used in the hosted `checkout_url`
`checkout_url`	Hosted page if you don’t want to build your own UI

The customer pays your MoMo number with the HPN code as the reference. When the payment is verified, your webhook fires.

Hosted checkout →

Set up

Webhooks →