Overview
Accept online payments with Ginger Payments through one API, from a hosted checkout to a fully custom integration.
Ginger Payments Payment Acceptance lets you accept online payments in your webshop, app or platform. You connect once to the Ginger Payments API and offer a variety of payment methods to your customers.
Quickstart
Create a test payment in about 10 minutes.
Integration checklist
Everything to do between your first test payment and going live.
Hosted payment page
The fastest way to accept every payment method.
Webhooks
Get notified when the status of an order changes.
How a payment works
Every online payment follows the same flow, whichever integration you choose.
Create an order
Your server sends the amount, currency and a return_url to the API. The API responds with an order and a URL to the payment page.
Your customer pays
You redirect your customer to the payment page. They select a payment method and complete the payment, including any authentication such as 3-D Secure.
Your customer returns
After the payment, your customer is redirected to your return_url.
You receive a webhook
Ginger Payments notifies your server every time the order status changes. The notification contains the order ID, not the status.
You check the status and deliver
Your server retrieves the order from the API. When the status is completed, you deliver the goods or service.
Key concepts
| Concept | What it is |
|---|---|
| Merchant | Your company, as registered with Ginger Payments. A merchant has one or more projects. |
| Project | One website, app or sales channel. Each project has its own API key, webhook URL and settings, and is either in test mode or live mode. |
| Order | What your customer pays for: an amount, a currency and a description. The order status tells you whether you've been paid. |
| Transaction | A payment attempt for an order with a specific payment method. An order can have several transactions, for example when the first attempt fails. |
| Webhook | A POST request from Ginger Payments to your server whenever the status of an order changes. |
All amounts are in the smallest unit of the currency (cents for EUR): send 1295 for € 12.95. Currencies use ISO 4217 codes, such as EUR, SEK or NOK.
Order statuses
Base your business logic on the order status, not on the transaction status. See Order and transaction status for every status and how to keep it up to date.
| Status | Meaning | Final |
|---|---|---|
new | The order has been created. | No |
processing | A payment is in progress. | No |
completed | The payment succeeded. You can deliver. | Yes |
cancelled | The payment was cancelled. | Yes |
expired | The customer didn't pay in time. | Yes |
error | The payment failed for technical reasons or was declined. | Yes |
Test mode and live mode
Every project is either in test mode or live mode, and uses the same API URL in both. In test mode, payments run against a sandbox: no money moves and you can't be charged. You can keep a project in test mode permanently, for example for your acceptance environment.
Use a separate project for each environment, so test payments never mix with real ones.
Choose your integration
| Integration | Best for | Your effort | Checkout control | PCI DSS impact |
|---|---|---|---|---|
| Hosted payment page | Getting started fast with every payment method | Low | Ginger Payments-hosted page, your customer is redirected | Lowest: card data never reaches your systems |
| Server-to-server | Letting customers select the payment method in your own checkout, including your own card form | Medium to high | Full | Higher: you're responsible for how card data is handled |
| Payment links | Invoices, email, chat and phone sales without a webshop | None | Ginger Payments-hosted page | Lowest |
| Plugins | Webshops on platforms such as WooCommerce | Low | Plugin settings | Usually lowest: most plugins use the hosted payment page |
Not sure? Start with the hosted payment page. You can move to a server-to-server integration later without changing how you handle webhooks and order statuses.
Payment methods
| Type | Payment methods |
|---|---|
| Cards | Visa, Mastercard, Maestro, American Express |
| Wallets | Apple Pay, Google Pay, PayPal |
| Bank and account-to-account | SEPA Direct Debit, Bancontact, Swish, Vipps MobilePay |
| Buy now, pay later | Billink |
See Payment methods for the operations each method supports. Which payment methods are active for your account depends on your agreement with Ginger Payments.
Platforms and software vendors
If you build software that many merchants use, such as a marketplace, booking system or e-commerce platform, you can onboard merchants and manage their projects through the API. This needs a platform account.
Security
- The API is only available over HTTPS with TLS 1.2 or newer.
- Every request authenticates with your project's API key using HTTP Basic authentication. See API basics.
- Keep your API key on your server. Never put it in a browser, mobile app or public repository.