Send payouts to Haiti,
programmatically.

From zero to first payout

Every account starts in Sandbox, where a fake balance lets you build and test with zero real money moving.

Signing requests

# signing string = "{ts}.{METHOD} {path}.{body}"
TS=$(($(date +%s)*1000))
BODY='{"recipient":"+509XXXXXXXX","amount":1000,"reference":"order-1001"}'
MSG="$TS.POST /transfers.$BODY"
SIG=$(printf '%s' "$MSG" | openssl dgst -sha256 \
      -hmac "$ERTHA_API_SECRET" | sed 's/^.* //')

curl https://api.erthapay.com/transfers \
  -H "content-type: application/json" \
  -H "x-partner-key: $ERTHA_API_KEY" \
  -H "x-partner-timestamp: $TS" \
  -H "x-partner-signature: $SIG" \
  -d "$BODY"

import crypto from 'node:crypto';

const ts   = Date.now().toString();
const body = JSON.stringify({ recipient:'+509XXXXXXXX', amount:1000, reference:'order-1001' });
const msg  = `${ts}.POST /transfers.${body}`;
const sig  = crypto.createHmac('sha256', process.env.ERTHA_API_SECRET)
                   .update(msg).digest('hex');

await fetch('https://api.erthapay.com/transfers', {
  method:'POST',
  headers:{
    'content-type':'application/json',
    'x-partner-key':process.env.ERTHA_API_KEY,
    'x-partner-timestamp':ts,
    'x-partner-signature':sig,
  },
  body,
});

import hashlib, hmac, json, os, time
import requests

ts   = str(int(time.time() * 1000))
body = json.dumps({"recipient":"+509XXXXXXXX","amount":1000,"reference":"order-1001"}, separators=(",",":"))
msg  = f"{ts}.POST /transfers.{body}"
sig  = hmac.new(os.environ["ERTHA_API_SECRET"].encode(), msg.encode(), hashlib.sha256).hexdigest()

requests.post("https://api.erthapay.com/transfers", data=body, headers={
  "content-type":"application/json",
  "x-partner-key":os.environ["ERTHA_API_KEY"],
  "x-partner-timestamp":ts,
  "x-partner-signature":sig,
})

Sandbox & Live

Two isolated key pairs. Which key signs the request decides the mode — the same endpoints serve both.

Create a payout

{
  "status": "accepted",
  "reference": "order-1001",
  "transaction_id": "txn_9f3c1a20e5b74c1d8a2f6b90",
  "payout_status": "pending",
  "fee": 15,
  "total_debited": 1015,
  "balance": 95364,
  "currency": "HTG",
  "created_at": "2026-08-07T12:00:00Z",
  "estimated_processing_time_seconds": 5
}

Retrieve a payout

{
  "reference": "order-1001",
  "transaction_id": "txn_9f3c1a20e5b74c1d8a2f6b90",
  "status": "paid",
  "amount": 1000,
  "fee": 15,
  "currency": "HTG",
  "created_at": "2026-08-07T12:00:00Z",
  "settled_at": "2026-08-07T12:00:04Z"
}

Validate a recipient

{
  "recipient": "+509XXXXXXXX",
  "name": "Jean Baptiste",
  "livemode": true
}

Get balance

{
  "balance": 96379,
  "currency": "HTG",
  "livemode": true
}

Idempotency

Networks fail. Retries shouldn't cost money twice.

Every payout carries your reference. If a request times out, re-send the same reference with the same body — you'll get the original payout back, never a duplicate. Re-using a reference with a different amount or recipient is rejected with 409 DUPLICATE_REQUEST, so a mistaken reuse can't silently overwrite a real payment. An optional Idempotency-Key header is supported, but if you send it, it must equal the body reference (otherwise 400 IDEMPOTENCY_KEY_MISMATCH).

A timeout or a 503 is not a failure — the payout may have succeeded. See Uncertain outcomes.

Uncertain outcomes

A timed-out request or a 503 tells you nothing about the payout itself — it may already have gone through. Resolve the ambiguity before you move any more money.

Webhooks

When a payout reaches a terminal state, ERTHA POSTs a signed event to your endpoint. A webhook is a notification, not proof — verify its signature and reconcile against the API before acting on money.

Events

Only these two terminal events are sent. In-flight states (pending, processing) and review_required do not emit a webhook — poll Retrieve for those.

{
  "event": "payout.paid",
  "event_id": "9f3c1a20-4e2b-4c1d-8a2f-6b90e5b74c1d",
  "reference": "order-1001",
  "status": "paid",
  "amount": 1000,
  "fee": 15,
  "currency": "HTG",
  "created_at": "2026-08-07T12:00:00Z",
  "settled_at": "2026-08-07T12:00:04Z"
}

import crypto from 'node:crypto';

// rawBody = the exact bytes of the POST body — do NOT re-serialize.
function verifyErthaWebhook(headers, rawBody) {
  const ts  = headers['x-ertha-timestamp'];
  const sig = headers['x-ertha-signature'];
  const expected = crypto.createHmac('sha256', process.env.ERTHA_WEBHOOK_SECRET)
                        .update(`${ts}.${rawBody}`).digest('hex');
  const ok = sig && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) throw new Error('bad signature');
  // freshness guard (choose your own tolerance)
  if (Math.abs(Date.now() - Number(ts)) > 300000) throw new Error('stale');
  return JSON.parse(rawBody); // parse only AFTER verifying
}

Delivery, retries & ordering

In Sandbox you can fire a test payout.paid from your dashboard. The test payload carries "test": true and no body event_id — use the x-ertha-event-id header for dedup.

Limits & formats

The exact shapes, bounds, and rate limits the API enforces.

Fields & formats

Signing string (exact)

METHOD is upper-case; path is the route (e.g. /transfers); for a GET the body is empty, so the string ends in a trailing dot (e.g. <ts>.GET /balance.). Sign the exact raw bytes you send — the signature is byte-for-byte.

Rate limits

The default limit is 60 requests/minute per key (counted separately for Sandbox and Live); recipient validation is limited separately (10/min, 200/day). Over the limit returns 429 RATE_LIMITED.

Errors & status codes

Errors return a JSON body of the shape { "error": "CODE" }. Never surface a raw error to your end user — map it to your own copy.

Codes are stable strings; treat any unlisted code as a generic failure and reconcile via Retrieve.