Create a One-Time Charge

Creates a single, one-time charge that requires seller approval. Once created, redirect the seller to the returned confirmation_url. After the seller responds, YouCan redirects them to your return_url.

Endpoint: https://api.youcan.shop/billing/apps/charges/onetime

Method: POST

TIP

Raw amounts work without any catalog. For your standard tiers, prefer referencing a pricing plan by handle, so your listing and your charges cannot drift apart.

Parameters

Parameter	Type	Required	Validation	Description
name	string	Yes	max:255	Display name shown to the seller on the confirmation page.
return_url	string	Yes	url, max:2048	URL to redirect the seller to after they approve or decline.
plan_handle	string	No	max:64	Handle of a pricing plan. The charge is priced from the plan.
price.amount	numeric	Yes*	min:0.00, max:1000.00	Charge amount in USD.
test	boolean	No	-	Mark as a test charge. Defaults to false. Required for non-approved apps and development stores.

* Required unless plan_handle is given.

Request

{
  "name": "Premium Features Unlock",
  "return_url": "https://myapp.com/billing/success",
  "price": {
    "amount": 29.99
  },
  "test": false
}

Response

[201]
{
  "type": "onetime",
  "id": "aoch_01234567890abcdef",
  "store_id": "...",
  "name": "Premium Features Unlock",
  "status": "pending",
  "plan_id": null,
  "price": {
    "amount": "29.99",
    "currency": "USD"
  },
  "test": false,
  "confirmation_url": "https://..."
}

Redirect the seller to confirmation_url immediately after receiving this response.

TIP

The charge remains in pending status until the seller approves or declines it. Verify the final status via List charges after the seller is redirected back to your return_url.

AppOnetimeCharge object

Field	Type	Description
type	string	Always "onetime" for one-time charges.
id	string	Unique charge identifier, prefixed with aoch_.
store_id	string	ID of the store this charge belongs to.
name	string	Name of the charge as provided in the request.
status	string	Current charge status. See charge statuses.
price	object	Price information object.
price.amount	string	Charge amount as a decimal string (e.g. "29.99").
price.currency	string	Currency code. Always "USD".
test	boolean	Whether this is a test charge.
confirmation_url	string	URL for the seller to approve or decline the charge. Only present when status is pending.