Endpoint

POST /api/init-payment
Host: pay.iconeht.com
Content-Type: application/json
x-api-key: YOUR_API_KEY

curl -X POST https://pay.iconeht.com/api/init-payment \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "action": "purchase",
    "referenceId": "order_1024",
    "currency": "htg",
    "amount": 2500,
    "items": [{ "name": "T-shirt", "quantity": 1, "unitPrice": 2500 }],
    "successUrl": "https://yourstore.com/thanks",
    "cancelUrl": "https://yourstore.com/cart"
  }'

Request Body

Field	Type	Description
actionrequired	string	A label for the transaction, e.g. "purchase".
referenceIdrequired	string	Your own order/reference id, echoed back in webhooks.
amountrequired	number	Order amount in the presentment currency. May be `0` for a pay-on-delivery (HTG) order.
currency	"htg"\|"usd"\|"dop"\|"clp"	Presentment currency. Defaults to `htg`.
paymentCurrency	"htg"\|"usd"\|"dop"\|"clp"	Optional. Fixes the charge currency; omit to let the customer choose.
itemsrequired	Item[]	Line items shown on checkout (see below).
successUrlrequired	string	Where the customer is sent after a successful payment.
cancelUrlrequired	string	Where the customer is sent if they cancel.
shipping	number	Optional shipping fee, in the presentment currency.
taxes	number	Optional tax as a percentage (e.g. 10 = 10%).
discount	object	Optional `{ code, amount }` where `amount` is a percentage 0–100.
fees	Fee[]	Optional extra fees (see Discounts and Fees).
allowPayOnDelivery	boolean	Offer pay on delivery at checkout. HTG orders only. See Pay on Delivery.
deliveryFee	"prepaid"\|"on_delivery"	For COD: is the shipping fee paid online up front, or collected on delivery.
sellerId	string	For marketplaces: routes the payment to this seller's Stripe Connect account.

Items

Each item describes one line on the checkout summary.

Field	Type	Description
namerequired	string	Item name.
quantityrequired	number	Quantity (minimum 1).
unitPricerequired	number	Price per unit in the presentment currency.
currency	"htg"\|"usd"\|"dop"\|"clp"	Item currency. Defaults to `htg`.
imageUrl	string	Optional image URL.

Discounts and Fees

discount.amount is a percentage (0–100) applied to the subtotal. Each entry in fees is either a fixed amount or a percentage:

{
  "discount": { "code": "WELCOME10", "amount": 10 },
  "fees": [
    { "name": "Service fee", "type": "percentage", "amount": 3 },
    { "name": "Packaging", "type": "fixed", "amount": 50 }
  ]
}

Response

{
  "error": false,
  "message": "Payment initiated successfully",
  "url": "https://pay.iconeht.com/pay/V1StGXR8_Z5jdHi6B-myT"
}

Redirect the customer to url. The URL is valid for 24 hours.

Errors

Status	Meaning
`401`	Missing or invalid API key.
`400`	Validation failed (e.g. negative total, COD on a non-HTG order).
`404`	Route/app not found for the key.
`429`	Rate limit exceeded — retry after the Retry-After delay.