API basics

Connect securelyCopy Anchor Link

The API is only available over HTTPS with TLS 1.2 or newer. This protects your customers' data on its way between your server and Ginger Payments.

Most modern HTTP clients support TLS 1.2 by default. If you use an old library or an old version of a programming language, update it.

All requests go to https://api.dev.gingerpayments.com, followed by the path of the endpoint, such as /v1/orders/. Card data for server-to-server payments goes to the card vault at https://tokens.dev.gingerpayments.com.

AuthenticateCopy Anchor Link

Authenticate every request with HTTP Basic authentication. Your project's API key is the username, and the password is empty.

Most HTTP clients handle Basic authentication for you. With cURL:

curl https://api.dev.gingerpayments.com/v1/merchants/self/projects/self/ \
  --user "$API_KEY:"

If your client doesn't support Basic authentication, build the Authorization header yourself: encode your API key followed by a colon (:) with Base64. For the API key hunter2, you encode hunter2:, which results in this header:

Authorization: Basic aHVudGVyMjo=

HTTP status codesCopy Anchor Link

The API uses standard HTTP status codes.

Handle 2xx responsesCopy Anchor Link

A 2xx response means Ginger Payments received and accepted your request. It doesn't mean the payment succeeded: check the status in the response.

For example, when you start a card payment:

1. The API responds with 200 OK or 201 Created. Ginger Payments has your request and processes the payment, but the outcome isn't known yet.
2. The card issuer declines the card. No money is collected.
3. Ginger Payments sends a webhook because the order status changed.
4. You retrieve the order. The status is error, and the reason field briefly explains why. See Error reasons.

Handle 4xx and 5xx responsesCopy Anchor Link

Ginger Payments doesn't accept or store your request when:

• the request doesn't pass validation;
• the request violates a security constraint;
• the request violates a configuration constraint, such as a payment method that isn't active for your project;
• an internal error occurs at Ginger Payments.

You receive an error response that describes the problem. Handle it as an exception in your code. Rejected requests aren't charged.

Error responseCopy Anchor Link

An error response contains an error object:

{
  "error": {
    "status": 400,
    "type": "RefundError",
    "value": "Cannot refund more (500) than the remaining order amount (0)"
  }
}

Common error types: