Skip to content

Boarding API

Create and manage merchants, users, roles, projects, contracts and payout configurations on your platform, under /v1/admin.

The Boarding API is what the Admin portal does, as an API: you create merchants and everything they need to take payments, from your own onboarding or CRM system. It works on any merchant of your platform.

Use the Boarding API for the operator's tasks, such as setting contracts, base permissions and payouts. Merchants manage their own users, roles and projects with the Merchant Self-Service API (/v1/merchants), within the permissions you give them.

Base path and authentication

All operations are under /v1/admin on the API domain of your platform, such as https://api.example.com/v1/admin/merchants/.

Authenticate with an admin API key with HTTP Basic authentication: the key as the username and an empty password.

curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/ \
  --user "$API_KEY:"

What an admin key may do depends on its permissions.

Resources

ResourcePathWhat it is
Merchants/v1/admin/merchants/The businesses on your platform: company details, base permissions, tags, status
Users/v1/admin/merchants/{merchant_id}/users/People who log in to the Merchant portal
Roles/v1/admin/merchants/{merchant_id}/roles/Bundles of permissions you give to users
Projects/v1/admin/merchants/{merchant_id}/projects/The webshops and apps of a merchant, each with its API key, payment method settings and hosted payment page style
Contracts.../contracts/{contract}/ on a merchant or projectThe processor terms of a payment method. See Processor contracts
Hosted payment page images.../projects/{project_id}/hpp-uploads/Logo and background of the hosted payment page
Payout entities/v1/admin/payouts/payout-entities/Payout configurations: schedule, bank account, price plan, adjustments, reserves
Platform settings/v1/admin/platform-settings/Platform-wide integrations, such as the fraud prevention providers

How requests behave

  • Updates merge. A PUT on a merchant or a contract merges the fields you send into the stored object. A merchant update needs company_name. A project update needs trade_name, description, website_url and status.
  • Unknown fields are dropped. Fields that aren't in the schema are removed from the request, not rejected.
  • Admin-only fields. Some fields, such as base_permissions, contracts, status and the company details of a merchant, can only be changed with the Boarding API. The Merchant Self-Service API ignores them.
  • Delete is soft. DELETE on a merchant, project or user sets its status to inactive.
  • Ended merchants are frozen. Nothing of a merchant with status ended can be changed.

Example: board a merchant

The full walk-through is in Board a merchant. In short:

  1. Create the merchant with its base permissions.
  2. Create a role and a user with that role.
  3. Create a test and a live project.
  4. Add the contracts to the live project.
  5. Create a payout entity, if you pay out with Ginger Payout.
  6. Set the merchant to active.

For example, create a project:

curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "trade_name": "Acme Coffee",
    "description": "Acme Coffee webshop",
    "status": "active-production",
    "website_url": "https://www.example.com/"
  }'

The API responds with 201 Created and the project, with its id and its apikey for the Order API. See Create a project in the API reference.

Errors

The Boarding API returns the errors of every platform API: see Errors. The payout endpoints also answer with 409 Conflict and 422 Unprocessable Entity; the reference lists them per operation.

API reference

The fields of every object are in the Boarding API reference.