The big picture (read first)

The big picture (read first)

Woosa Payments sits between your shop and Adyen (the actual payment processor). You never talk to Adyen directly. You talk to a Woosa server called the Midlayer, and the Midlayer talks to Adyen for you.

Environments: you will do setup twice

There are two completely separate midlayer environments:
Environment
Base URL
Money
Development
https://midlayer-dev.woosa.nl
Test only
Production
https://midlayer.woosa.nl
Real
These are not two modes of one account. They are two independent accounts. Everything in the setup section of this guide is performed once against development and then again against production. A development secret will not produce a valid signature against production, and vice versa.
Build and test everything against development first. Only register against production once you have watched real test payments succeed end to end.

What is separate, and what is shared

Title
Development
Production
Shop registration (POST /woocommerce/shops)
Done separately
Done separately
woosa_secret
Its own
Its own
Legal entity / contractor
A dummy entity you create for testing
The merchant's real legal entity
Store and store_id
Its own
Its own
Onboarding / KYC
Adyen's test environment accepts the dummy entity without real documents
Genuine KYC, the merchant provides real identity and business documents
Active payment methods
Configured separately
Must be configured again, this does not carry over
Your three callback endpoints
Shared, the same endpoints serve both
Shared, the same endpoints serve both
Your integration code
Shared, only the base URL and secret differ
Shared, only the base URL and secret differ
The last two rows are the reason this is manageable. You write the callback endpoints once and the payment code once. What changes between environments is configuration, not code: the base URL you call and the secret you sign with.

Important clarification

Here is the part that trips people up, so let us be clear about it up front. The connection works in two directions:
    You call WoosaMost of the time your shop sends requests to the Midlayer: "create a payment", "refund this", "list my stores". This is the normal, outbound direction.
    Woosa calls youDuring setup, the Midlayer calls back to your shop to check your credentials and to hand you a secret key. Your shop has to expose a few small endpoints that the Midlayer can reach.
That second direction is the whole reason a non-WooCommerce integration takes a little extra work. A WooCommerce shop already exposes these endpoints out of the box. Yours does not yet, so you should build them first. How to do that is described in  ⁠⁠Endpoints your shop must expose⁠ .
A useful way to picture the full journey:
[ PREP ] Build 3 small endpoints on your shop that Woosa can call back to.
|
[ REGISTER ]  Tell Woosa your shop exists. Woosa calls you back and gives you a secret key.
|
[ SIGN ] From now on, every request you send should be "signed" with that secret key.
|
[ CONNECT ] Create or link your existing Woosa Payments UI account (email + verification code).
|
[ SET UP ] Pick your legal entity, create a store, complete onboarding (ID checks).
|
[ CONFIGURE ] Choose which payment methods (iDEAL, cards, Klarna, etc.) are active.
|
[ TEST ] On the dev environment, run real test payments end-to-end.
|
[ GO LIVE ] Onboard the real legal entity in production and switch the base URL.
|
[ TAKE MONEY ] Create payments, handle any extra shopper steps, capture, refund.
We will walk through each block in order.