OneShot Subscription Creation

The OneShot flow is designed for merchants who are not PCI compliant and cannot handle payment card data directly.

Endpoint

POST 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

Request Example

{
  "invoice_id": "INV123456",
  "amount": 70.00,
  "currency": "BRL",
  "country": "BR",
  "payer": {
    "id": "PAYER123",
    "document": "123456789",
    "document_type": "CPF",
    "email": "[e-mail]",
    "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"
}

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

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

post

HTTPcURLJavaScriptPython

POST /v3/subscriptions HTTP/1.1
Host: api-stg.onekeypayments.com
Content-Type: application/json
X-Date: 2025-04-27T01:32:55.339Z
X-Login: text
Authorization: text
Accept: */*
Content-Length: 547

{
  "invoice_id": "INV123456",
  "amount": 70,
  "currency": "BRL",
  "country": "BR",
  "payer": {
    "id": "PAYER123",
    "document": 123456789,
    "document_type": "CPF",
    "email": "[e-mail]",
    "first_name": "Roberto",
    "last_name": "Carlos"
  },
  "description": "Premium Subscription",
  "subscription": {
    "start_date": "2025-01-01",
    "plan": "MONTHLY",
    "plan_unit": 3,
    "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
}

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

{
  "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

Field	Type	Description	Example
code	Integer	Error code indicating the type of error	400
description	String	Human-readable description of the error	"Invalid input data"
type	String	Machine-readable error type identifier	"VALIDATION_ERROR"

Bad Request - Invalid input data

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

Unprocessable Entity - Validation error

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

Service Unavailable - Error creating subscription

{
  "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

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.