Open Collections

Routing

One rule per thing you want sent somewhere.

A rule claims payments by the number that received them.

How a payment is matched

Every rule that claims it fires, on every endpoint. Two systems can both receive one payment.
If none claims it, catch-alls fire instead. A catch-all is a rule with no payment_method_id.
A payment that matched none of your numbers reaches catch-alls only.

Payments a Harpoon payment code already matched are skipped, unless a rule sets include_matched.

Create a rule

Bash

POST /v1/open-collections/endpoints/{endpoint_id}/routes
Authorization: Bearer hpn_live_sk_xxxxxxxxxxxxx
Content-Type: application/json

{
  "payment_method_id": "8f14e45f-ceea-467a-9d0f-2b6f0e4c4b71",
  "reference_prefix": "INV",
  "min_amount": "10.00"
}

Field	Type	Description
`payment_method_id`	string \| null	The number this rule claims. Null makes it a catch-all
`merchant_code`	string \| null	Narrows the number to one till. Requires `payment_method_id`
`reference_prefix`	string \| null	Matched case-insensitively against the start of the reference
`min_amount`	string \| null	Inclusive
`max_amount`	string \| null	Inclusive
`include_matched`	boolean	Also send payments a Harpoon payment code already matched. Default `false`
`is_active`	boolean	`false` stops the rule without deleting it

payment_method_id values come from GET /v1/payment-methods.

List, update, remove

Bash

GET    /v1/open-collections/endpoints/{endpoint_id}/routes
PUT    /v1/open-collections/routes/{id}
DELETE /v1/open-collections/routes/{id}

PUT replaces every field, so send the whole rule.

One number, several projects

Give each project a reference prefix and its own endpoint:

JSON

{ "payment_method_id": "8f14e...", "reference_prefix": "INV" }
{ "payment_method_id": "8f14e...", "reference_prefix": "SUB" }

INV-8842 reaches the first, SUB-1120 the second, anything else your catch-all.

Till payments on a shared number

A rule with merchant_code claims till payments only:

JSON

{ "payment_method_id": "8f14e...", "merchant_code": "554120" }

Available on Telecel. Leave it off on MTN and AirtelTigo, where it matches nothing yet.

Limits

20 endpoints
20 rules per endpoint
One verified transaction per payment, however many endpoints receive it

Payload reference →

Also useful

Management →