Subscription - Create
curl --request POST \
--url https://sandbox.birrpay.io/subscriptions/create \
--header 'Content-Type: application/json' \
--header 'X-Profile-Id: <x-profile-id>' \
--header 'api-key: <api-key>' \
--data '
{
"customer_id": "cust_123456789",
"item_price_id": "standard-plan-USD-Monthly",
"payment_details": {
"authentication_type": "no_three_ds",
"capture_method": "automatic",
"return_url": "https://google.com",
"setup_future_usage": "off_session"
}
}
'import requests
url = "https://sandbox.birrpay.io/subscriptions/create"
payload = {
"customer_id": "cust_123456789",
"item_price_id": "standard-plan-USD-Monthly",
"payment_details": {
"authentication_type": "no_three_ds",
"capture_method": "automatic",
"return_url": "https://google.com",
"setup_future_usage": "off_session"
}
}
headers = {
"X-Profile-Id": "<x-profile-id>",
"api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Profile-Id': '<x-profile-id>',
'api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
customer_id: 'cust_123456789',
item_price_id: 'standard-plan-USD-Monthly',
payment_details: {
authentication_type: 'no_three_ds',
capture_method: 'automatic',
return_url: 'https://google.com',
setup_future_usage: 'off_session'
}
})
};
fetch('https://sandbox.birrpay.io/subscriptions/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.birrpay.io/subscriptions/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'customer_id' => 'cust_123456789',
'item_price_id' => 'standard-plan-USD-Monthly',
'payment_details' => [
'authentication_type' => 'no_three_ds',
'capture_method' => 'automatic',
'return_url' => 'https://google.com',
'setup_future_usage' => 'off_session'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Profile-Id: <x-profile-id>",
"api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.birrpay.io/subscriptions/create"
payload := strings.NewReader("{\n \"customer_id\": \"cust_123456789\",\n \"item_price_id\": \"standard-plan-USD-Monthly\",\n \"payment_details\": {\n \"authentication_type\": \"no_three_ds\",\n \"capture_method\": \"automatic\",\n \"return_url\": \"https://google.com\",\n \"setup_future_usage\": \"off_session\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Profile-Id", "<x-profile-id>")
req.Header.Add("api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.birrpay.io/subscriptions/create")
.header("X-Profile-Id", "<x-profile-id>")
.header("api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"customer_id\": \"cust_123456789\",\n \"item_price_id\": \"standard-plan-USD-Monthly\",\n \"payment_details\": {\n \"authentication_type\": \"no_three_ds\",\n \"capture_method\": \"automatic\",\n \"return_url\": \"https://google.com\",\n \"setup_future_usage\": \"off_session\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.birrpay.io/subscriptions/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Profile-Id"] = '<x-profile-id>'
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customer_id\": \"cust_123456789\",\n \"item_price_id\": \"standard-plan-USD-Monthly\",\n \"payment_details\": {\n \"authentication_type\": \"no_three_ds\",\n \"capture_method\": \"automatic\",\n \"return_url\": \"https://google.com\",\n \"setup_future_usage\": \"off_session\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"status": "active",
"profile_id": "<string>",
"merchant_id": "<string>",
"customer_id": "<string>",
"merchant_reference_id": "<string>",
"plan_id": "<string>",
"item_price_id": "<string>",
"client_secret": "<string>",
"coupon_code": "<string>",
"payment": {
"payment_id": "<string>",
"status": "succeeded",
"amount": 123,
"currency": "AED",
"profile_id": "<string>",
"connector": "<string>",
"payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
"return_url": "<string>",
"next_action": {
"redirect_to_url": "<string>",
"type": "redirect_to_url"
},
"payment_experience": "redirect_to_url",
"error_code": "<string>",
"error_message": "<string>",
"payment_method_type": "ach",
"client_secret": "<string>",
"billing": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe",
"origin_zip": "08807"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"shipping": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe",
"origin_zip": "08807"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"payment_type": "normal",
"payment_token": "token_sxJdmpUnpNsJk5VWzcjl"
},
"invoice": {
"id": "<string>",
"subscription_id": "<string>",
"merchant_id": "<string>",
"profile_id": "<string>",
"merchant_connector_id": "<string>",
"customer_id": "<string>",
"amount": 123,
"currency": "AED",
"status": "invoice_created",
"payment_intent_id": "<string>",
"payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
"billing_processor_invoice_id": "<string>"
}
}Subscriptions
Subscription - Create
Creates a subscription that requires separate confirmation.
POST
/
subscriptions
/
create
Subscription - Create
curl --request POST \
--url https://sandbox.birrpay.io/subscriptions/create \
--header 'Content-Type: application/json' \
--header 'X-Profile-Id: <x-profile-id>' \
--header 'api-key: <api-key>' \
--data '
{
"customer_id": "cust_123456789",
"item_price_id": "standard-plan-USD-Monthly",
"payment_details": {
"authentication_type": "no_three_ds",
"capture_method": "automatic",
"return_url": "https://google.com",
"setup_future_usage": "off_session"
}
}
'import requests
url = "https://sandbox.birrpay.io/subscriptions/create"
payload = {
"customer_id": "cust_123456789",
"item_price_id": "standard-plan-USD-Monthly",
"payment_details": {
"authentication_type": "no_three_ds",
"capture_method": "automatic",
"return_url": "https://google.com",
"setup_future_usage": "off_session"
}
}
headers = {
"X-Profile-Id": "<x-profile-id>",
"api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Profile-Id': '<x-profile-id>',
'api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
customer_id: 'cust_123456789',
item_price_id: 'standard-plan-USD-Monthly',
payment_details: {
authentication_type: 'no_three_ds',
capture_method: 'automatic',
return_url: 'https://google.com',
setup_future_usage: 'off_session'
}
})
};
fetch('https://sandbox.birrpay.io/subscriptions/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.birrpay.io/subscriptions/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'customer_id' => 'cust_123456789',
'item_price_id' => 'standard-plan-USD-Monthly',
'payment_details' => [
'authentication_type' => 'no_three_ds',
'capture_method' => 'automatic',
'return_url' => 'https://google.com',
'setup_future_usage' => 'off_session'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Profile-Id: <x-profile-id>",
"api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.birrpay.io/subscriptions/create"
payload := strings.NewReader("{\n \"customer_id\": \"cust_123456789\",\n \"item_price_id\": \"standard-plan-USD-Monthly\",\n \"payment_details\": {\n \"authentication_type\": \"no_three_ds\",\n \"capture_method\": \"automatic\",\n \"return_url\": \"https://google.com\",\n \"setup_future_usage\": \"off_session\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Profile-Id", "<x-profile-id>")
req.Header.Add("api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.birrpay.io/subscriptions/create")
.header("X-Profile-Id", "<x-profile-id>")
.header("api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"customer_id\": \"cust_123456789\",\n \"item_price_id\": \"standard-plan-USD-Monthly\",\n \"payment_details\": {\n \"authentication_type\": \"no_three_ds\",\n \"capture_method\": \"automatic\",\n \"return_url\": \"https://google.com\",\n \"setup_future_usage\": \"off_session\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.birrpay.io/subscriptions/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Profile-Id"] = '<x-profile-id>'
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customer_id\": \"cust_123456789\",\n \"item_price_id\": \"standard-plan-USD-Monthly\",\n \"payment_details\": {\n \"authentication_type\": \"no_three_ds\",\n \"capture_method\": \"automatic\",\n \"return_url\": \"https://google.com\",\n \"setup_future_usage\": \"off_session\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"status": "active",
"profile_id": "<string>",
"merchant_id": "<string>",
"customer_id": "<string>",
"merchant_reference_id": "<string>",
"plan_id": "<string>",
"item_price_id": "<string>",
"client_secret": "<string>",
"coupon_code": "<string>",
"payment": {
"payment_id": "<string>",
"status": "succeeded",
"amount": 123,
"currency": "AED",
"profile_id": "<string>",
"connector": "<string>",
"payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
"return_url": "<string>",
"next_action": {
"redirect_to_url": "<string>",
"type": "redirect_to_url"
},
"payment_experience": "redirect_to_url",
"error_code": "<string>",
"error_message": "<string>",
"payment_method_type": "ach",
"client_secret": "<string>",
"billing": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe",
"origin_zip": "08807"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"shipping": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe",
"origin_zip": "08807"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"payment_type": "normal",
"payment_token": "token_sxJdmpUnpNsJk5VWzcjl"
},
"invoice": {
"id": "<string>",
"subscription_id": "<string>",
"merchant_id": "<string>",
"profile_id": "<string>",
"merchant_connector_id": "<string>",
"customer_id": "<string>",
"amount": 123,
"currency": "AED",
"status": "invoice_created",
"payment_intent_id": "<string>",
"payment_method_id": "pm_01926c58bc6e77c09e809964e72af8c8",
"billing_processor_invoice_id": "<string>"
}
}Authorizations
Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.
Headers
Profile ID for authentication
Body
application/json
Request payload for creating a subscription.
This struct captures details required to create a subscription, including plan, profile, merchant connector, and optional customer info.
Identifier for the associated item_price_id for the subscription.
A type for customer_id that can be used for customer ids
Show child attributes
Show child attributes
Merchant specific Unique identifier.
Identifier for the subscription plan.
Optional coupon code applied to the subscription.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Response
Subscription created successfully
Response payload returned after successfully creating a subscription.
Includes details such as subscription ID, status, plan, merchant, and customer info.
A type for subscription_id that can be used for subscription ids
Possible states of a subscription lifecycle.
Created: Subscription was created but not yet activated.Active: Subscription is currently active.InActive: Subscription is inactive.Pending: Subscription is pending activation.Trial: Subscription is in a trial period.Paused: Subscription is paused.Unpaid: Subscription is unpaid.Onetime: Subscription is a one-time payment.Cancelled: Subscription has been cancelled.Failed: Subscription has failed.
Available options:
active, created, in_active, pending, trial, paused, unpaid, onetime, cancelled, failed A type for profile_id that can be used for business profile ids
A type for merchant_id that can be used for merchant ids
A type for customer_id that can be used for customer ids
Merchant specific Unique identifier.
Identifier for the associated subscription plan.
Identifier for the associated item_price_id for the subscription.
This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK
Optional coupon code applied to this subscription.
Show child attributes
Show child attributes
Show child attributes
Show child attributes