Quick start

This takes about ten minutes once you have test credentials (section 3). You’ll log in, generate a US$1.00 payment code, pay it with the InnBucks test app, and check that it was paid. You need curl and jq.

2.1 Set your credentials

export INNBUCKS_BASE_URL='https://<test-base-url-from-innbucks>'
export INNBUCKS_API_KEY='your-api-key'
export INNBUCKS_USERNAME='your-username'
export INNBUCKS_PASSWORD='your-password'

2.2 Log in

TOKEN=$(curl -sS -X POST "$INNBUCKS_BASE_URL/auth/third-party" \
  -H "X-Api-Key: $INNBUCKS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"username":"'"$INNBUCKS_USERNAME"'","password":"'"$INNBUCKS_PASSWORD"'"}' \
  | jq -r '.accessToken')
echo "$TOKEN"

A token string means you’re in. null means the login failed; run the command without | jq ... to see responseDescription.

2.3 Generate a payment code

REF="QS$(date +%s)"
curl -sS -X POST "$INNBUCKS_BASE_URL/api/code/generate" \
  -H "X-Api-Key: $INNBUCKS_API_KEY" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "'"$REF"'",
    "narration": "Quick start '"$REF"'",
    "currency": "USD",
    "amount": 100,
    "type": "PAYMENT"
  }' | tee code.json | jq 'del(.qrCode)'

"amount": 100 is 100 cents = US$1.00. A responseCode of "00" means the code exists. Note the code value (for example 535403380); the qrCode field holds the same code as a base64 image.

CODE=$(jq -r '.code' code.json)

2.4 Pay it

Open the InnBucks test customer app (3.3) and pay against the code, or scan the QR code. Save the QR code to a file to scan it from your screen:

jq -r '.qrCode' code.json | sed 's/^data:[^,]*,//' | base64 -d > qr.png

2.5 Check the code

curl -sS -X POST "$INNBUCKS_BASE_URL/api/code/inquiry" \
  -H "X-Api-Key: $INNBUCKS_API_KEY" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"code":"'"$CODE"'"}' | jq '{responseCode, status, timeToLive, amount}'

Before payment the status is New. After the customer pays it becomes Claimed (or Paid). If nobody pays within 10 minutes it becomes Expired or Timed Out. Wait 30 seconds between checks (12.3).

That’s the whole payment flow. Everything else in this guide is about doing it reliably: keeping the token fresh, showing the code well, checking status on a schedule, handling errors, and passing UAT.

---

This page is generated from section 2 of the README in README.md. Spotted something wrong? Open an issue.