API basics
What every platform API has in common: environments, requests, errors and paging.
The platform APIs share the same conventions. This page lists them once; the page of each API adds what's specific to it. For the base URL and authentication, see the introduction and Authentication.
Test and live
Projects in test mode and live projects can run on the same platform and the same API: the API key decides. A request
with the API key of a project in active-testing creates test orders, flagged is-test. Ask your Ginger contact whether
you also have a separate test instance. See Take a test payment.
Requests
- Send and receive JSON, with
Content-Type: application/. File uploads, such as the images of the hosted payment page, send the file as the request body with its own content type.json - Most paths end with a slash, such as
/.v1/ admin/ merchants/ - The IDs of merchants, projects, users, roles and orders are UUIDs.
selfin a path stands for the merchant, project or user of the caller, such as/.v1/ merchants/ self/ - Amounts are in the smallest currency unit, currencies in ISO 4217 and countries in ISO 3166-1 alpha-2.
Errors
Most errors come back as JSON with the HTTP status:
{
"error": {
"status": 400,
"type": "ValidationError",
"value": "'active-live' is not one of ['inactive', 'active-testing', 'active-production']",
"property_path": "status",
"property_description": ""
}
}| Status | Meaning |
|---|---|
400 | The request doesn't match the schema. property_ names the field. Logins also use 400, with an error.type per cause: see Log in with a username and password |
401 | The credentials are missing, unknown or expired, or the project, user or merchant isn't active. See Authentication |
403 | The credentials are valid, but their permissions don't allow the request, or the merchant's status doesn't allow the change |
404 | The object doesn't exist |
409 | The request conflicts with the current state, such as a payout entity that already has this status |
422 | The payout service rejected the request, such as a malformed price plan or an invalid IBAN |
Each API's reference lists the errors of each operation.
Paging
Searches return results a page at a time. The Search API pages with start and size
for the first results, and with search_ to go through large result sets. The Stream API
follows changes with a pointer instead of pages.