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
Merchant submits subscription request with customer and billing information
API returns a redirect URL to our secure payment page
Customer completes payment on our PCI-compliant page
System creates subscription and notifies merchant via webhook
Customer is redirected to merchant's success/error URL
This endpoint allows the creation of a new subscription with payment details.
Media type of the body sent to the API.
application/jsonISO8601 Datetime with Timezone (yyyy-MM-dd'T'HH:mm:ssZ)
Merchant X-Login API Key.
Authorization control hash.
Unique idempotency key for ensuring that the same request is not processed more than once.
Unique identifier for the invoice
INV123456Amount to be charged for the subscription
70Three-letter currency code (ISO 4217)
BRLTwo-letter country code (ISO 3166-1 alpha-2)
BRDescription of the subscription
Premium SubscriptionIP address of the client
192.168.1.1URL to redirect after payment process
https://example.com/backURL to redirect after successful payment
https://example.com/successURL to redirect after failed payment
https://example.com/errorURL to send payment status notifications
https://example.com/notifySubscription created successfully
Bad Request - Invalid input data
Unprocessable Entity - Validation error
Service Unavailable - Error creating subscription
POST /v3/subscriptions HTTP/1.1
Host: api-stg.onekeypayments.com
Content-Type: application/json
X-Date: 2025-11-15T05:10:30.095Z
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": "[email protected]",
"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
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
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:
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.
Last updated