Skip to main content
POST
/
api
/
v1
/
checkouts
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"
}'

{
    "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
}

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.

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

Draft King's Style Deposit

Input form where the customer enters a custom deposit amount.

Preset Amount Deposit

Deposit a fixed amount (e.g. $100) into the customer’s balance.

Subscription Checkout

Create a recurring deposit checkout with subscription billing metadata.

Digital Goods Purchase

Purchase virtual currency, in-game tokens, sweepstakes coins, and other digital goods.

Ecomm Purchase

Purchase physical goods such as nutraceuticals, peptides, supplements, and more.

​
Send Payments

Balance Withdrawal

Input form where the customer withdraws up to their available balance.

Preset Amount Withdrawal

Withdraw a fixed amount (e.g. $100) from the customer’s balance.

​
Common Parameters

ParameterRequiredDescription
customer_idYesSoap customer ID for the customer starting the checkout.
typeYesCheckout direction. Use "deposit" for deposits, purchases, and subscriptions. Use "withdrawal" for withdrawals.
line_itemsRequired for purchase and subscription checkoutsProducts included in the checkout. Supports existing product references and inline dynamic products.
subscription_dataRequired for subscription checkoutsBilling cadence for a recurring subscription checkout. Includes interval and interval_count.
fixed_amount_centsRequired for preset amount flowsFixed amount in cents for preset deposits or preset withdrawals. Must be at least 1.
balance_amount_centsRequired for balance withdrawal flowsCustomer balance in cents. The customer can withdraw up to this amount. Must be at least 1.
experienceNoCheckout presentation. Use "web" or "webview".
return_urlNoURL where Soap redirects the customer after checkout completion.

​
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

ParameterRequiredDescription
line_items[].product_idYes for existing productsSoap product ID for an existing product. Use this shape with quantity when the product is already in Soap.
line_items[].nameYes for inline productsProduct name to create and display in checkout.
line_items[].price_centsYes for inline productsUnit price in cents for the inline product. Must be at least 1.
line_items[].quantityYesNumber of units to purchase. Must be at least 1.
line_items[].skuRequired when dedup is trueStable merchant SKU used with price_cents to find an existing product for this business.
line_items[].urlNoProduct image URL shown in checkout where supported.
line_items[].dedupNoWhen 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

{
  "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

ParameterRequiredDescription
subscription_data.intervalYesBilling interval. Must be day, week, month, or year.
subscription_data.interval_countYesNumber of intervals between charges. Use interval: "month" and interval_count: 3 for quarterly billing.
{
  "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
  }
}

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"
}'

{
    "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
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key

Body

application/json

Standard sports-book styles deposit.

​
customer_id
string
required

Unique identifier for the customer

Example:

"cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870"

​
type
enum<string>
required

Type of transaction - deposit

Available options:
deposit
Example:

"deposit"

​
experience
enum<string>

The experience type for the checkout flow

Available options:
web,
webview
​
return_url
string

URL to redirect the customer after completion (if you are opening a new tab or window for your customer you do not need this)

Example:

"https://myapp.com/game/:id"

Response

Use the url field in the response. In web, you can redirect or open a new tab. In native, you can use a WebView.

​
url
string

The url of the checkout experience

​
id
string

Unique identifier for the checkout

​
client_secret
string

Secret used for client-side checkout processing

​
line_items
object[]

Line items contained in the checkout (non-empty only for purchases)

​
line_items_total_amount_cents
integer | null

Total amount in cents for all line items

​
balance_amount_cents
integer | null

Amount in cents withdrawn from or to be added to balance

​
type
enum<string>

Type of checkout transaction

Available options:
deposit,
withdrawal
​
experience
enum<string>

The experience type for the checkout flow

Available options:
web,
webview
​
subscription
object

Subscription metadata returned only for subscription checkouts