Payments

Manual reconciliation

Verify a payment by transaction ID when auto-match missed it.

Use this when a customer claims to have paid but their payment didn’t auto-verify — usually because they didn’t include the HPN code, or paid from an unexpected number. Ask them for the transaction ID from their MoMo confirmation, then submit it here.

Bash

POST /v1/transactions/{reference}/reconcile

Scope: transactions:write

Request

Field	Type	Required	Description
`transaction_id`	string	Yes	Transaction ID from the customer’s MoMo confirmation (MTN: `73012849466`, Telecel: `0000011528209461`, AT: `PP260203.1254.C00772`)
`amount`	decimal	No	Strict-check opt-in. If supplied, mismatch returns `AMOUNT_MISMATCH`. Omit to accept whatever was paid.
`notes`	string	No	Free-text context for the audit log

Bash

curl -X POST https://api.harpoonsms.com/v1/transactions/hpn_trx_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/reconcile 
  -H "Authorization: Bearer hpn_live_sk_xxxxxxxxxxxxx" 
  -H "Content-Type: application/json" 
  -d '{ "transaction_id": "73012849466" }'

Response

JSON

{
  "success": true,
  "data": {
    "reconciliation_id": "rec_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "status": "VERIFIED",
    "transaction_id": "73012849466",
    "transaction_updated": true,
    "new_transaction_status": "SUCCESS",
    "matched_amount": "150.00",
    "expected_amount": "150.00",
    "difference": "0.00",
    "difference_type": "exact",
    "message": "Payment verified successfully"
  }
}

Statuses

`status`	Meaning
`VERIFIED`	Payment matched. `new_transaction_status` is `SUCCESS`, `PARTIAL`, or `OVERPAID`.
`ALREADY_CONFIRMED`	The transaction was already verified, or the transaction ID has already been used.
`NOT_FOUND`	No matching payment found on your account. Check the ID.
`AMOUNT_MISMATCH`	Only when you supplied `amount` and it didn’t equal the actual amount.

Response fields

Field	Description
`new_transaction_status`	New state of the payment
`matched_amount`	Actual amount received
`expected_amount`	Amount on the original payment request
`difference`	Signed: `matched - expected`. Negative = underpaid.
`difference_type`	`exact`, `underpaid`, or `overpaid`

A successful reconcile fires a transaction.completed webhook.

Cancel a payment →

Reference

Retrieve a transaction →