Skip to content

Gateway order API

Create orders for several merchants and projects with one API key, with JWS-signed requests and responses.

The gateway order API creates and retrieves orders for any project you have access to, with a single API key. Use it when your own system sits between your merchants and Ginger, such as a payment gateway or a platform that integrates many merchants. On top of the API key, it can require a JSON Web Signature (JWS) on every request, and it signs its responses.

Your merchants don't need this API. A merchant accepts payments with the order API of its own project, documented in the payment acceptance docs.

When to use it

Order APIGateway order API
Path/v1/orders//v1/merchants/{merchant_id}/projects/{project_id}/orders/{order_id}/
API keyOne per projectOne for all the projects it may access
Order IDChosen by GingerChosen by you, a UUID
Request signingNoJWS, if your platform requires it

The order itself is the same: the same fields, payment methods, statuses and flows as in the order API reference.

Before you begin

  • An API key with access to the merchants and projects you create orders for. See Authentication and Permissions.
  • For signed requests: an ES256 key pair, and a public URL where you publish your public keys. See Publish your keys.

Create an order

Choose the order ID yourself, as a UUID, and send a PUT with the order to the path of the project:

curl https://api.example.com/v1/merchants/$MERCHANT_ID/projects/$PROJECT_ID/orders/$ORDER_ID/ \
  --user "$API_KEY:" \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "x-jws-signature: $JWS" \
  --data '{
    "currency": "EUR",
    "amount": 2995,
    "transactions": [{ "payment_method": "credit-card" }]
  }'

$JWS is the signature of the body, see Sign the request. The response is the order, as in the order API. See Create a gateway order in the API reference.

Retrieve the order later with a GET on the same path. Create a refund of an order with a PUT to /v1/merchants/{merchant_id}/projects/{project_id}/refunds/{refund_id}/, also with an ID you choose.

Sign the request

When your platform requires signed requests, every request to the gateway order API carries a JWS in the x-jws-signature header. The signature covers the exact bytes of the request body.

Create the JWS with:

  • The algorithm ES256: ECDSA with the P-256 curve and SHA-256. Ginger accepts no other algorithm.
  • A detached, unencoded payload (RFC 7797): the protected header holds "b64": false and "crit": ["b64"]. The signing input is the base64url-encoded header, a dot and the raw request body.
  • The kid of the key you signed with, in the header.
  • The compact form without the payload: <header>..<signature>.

For a GET, the body is empty: sign an empty payload.

Use a JOSE library

Most JOSE libraries create detached, unencoded JWS. For example, in Python with PyJWT: jwt.api_jws.PyJWS().encode(body, private_key, "ES256", is_payload_detached=True, headers={"kid": kid}). Check that the protected header your library creates holds "b64": false and "crit": ["b64"].

Ginger checks the signature against the public keys you publish. The response tells you the result in the x-jws-feedback header: Valid signature, Missing required signature or Invalid signature provided. When your platform enforces signatures, a request without a valid signature is refused with 401 Unauthorized. When it only reports, the request is processed, and x-jws-feedback tells you what would have failed.

Publish your keys

Publish your public keys as a JSON Web Key Set (JWKS) on a public HTTPS URL. Your Ginger contact sets up the URL for your platform.

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "alg": "ES256",
      "use": "sig",
      "kid": "20261103-acme",
      "x": "<base64url x coordinate>",
      "y": "<base64url y coordinate>"
    }
  ]
}

Ginger tries every key in the set, so you can publish more than one.

Rotate your keys

Rotate your keys at an interval that suits your compliance rules:

  1. Add the new public key to the key set, next to the current one.
  2. Wait at least 30 minutes. Ginger caches your key set, and a key used earlier may be rejected.
  3. Sign with the new key.
  4. Remove the old key once no requests signed with it are underway.

Keep the private key on your servers

Anyone with your private key and your API key can create orders in your name. Store it like the API key: never in a browser, an app or a repository.

Verify the response

When your platform signs responses, Ginger signs them in the same way: a detached, unencoded ES256 JWS of the response body, in the x-jws-signature header of the response. Ask your Ginger contact whether yours does. Verify it with the public keys Ginger publishes on your platform:

curl https://api.example.com/.well-known/jwks.json

See Get Ginger's public keys in the API reference.

Pick the key with the kid from the JWS header. Ginger signs with the newest key that has been published for at least an hour, so you can cache the key set: fetch it again when you see a kid you don't know.

API reference

See Create a gateway order and the order API reference for the fields of the order.