Documentation

API Overview

Integrate Harpoon payment verification into your application.

Authentication

API keys and scopes.

Payments API

Create and verify payments.

Webhooks

Real-time notifications.

Open Collections

Forward every incoming payment to your server.

Errors

Error response format and codes.

How it works

You issue an HPN code per payment. The customer pays your MoMo number with that code as the reference. Harpoon verifies the payment and fires your webhook.

  • Payments go directly to your MoMo number — Harpoon never holds funds.
  • Supported providers: MTN MoMo, Telecel Cash, AT Money.

Base URL

Plain Text 
https://api.harpoonsms.com

Quick start

1. Get an API key

Settings → API Keys → Create. Choose scopes (transactions:read, transactions:write). Copy the secret immediately — it’s shown once.

2. Initialize a payment

Bash 
POST /v1/transactions/initialize
Authorization: Bearer hpn_live_sk_your_api_key
Content-Type: application/json

{
  "amount": "150.00",
  "phone_number": "0244123456",
  "description": "Order #1234"
}
JSON 
{
  "success": true,
  "data": {
    "reference": "hpn_trx_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "hpn_code": "K7M3F6",
    "amount": "150.00",
    "status": "PENDING",
    "expires_at": "2026-04-30T12:00:00Z",
    "checkout_url": "https://harpoonsms.com/pay/a1b2c3d4e5f6a7b8"
  }
}

3. Customer pays

The customer sends MoMo to your number using hpn_code as the reference. When the payment is verified, your webhook fires:

JSON 
{
  "event": "transaction.completed",
  "webhook_id": "whk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "timestamp": "2026-04-29T12:05:32Z",
  "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",
    "telco_provider": "mtn",
    "telco_transaction_id": "73012849466"
  }
}

Rate limits

100 requests per minute per API key. 429 Too Many Requests includes Retry-After. See errors.

Never expose secret keys in client-side code. Use a public key (hpn_*_pk_*) for browsers.