Create an order
Creates an order with the amount your customer pays.
- Without
transactions, redirect your customer to theorder_url. The hosted payment page shows every payment method that's active in your project. - With one transaction, you pick the payment method yourself. Redirect your customer to the
payment_urlof the transaction, or continue with a server-to-server payment.
A 2xx response doesn't mean that your customer has paid. Check the status of the order, see Order and transaction status.
apiKeyAuthorizationBasic <token>Use your project's API key as the username and leave the password empty. Only use the API key from your server: it gives full access to your project.
application/json- body
merchant_order_id?stringYour own order reference. Recommended.
merchant_name?stringYour merchant name. Can be used for payouts, if configured.
description?stringDescription of the order. Recommended.
currency*CurrencyISO 4217 currency code, such as EUR, GBP or USD. Get supported currencies lists the currencies of your project.
^[A-Z]{3}$amount*AmountAmount in the smallest currency unit, including VAT. 1234 is € 12.34. For currencies without minor units, send the whole amount.
0 <= valueexpiration_period?DurationHow long the order stays valid, such as PT1H for one hour.
payment_methods?array<>The payment methods to show on the hosted payment page. Without it, every payment method that's active in your project is shown.
transactions?array<>The payment attempts of the order. When you create the order, send one transaction to pick the payment method yourself. Without it, your customer picks a payment method on the hosted payment page.
return_url?stringWhere your customer goes after the payment. Recommended.
urifailure_url?stringWhere your customer goes when the payment fails, with status cancelled, expired or error. Without it, your customer goes to the return_url.
uriwebhook_url?stringWhere webhooks for this order are sent. Overrides the webhook URL of your project.
uricustomer?Your customer. Card schemes use these details for 3-D Secure risk assessment, so complete details lead to more frictionless payments. Your acquirer can require some of them.
client?The software that sends the request, such as your e-commerce platform or plugin.
extra?Your own data to store with the order. It's returned when you retrieve the order.
The order has been created.
application/json- response
id?stringOrder ID.
uuidproject_id?stringID of the project the order belongs to.
uuidmerchant_id?stringID of your merchant account.
uuidmerchant_order_id?stringYour own order reference. Recommended.
merchant_name?stringYour merchant name. Can be used for payouts, if configured.
description?stringDescription of the order. Recommended.
currency*CurrencyISO 4217 currency code, such as EUR, GBP or USD. Get supported currencies lists the currencies of your project.
^[A-Z]{3}$amount*AmountAmount in the smallest currency unit, including VAT. 1234 is € 12.34. For currencies without minor units, send the whole amount.
0 <= valuestatus?stringStatus of the order. completed, cancelled, expired and error are final. With see-transactions, the transactions have different statuses: check each of them. See Order statuses.
"new""processing""completed""cancelled""expired""error""see-transactions"flags?array<string>Labels of the order, such as is-test for orders in a test project and is-refund for refund orders.
created?TimestampDate and time in ISO 8601 format.
date-timemodified?TimestampDate and time in ISO 8601 format.
date-timecompleted?TimestampDate and time in ISO 8601 format.
date-timeexpiration_period?DurationHow long the order stays valid, such as PT1H for one hour.
payment_methods?array<>The payment methods to show on the hosted payment page. Without it, every payment method that's active in your project is shown.
transactions?array<>The payment attempts of the order. When you create the order, send one transaction to pick the payment method yourself. Without it, your customer picks a payment method on the hosted payment page.
order_url?stringThe hosted payment page of the order. Redirect your customer here when you didn't send a transaction.
urireturn_url?stringWhere your customer goes after the payment. Recommended.
urifailure_url?stringWhere your customer goes when the payment fails, with status cancelled, expired or error. Without it, your customer goes to the return_url.
uriwebhook_url?stringWhere webhooks for this order are sent. Overrides the webhook URL of your project.
uricustomer?Your customer. Card schemes use these details for 3-D Secure risk assessment, so complete details lead to more frictionless payments. Your acquirer can require some of them.
client?The software that sends the request, such as your e-commerce platform or plugin.
extra?Your own data to store with the order. It's returned when you retrieve the order.
refunded_amount?integerThe amount refunded on this order so far, in the smallest currency unit.
refund_of_order_id?stringFor a refund order, the ID of the original order.
uuidrefund_orders?array<>IDs of the refund orders of this order.
capture_of_order_id?stringFor a capture order, the ID of the original order.
uuidvoid_of_order_id?stringFor a void order, the ID of the original order.
uuidchargeback_of_order_id?stringFor a chargeback order, the ID of the original order.
uuidchargeback_orders?array<>IDs of the chargeback orders of this order.
reversal_of_order_id?stringFor a reversal order, the ID of the original order.
uuidreversal_orders?array<>IDs of the reversal orders of this order.
related_order_id?stringID of the original order, for any order created from another one.
uuidrelated_orders?array<>IDs of the orders created from this order.
related_payment_link_id?stringID of the payment link the order was created from.
uuidcurl -X POST 'https://api.dev.gingerpayments.com/v1/orders/' \ -H 'Content-Type: application/json' \ -d '{ "currency": "EUR", "amount": 995, "merchant_order_id": "EXAMPLE001", "description": "Example order", "return_url": "https://www.example.com/order/EXAMPLE001", "webhook_url": "https://www.example.com/webhook", "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" }}'{ "id": "23cd147d-cd2b-4df6-ae50-199de346ded1", "project_id": "05ad138f-52fa-40dc-9751-5fde949dcb57", "merchant_id": "b251b220-5d8b-4b9d-9915-b89676dc0948", "merchant_order_id": "EXAMPLE001", "created": "2026-10-12T10:43:13.905092+00:00", "modified": "2026-10-12T10:43:13.905092+00:00", "currency": "EUR", "amount": 995, "description": "Example card order", "status": "new", "flags": [ "is-test" ], "expiration_period": "PT1H", "order_url": "https://api.dev.gingerpayments.com/pay/23cd147d-cd2b-4df6-ae50-199de346ded1/select-payment-method/", "return_url": "https://www.example.com/order/EXAMPLE001", "webhook_url": "https://www.example.com/webhook", "transactions": [ { "id": "12774973-2ff1-49f5-926c-b5dc471ee96b", "order_id": "23cd147d-cd2b-4df6-ae50-199de346ded1", "created": "2026-10-12T10:43:13.905092+00:00", "currency": "EUR", "amount": 995, "credit_debit": "credit", "expiration_period": "PT30M", "is_capturable": false, "payment_method": "credit-card", "payment_method_details": { "setup_token": "87f05a5d-1755-48c7-8161-f8a9544e56bf" }, "payment_url": "https://api.dev.gingerpayments.com/pay/23cd147d-cd2b-4df6-ae50-199de346ded1/select-payment-method/credit-card/12774973-2ff1-49f5-926c-b5dc471ee96b/", "status": "new" } ], "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" }}