Create a One-Time Charge
Creates a single, one-time charge that requires merchant approval. Once created, redirect the merchant to the returned confirmation_url. After the merchant 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 merchant on the confirmation page. |
return_url | string | Yes | url, max:2048 | URL to redirect the merchant to after they approve or decline. If it has the scheme, host and port of your app URL, the merchant returns to your app inside the admin, with the signed session parameters. Otherwise the merchant is redirected to it with no parameters added. |
plan_handle | string | No | max:64 | Handle of a pricing plan. The charge is priced from the plan. |
price.amount | numeric | Yes* | decimal:0,2, 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
json
{
"name": "Premium Features Unlock",
"return_url": "https://myapp.com/billing/success",
"price": {
"amount": 29.99
},
"test": false
}Response
json
[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 merchant to confirmation_url immediately after receiving this response.
Tip
The charge remains in pending status until the merchant approves or declines it. Verify the final status via List charges after the merchant 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 merchant to approve or decline the charge. Only present when status is pending. |