Start here (for AI agents)

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

v2 is a beta contract whose hosts do not serve traffic. Build on v2 only if the person asked for it explicitly; it has its own agent pages in the v2 version of this site.

1. Pick the contract

Task	Contract
Apple Pay or Google Pay pay-in, their refunds	Apple Pay and Google Pay
Bank card pay-in, hold, refund	Card payments
Payout to a card	Payouts

The three contracts share nothing: credentials, signature, format and statuses all differ. See Which contract to use.

2. Get the inputs before writing code

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

Contract	Ask for
Apple Pay and Google Pay	service_id and secret for Sdk-Partner-Token, the Sign Key, the callback URL configured with the integration manager
Card payments	api_key, secret_key, the callback URL
Payouts	service_id, secret_key, the callback URL

Also ask which environment, and whether the server IPs are allow-listed. Credentials of one contract do not work on another.

3. Read exactly this

Read the pages, then load the operations from /api-reference/openapi.json by operationId.

Task	Pages	Operations
Apple Pay pay-in	Authentication, Apple Pay, Statuses, Webhooks	postSdkPartnerAlternativeMobilePayValidateMerchant, postSdkPartnerAlternativeMobilePayMobilePay, getSdkPartnerAlternativeMobilePayMobilePayIdStatus
Google Pay pay-in	Authentication, Google Pay, Statuses, Webhooks	postSdkPartnerAlternativeMobilePayMobilePay, getSdkPartnerAlternativeMobilePayMobilePayIdStatus
Apple Pay or Google Pay refund	Refunds	postSdkPartnerAlternativeMobilePayRefund
Card pay-in	Card payments guide, Card statuses	postPayDirect, postPayOrderStatus; hold: postPayComplete, postPayVoid
Card refund	Card refunds	postPayRefund
Card payout	Authentication, Integration flow, Statuses, Webhooks	postPartnerServiceIdPayout, postPartnerServiceIdCheck, postPartnerServiceIdBalance

Then read your contract's section in Integration rules and Common pitfalls.

4. Build in this order

1. Take the host from the servers of each operation, not from memory or another contract.
2. Implement the contract's signature exactly as its authentication page shows. Check it against the page's example before the first call.
3. Generate your reference and save it before the create call: merchant_transaction_id (Apple Pay, Google Pay), reference (card), id (payout). Never change the body under a used reference.
4. Create, then handle the intermediate statuses from the contract's statuses page, including the redirect step: Apple Pay and Google Pay — redirect_data.url, card 8.
5. Callback handler: verify the signature, process idempotently, then re-read the status before releasing goods.
6. On a timeout, resend the same request with the same reference. Read a payout's OK as "accepted", not "paid".
7. Run the integration checklist: the common block and your contract's block.

5. Stop and ask when

• A credential or the callback URL 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 a method v1 does not document, for example BLIK.

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. /agents/rules/index.md
v1 OpenAPI	/api-reference/openapi.json	All three contracts, tags Apple Pay and Google Pay, Card payments, Payouts. .yaml serves the same document.
Docs MCP	/mcp	Search this documentation. Not enabled yet; use /llms.txt and /llms-full.txt.