Quickstart

Get your test API keyCopy Anchor Link

1. Log in to the merchant portal at https://admin.dev.gingerpayments.com.
2. Create a project in test mode, or open an existing test project.
3. Go to Settings > API Key and copy the key.

Store the key as an environment variable on your server, so it doesn't end up in your code:

export API_KEY="your-test-api-key"

Check your connectionCopy Anchor Link

The API uses HTTP Basic authentication: your API key is the username and the password is empty. Retrieve your project to check that the key works:

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

A 200 OK response with your project details means you're connected. A 401 Unauthorized response means the API key is wrong.

Create an orderCopy Anchor Link

Create an order for € 9.95. The amount is in cents.

curl https://api.dev.gingerpayments.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "EUR",
    "amount": 995,
    "merchant_order_id": "QUICKSTART-001",
    "description": "Quickstart test order",
    "return_url": "https://www.example.com/order/QUICKSTART-001",
    "webhook_url": "https://www.example.com/webhook"
  }'

Replace the return_url and webhook_url with URLs of your own server. The API responds with the new order:

{
  "id": "1c969951-f5f1-4290-ae41-6177961fb3cb",
  "currency": "EUR",
  "amount": 995,
  "merchant_order_id": "QUICKSTART-001",
  "description": "Quickstart test order",
  "return_url": "https://www.example.com/order/QUICKSTART-001",
  "webhook_url": "https://www.example.com/webhook",
  "created": "2026-10-12T11:41:57.121017+00:00",
  "modified": "2026-10-12T11:41:57.183822+00:00",
  "order_url": "https://api.dev.gingerpayments.com/pay/1c969951-f5f1-4290-ae41-6177961fb3cb/",
  "status": "new"
}

Save the id: you need it to look up the order later.

Pay on the hosted payment pageCopy Anchor Link

Redirect your customer to the order_url. For this test, open it in your browser.

The hosted payment page shows every payment method that's active in your project. Select one and complete the payment with test details. For test card numbers, see Test data.

After the payment, the browser goes to your return_url.

Handle the webhookCopy Anchor Link

When the order status changes, Ginger Payments sends a POST request to your webhook_url:

{
  "event": "status_changed",
  "order_id": "1c969951-f5f1-4290-ae41-6177961fb3cb",
  "project_id": "b5f39273-44e7-4385-8e08-44612ef3e117"
}

The webhook deliberately doesn't contain the status. See Webhooks for the full delivery rules. Retrieve the order from the API, so you only act on data that comes from Ginger Payments directly:

import express from 'express';

const app = express();
app.use(express.json());

const authorization = `Basic ${Buffer.from(`${process.env.API_KEY}:`).toString('base64')}`;

app.post('/webhook', async (req, res) => {
  try {
    const response = await fetch(`https://api.dev.gingerpayments.com/v1/orders/${req.body.order_id}/`, {
      headers: { Authorization: authorization },
    });
    if (!response.ok) throw new Error(`Status request failed: ${response.status}`);

    const order = await response.json();
    await updateOrderInYourShop(order.merchant_order_id, order.status);
    res.sendStatus(200);
  } catch (error) {
    console.error(error);
    res.sendStatus(500); // Ginger Payments retries the webhook
  }
});

app.listen(3000);

updateOrderInYourShop and update_order_in_your_shop stand for your own code that stores the status.

Keep these rules in mind:

• Respond fast. Return a 2xx response within 4 seconds. Any other response, or a timeout, counts as a failure.
• Expect retries. After a failure, Ginger Payments retries every 2 minutes, up to 10 attempts. Your handler can receive the same notification more than once, so make it safe to process twice.
• Have a backup. A webhook can be delayed or lost. Regularly check the status of orders that aren't final after 10 minutes, or a period that suits your business.
• Allow the traffic. If a firewall or bot protection runs in front of your server, make sure it doesn't block webhook requests.

Check the statusCopy Anchor Link

Retrieve the order to see the result of the payment. Do the same when your customer lands on your return_url:

curl https://api.dev.gingerpayments.com/v1/orders/1c969951-f5f1-4290-ae41-6177961fb3cb/ \
  --user "$API_KEY:"

{
  "id": "1c969951-f5f1-4290-ae41-6177961fb3cb",
  "amount": 995,
  "currency": "EUR",
  "merchant_order_id": "QUICKSTART-001",
  "status": "completed",
  "completed": "2026-10-12T11:43:12.402150+00:00",
  "transactions": [
    {
      "id": "058cf70d-7a84-4957-941c-532c065cef72",
      "payment_method": "credit-card",
      "status": "completed"
    }
  ]
}

The response is shortened. Act on the order status: