Digital Goods Purchase

Overview

A digital goods purchase allows customers to buy virtual currency, in-game tokens, sweepstakes coins, and other digital products. This uses the line items checkout flow where you specify the products, prices, and quantities being purchased. Every Soap API request is authenticated with a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Your API key is in the Soap Dashboard under the Developers section. It looks like key_.... Requests with a missing or invalid API key return 422 — never 401 — with a JSON error field, usually {"error": "API key not found."}. Branch on the status code rather than the message: GET /api/v1/device_pings/latest_geo_check does not yet return the same wording. Never expose your API key in client-side code — it is server-side only.

How It Works

Create products in Soap, or pass inline dynamic product details directly in line_items.
Create a checkout session with type: "deposit" and include line_items.
The customer is redirected to the Soap-hosted checkout page showing the items and total.
The customer selects a payment method and completes the purchase.
Upon completion, a webhook is fired and the customer is redirected back to your app.

API Request

You can also manage products from the Soap dashboard and reference them by ID. Simply pass line_items: [{ "product_id": "pr_XXX", "quantity": 1 }] instead of inline product details.

curl -X POST 'https://api-sandbox.paywithsoap.com/api/v1/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "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"
}'

Key Parameters

Parameter	Required	Description
`customer_id`	Yes	The customer’s unique identifier
`type`	Yes	Must be `"deposit"`
`line_items`	Yes	Array of existing product references or inline dynamic products
`experience`	No	`"web"`, `"webview"`, or `"iframe"`. Use `"iframe"` when embedding the checkout — see Embedded Checkout.
`return_url`	No	Where to redirect the customer after completion

Line Item Parameters

Each line item can reference an existing product or define a product inline.

Parameter	Required	Description
`line_items[].product_id`	Yes for existing products	Soap product ID for an existing product. Use with `quantity`.
`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. 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 reuses an existing product for the same business when `sku` and `price_cents` match. Requires `sku`.

When to Use

Virtual currency purchases (gold coins, tokens, credits, etc.)
Sweepstakes coin packages
Any digital goods tied to a product catalog or priced dynamically at checkout time

← Back to Create Checkout

View the full API reference for creating checkouts.

API Documentation

API Endpoints

Webhooks

Testing

Digital Goods Purchase

Overview

How It Works

API Request

Key Parameters

Line Item Parameters

When to Use

← Back to Create Checkout

​Overview

​How It Works

​API Request

​Key Parameters

​Line Item Parameters

​When to Use

← Back to Create Checkout

Overview

How It Works

API Request

Key Parameters

Line Item Parameters

When to Use