Skip to content

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/json. File uploads, such as the images of the hosted payment page, send the file as the request body with its own content type.
  • Most paths end with a slash, such as /v1/admin/merchants/.
  • The IDs of merchants, projects, users, roles and orders are UUIDs.
  • self in 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": ""
  }
}
StatusMeaning
400The request doesn't match the schema. property_path names the field. Logins also use 400, with an error.type per cause: see Log in with a username and password
401The credentials are missing, unknown or expired, or the project, user or merchant isn't active. See Authentication
403The credentials are valid, but their permissions don't allow the request, or the merchant's status doesn't allow the change
404The object doesn't exist
409The request conflicts with the current state, such as a payout entity that already has this status
422The 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_after to go through large result sets. The Stream API follows changes with a pointer instead of pages.

Next steps