API reference overview
The exact contract — every operation, every field, every status code — lives in the API references, not in prose. The guides teach you why and when; the reference tells you exactly what.
There are two references. Both are protected: you sign in, and you need the access each one names.
| Reference | What it covers | Who can open it | Open it |
|---|---|---|---|
Merchant API reference (client.yaml) | Everything a merchant integration calls or receives: starting a checkout, preparing collection, submitting a payment, looking a payment up, branding, files, and the calls Wasp's own payment page and SDK make on your customer's behalf | A signed-in Wasp user holding Merchant API reference access | Merchant API reference |
Wasp API reference (wasp.yaml) | The broader external Wasp contract: everything in the Merchant API reference, plus the administration operations Stratsol runs to set up and maintain merchants and the platform | A signed-in Wasp user holding Wasp API reference access | Wasp API reference |
Each reference is opened by its own access, granted deliberately. Holding one does
not open the other, and being registered or attached to a merchant opens neither.
Administrators see these two kinds of access listed as portal:reference:client
and portal:reference:wasp. If you open a reference without its access, the
portal answers "You do not have access to this API reference." —
Register and get access explains how to get
it.
Each reference can also be downloaded as the exact YAML file it is rendered from, from the reference page itself.
There is no public reference and no "Try it" console. A reference describes the contract; you call the API from your own backend, with your own merchant credentials. See Before you begin.
The reference and the API are the same contract
The references are not prose someone wrote about the API. They are the published
specification itself. In the sandbox, Wasp checks each request body against the
published schema, and refuses one that does not match with a 400 that lists
each problem in response.violations.
That matters when you are diagnosing a difference between what a reference says and what the API does: there should not be one. If you find one, report it to Support rather than working around it, because one of the two is wrong and it is not always the API.
Each reference is labelled with the version you are looking at, so you can say which one you read when you report something.
Linking to one operation
Every operation in a reference has its own stable address, made from its
operation id — for example
/portal/reference/client#operation/payment for submitting a payment. The
guides link this way the first time they name an operation, so following a link
from a guide lands on that exact operation rather than at the top of the
reference.
Operation map: the Merchant API reference
One line per operation. Each link opens that operation in the Merchant API reference, so it needs Merchant API reference access.
Your backend calls these
Your server makes these calls, with your merchant's API key — and, where the operation says so, a request signature made with your key phrase. They never come from browser code.
| Operation | What it is for |
|---|---|
Initiate Transaction (payment) | Submit a payment — or a refund, void or other transaction — for one reference |
Query Order (query) | Look up everything recorded under one reference, to recover a result you did not receive |
Start Embedded Checkout (startEmbeddedCheckout) | Start an Embedded Checkout and get the payment context your page gives the SDK |
Register Hosted Checkout (registerHostedCheckout) | Register a Hosted Checkout and get the address to send your customer to |
Prepare Collection (prepareCollection) | Prepare one payment method when you collect it on your own page |
Read Hosted Checkout Branding (getHostedCheckoutBranding) | Read how your Hosted Checkout page looks |
Update Hosted Checkout Branding (updateHostedCheckoutBranding) | Change how your Hosted Checkout page looks |
List Files (listFiles) | List the files stored for your merchant |
Upload File (uploadFile) | Store a file, such as your Hosted Checkout logo |
Download File (downloadFiles) | Fetch a stored file |
Status endpoint (status) | Check that Wasp is up and answering |
Wasp's page and SDK call these
Wasp's own Hosted Checkout page, customer authentication page and Checkout SDK make these calls from your customer's browser. You do not call them; they are in the reference so you can see what crosses the browser, and why none of it needs your credentials.
| Operation | What it is for |
|---|---|
Get Checkout Config (getCheckoutConfig) | The browser-safe checkout configuration for a merchant |
Read Embedded Checkout Browser Context (readEmbeddedCheckoutContext) | What the SDK needs to render an Embedded Checkout your backend started |
Open Payment Method Session (openEmbeddedCheckoutPaymentMethodSession) | Open a wallet's session for an Embedded Checkout |
Get Hosted Checkout Page (getHostedCheckoutPage) | The Hosted Checkout payment page itself |
Pay Hosted Checkout (payHostedCheckout) | The customer paying on the Hosted Checkout page |
Cancel Hosted Checkout (cancelHostedCheckout) | The customer cancelling on the Hosted Checkout page |
Open Apple Pay Payment Session (openHostedCheckoutApplePaySession) | Open Apple Pay on the Hosted Checkout page |
Get Hosted Checkout Status (getHostedCheckoutStatus) | Keep the Hosted Checkout page up to date while a payment finishes |
Get Customer Authentication Page (getStepUpPage) | The page at a 202's action.url, where the customer authenticates |
Get Customer Authentication Status (getStepUpStatus) | Keep the authentication page up to date |
Complete Customer Authentication (completeStepUp) | The customer finishing the authentication step |
Your backend learns a payment's result from Wasp's response, from the signed
outcome notification,
or — for recovery — from one lookup by reference. It never needs to call the
browser operations above to find out.
What neither reference publishes
Stratsol's own internal operations — how Wasp is run, monitored and connected to banks — are not part of either reference. They are not a contract with you, and nothing you build depends on them.
The administration operations in the Wasp API reference are a published contract, but they are not yours to run: they need Stratsol's administration keys, not your merchant credentials, and Stratsol operates them. See the Wasp API reference page for who can call what.
Not publishing something is not what secures it — the API authenticates every call regardless.
Related
- Merchant API reference
- Wasp API reference
- Register and get access — how you get access to a reference