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 (/),
within the permissions you give them.
Base path and authentication
All operations are under / on the API domain of your platform, such as
https:/.
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
| Resource | Path | What it is |
|---|---|---|
| Merchants | / | The businesses on your platform: company details, base permissions, tags, status |
| Users | / | People who log in to the Merchant portal |
| Roles | / | Bundles of permissions you give to users |
| Projects | / | The webshops and apps of a merchant, each with its API key, payment method settings and hosted payment page style |
| Contracts | .../ on a merchant or project | The processor terms of a payment method. See Processor contracts |
| Hosted payment page images | .../ | Logo and background of the hosted payment page |
| Payout entities | / | Payout configurations: schedule, bank account, price plan, adjustments, reserves |
| Platform settings | / | Platform-wide integrations, such as the fraud prevention providers |
How requests behave
- Updates merge. A
PUTon a merchant or a contract merges the fields you send into the stored object. A merchant update needscompany_. A project update needsname trade_,name description,website_andurl 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,statusand the company details of a merchant, can only be changed with the Boarding API. The Merchant Self-Service API ignores them. - Delete is soft.
DELETEon a merchant, project or user sets its status toinactive. - Ended merchants are frozen. Nothing of a merchant with status
endedcan be changed.
Example: board a merchant
The full walk-through is in Board a merchant. In short:
- Create the merchant with its base permissions.
- Create a role and a user with that role.
- Create a test and a live project.
- Add the contracts to the live project.
- Create a payout entity, if you pay out with Ginger Payout.
- 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.