Skip to main content

Connect to an Existing Backend

Dependencies

Build a New App With Payments or Add Payments to an Existing App - the builder must be run first so that you can choose how to handle the backend.

Example prompts

"Connect this app to the backend running at http://localhost:8000"

"App uses a backend with specs @openapi.json." - see how this one is used below

If you already run a server that opens Nuvei orders, the builder can point the app at it instead of creating a new one. You give it the base URL - the address your backend answers on, such as http://localhost:8000 or https://api.example.com.

How the builder checks your backend​

The app needs one thing from your backend: an endpoint that opens an order and returns a sessionToken. Before wiring anything, the builder checks that this endpoint exists.

It does this by reading your backend's API description - a JSON file that lists every endpoint the service has, what you send to it, and what it sends back. Most web frameworks generate this file for you and publish it at an address like /openapi.json or /swagger.json. You may know it as an OpenAPI or Swagger document; they are the same kind of file, and the builder accepts either. If you have never set one up, that is fine - see When there is no description below.

Reading the description is all the builder does. It only sends GET requests, and only to documentation addresses - never to a payment endpoint. It cannot accidentally open a real order against your live service.

What the builder reports​

  • Endpoint found - Your backend has the endpoint the app needs. The builder asks whether to connect the app to it.
  • No endpoint - The backend answers, but its description does not list the endpoint. The builder offers to create a sample backend instead.
  • No description - The backend answers, but the builder cannot find a description file, so it cannot confirm the endpoint. See below.
  • Unreachable - The builder cannot connect to the URL at all. It asks whether the backend is simply not running right now. If you confirm it exists, the builder continues.

If the endpoint is missing, or returns data in a shape the app cannot read, the builder tells you before connecting anything. The app still builds and launches, but real payments will not work until the endpoint is there. The builder says so clearly in its result.

When there is no description​

You have three options, and the builder offers all of them:

  1. Give it the file. If your backend has a description file somewhere - exported, or checked into the repo - drop it in your project folder and mention it in the prompt: "App uses a backend with specs @openapi.json." The builder reads it from disk, so your backend does not even have to be running.
  2. Name the endpoint yourself. Tell the builder the path, for example /openOrder. It continues and wires the app, but it will tell you the endpoint was never verified.
  3. Use a sample backend instead of your own.

Example description file​

For a full description file the builder accepts, and what makes it usable, see Examples.