Skip to main content

Glossary

Every term the documentation uses, in plain language. Nothing here assumes you have integrated a payment platform before.

This is a glossary of concepts, not a field reference. Where a concept has an exact name, type and behaviour in the API, that belongs with the contract itself and is covered in the Merchant API reference and the implementation guides, which open with Merchant API reference access.

Identifiers and credentials​

reference​

Your own identifier for an order — an order number, an invoice id, whatever you use. You choose it, it must be unique per order for your merchant, and it is how you look the payment up later. The sale and every transaction that follows it share it. There is no other payment identifier: Wasp does not give you a separate payment id, and you should not look for one.

Merchant ID​

Identifies your merchant, in UUID format. Stratsol issues it at onboarding. It goes in API paths and is not secret. Use the one Stratsol issues for each environment: see Merchant ID and Aggregator ID by environment.

Aggregator ID​

Identifies the organisation your merchant sits under, in UUID format. Also issued at onboarding, it goes in API paths, and is not secret. You do not need to understand the hierarchy to use it.

API Key​

Identifies which account is calling. Your backend sends it with every API call, in a header Wasp expects. Server-side only — it never belongs in browser code.

Key Phrase​

A secret used to sign requests, proving they came from you and were not altered. Server-side only, and it is never sent — only the signature it produces is.

Signing​

Producing a short cryptographic value from your request plus your Key Phrase, so Wasp can tell the request is genuine. Wasp uses HMAC for this. See HMAC signing.

HMAC​

Short for hash-based message authentication code: a standard way to sign a message with a shared secret. Your backend runs the request details and your Key Phrase through HMAC-SHA256 and sends the result as the request's signature. Wasp holds the same Key Phrase, repeats the calculation, and accepts the request only if the two results match — so a request that was forged or altered on the way is refused. The Key Phrase itself never leaves your server. See HMAC signing.

Card data​

These are the values that make card data sensitive. Most integrations never see any of them; the ones that do must never log, display or store them.

PAN​

Short for primary account number: the long number on the front of a payment card. It is the most sensitive part of a card. With Hosted Checkout, Embedded Checkout and wallet payments your systems never see it. If you collect card details on your own page, your backend sends it to Wasp in the payment request — and must never log it, display it in full, or put it in a support request.

DPAN​

Short for device primary account number. When a customer pays with Google Pay or Apple Pay, the wallet usually does not reveal the real card number. It uses a substitute number tied to the customer's device or account, sealed inside the wallet's encrypted payment data. You forward that data to Wasp unopened, so you never see a DPAN and never need to.

CVV, CVC and CCV​

The three- or four-digit security code printed on a card. Card brands give it different names — CVV, CVC, CVV2, CID — and Wasp's request field for it is ccv. Card industry rules forbid keeping it once the payment has been made, so never store it and never log it.

Cryptogram​

A one-time value generated for a single payment, proving that it came from a genuine card chip or wallet and has not been replayed. A wallet's cryptogram travels inside its encrypted payment data, which you pass to Wasp unopened. Never log or display one.

PCI DSS​

The Payment Card Industry Data Security Standard: the card industry's rules for any business that receives, sends or stores card numbers. If card numbers pass through your systems — as they do with the Direct Payment API — those systems are in scope, and meeting the standard is your responsibility. With Hosted Checkout the card is typed on Wasp's page, so it never touches yours. With Embedded Checkout your servers never receive the card number, but the customer types it into your page, so that page's security still matters — see Card entry.

Who takes part in a card payment​

Issuer​

The bank that gave the customer their card. The issuer decides whether to approve a payment, and it is the issuer that checks the cardholder during 3-D Secure. Its decision reaches you as the payment's result.

Acquirer​

The bank or payment processor that accepts card payments for a merchant and passes them through the card networks to the issuer. Wasp submits your payment to your merchant's acquirer, and the answer comes back to you as the payment's responseCode. A responseCode beginning with W is Wasp's own, and means the payment ended before it reached an acquirer.

eftpos​

Australia's domestic debit card network, alongside international networks such as Visa and Mastercard. Its cards carry their own card numbers, and in the sandbox they have their own test card.

