Create a subscription (OneShot)

Create a new subscription

post

This endpoint allows the creation of a new subscription with payment details.

Header parameters

Content-TypestringRequired

Media type of the body sent to the API.

Default: application/json

X-Datestring · date-timeRequired

ISO8601 Datetime with Timezone (yyyy-MM-dd'T'HH:mm:ssZ)

X-LoginstringRequired

Merchant X-Login API Key.

AuthorizationstringRequired

Authorization control hash.

X-Idempotency-KeystringOptional

Unique idempotency key for ensuring that the same request is not processed more than once.

Body

application/json

invoice_idstringRequired

Unique identifier for the invoice

Example: INV123456

amountnumber · doubleRequired

Amount to be charged for the subscription

Example: 70

currencystringRequired

Three-letter currency code (ISO 4217)

Example: BRL

countrystringRequired

Two-letter country code (ISO 3166-1 alpha-2)

Example: BR

descriptionstringOptional

Description of the subscription

Example: Premium Subscription

client_ipstringOptional

IP address of the client

Example: 192.168.1.1

back_urlstring · uriOptional

URL to redirect after payment process

Example: https://example.com/back

success_urlstring · uriOptional

URL to redirect after successful payment

Example: https://example.com/success

error_urlstring · uriOptional

URL to redirect after failed payment

Example: https://example.com/error

notification_urlstring · uriOptional

URL to send payment status notifications

Example: https://example.com/notify

Responses

200

Subscription created successfully

application/json

subscription_idintegerOptional

Unique identifier of the created subscription

Example: 1234

redirect_urlstring · uriOptional

URL to redirect the user to complete the subscription process

Example: https://checkout.cc-stg.checkoutogate.net/validate/6mIsesbbmvYn2hzAOwuYQSMAYIyISUgl?subscriptionId=513

expiration_datestring · date-timeOptional

Expiration date and time for the subscription checkout process

Example: 2025-03-06 15:58:02

payment_amountnumber · doubleOptional

Amount to be charged for the subscription

Example: 70

redirectbooleanOptional

Indicates if the user should be redirected to complete the process

Example: true

400

Bad Request - Invalid input data

application/json

422

Unprocessable Entity - Validation error

application/json

503

Service Unavailable - Error creating subscription

application/json

post

/v3/subscriptions

HTTPcURLJavaScriptPython

POST /v3/subscriptions HTTP/1.1
Host: api-stg.onekeypayments.com
X-Date: 2026-03-03T02:47:42.405Z
X-Login: text
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 547

{
  "invoice_id": "INV123456",
  "amount": 70,
  "currency": "BRL",
  "country": "BR",
  "payer": {
    "id": "PAYER123",
    "document": 123456789,
    "document_type": "CPF",
    "email": "[email protected]",
    "first_name": "Roberto",
    "last_name": "Carlos"
  },
  "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"
}

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