> For the complete documentation index, see [llms.txt](https://apidocs.onekeypayments.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.onekeypayments.com/api-documentation/subscriptions-api/subscription-creation-endpoints/oneshot-subscription-creation.md).

# OneShot Subscription Creation

### Endpoint

<mark style="color:orange;background-color:orange;">**POST**</mark> `https://api-stg.onekeypayments.com/v3/subscriptions`

### Process

1. Merchant submits subscription request with customer and billing information
2. API returns a redirect URL to our secure payment page
3. Customer completes payment on our PCI-compliant page
4. System creates subscription and notifies merchant via webhook
5. Customer is redirected to merchant's success/error URL

<details>

<summary>Request Example</summary>

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "invoice_id": "INV123456",
  "amount": 70.00,
  "currency": "BRL",
  "country": "BR",
  "payer": {
    "id": "PAYER123",
    "document": "123456789",
    "document_type": "CPF",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "description": "Premium Subscription",
  "subscription": {
    "start_date": "2025-01-01",
    "plan": "MONTHLY",
    "plan_unit": 1,
    "auto_renewal": false
  },
  "client_ip": "192.168.1.1",
  "back_url": "https://example.com/back",
  "success_url": "https://example.com/success",
  "error_url": "https://example.com/error",
  "notification_url": "https://example.com/notify"
}
</code></pre>

</details>

{% openapi src="/files/ks4AhUAUNTfDaWAM9JUw" path="/v3/subscriptions" method="post" %}
[okpsubs-creation-v4.yml](https://1595349702-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7aIgg5dys0yN8otrASQq%2Fuploads%2FOpdo17wIZu49H12a5agC%2Fokpsubs-creation-v4.yml?alt=media\&token=4678aef6-1c07-4d01-a777-50dfa63b068d)
{% endopenapi %}

### Successful Response fields

| Field             | Type               | Description                                                        | Example                                                                                                     |
| ----------------- | ------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `subscription_id` | Integer            | Unique identifier of the created subscription                      | 1234                                                                                                        |
| `redirect_url`    | String (URI)       | URL to redirect the user to complete the subscription process      | "<https://checkout.cc-dev.onekeypayments.net/validate/6mIsesbbmvYn2hzAOwuYQSMAYIyISUgl?subscriptionId=513>" |
| `expiration_date` | String (Date-time) | Expiration date and time for the subscription checkout process     | "2025-03-06 15:58:02"                                                                                       |
| `payment_amount`  | Number (Double)    | Amount to be charged for the subscription                          | 70.00                                                                                                       |
| `redirect`        | Boolean            | Indicates if the user should be redirected to complete the process | true                                                                                                        |

#### **Response Example**

```json
{
  "subscription_id": 1234,
  "redirect_url": "https://checkout.cc-dev.onekeypayments.net/validate/6mIsesbbmvYn2hzAOwuYQSMAYIyISUgl?subscriptionId=513",
  "expiration_date": "2025-03-06 15:58:02",
  "payment_amount": 70.00,
  "redirect": true
}
```

### Error Response Structure

<table><thead><tr><th>Field</th><th width="128.3515625">Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>code</code></td><td>Integer</td><td>Error code indicating the type of error</td><td>400</td></tr><tr><td><code>description</code></td><td>String</td><td>Human-readable description of the error</td><td>"Invalid input data"</td></tr><tr><td><code>type</code></td><td>String</td><td>Machine-readable error type identifier</td><td>"VALIDATION_ERROR"</td></tr></tbody></table>

#### Bad Request - Invalid input data

```json
{
  "code": 400,
  "description": "Invalid input data",
  "type": "VALIDATION_ERROR"
}
```

#### Unprocessable Entity - Validation error

```json
{
  "code": 422,
  "description": "Validation error",
  "type": "VALIDATION_ERROR"
}
```

#### Service Unavailable - Error creating subscription

```json
{
  "code": 503,
  "description": "Error creating subscription",
  "type": "SERVICE_ERROR"
}
```

### Subscription Plans

The following subscription frequencies are supported:

| Plan       | Description                   |
| ---------- | ----------------------------- |
| `DAILY`    | Recurring billing every day   |
| `WEEKLY`   | Recurring billing every week  |
| `MONTHLY`  | Recurring billing every month |
| `ANNUALLY` | Recurring billing every year  |

{% hint style="success" %}

#### Tests in STG Environment. <a href="#tests-in-stg-environment" id="tests-in-stg-environment"></a>

To test the Subscriptions API in the staging environment, use the parameter `plan` with the value `TEST` inside the `subscription[]` object when calling either the OneShot or PCI endpoints.

This triggers simulated deposits **every minute**, along with the corresponding webhook events, so you can quickly verify the full subscription lifecycle.\
The number of deposits generated depends on the value of the `plan_unit` parameter, making it easy to observe the expected behavior in just a few minutes.
{% endhint %}