Acquiring route​

The connection Wasp uses to send your merchant's card payments to an acquirer — for example eftpos or Visa. Stratsol sets it up for your merchant, and it decides which test card is approved in the sandbox: see Test payments.

The payment itself​

Instrument​

The means of payment the customer chose, in a normalised shape — a card, a Google Pay token, an Apple Pay token. The SDK collects it in the browser; your backend passes it on without inspecting it.

Order​

What a reference identifies: the payment and every transaction that follows it under the same reference, such as a refund or a void. A status lookup returns the whole set, oldest first. It is Wasp's grouping of related transactions, not your own record of a shopping basket — a declined payment the customer retries is a new order under a new reference.

Transaction​

The record of a payment that has actually been attempted with the bank. It is created once, at the point the payment can execute — so a payment still waiting on its customer has no transaction yet.

PreAuth and Advice​

A PreAuth authorises an amount and moves no money. An Advice completes it for the final amount: a new request under its own reference, naming the PreAuth in initialReference. A Void under the PreAuth's own reference releases it instead. Authorising now, completing later has the full rule.

Terminal​

Finished, one way or the other. An approved or declined payment is terminal; a payment waiting for its customer is not.

Payment intent​

What you asked for — amount, currency, reference, request type — before any payment has been attempted. Hosted Checkout registers an intent before the customer pays.

Waiting for the customer to authenticate​

A payment Wasp answered with a 202 whose status is authentication_required. Wasp has accepted it, and it cannot go ahead until the customer completes the authentication step at the action URL. Until then nothing has been attempted with the bank: no transaction, no money moved, nothing to reconcile. It is not a failure, and it is not something you retry.

Outcomes​

HTTP 200​

The payment is decided — approved or declined. Read the result and move on.

HTTP 202​

Wasp accepted the payment, but it cannot finish inside your request. The status field tells you which of two shapes you have:

  • status: authentication_required — the customer must authenticate. The response carries an action; send the customer's browser to its action.url.
  • status: processing — Wasp is finishing the payment without the customer. There is no action, because there is nothing to send the customer to.

Both shapes normally finish the same way: Wasp sends one signed outcome notification to your callback URL. If none has arrived by the expiresAt time given in the 202, look the payment up once by its reference — see After a 202 with no notification. Either shape can end in a decline: an authentication that fails is a final W1 decline and one nobody finishes a final W2, and that lookup is how you see either if no notification came.

Never resubmit a payment that returned 202. See Payment outcomes.

Action URL (action.url)​

Where to send the customer's browser when a 202 has the status authentication_required. It is just an address: it names no provider and carries no payment identifier. Your backend receives it in the 202's action and passes the customer to it. A processing payment has no action, so there is no action URL to follow.

Expiry (expiresAt)​

A payment Wasp answered with a 202 does not wait forever. The expiresAt value in the 202 tells your backend when it stops being actionable; after that moment the payment cannot complete. If no outcome notification has arrived by then, look the payment up once by its reference.

Authoritative result​

What Wasp tells your backend: the response to your payment request, or a signed outcome notification you have verified. A lookup by reference is authoritative too, and is how you recover a result that never reached you. A browser redirect is never proof of anything on its own.

W1​

The responseCode of a payment declined because customer authentication ran and the cardholder was not authenticated. It is final: the payment did not happen, and it is notified like any other outcome. Like every W code, it is Wasp's own and the payment never reached an acquirer. See Customer authentication.

W2​

The responseCode of a payment declined because nobody finished the customer authentication before its deadline. It is final, it is notified, and nothing was charged. It is deliberately a different code from W1: an authentication that answered no is a different fact from one that was never answered, which is what a merchant reconciling an abandoned checkout needs to know. See The customer abandons it.

Customer authentication​

3-D Secure (3DS)​

An industry scheme that lets a card issuer check the cardholder is who they claim to be, before a payment goes ahead. In practice the customer may be shown a page from their own bank — a code, an app prompt, a fingerprint. It exists to reduce fraud, and for many transactions it is required by regulation or by the card scheme. Wasp performs it for you; you do not integrate a 3DS provider.

