Channel API

Overview

The Payment Portal is a payment orchestrator. Your channel sends it the order inside an encrypted, signed envelope; the Portal shows the customer the payment methods that fit the amount, hands the customer to the chosen provider's own hosted page, verifies the result with the provider server-to-server, and tells your server with a signed webhook.

How a payment works

Who does what, step by step (the same journey as the numbered list below the diagram):

1. The customer confirms the purchase in your channel.
2. Your server builds the order and seals it with the Portal's public key and your channel secret (envelope v1).
3. The browser auto-posts the envelope to /pay (or your server calls /api/v1/channel/orders).
4. The Portal verifies the HMAC, decrypts, checks the order and records it, then sends the browser to its checkout page.
5. The checkout offers only the providers and methods whose limits fit the amount and currency; the customer picks one.
6. The customer pays on the provider's hosted page (card, QR or wallet; OTP or PIN as the provider asks).
7. The provider's notification only triggers a status query: the Portal marks the payment paid only after the provider's server confirms it, with the exact amount.
8. Your webhook receives the signed payment.paid: verify it and fulfil the order.
9. The customer is sent back to your return_url with a signed status: verify it and show the result.

Data flow

What data moves between the four parties, how each flow is protected, and where the Portal keeps it. The letters match the table below.

Onboarding checklist

