Server-to-server
Collect card details in your own checkout and send them to the Ginger Payments API from your server.
With a server-to-server integration, your customers enter their card details in your own checkout form. Your server sends them to the Ginger Payments API. You control the full checkout experience, and your customers never leave your website.
PCI DSS compliance required
Card data passes through your systems, so you must be PCI DSS compliant to store, process or transmit it. Not compliant, or not sure? Use the hosted payment page instead.
How it works
A card payment takes three requests:
| Step | Request | Result |
|---|---|---|
| 1 | POST https://api.dev.gingerpayments.com/v1/orders/ | An order with a transaction and a setup_token. |
| 2 | POST https://tokens.dev.gingerpayments.com/v1/cards/ | The card details are stored in the vault. You get a vault_token. |
| 3 | POST https://api.dev.gingerpayments.com/v1/orders/{order_id}/transactions/{transaction_id}/authenticate/ | A redirect_url for 3-D Secure authentication. |
After step 3, you redirect your customer to the redirect_url to authenticate with their bank. Your customer then returns to your return_url, and you check the result.
Create an order
Create an order with one transaction for the credit-card payment method:
curl https://api.dev.gingerpayments.com/v1/orders/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"currency": "GBP",
"amount": 995,
"merchant_order_id": "EXAMPLE001",
"description": "Example card order",
"return_url": "https://www.example.com/order/EXAMPLE001",
"webhook_url": "https://www.example.com/webhook",
"transactions": [
{
"payment_method": "credit-card"
}
],
"customer": {
"merchant_customer_id": "123456789",
"email_address": "user@example.com",
"first_name": "John",
"last_name": "Smith",
"address_type": "billing",
"address": "100 Main Street",
"postal_code": "SW1A 1AA",
"city": "London",
"country": "GB",
"locale": "en-GB",
"phone_numbers": ["+441234566788"],
"ip_address": "192.0.2.1"
}
}'The response contains the order and its transaction. The response is shortened:
{
"id": "8078d78f-8700-4cfe-94b1-4a777d3400f2",
"amount": 995,
"currency": "GBP",
"merchant_order_id": "EXAMPLE001",
"status": "new",
"transactions": [
{
"id": "a5dac3de-d304-4570-922b-373d478b8b3a",
"amount": 995,
"currency": "GBP",
"payment_method": "credit-card",
"payment_method_details": {
"setup_token": "87f05a5d-1755-48c7-8161-f8a9544e56bf"
},
"status": "new"
}
]
}Save the order id, the transaction id and the setup_token. You need them in the next steps.
Store the card in the vault
Send the card details and the setup_token to the vault. The vault stores the card and returns a vault_token that represents it.
curl https://tokens.dev.gingerpayments.com/v1/cards/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"name": "John Smith",
"pan": "4111111111111111",
"expiry": "012030",
"setup_token": "87f05a5d-1755-48c7-8161-f8a9544e56bf"
}'{
"vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3",
"truncated_pan": "4111********1111",
"brand": "visa",
"brands": ["visa"]
}The setup token expires quickly
A setup_token works only once, and only within 300 seconds after the order was created. Store the card right after your customer submits your checkout form.
Store the vault_token if you want to reuse the card later, for example for one-click payments.
Start authentication
Send the vault_token and the card's CVC to the transaction:
curl https://api.dev.gingerpayments.com/v1/orders/8078d78f-8700-4cfe-94b1-4a777d3400f2/transactions/a5dac3de-d304-4570-922b-373d478b8b3a/authenticate/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3",
"cvc": "123"
}'{
"redirect_url": "/pay/8078d78f-8700-4cfe-94b1-4a777d3400f2/a5dac3de-d304-4570-922b-373d478b8b3a/authenticate-3ds/"
}Redirect your customer to the redirect_url, on the https://api.dev.gingerpayments.com domain. Ginger Payments checks whether the card is enrolled for 3-D Secure and forwards your customer to their bank. The bank decides whether your customer needs to approve the payment. Afterwards, your customer is redirected back to your return_url.
Already authenticated your customer with your own 3-D Secure provider? Send the authentication values in this request instead. See external 3-D Secure.
Check the result
When your customer is back on your website, wait for the webhook and retrieve the order, or poll the order status. The payment succeeded when the order status is completed and the transaction status is accepted. Stop polling when the status is final, such as error or expired.
Fields
Order fields
| Field | Required | Description |
|---|---|---|
currency | Yes | ISO 4217 currency code, such as EUR, GBP or USD. |
amount | Yes | Amount in the smallest currency unit: 1234 is £ 12.34. |
merchant_order_id | Recommended | Your own order reference. |
description | Recommended | Description of the order. |
transactions | Yes | One transaction with payment_method set to credit-card. |
return_url | Recommended | Where your customer goes after 3-D Secure authentication. Without it, use webhooks and status requests to track the payment. |
failure_url | No | Where your customer goes when the payment fails: the status is cancelled, expired or error. |
webhook_url | No | Where status changes are sent. Overrides the webhook URL of the project for this order. |
Customer fields
The customer object takes the same fields as on the hosted payment page. See customer fields.
Card fields
Send these fields to the vault and to the authenticate request. Never log or store them yourself unless your PCI DSS certification covers it.
| Field | Request | Description |
|---|---|---|
name | Vault | Cardholder name as printed on the card. 1 to 120 characters. |
pan | Vault | Card number without spaces. 12 to 19 digits. |
expiry | Vault | Expiry date in MMYYYY format, such as 012030 for January 2030. |
setup_token | Vault | The setup_token from the transaction. |
vault_token | Authenticate | The vault_token from the vault. |
cvc | Authenticate | The card's CVC or CVV. 3 characters. |
E-wallet merchants
If you're an e-wallet merchant, add receiver_account_number and receiver_account_number_type to the payment_method_details of the transaction. See e-wallet merchants.
Next steps
- 3-D Secure: how authentication works and how to use your own 3-D Secure provider.
- One-click payments and recurring payments: reuse a stored card.
- Apple Pay and Google Pay in your own checkout.