Workflow

The MCP server gives the agent a set of tools, and those tools are meant to be called in a particular order - each one depends on what the previous one established.

This page describes that order. You do not have to follow it yourself. You describe what you want in plain language; the agent picks the tools and works through the steps. This page is here so you can recognize where you are when the agent tells you what it just did, and so nothing that happens to your project is a surprise.

However you start - a new app, an app you already have, a change to an app that already takes payments - the work follows the same arc:

init
↓
save the design
↓
install the guides
↓
settle the backend
↓
wire the payment
↓
set up the toolchain
↓
build
↓
launch
↓
make a real test payment

The steps

1. init

Always first, in every session. The builder looks at your project folder before it asks you anything - it is scan-first, so what is already on disk decides the rest of the flow. Then it interviews you about whatever is still undecided.

What the scan finds	What happens
An app, no Nuvei yet	The interview is about the payment only. Your app is not redesigned.
An app that already has Nuvei	The interview is about changing it. Only modules you don't already have are offered.
An empty folder	The interview is about the app you want to build, then the payment.

2. Save the design

The answers from the interview are written to a small file inside your project (.nuvei/spec.json). This is the specification of your project: which platform, which payment methods, which currency, how the backend is handled, and so on.

Two reasons this step exists:

• Every later tool reads it. The backend, the payment code, and the app shell are all generated from this one description, so they cannot drift apart.
• It survives between sessions. If you close your editor and come back tomorrow, init finds this file and resumes from it instead of interviewing you all over again.

It never contains account details. A specification that names a secret key or a merchant id is rejected outright - see Store Nuvei Credentials Securely.

3. Install the guides

The builder writes Nuvei's integration rules and API reference into your project, in the format your agent reads (.agents/). This is what keeps the generated code aligned with Nuvei's own documentation rather than with the agent's guesswork. See Generate Payment Code That Follows Nuvei's Documentation.

4. Settle the backend

Opening a payment order needs your merchant secret key, so it can never happen inside the app. That call lives on a server. This step decides which server:

• Spin up a test backend - the builder writes and runs a working example backend for you, and this is also where your credentials get stored and injected.
• Connect to an existing backend - you already run one, and the builder checks it exposes what the app needs.
• Deferred - you will implement the endpoint later. Everything else still gets built, and the builder keeps reminding you what is missing.

5. Wire the payment

The builder writes the Nuvei layer into your app: the SDK dependency, the checkout code, and the platform permissions the SDK needs. It only adds - it never overwrites your own screens or source files. For a brand-new app, it first lays down a bare build foundation for the agent to build your app on.

Anything it deliberately leaves to you comes back as a checklist, and a separate check confirms the wiring is complete before you spend time on a build. See Verify the Integration Before Building.

6. Set up the toolchain

The builder checks the tools needed to compile your app - the JDK, Android SDK, and an emulator, or Xcode on macOS - and installs what is missing. See Install the Required Development Tools.

7. Build

The app is compiled. If it fails, the builder reports what broke rather than moving on.

8. Launch

The app is installed and started on an emulator or a real device, and the builder confirms the app can actually reach its backend. See Build and Launch the App.

9. Make a real test payment

Android only, for now

This step is implemented for Android only. iOS support is planned; until it lands, the payment is handed back to you to run by hand on iOS.

The last step in every flow, on Android. The builder works out how to reach your payment screen, then drives an actual payment through the running app with a sandbox test card and reads the gateway's answer, so you end with proof that the whole chain works - not just that the app compiled. See Run an End-to-End Test Payment.