Skip to content

Start paying for a cart

POST
/commerce/delivery/v1/carts/{id}/checkout
curl --request POST \
--url https://api.ebitex.io/commerce/delivery/v1/carts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/checkout \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "email": "example", "name": "example", "successUrl": "example", "cancelUrl": "example" }'

Turns the cart into an order awaiting payment and returns the payment provider’s page to send the shopper to. Send { "email": "ada@example.com", "name": "Ada Lovelace", "successUrl": "https://shop.example/thanks", "cancelUrl": "https://shop.example/cart" }. The server prices the cart afresh, so what the shopper is charged is what the cart shows now, and the order records the rate a converted price used. The shopper enters card details on the provider’s page, never on yours.

The return addresses must be absolute https addresses (http is allowed only to localhost, for development), and for a browser-safe key they must be on one of the key’s allowed origins. The stock is held for 30 minutes while the shopper pays (not at all while the store is in test mode, when the order is marked as a test), and an order that is not paid in time expires and releases it. A payment confirmed late is still matched to its order. Starting again for the same cart ends the earlier attempt and takes its stock back, and a cart may start a checkout a few times a minute.

The answer is { orderId, number, redirectUrl, totalMinor, currency, isTest, expiresAtUtc }. Whether the order was paid is for your server to learn from the store’s own records (the next release reports it), not from the shopper’s browser arriving at the success address.

A cart belongs to one shopper in one store and holds SKUs and quantities only: it never holds a price, because the server prices everything, so a client cannot name one. The shopper is proven by their visitor token, sent in X-Visitor-Token: a missing, expired, revoked or unrecognised token is 401 visitor_token_required. Another shopper’s cart, and a cart in another store, answer 404 cart_not_found. The key must carry the checkout permission (Allow carts and checkout when the key is made); a key that can only read answers 403 scope_denied. Cart responses are never cached (Cache-Control: private, no-store).

Key: commerce.checkout.write

id
required
string format: uuid
Media typeapplication/json
One of:
null
Examplegenerated
{
"email": "example",
"name": "example",
"successUrl": "example",
"cancelUrl": "example"
}

OK

invalid_email, invalid_name or invalid_return_url: the buyer’s email, name, or a return address was refused.

visitor_token_required: send the shopper’s visitor token in X-Visitor-Token.

missing_api_key or invalid_api_key: no key was sent, or it is unknown, revoked or expired, or its store binding was removed.

payment_required: the organization’s subscription needs attention.

scope_denied: the key was not allowed to run carts and checkout.

scope_denied: the key lacks commerce.delivery.read. app_not_available: Commerce is not enabled for the organization. origin_denied or ip_denied: the key was used from an origin or address outside its restrictions.

cart_not_found: there is no such cart for this shopper in this store.

The cart cannot be paid for as it stands: payments_not_configured (the store has no payment connection with keys for its mode), cart_empty, cart_has_issues (a line can no longer be sold), address_required, shipping_unavailable, tax_not_calculated, nothing_to_pay, or insufficient_stock (detail.skus lists them).

The payment provider could not be used: payment_provider_failed (it refused or could not open a payment) or payment_provider_unavailable (it is not available). Nothing was held and no order was left behind. Try again shortly.

rate_limited: slow down; Retry-After says how long to wait.

rate_limited: the key spent its requests-per-minute budget; Retry-After says how long to wait. too_many_failed_authentications: too many bad keys from this address.