1. Ask Lao Airlines (QV) operations to register your channel. Give them a channel name, the exact origins of your return pages (for example https://shop.example) and your webhook URL (https).
2. You receive a channel_id and a channel secret. The secret is shown once: store it in your server's secret store.
3. Fetch the Portal's public key (step 1) at deploy time.
4. Implement sealing, the redirect, the webhook and the return page. The code samples cover all four.
5. Run the test plan against the sandbox, then ask for production credentials. Each environment has its own channel id, secret and keys.

Environments & base URL

Every path in these docs is relative to the Portal's base URL. This page is served by the Portal at …, whose environment is ….

Check which Portal you are talking to with GET /api/v1/status (field environment).

1. Get the Portal public key

Returns every active RSA-2048 public key with its kid. Use the first key. Fetch it on deploy or cache it for up to an hour (the response says Cache-Control: max-age=3600).

Loading…

2. Build the order

The order is a JSON object. Build it on your server.

{
  "v": 1,
  "channel_id": "<your channel_id>",
  "ts": 1791523200,
  "nonce": "<16+ random bytes, base64url>",
  "merchant_order_id": "QV-2026-000123",
  "amount": "150.00",
  "currency": "USD",
  "description": "Vientiane → Bangkok, 1 adult",
  "expires_at": "2026-10-07T10:30:00Z",
  "return_url": "https://shop.example/payment/return",
  "customer": { "name": "Somchai P.", "email": "somchai@example.com", "phone": "+85620xxxxxxx" },
  "metadata": { "pnr": "ABC123" },
  "locale": "lo"
}

3. Seal the envelope

Envelope v1 is hybrid encryption plus an HMAC over the ciphertext (encrypt-then-MAC), so the Portal can refuse a forged envelope before any RSA work.

1. Generate a random 32-byte AES key K and a random 12-byte iv.
2. wrapped = RSA-OAEP(SHA-256, MGF1-SHA-256)(portal public key, K) — 256 bytes.
3. header = 0x01 || len(kid) (1 byte) || kid
4. ct = AES-256-GCM(K, iv, plaintext = order JSON, aad = header) — includes the 16-byte tag.
5. payload = base64url_nopad(header || wrapped || iv || ct)
6. hashValue = lowercase hex(HMAC-SHA256(channel secret, payload))

4. Send the customer to pay

Render an auto-submitting form. POST keeps the envelope out of browser history and access logs; GET /pay?channel=…&payload=…&hashValue=… is accepted for channels that can only redirect.

<form id="qvpay" method="post" action="…/pay">
  <input type="hidden" name="channel" value="<channel_id>">
  <input type="hidden" name="payload" value="<payload>">
  <input type="hidden" name="hashValue" value="<hashValue>">
  <noscript><button>Continue to payment</button></noscript>
</form>
<script>document.getElementById("qvpay").submit();</script>

4b. Create the order server-side

The same checks as /pay, for a channel server that wants the checkout URL back as JSON (for example a mobile app that opens it in a browser tab).

curl -X POST "…/api/v1/channel/orders" \
  -H "Content-Type: application/json" \
  -d '{"channel":"<channel_id>","payload":"<payload>","hashValue":"<hashValue>"}'

{
  "order_id": "36d4955c-48e2-4ef5-b595-cc2d481c743f",
  "merchant_order_id": "QV-2026-000123",
  "amount": "150.00",
  "currency": "USD",
  "expires_at": "2026-10-07T10:30:00Z",
  "replayed": false,
  "state": "OPEN",
  "checkout_url": "…/checkout.html?order=36d4955c-48e2-4ef5-b595-cc2d481c743f"
}

Errors: 400 invalid_envelope, 409 already_paid, 409 order_conflict, 503 envelope_unavailable.

5. The customer comes back

When the payment is final, the checkout's "Back to the shop" sends the browser to your return_url with these query parameters:

Webhook events

The Portal POSTs JSON to your webhook URL from a durable outbox.

{
  "event_id": "4a1d0d2e-6a43-4a1b-9a53-1f3f0f7c9b11",
  "type": "payment.paid",
  "payment_id": "a1cb64e1-4a2f-46e7-8593-6aa8ddfe6cfe",
  "order_id": "36d4955c-48e2-4ef5-b595-cc2d481c743f",
  "channel_id": "<your channel_id>",
  "merchant_order_id": "QV-2026-000123",
  "provider": "2C2P",
  "provider_ref": "<provider reference>",
  "amount": "150.00",
  "currency": "USD",
  "status": "PAID",
  "paid_at": "2026-10-07T10:12:31Z"
}

Verifying a webhook

Compute the HMAC over the raw request body exactly as received (before any JSON parsing), compare in constant time, and refuse timestamps more than 5 minutes old.

Retries & deduplication

• Answer 2xx once you have recorded the event. Do the slow work afterwards.
• A timeout or 5xx is retried with exponential backoff; retries are normal, so the same event_id can arrive more than once. Store processed event ids and ignore repeats.
• A 4xx answer stops the retries and opens an exception for Lao Airlines operations, so answer 4xx only for a bad signature.
• If you missed events, read the order history: it is the source of truth.

Payment after the order expired

If a provider confirms a payment after the order's expires_at, the money is real but the order may no longer be fulfillable. You get no payment.paid; operations get a LATE_PAYMENT exception and a full refund is proposed automatically. After a person approves it you get refund.completed.

Signed channel requests

Server-to-server calls to /api/v1/channel/* carry three headers:

path is the URL path without the query string, for example /api/v1/channel/orders/QV-2026-000123. The one exception is the order report, which signs the query too: ts + ".GET " + path + "?" + query. A missing or wrong signature gets 401 unauthorized.

Read a payment

Returns one of your payments (404 not_found for another channel's). Fields include id, order_id, merchant_order_id, amount, currency, provider, method, status, provider_ref, verified_at, created_at, and for another currency pay_amount, pay_currency, fx_rate.

Order history

Everything that happened under one of your order keys: each Portal order, each payment attempt and each refund. Use it to answer "was I charged?" and to recover missed webhooks.

{
  "merchant_order_id": "QV-2026-000123",
  "paid": true,
  "paid_amount": "150.00",
  "refunded_amount": "150.00",
  "orders": [{
    "order_id": "36d4955c-…", "amount": "150.00", "currency": "USD", "state": "PAID",
    "metadata": { "pnr": "ABC123" }, "created_at": "…", "expires_at": "…",
    "attempts": [{
      "payment_id": "a1cb64e1-…", "provider": "LAOSPAY_SIM", "method": "QR",
      "amount": "150.00", "currency": "USD", "status": "VERIFIED", "result": "PAID",
      "created_at": "…", "verified_at": "…",
      "refunds": [{ "id": "…", "amount": "150.00", "status": "CONFIRMED", "refund_reference": "RF-2026-0001", "created_at": "…" }]
    }]
  }]
}

Refund requests

Ask for refunds of up to 500 of your orders (for example after a cancelled flight, or one passenger of a booking). Each item becomes a refund proposal; Lao Airlines staff approve or reject each one (maker ≠ checker) before it is sent to the provider. You then get refund.completed, refund.rejected or refund.failed.

• merchant_order_ids: a full refund of what is still refundable on each order.
• refunds: one item per refund. amount is a decimal string in the order currency (leave it out for the full remaining amount). refund_reference is your own id for the refund (up to 64 characters, unique per channel) and is required for a partial amount: sending the same item again returns the refund already made ("replayed": true), never a second one. kind is INVOLUNTARY (default) or CUSTOMER.
• Refunds of a payment never add up to more than was paid; refunds still waiting for a decision count too.

{
  "reason": "Flight QV635 cancelled",
  "merchant_order_ids": ["QV-2026-000123", "QV-2026-000124"],
  "refunds": [{ "merchant_order_id": "QV-2026-000125", "amount": "40.00", "refund_reference": "RF-2026-0001", "kind": "CUSTOMER" }]
}

{
  "batch_id": "…",
  "status": "PROPOSED",
  "items": [
    { "merchant_order_id": "QV-2026-000123", "refund_id": "…", "amount": "150.00 USD" },
    { "merchant_order_id": "QV-2026-000124", "error": "no paid attempt for this order" },
    { "merchant_order_id": "QV-2026-000125", "refund_reference": "RF-2026-0001", "refund_id": "…", "amount": "40.00 USD" }
  ]
}

Refunds always go back to the payer's original card or account, in the order's currency.

Cancel an order

When the booking behind an open order is released before the customer pays, cancel the order so it can no longer be paid. Body (optional): { "reason": "seat hold released" }.

The checkout then shows the order as cancelled. pending_attempts > 0 means the customer had already opened a provider's page; if they still finish paying there, it is handled like a late payment (no payment.paid, automatic full refund). The same merchant_order_id can then be used for a new order.

Order report

Your orders created in a range, oldest first, with what was paid and refunded, and totals per currency over the whole range: for your daily reconciliation. The signature covers the path and the query exactly as sent.

{
  "from": "2026-10-06T17:00:00Z", "to": "2026-10-07T17:00:00Z",
  "orders": [{
    "order_id": "36d4955c-…", "merchant_order_id": "QV-2026-000123", "amount": "150.00", "currency": "USD",
    "state": "PAID", "metadata": { "pnr": "ABC123" }, "created_at": "…",
    "payment_id": "a1cb64e1-…", "provider": "2C2P", "method": "CARD", "paid_at": "…",
    "refunded_amount": "25.00", "refund_pending_amount": "10.00"
  }],
  "next_cursor": "…",
  "totals": [{ "currency": "USD", "orders": 3, "paid_orders": 1, "paid_amount": "150.00", "refunded_amount": "25.00", "net_amount": "125.00" }]
}

Payment options

The providers and methods the Portal can route right now: a provider counts only when it is configured and healthy, a method only when an enabled limit exists. Show them if you let customers pick a preferred method. Amounts are in minor units.

Paying in another currency

You are always paid in the order's currency. When Lao Airlines enables it, a payer may pay in another currency at a provider's own rate; the checkout handles this.

Indicative rates to show before booking: policy, pay_currencies, and rates[] with currency, provider, rate (1 from = rate), per_unit, best, quoted_at, expires_at. Cached 10 minutes per provider. A payment always uses the quote made for its order at checkout.

Webhooks for such payments carry pay_amount and pay_currency. Refunds go back at the same rate.

Statuses

Order state

Payment status (status) and attempt result (result)

Refund status

PROPOSED → APPROVED → SUBMITTED → CONFIRMED; or REJECTED (by the checker) / FAILED (by the provider).

Error codes

JSON errors have the form {"error": "<code>", "message": "<text>"}. Branch on error; message is for people and may change.

Limits & timeouts

Rate limits & bot challenge

The payment endpoints resist card-testing and enumeration (Annex A C-12). Normal customers never notice them.

A throttled request gets 429 rate_limited with Retry-After. After a throttle, that IP, session or order must solve a short proof-of-work challenge (428 challenge_required) for each payment start for 10 minutes; the Portal's own checkout page does this in about a second, with no third-party script. Servers that create orders through /api/v1/channel/orders share the per-IP limit, so spread bulk work over time.

Key & secret rotation

• Portal key: when a new key appears in /api/v1/channel/keys, start using the first key; the old one keeps working until every channel has switched. Re-fetch on deploy and at least hourly.
• Channel secret: operations can rotate it and give you the new one. What you sign (envelopes, signed requests) is accepted with the old secret too during the grace period they set (up to 7 days). What the Portal signs (webhooks, return redirects) uses the new secret at once, so install it before the rotation or verify with either secret during the grace period.

Code samples

Complete, dependency-light helpers for each language. Each file seals envelopes, verifies webhooks and returns, and signs requests, and runs from the command line for quick tests. They are tested against the Portal's own envelope and signature code on every build.

Sandbox

The sandbox Portal adds two sandbox payment providers with their own payer accounts and operator consoles, so you can run a whole payment without real money:

1. Open a payer account on the provider's account page (name, login, password).
2. Fund it: ask operations for a cash-in (as the provider's staff would record), or link an account at the sandbox bank (/simbank/) on the account page and top up from it.
3. Send an order from your channel, choose the sandbox provider at checkout and pay on its page with the account's password. Where the page shows an EMVCo QR, you can instead use Scan to pay on the account page (camera, or paste the QR content), as a wallet app would.
4. You receive payment.paid; the order history shows the attempt. Operations can also play declines, expiries, refunds and chargebacks.

Wallets have a KYC level, as e-money rules require: Unverified (new accounts), Basic (ID document seen) or Full (verified identity). Where the provider's operators have set limits for a level (balance, per payment, per day, per month), a payment over them is refused on the provider's page with the limit it broke. If a large test order is refused this way, ask operations to raise the account's KYC level; it is not an error in your integration.

Go-live test plan

Run these against the sandbox and keep the results for the go-live review.

FAQ & troubleshooting