Documentation

API Overview

Everything you need to integrate Harpoon payment verification into your application.

Authentication

Learn about API keys, scopes, and authentication methods.

Payments API

Create payment requests and verify MoMo transactions.

Webhooks

Receive real-time payment notifications at your endpoint.

Error Handling

Understand error codes and how to handle them.

Introduction

The Harpoon API allows you to accept MoMo (Mobile Money) payments directly to your own number with automatic verification. Unlike traditional payment processors, Harpoon doesn’t process payments - we verify them. This means:

Zero transaction fees - Payments go directly to your MoMo number
Instant settlement - Money is immediately in your account
HPN codes - Unique reference codes for automatic payment verification
Webhooks - Real-time notifications when payments are verified

Base URL

All API requests should be made to:

Plain Text

https://api.harpoonsms.com

Quick Start

Here’s how to accept your first payment in 3 steps:

1. Get your API key

First, create a Harpoon account if you haven’t already. Then:

Go to Settings → API Keys in your dashboard
Click Create API Key
Choose the scopes you need (at minimum: transactions:read, transactions:write)
Copy and securely store your secret key - it won’t be shown again

2. Create a payment request

Bash

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

{
  "amount": "150.00",
  "currency": "GHS",
  "description": "Order #1234"
}

Response:

JSON

{
  "success": true,
  "data": {
    "reference": "ref_abc123xyz",
    "hpn_code": "KXRT5M2PA3",
    "amount": "150.00",
    "status": "PENDING",
    "expires_at": "2024-01-09T12:00:00Z",
    "payment_instructions": {
      "mtn_momo": "Dial *170# > Transfer Money > Enter 024XXXXXXX > GHS 150.00 > Reference: KXRT5M2PA3"
    }
  }
}

3. Customer pays with the HPN code

The customer sends MoMo to your number using the hpn_code as the reference. When the payment is received, Harpoon automatically verifies it and sends a webhook to your endpoint.

JSON

// Webhook payload to your endpoint
{
  "event": "transaction.completed",
  "webhook_id": "whk_abc123xyz",
  "timestamp": "2024-01-08T12:05:32Z",
  "data": {
    "reference": "ref_abc123xyz",
    "hpn_code": "KXRT5M2PA3",
    "status": "SUCCESS",
    "expected_amount": "150.00",
    "actual_amount": "150.00",
    "difference_type": "EXACT",
    "currency": "GHS",
    "payer_phone": "+233244123456",
    "telco_provider": "mtn",
    "telco_transaction_id": "1234567890",
    "meta": {}
  }
}

Supported Providers

Harpoon currently supports the following Mobile Money providers in Ghana:

Provider	Name
MTN	MoMo
Telecel	Cash
AT	Money

Important

Never expose your secret API keys in client-side code. Always make API calls from your server.

Rate Limits

API requests are rate-limited per API key. The default limit is 100 requests per minute.

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response with headers indicating when you can retry. Implement exponential backoff in your integration.

Next Steps

Set up authentication - Learn about API keys and scopes
Payments API - Create and verify payments
Configure webhooks - Receive real-time notifications
Error handling - Handle errors gracefully