Step-up​

Asking the customer to authenticate. "This payment stepped up" means the cardholder was required to prove who they are.

There are three ways an authentication can go, and the difference that matters to your code is whether the customer has to do anything — not whether authentication happened.

Challenge​

The issuer asked the customer to do something: a code, an app prompt, a fingerprint. The payment is answered with a 202 whose status is authentication_required, carrying an action you send the customer to.

Frictionless​

The issuer was satisfied from the payment request alone, without asking the customer anything. Authentication still happened — the customer just never noticed — and the payment is decided in your original request, as a 200.

Decoupled (background)​

The issuer resolves the authentication away from your request, but still without asking the customer anything. The payment is answered with a 202 whose status is processing, and there is no action — because there is nothing to send the customer to.

That last one is the case integrations most often get wrong. A 202 does not mean the customer has a job to do; status is what tells you whether they do. An absent action on a processing payment is correct and expected, not a fault, and not a repeat of an earlier response. A background authentication can still fail, and then the payment ends as a final W1 decline, notified like any other outcome; if no notification has arrived by expiresAt, one lookup by reference shows you. See Payment outcomes.

Requesting authentication​

On a payment your backend submits directly, you can ask Wasp to authenticate the cardholder rather than leaving it to be decided for you. It is a backend-only choice — nothing in the browser can make it.

Authentication evidence​

What a successful authentication produces, proving to the card issuer that the cardholder was verified. When Wasp performs the authentication it produces and carries this for you, and you never handle it.

If you run your own 3-D Secure and supply the resulting evidence on a payment request, those fields are defined in the Merchant API reference.

Integration surfaces​

Wasp Checkout SDK​

Browser JavaScript that collects a payment instrument inside your own page and hands it to your backend. Also called embedded checkout.

Drop-in and Headless​

Two ways the SDK can render: Drop-in arranges the payment controls for you, Headless leaves the arrangement to your page. Same payment contract either way.

Hosted Checkout​

A Wasp-hosted payment page. You redirect the customer to it, and it runs the whole payment. See Hosted Checkout.

Direct API​

Calling the Payment API from your backend with an instrument you already hold, no SDK involved.

Checkout Web Domains​

The web domains you own and authorise to run Wasp Embedded Checkout. Wasp checks the browser's origin against them, so a page on a domain you have not authorised does not receive your checkout configuration and renders no payment method. One list covers every method — Card, Google Pay and Apple Pay — because it describes your checkout, not any one method. Authorising none means Embedded Checkout is not enabled at all, rather than unrestricted. Hosted Checkout runs on a Stratsol domain, is never selected from this list, and is unaffected by it. See What Stratsol provides and what you provide.

Return profile​

A return destination configured for your merchant in advance and given a name. Hosted Checkout takes the name, and Wasp resolves the actual address on its own side. You cannot pass a URL, deliberately: a redirect target supplied in a request is a way to send your customers somewhere they should not go.

Results and reconciliation​

Outcome notification (callback)​

A signed message Wasp sends to your backend's outcome callback URL when a payment it accepted earlier reaches its result. It is signed with your key phrase: verify the signature, and the body is the answer — there is nothing to look up. See Outcome notifications.

Browser return / redirect​

The customer arriving back on your site after Hosted Checkout. A customer-experience signal only — never proof of payment.

Return outcome​

A rough indication that comes back with the customer from Hosted Checkout — broadly, whether things went well, went badly, were cancelled, or ran out of time. Use it to decide what to put on the screen. Never use it to decide what is true; for that, ask your own backend.

Reconciliation​

Catching up on payments you did not hear about — a customer who closed the tab, a notification that never arrived. See Reconciliation.

Sandbox​

Sandbox​

The test environment. Real API, real flows, no real money. Stratsol also calls it Stage, and its base URL is https://stage.api.strat-sol.biz.

Deterministic test provider​

The stand-in used for customer authentication in the sandbox. Not a real bank: it always answers the same way for the same payment, so your tests are repeatable. It cannot tell you how a real issuer will behave, and it is refused in production.

Last updated on