Start here (for AI agents)

This tab covers v2, beta. Follow the steps in order. When a step says stop, stop and ask the person you work for.

1. Check that v2 is the right version

v2 hosts do not serve traffic yet. Build on v2 only if the person asked for it explicitly: for planning, a prototype, or code against a mock. For an integration that must work today, switch the version selector to v1 and follow its agent pages.

2. Get the inputs before writing code

Do not start without them. Do not invent keys, hosts or test data.

Direction	Ask for
Payin	A sandbox key of a payin shop (psbox_…), its webhook signing secret, the methods enabled for the shop
Payout	A sandbox key of a payout shop (psbox_…), its webhook signing secret

Both directions mean two shops and two keys. Terms — Glossary.

3. Read exactly this

1. The page of your method. It is self-contained: endpoints, request, response, payer step, statuses, decline reasons, errors, webhooks.
2. Integration rules — R1…R20, the whole contract in one page. For a method with a payer step also Payer actions.
3. Sandbox — how to force each outcome.
4. Integration flow — the steps of a complete integration.

Task	Method page	Operations
Card payin	Card	createCardPayin, retrieveTransaction, createRefund; hold: capturePayin, voidPayin
Card payin on the payment form	Hosted payment form	createPaySession, listTransactions, retrieveTransaction
Apple Pay payin	Apple Pay	createApplePaySession, createApplePayPayin, retrieveTransaction, createRefund
Google Pay payin	Google Pay	createGooglePayPayin, retrieveTransaction, createRefund
BLIK payin	BLIK	createBlikPayin, retrieveTransaction
Card payout	Card payout	createCardPayout, retrieveTransaction, listBalances
Reconciliation	Transactions	listTransactions
Testing	Sandbox	advanceTestTransaction, sendTestWebhook

Load the operations from /v2/api-reference/openapi.json by operationId. Use its extensions instead of guessing:

Extension	Answers
x-shop-type	Which shop's key an endpoint accepts
x-status-transitions	Every status transition of a method
x-terminal-values	Which statuses are final
x-enumDescriptions	What each status, error code and reason means
x-extensible-enums	Enums grow without a new version — R13
x-retryable-codes	Which error codes may be retried
x-retry-policy, x-signature-tolerance-seconds	Webhook timeout, redeliveries, timestamp window
x-test-amounts	Sandbox amounts that force each outcome
x-availability	Endpoints and fields that are not supported yet
x-availability-by-method	Which methods an endpoint does not support yet
x-test-fixtures	Sandbox card numbers, BLIK codes, Apple Pay and Google Pay tokens

4. Build, then prove it in the sandbox

Build in the order of the integration flow, then run every item of the integration checklist against the sandbox.

5. Stop and ask when

• A key or the webhook signing secret is missing.
• A page and the OpenAPI document disagree on a field, path or status. Follow the OpenAPI document and report the difference.
• The task needs something marked not supported yet: BLIK refunds, partial capture. Such calls return 501 not_supported_yet.
• The task needs a method or direction v2 does not have: payouts other than to a card.
• The task sends raw card numbers and nobody has confirmed PCI DSS scope.

Machine-readable entry points

All paths are on https://payments-docs.mercuryo.io.

Resource	Path	What it is
Index	/llms.txt	Every page, titled and linked.
Full text	/llms-full.txt	All documentation as one plain-text file.
Any page as Markdown	its path + /index.md	e.g. /v2/agents/rules/index.md
v2 OpenAPI	/v2/api-reference/openapi.json	The whole contract, with webhooks. .yaml serves the same document.
Docs MCP	/mcp	Search this documentation. Not enabled yet; use /llms.txt and /llms-full.txt.