Introduction
Manage your Ginger platform from your own systems, or build your own portals on top of it, with the platform APIs.
Ginger provides platform APIs to manage your platform. Use them to build your own portals, or to integrate the platform with your existing systems. The platform APIs are for Ginger customers: the operators of a Ginger platform instance.
Your merchants use another API to accept payments, the order API. It's documented in the payment acceptance docs.
This reference has a section per API in the sidebar: what the API is for and how to use it, then each of its operations with their parameters, request body, responses and code samples. Start with API basics and Authentication, which hold for every API.
Base URL
Every platform instance has its own domain. Send the requests to the API of your instance, such as https:/, followed by the path of the endpoint. Your Ginger contact gives you the domain of your test and live instance.
The API is only available over HTTPS, with TLS 1.2 or newer.
Which API to use
| API | Use it to | Path |
|---|---|---|
| Boarding API | Create and manage your merchants and their projects, users, roles and contracts | / |
| Merchant Self-Service API | Let a merchant manage its own users, roles, projects, API keys and payment method settings | / |
| Search API | Search orders, transactions, merchants and more, and follow new orders with the Stream API | / |
| Fraud prevention rules API | Manage the Ginger fraud rules of a project | …/ |
| Gateway order API | Create orders on behalf of your merchants, signed with JWS | …/ |
| Health check | Check that the API is up and your API key works | / |
The Boarding API and the Merchant Self-Service API work on the same merchants, users, projects and roles. The Boarding API (/) is for you as the operator: it acts on any merchant and can set what merchants can't, such as base permissions, contracts and statuses. The Merchant Self-Service API (/) acts on one merchant only, within the permissions you gave it, so use it for the portals and integrations of your merchants.
Authentication
Authenticate every request with HTTP Basic authentication. For your own systems, use an admin API key: the API key of a project in your admin merchant, sent as the username with an empty password. Interactive applications, such as a portal, log a user in with an email address, a password and, when enabled, a multi-factor authentication code, and receive a temporary token that they send the same way. Permissions on the merchant, the project, the user and its roles decide which endpoints each key or token may call. See Authentication.
curl https://api.example.com/v1/merchants/self/projects/self/ \
--user "$API_KEY:"Use the reference in your tools
Generate a client in your language from the OpenAPI document, or import the Postman collection to send your first requests before you write any code. Set the apiKey variable of the collection to your API key, and domain to the domain of your platform instance.
The downloads hold every API, with the API's name in front of its operations, schemas and tags.
More APIs are on their way
The platform APIs are documented in OpenAPI one by one. An API without operations in the sidebar yet describes its endpoints on its own page.
Before you go live
Check these before your platform's first live payment. The rest of the go-live checks are in the Go-live checklist.
- You have separate admin API keys for testing and for live, kept in a secret store, never in browsers, apps or repositories, and never shared with a merchant. See API keys.
- Your admin API key leaves
DELETEoff unless your systems need it. - You know how to rotate a key: a new key revokes the old one at once.
- Your systems connect with TLS 1.2 or newer.
- You monitor the platform with the health check.
- Your own portals, if you build them, handle multi-factor authentication and the lockout after failed logins. See Log in with a username and password.
- Your systems that follow orders with the Stream API store their pointer, and their admin API key may use the stream and the Search API.
- If you create orders for your merchants with the gateway order API: your JWKS is published before you sign with a new key, and you verify the signature of every response.
Next steps
- Confirm that you can reach the API and that your key works with the health check.
- Read the conventions every API shares in API basics.