# OneShot Subscription Creation

### Endpoint

<mark style="color:orange;background-color:orange;">**POST**</mark> `https://api-stg.directa24.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="<https://1770394879-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnTyHI84quh3WRqHk04Z4%2Fuploads%2Fu2Pk5TRedrtOuyisMVBj%2Fsubs-creation-v3.yml?alt=media&token=a0aa8231-891f-4580-b784-d35fa654c7a1>" path="/v3/subscriptions" method="post" %}
[subs-creation-v3.yml](https://1770394879-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnTyHI84quh3WRqHk04Z4%2Fuploads%2Fu2Pk5TRedrtOuyisMVBj%2Fsubs-creation-v3.yml?alt=media\&token=a0aa8231-891f-4580-b784-d35fa654c7a1)
{% 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.directa24.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.directa24.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.

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