Complete Checkout

Complete the checkout process by processing payment and creating an order

POST /v1/checkouts/:id/complete

cURL

curl -X POST https://api.stateset.com/v1/checkouts/checkout_abc123/complete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_data": {
      "token": "spt_123",
      "provider": "stripe",
      "billing_address": {
        "name": "John Doe",
        "line_one": "123 Main St",
        "line_two": "Apt 4B",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "postal_code": "94105"
      }
    }
  }'

const checkout = await stateset.checkouts.complete('checkout_abc123', {
  payment_data: {
    token: "spt_123",
    provider: "stripe",
    billing_address: {
      name: "John Doe",
      line_one: "123 Main St",
      line_two: "Apt 4B",
      city: "San Francisco",
      state: "CA",
      country: "US",
      postal_code: "94105"
    }
  }
});

checkout = stateset.checkouts.complete(
    'checkout_abc123',
    payment_data={
        "token": "spt_123",
        "provider": "stripe",
        "billing_address": {
            "name": "John Doe",
            "line_one": "123 Main St",
            "line_two": "Apt 4B",
            "city": "San Francisco",
            "state": "CA",
            "country": "US",
            "postal_code": "94105"
        }
    }
)

Success Response

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]"
  },
  "status": "completed",
  "currency": "usd",
  "order_id": "order_xyz789",
  "payment": {
    "id": "pay_456",
    "status": "succeeded",
    "amount": 3750,
    "provider": "stripe"
  },
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [],
  "links": []
}

{
  "success": false,
  "error": {
    "type": "processing_error",
    "code": "PAYMENT_DECLINED",
    "message": "Payment was declined by the payment processor",
    "details": {
      "decline_code": "insufficient_funds",
      "provider_message": "Card has insufficient funds"
    }
  }
}

{
  "success": false,
  "error": {
    "type": "invalid_request",
    "code": "INVALID_STATUS",
    "message": "Checkout must be in ready_for_payment status to complete",
    "param": "status"
  }
}

This endpoint finalizes the checkout session by processing the payment and converting it into an order. The checkout status will be updated to completed upon successful payment.

Authentication

This endpoint requires a valid API key with checkouts:write and payments:write permissions.

Authorization: Bearer YOUR_API_KEY

Path Parameters

id · string · required

Unique identifier for the checkout session

Request Body

payment_data · object · required

Payment method details for processing the transaction

Show Payment data properties

token · string · required

Secure reference to a payment credential (tokenized payment method)

provider · string · required

Payment provider: stripe, paypal, square

billing_address · object

Billing address for the payment method

Show Address properties

name · string

Billing name

line_one · string

Street address line 1

line_two · string

Street address line 2

city · string

City name

state · string

State or province code

country · string

ISO 3166-1 alpha-2 country code

postal_code · string

Postal or ZIP code

buyer · object

Additional buyer information if needed

Show Buyer properties

first_name · string

First name of the buyer

last_name · string

Last name of the buyer

email · string

Email address of the buyer

phone_number · string

Phone number of the buyer

Response

id · string

Unique identifier for the Checkout Session

status · string

Status will be completed after successful payment

order_id · string

ID of the created order

payment · object

Payment processing details and status

line_items · array

Final line items with calculated amounts

totals · array

Final breakdown of all charges

cURL

curl -X POST https://api.stateset.com/v1/checkouts/checkout_abc123/complete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_data": {
      "token": "spt_123",
      "provider": "stripe",
      "billing_address": {
        "name": "John Doe",
        "line_one": "123 Main St",
        "line_two": "Apt 4B",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "postal_code": "94105"
      }
    }
  }'

const checkout = await stateset.checkouts.complete('checkout_abc123', {
  payment_data: {
    token: "spt_123",
    provider: "stripe",
    billing_address: {
      name: "John Doe",
      line_one: "123 Main St",
      line_two: "Apt 4B",
      city: "San Francisco",
      state: "CA",
      country: "US",
      postal_code: "94105"
    }
  }
});

checkout = stateset.checkouts.complete(
    'checkout_abc123',
    payment_data={
        "token": "spt_123",
        "provider": "stripe",
        "billing_address": {
            "name": "John Doe",
            "line_one": "123 Main St",
            "line_two": "Apt 4B",
            "city": "San Francisco",
            "state": "CA",
            "country": "US",
            "postal_code": "94105"
        }
    }
)

Success Response

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]"
  },
  "status": "completed",
  "currency": "usd",
  "order_id": "order_xyz789",
  "payment": {
    "id": "pay_456",
    "status": "succeeded",
    "amount": 3750,
    "provider": "stripe"
  },
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [],
  "links": []
}

{
  "success": false,
  "error": {
    "type": "processing_error",
    "code": "PAYMENT_DECLINED",
    "message": "Payment was declined by the payment processor",
    "details": {
      "decline_code": "insufficient_funds",
      "provider_message": "Card has insufficient funds"
    }
  }
}

{
  "success": false,
  "error": {
    "type": "invalid_request",
    "code": "INVALID_STATUS",
    "message": "Checkout must be in ready_for_payment status to complete",
    "param": "status"
  }
}