LogoLogo
  • OKP APIs
  • Getting Started with OKP
  • API Documentation
    • Deposits API
      • Technical and Security Aspects
        • Calculating the Signature
      • Endpoints
        • Deposit Creation Endpoint
          • Notifications
        • Transactional Account Endpoint
          • Understanding the Solution
        • PCI Deposit Creation Endpoint
        • Deposit Status Endpoint
        • Payment Methods Endpoint
        • Currency Exchange Endpoint
        • Crypto Exchange Endpoint
        • Country States Codes Endpoint
        • Refund Creation Endpoint
          • Notifications
        • Refund Status Endpoint
      • Payment Methods
        • 馃寧America
          • 馃嚙馃嚪Brazil
            • PIX Biometric
      • API Codes
    • Cashouts API
      • Technical and Security Aspects
        • Calculating the Payload-Signature
      • Endpoints
        • Cashout Creation Endpoint
          • Notifications
        • Cashout Status Endpoint
        • Cashout Update Status Endpoint
        • Cashout Cancellation Endpoint
        • Cashout Bank Codes
      • Countries Validations
        • American Countries
          • 馃嚙馃嚪Brazil
      • API Codes
    • Subscriptions API
      • Technical and Security Aspects
        • Calculating the Signature
      • Subscription Creation Endpoints
        • OneShot Subscription Creation
        • PCI Subscription Creation Endpoint
        • Notifications
      • Subscription Cancellation Endpoint
      • Subscription Status Endpoint
    • Quickpay
      • Endpoints
        • Deposit creation endpoint
          • Notifications
        • Deposit status endpoint
    • Bank Account Validation
      • Technical and Security Aspects
        • Calculating the Signature
      • Endpoints
        • Bank Account Validation Endpoint
          • Pix Key Validation and Details Endpoint
      • API Codes
    • KYC API
      • Technical and Security Aspects
        • Calculating the Signature
      • KYC Endpoint
      • API Codes
  • Deposits Tools
    • Cards SDK
      • With User Interface
        • 馃殌Color Customization
      • Without User Interface
    • Java SDK
    • PHP SDK
  • Knowledge Base
    • Deposits with Cards SDK
      • With User Interface
      • Without User Interface
    • Countries Specifications
  • PLUGINS
    • WooCommerce
      • Installation
      • Configuration
  • Status Page
Powered by GitBook
On this page
  1. API Documentation
  2. Subscriptions API
  3. Subscription Creation Endpoints

OneShot Subscription Creation

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

PreviousSubscription Creation EndpointsNextPCI Subscription Creation Endpoint

Last updated 1 month ago

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": "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"
}

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.

  • Endpoint
  • Process
  • POSTCreate a new subscription
  • Successful Response fields
  • Error Response Structure
  • Subscription Plans

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
200
Subscription created successfully
application/json
400
Bad Request - Invalid input data
application/json
422
Unprocessable Entity - Validation error
application/json
503
Service Unavailable - Error creating subscription
application/json
post
POST /v3/subscriptions HTTP/1.1
Host: api-stg.onekeypayments.com
Content-Type: application/json
X-Date: 2025-05-15T13:12:54.860Z
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": "robertocarlos@example.com",
    "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
}