# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.onekeypayments.com/api-documentation/subscriptions-api/subscription-creation-endpoints/oneshot-subscription-creation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.