Payments API

Check that a mobile-wallet payment reached your PIQX gateway, and mark it as used for one order.

Overview

The API has two endpoints. Both take JSON and return JSON, over HTTPS, at https://piqxgateway.com.

Endpoint	What it does
`POST /api/verify-payment`	Looks up a transaction ID. Changes nothing.
`POST /api/claim-payment`	Marks a transaction ID as used for an order, so it cannot be reused.

Ask your PIQX administrator for a payments API key. It works for these two endpoints only.

Authentication

Send your key in the X-Ext-Api-Key header on every request.

Header

X-Ext-Api-Key: YOUR_API_KEY
Content-Type: application/json

A missing or wrong key returns 403. Repeated wrong keys from one address are blocked for a while. A key that is valid but not allowed for an endpoint returns 403 with insufficient_scope.

Recommended flow

Your customer pays and gives you the transaction ID (TrxID) from their receipt.
Your server calls claim-payment with the TrxID, the order total and your order reference.
On 200, mark the order paid. On 409 already_claimed, do not fulfil it a second time.
Use verify-payment when you only want to show the customer a status and not use up the payment.

Always send amount with a claim. Without it, the amount is not checked.

Verify a payment

POST/api/verify-payment

Request body

Field	Type	Description
`trx`	string, required	The transaction ID. Letters and digits only; other characters are removed and the value is upper-cased. At least 6 characters, at most 40.
`amount`	number, optional	The amount you expect. When sent, the response says whether it matches.

curl

curl -X POST https://piqxgateway.com/api/verify-payment \
  -H "X-Ext-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trx":"7K2ABC9QA","amount":1250}'

Response: found

200 OK

{
  "ok": true,
  "found": true,
  "trx": "7K2ABC9QA",
  "provider": "...",
  "amount": 1250,
  "direction": "...",
  "kind": "payment_in",
  "receivedAt": "...",
  "amountMatches": true,
  "claimed": false
}

kind is payment_in for money received. amountMatches is true or false when you sent amount, and null when you did not. claimed tells you whether the transaction was already used. The values shown as "..." are filled in by the server.

Response: not found

200 OK

{ "ok": true, "found": false, "trx": "7K2ABC9QA", "claimed": false }

A payment can take a moment to arrive. If it is not found, wait a few seconds and ask again.

Claim a payment

POST/api/claim-payment

Request body

Field	Type	Description
`trx`	string, required	The transaction ID, as above.
`amount`	number, recommended	The order total. The claim is refused if it does not match.
`orderRef`	string, optional	Your order reference. Kept with the claim; the first 60 characters are used.

curl

curl -X POST https://piqxgateway.com/api/claim-payment \
  -H "X-Ext-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trx":"7K2ABC9QA","amount":1250,"orderRef":"ORDER-1042"}'

200 OK

{ "ok": true, "claimed": "7K2ABC9QA", "amount": 1250, "provider": "..." }

Node.js

const res = await fetch("https://piqxgateway.com/api/claim-payment", {
  method: "POST",
  headers: {
    "X-Ext-Api-Key": process.env.PIQX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ trx, amount: order.total, orderRef: order.id }),
});
const data = await res.json();
if (res.ok) markOrderPaid(order.id);
else if (data.error === "already_claimed") { /* do not fulfil twice */ }

Python

import os, requests

r = requests.post(
    "https://piqxgateway.com/api/claim-payment",
    headers={"X-Ext-Api-Key": os.environ["PIQX_API_KEY"]},
    json={"trx": trx, "amount": order_total, "orderRef": order_id},
    timeout=15,
)
if r.ok:
    mark_order_paid(order_id)
elif r.json().get("error") == "already_claimed":
    pass  # do not fulfil twice

Errors

HTTP	`error`	Meaning
200	`trx_too_short` (with `ok: false`)	On `verify-payment`, the transaction ID is shorter than 6 characters.
400	`trx_too_short`	On `claim-payment`, the transaction ID is shorter than 6 characters.
404	`not_found`	No payment with this transaction ID has arrived.
409	`not_incoming_payment`	The transaction is not money received.
409	`amount_mismatch`	The amount you sent differs from the payment.
409	`already_claimed`	This transaction was already used.
403	none, or `insufficient_scope`	The key is missing, wrong, blocked or not allowed here.

Security

Keep the key on your server. Never put it in a web page, a mobile app or a public repository.
Use HTTPS only.
If a key may have leaked, tell your PIQX administrator so it can be replaced.
PIQX will never ask for your key in chat.