Skip to main content
This guide explains how to complete the checkout process using the Checkout API. The steps are:
  1. Create a checkout record
  2. Retrieve and set shipping and payment methods
  3. Validate checkout readiness
  4. Process payment
On successful payment, an order resource is returned.

​
Order resource example

{
  "data": {
    "type": "orders",
    "relationships": {
      "billingAddress": {
        "data": {"type": "orderaddresses", "id": "billing1"}
      },
      "shippingAddress": {
        "data": {"type": "orderaddresses", "id": "shipping1"}
      },
      "lineItems": {
        "data": [{"type": "orderlineitems", "id": "item1"}]
      }
    }
  },
  "included": [
    {
      "type": "orderaddresses",
      "id": "billing1",
      "relationships": {
        "customerAddress": {
          "data": {"type": "customeraddresses", "id": "1"}
        }
      }
    },
    {
      "type": "orderaddresses",
      "id": "shipping1",
      "relationships": {
        "customerAddress": {
          "data": {"type": "customeraddresses", "id": "1"}
        }
      }
    },
    {
      "type": "orderlineitems",
      "id": "item1",
      "attributes": {"quantity": 10},
      "relationships": {
        "product": {"data": {"type": "products", "id": "1"}},
        "productUnit": {"data": {"type": "productunits", "id": "item"}}
      }
    }
  ]
}

​
Step 1: Create a checkout record

Create a new checkout record with a POST request: 
POST /api/checkouts HTTP/1.1

{
  "data": {
    "type": "checkouts"
  }
}
Alternatively, initiate checkout from an existing source entity:
  • POST /api/orders/{id}/checkout — from a specific order
  • POST /api/shoppinglists/{id}/checkout — from a shopping list
For guest users, checkout must be initiated from a shopping list.

​
Step 2: Retrieve and set shipping and payment methods

To retrieve available shipping methods: 
GET /api/checkouts/1/availableShippingMethods HTTP/1.1
Shipping method information includes two parts: the shipping method and the shipping method type. Types define different specifics of the same shipping method.
To retrieve available payment methods: 
GET /api/checkouts/1/availablePaymentMethods HTTP/1.1
Once you have selected the preferred methods, update the checkout record: 
PATCH /api/checkouts/1 HTTP/1.1

{
  "data": {
    "type": "checkouts",
    "id": "1",
    "attributes": {
      "paymentMethod": "oro_paypal_express_1",
      "shippingMethod": "flat_rate_6",
      "shippingMethodType": "primary"
    }
  }
}
This step is currently not applicable to multi-organization setups like OroMarketplace, due to differences in how shipping is managed across organizations.

​
Step 3: Validate checkout readiness

Before initiating payment, confirm the checkout is fully configured: 
GET /api/checkouts/1/payment HTTP/1.1
Response when ready: 
{
  "meta": {
    "message": "The checkout is ready for payment.",
    "paymentUrl": "https://host/api/checkouts/1/paymentPaymentTerm",
    "errors": []
  }
}

​
Step 4: Process payment

The payment steps depend on the selected payment method.
In the examples below, https://my-application.ltd is the host of the client application using the Oro API, and https://oro-application.ltd is the Oro application itself.

​
Stripe payment

1

Submit Stripe payment details

Submit the Stripe PaymentMethod ID obtained from the Stripe Payment Element or Stripe API:
POST /api/checkouts/1/paymentInfoStripe HTTP/1.1

{
  "meta": {
    "stripePaymentMethodId": "pm_stripepaymentmethodid"
  }
}
2

Execute the payment

POST /api/checkouts/1/paymentStripe HTTP/1.1

{
  "meta": {
    "successUrl": "https://my-application.ltd/checkout/payment/stripe/success",
    "failureUrl": "https://my-application.ltd/checkout/payment/stripe/failure",
    "partiallyPaidUrl": "https://my-application.ltd/checkout/payment/stripe/partiallyPaid"
  }
}
On success, an order resource is returned. If additional steps (e.g., 3D Secure) are required, complete them and make a follow-up POST to finalize.

​
PayPal Express payment

1

Initiate PayPal Express payment

POST /api/checkouts/1/paymentPayPalExpress HTTP/1.1

{
  "meta": {
    "successUrl": "https://my-application.ltd/checkout/payment/paypal-express/success",
    "failureUrl": "https://my-application.ltd/checkout/payment/paypal-express/failure"
  }
}
The response contains a purchaseRedirectUrl to redirect the user to PayPal for authentication.
2

Finalize payment

After the user returns from PayPal, send a second POST to the same endpoint to complete the checkout.

​
Payment Term payment

POST /api/checkouts/1/paymentPaymentTerm HTTP/1.1
On successful completion, an order resource is returned.

​
Error handling

API responses include HTTP status codes and error messages to help troubleshoot payment failures. Follow PCI-DSS compliance guidelines when handling sensitive payment data. Checkout not ready for payment: 
{
  "meta": {
    "message": "The checkout is not ready for payment.",
    "paymentUrl": null,
    "errors": [
      {
        "status": "400",
        "title": "not blank constraint",
        "detail": "Shipping method is not selected.",
        "source": {"pointer": "/data/attributes/shippingMethod"}
      },
      {
        "status": "400",
        "title": "not blank constraint",
        "detail": "Payment method is not selected.",
        "source": {"pointer": "/data/attributes/paymentMethod"}
      }
    ]
  }
}
Payment failed: 
{
  "errors": [
    {
      "status": "400",
      "title": "payment constraint",
      "detail": "Payment failed, please try again or select a different payment method."
    }
  ]
}
Additional actions required (e.g., 3D Secure): 
{
  "errors": [
    {
      "status": "400",
      "title": "payment action constraint",
      "detail": "The payment requires additional actions.",
      "meta": {
        "data": {
          "paymentMethod": "stripe_payment_1",
          "requires_action": true,
          "payment_intent_client_secret": "pi_stripe_secret_key"
        }
      }
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us