Integration checklist
The steps from choosing an integration to accepting your first live payment with Ginger Payments.
Use this checklist to plan your integration. Each step links to the page with the details.
Choose your integration
Decide who collects the payment details: Ginger Payments or you.
| Hosted payment page | Server-to-server | |
|---|---|---|
| Who shows the payment form | Ginger Payments. Your customer is redirected to a hosted page. | You. Your customer stays on your website or in your app. |
| Card data | Never reaches your systems. | Passes through your systems. |
| PCI DSS | Lowest impact. | You must be PCI DSS compliant. |
| Effort | Hours to days. | Weeks. You build the form, error handling and retries. |
| Payment methods | Every method active in your project, from day one. | Each method you build into your checkout. |
With the hosted payment page, a payment goes like this:
- Your customer clicks Pay in your checkout.
- Your server creates an order through the API.
- The API returns a URL to the payment page.
- You redirect your customer to that URL.
- Your customer enters their payment details on the hosted page.
- The payment completes.
- Your customer is redirected back to your website.
With server-to-server, you collect the card details in your own form and send them to the API. You get full control over the checkout, its design and its branding, in exchange for more work and more security responsibility.
Not sure?
Start with the hosted payment page. You can switch to server-to-server later without changing how you handle webhooks and order statuses.
Don't need a checkout at all? Send your customers a payment link.
Get your test API key
After onboarding, you get access to a project in test mode. Its API key authenticates your requests to the API. Find it in the merchant portal at https://admin.dev.gingerpayments.com, under Settings > API Key.
Payments in test mode run against a sandbox: you can test every flow, but no money moves. Follow the quickstart to make your first test payment.
Keep your API key secret
Only use the API key from your server. Never put it in a browser, mobile app or public repository.
Build your integration
Make sure your integration covers these basics:
- Create orders with an amount in the smallest currency unit and an ISO 4217 currency code.
- Send a
return_url, so your customer comes back to your website after paying. - Handle webhooks, and respond with a
2xxstatus within 4 seconds. - Retrieve the order from the API before you deliver. Never rely on the redirect alone. See order status.
- Base your business logic on the order status, not on the transaction status.
- Check the status of orders that aren't final after a while, in case a webhook is delayed or lost.
- Handle declines and errors. See error reasons.
Add the flows your business needs, such as pre-authorizations, refunds or recurring payments.
Test every payment flow
Test each payment method you plan to offer, and each flow you've built, before you go live. Include unhappy paths: declined payments, cancelled payments, expired orders and a webhook that fails the first time.
Use the test data for card numbers and amounts that trigger specific results.
Go live
When your tests pass:
- Make sure your live project is active, with the payment methods you need.
- Replace the test API key with the API key of the live project in your production configuration.
- Check that the webhook URL of the live project points at your production server.
- Make a small real payment and refund it, to confirm the full flow works end to end.
Support
Check the FAQ for common questions and errors, and Error reasons for why a payment was declined.