> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithsoap.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Checkout
Use this endpoint to create a new checkout session for a customer.
We support these checkout types:
* A deposit checkout is used to deposit money into a customer's balance.
* A purchase checkout is used to purchase a product or service, such as credits, sweepstakes coins, or digital goods.
* A subscription checkout is used to create a recurring deposit checkout with subscription billing metadata.
* A withdrawal checkout is used to withdraw money from a customer's balance.
View the Soap Experiences PDF →
### Receive Payments
Input form where the customer enters a custom deposit amount.
Deposit a fixed amount (e.g. \$100) into the customer's balance.
Create a recurring deposit checkout with subscription billing metadata.
Purchase virtual currency, in-game tokens, sweepstakes coins, and other digital goods.
Purchase physical goods such as nutraceuticals, peptides, supplements, and more.
### Send Payments
Input form where the customer withdraws up to their available balance.
Withdraw a fixed amount (e.g. \$100) from the customer's balance.
## Common Parameters
| Parameter | Required | Description |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customer_id` | Yes | Soap customer ID for the customer starting the checkout. |
| `type` | Yes | Checkout direction. Use `"deposit"` for deposits, purchases, and subscriptions. Use `"withdrawal"` for withdrawals. |
| `line_items` | Required for purchase and subscription checkouts | Products included in the checkout. Supports existing product references and inline dynamic products. |
| `subscription_data` | Required for subscription checkouts | Billing cadence for a recurring subscription checkout. Includes `interval` and `interval_count`. |
| `fixed_amount_cents` | Required for preset amount flows | Fixed amount in cents for preset deposits or preset withdrawals. Must be at least `1`. |
| `balance_amount_cents` | Required for balance withdrawal flows | Customer balance in cents. The customer can withdraw up to this amount. Must be at least `1`. |
| `experience` | No | Checkout presentation. Use `"web"`, `"webview"`, or `"iframe"`. Set `"iframe"` when embedding the checkout in an iframe — required for in-frame Apple Pay. See [Embedded Checkout](/get_started/embedded-checkout). |
| `return_url` | No | URL where Soap redirects the customer after checkout completion. When the checkout is embedded in an iframe, this redirect happens **inside the frame**. |
## Line Items and Dynamic Pricing
Use `line_items` for purchase and subscription checkout flows where Soap should show purchased products and compute the checkout total from product quantities. Line items are not used for balance amount, fixed amount, or withdrawal-only flows.
Each line item can be either:
* An existing product reference with `product_id` and `quantity`.
* An inline dynamic product with `name`, `price_cents`, and `quantity`, plus optional `sku`, `url`, and `dedup`.
When `dedup` is `true`, include a stable `sku`. Soap reuses a matching product for the same business when both `sku` and `price_cents` match. If `dedup` is absent or `false`, Soap creates a new active product from the inline line item.
### Line Item Parameters
| Parameter | Required | Description |
| -------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `line_items[].product_id` | Yes for existing products | Soap product ID for an existing product. Use this shape with `quantity` when the product is already in Soap. |
| `line_items[].name` | Yes for inline products | Product name to create and display in checkout. |
| `line_items[].price_cents` | Yes for inline products | Unit price in cents for the inline product. Must be at least `1`. |
| `line_items[].quantity` | Yes | Number of units to purchase. Must be at least `1`. |
| `line_items[].sku` | Required when `dedup` is `true` | Stable merchant SKU used with `price_cents` to find an existing product for this business. |
| `line_items[].url` | No | Product image URL shown in checkout where supported. |
| `line_items[].dedup` | No | When `true`, Soap looks for an existing product for the same business by `sku` and `price_cents` before creating a new product. Requires `sku`. |
### Dynamic Purchase Example
```json theme={null}
{
"customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
"type": "deposit",
"line_items": [
{
"name": "Gold Coins Pack",
"price_cents": 999,
"quantity": 1,
"sku": "gold-coins-1000",
"url": "https://example.com/products/gold-coins.png",
"dedup": true
}
],
"experience": "web",
"return_url": "https://myapp.com/store"
}
```
## Subscription Checkouts
Create a subscription checkout by sending `subscription_data` on `POST /api/v1/checkouts`. Subscription checkouts are deposit-only and require `line_items`.
Subscription checkouts use the same line item formats as purchase checkouts: either existing products by `product_id` or inline dynamic products with `name`, `price_cents`, and `quantity`.
The `subscription_data.interval` value can be `day`, `week`, `month`, or `year`. For quarterly billing, use `interval: "month"` and `interval_count: 3`.
### Subscription Parameters
| Parameter | Required | Description |
| ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `subscription_data.interval` | Yes | Billing interval. Must be `day`, `week`, `month`, or `year`. |
| `subscription_data.interval_count` | Yes | Number of intervals between charges. Use `interval: "month"` and `interval_count: 3` for quarterly billing. |
```json theme={null}
{
"customer_id": "cus_aaN5GMMF8CFpsYMuEnN9DPFMtGQaVDQZ",
"type": "deposit",
"line_items": [
{
"name": "Premium Monthly Plan",
"price_cents": 2999,
"quantity": 1,
"sku": "PREMIUM-MONTHLY",
"url": "https://images.unsplash.com/photo-1516321318423-f06f85e504b3?auto=format&fit=crop&w=800&q=80",
"dedup": true
}
],
"subscription_data": {
"interval": "month",
"interval_count": 1
}
}
```
```bash Curl theme={null}
curl -X POST 'https://api-sandbox.paywithsoap.com/api/v1/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_KEY' \
--data '{
"customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
"type": "deposit"
}'
```
```ruby Ruby theme={null}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api-sandbox.paywithsoap.com/api/v1/checkouts')
request = Net::HTTP::Post.new(uri)
request.content_type = 'application/json'
request['Authorization'] = 'YOUR_API_KEY'
request.body = {
customer_id: 'cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870',
type: 'deposit'
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
```
```javascript JavaScript theme={null}
const fetch = require('node-fetch');
const options = {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY'
},
body: JSON.stringify({
customer_id: 'cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870',
type: 'deposit'
})
};
fetch('https://api-sandbox.paywithsoap.com/api/v1/checkouts', options)
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```
```python Python theme={null}
import requests
import json
url = "https://api-sandbox.paywithsoap.com/api/v1/checkouts"
headers = {
"Content-Type": "application/json",
"Authorization": "YOUR_API_KEY"
}
data = {
"customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
"type": "deposit"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
```
```json Response theme={null}
{
"url": "https://wallet-sandbox.paywithsoap.com?clientSecret=HMC3VTosbzJd7cLsoP3geC5QmSz8jqF6",
"id": "chk_HBq6ExeoRDMPFCCabR8n1h7S1towds7K",
"client_secret": "HMC3VTosbzJd7cLsoP3geC5QmSz8jqF6",
"line_items": [],
"line_items_total_amount_cents": null,
"balance_amount_cents": null,
"type": "deposit",
"experience": null,
"subscription": null
}
```
Redirect the customer to `url`, or embed it in an `