New Subscription Payment

curl --request POST \
  --url https://api.unibee.dev/merchant/subscription/payment/new \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "gatewayId": 123,
  "cancelUrl": "<string>",
  "countryCode": "<string>",
  "currency": "<string>",
  "description": "<string>",
  "email": "<string>",
  "externalPaymentId": "<string>",
  "externalUserId": "<string>",
  "gasPayer": "<string>",
  "items": [
    {
      "amount": 123,
      "amountExcludingTax": 123,
      "currency": "<string>",
      "description": "<string>",
      "name": "<string>",
      "quantity": 123,
      "tax": 123,
      "taxPercentage": 123,
      "unitAmountExcludingTax": 123
    }
  ],
  "metadata": {},
  "name": "<string>",
  "planId": 123,
  "redirectUrl": "<string>",
  "totalAmount": 123,
  "userId": 123
}
'

import requests

url = "https://api.unibee.dev/merchant/subscription/payment/new"

payload = {
    "gatewayId": 123,
    "cancelUrl": "<string>",
    "countryCode": "<string>",
    "currency": "<string>",
    "description": "<string>",
    "email": "<string>",
    "externalPaymentId": "<string>",
    "externalUserId": "<string>",
    "gasPayer": "<string>",
    "items": [
        {
            "amount": 123,
            "amountExcludingTax": 123,
            "currency": "<string>",
            "description": "<string>",
            "name": "<string>",
            "quantity": 123,
            "tax": 123,
            "taxPercentage": 123,
            "unitAmountExcludingTax": 123
        }
    ],
    "metadata": {},
    "name": "<string>",
    "planId": 123,
    "redirectUrl": "<string>",
    "totalAmount": 123,
    "userId": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    gatewayId: 123,
    cancelUrl: '<string>',
    countryCode: '<string>',
    currency: '<string>',
    description: '<string>',
    email: '<string>',
    externalPaymentId: '<string>',
    externalUserId: '<string>',
    gasPayer: '<string>',
    items: [
      {
        amount: 123,
        amountExcludingTax: 123,
        currency: '<string>',
        description: '<string>',
        name: '<string>',
        quantity: 123,
        tax: 123,
        taxPercentage: 123,
        unitAmountExcludingTax: 123
      }
    ],
    metadata: {},
    name: '<string>',
    planId: 123,
    redirectUrl: '<string>',
    totalAmount: 123,
    userId: 123
  })
};

fetch('https://api.unibee.dev/merchant/subscription/payment/new', 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://api.unibee.dev/merchant/subscription/payment/new",
  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([
    'gatewayId' => 123,
    'cancelUrl' => '<string>',
    'countryCode' => '<string>',
    'currency' => '<string>',
    'description' => '<string>',
    'email' => '<string>',
    'externalPaymentId' => '<string>',
    'externalUserId' => '<string>',
    'gasPayer' => '<string>',
    'items' => [
        [
                'amount' => 123,
                'amountExcludingTax' => 123,
                'currency' => '<string>',
                'description' => '<string>',
                'name' => '<string>',
                'quantity' => 123,
                'tax' => 123,
                'taxPercentage' => 123,
                'unitAmountExcludingTax' => 123
        ]
    ],
    'metadata' => [
        
    ],
    'name' => '<string>',
    'planId' => 123,
    'redirectUrl' => '<string>',
    'totalAmount' => 123,
    'userId' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://api.unibee.dev/merchant/subscription/payment/new"

	payload := strings.NewReader("{\n  \"gatewayId\": 123,\n  \"cancelUrl\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"description\": \"<string>\",\n  \"email\": \"<string>\",\n  \"externalPaymentId\": \"<string>\",\n  \"externalUserId\": \"<string>\",\n  \"gasPayer\": \"<string>\",\n  \"items\": [\n    {\n      \"amount\": 123,\n      \"amountExcludingTax\": 123,\n      \"currency\": \"<string>\",\n      \"description\": \"<string>\",\n      \"name\": \"<string>\",\n      \"quantity\": 123,\n      \"tax\": 123,\n      \"taxPercentage\": 123,\n      \"unitAmountExcludingTax\": 123\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"planId\": 123,\n  \"redirectUrl\": \"<string>\",\n  \"totalAmount\": 123,\n  \"userId\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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://api.unibee.dev/merchant/subscription/payment/new")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"gatewayId\": 123,\n  \"cancelUrl\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"description\": \"<string>\",\n  \"email\": \"<string>\",\n  \"externalPaymentId\": \"<string>\",\n  \"externalUserId\": \"<string>\",\n  \"gasPayer\": \"<string>\",\n  \"items\": [\n    {\n      \"amount\": 123,\n      \"amountExcludingTax\": 123,\n      \"currency\": \"<string>\",\n      \"description\": \"<string>\",\n      \"name\": \"<string>\",\n      \"quantity\": 123,\n      \"tax\": 123,\n      \"taxPercentage\": 123,\n      \"unitAmountExcludingTax\": 123\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"planId\": 123,\n  \"redirectUrl\": \"<string>\",\n  \"totalAmount\": 123,\n  \"userId\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unibee.dev/merchant/subscription/payment/new")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"gatewayId\": 123,\n  \"cancelUrl\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"description\": \"<string>\",\n  \"email\": \"<string>\",\n  \"externalPaymentId\": \"<string>\",\n  \"externalUserId\": \"<string>\",\n  \"gasPayer\": \"<string>\",\n  \"items\": [\n    {\n      \"amount\": 123,\n      \"amountExcludingTax\": 123,\n      \"currency\": \"<string>\",\n      \"description\": \"<string>\",\n      \"name\": \"<string>\",\n      \"quantity\": 123,\n      \"tax\": 123,\n      \"taxPercentage\": 123,\n      \"unitAmountExcludingTax\": 123\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"planId\": 123,\n  \"redirectUrl\": \"<string>\",\n  \"totalAmount\": 123,\n  \"userId\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "code": 123,
  "data": {
    "action": {},
    "externalPaymentId": "<string>",
    "link": "<string>",
    "paymentId": "<string>",
    "status": 123
  },
  "merchantId": 123,
  "message": "<string>",
  "redirect": "<string>",
  "requestId": "<string>"
}

POST

merchant

subscription

payment

new

New Subscription Payment

curl --request POST \
  --url https://api.unibee.dev/merchant/subscription/payment/new \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "gatewayId": 123,
  "cancelUrl": "<string>",
  "countryCode": "<string>",
  "currency": "<string>",
  "description": "<string>",
  "email": "<string>",
  "externalPaymentId": "<string>",
  "externalUserId": "<string>",
  "gasPayer": "<string>",
  "items": [
    {
      "amount": 123,
      "amountExcludingTax": 123,
      "currency": "<string>",
      "description": "<string>",
      "name": "<string>",
      "quantity": 123,
      "tax": 123,
      "taxPercentage": 123,
      "unitAmountExcludingTax": 123
    }
  ],
  "metadata": {},
  "name": "<string>",
  "planId": 123,
  "redirectUrl": "<string>",
  "totalAmount": 123,
  "userId": 123
}
'

import requests

url = "https://api.unibee.dev/merchant/subscription/payment/new"

payload = {
    "gatewayId": 123,
    "cancelUrl": "<string>",
    "countryCode": "<string>",
    "currency": "<string>",
    "description": "<string>",
    "email": "<string>",
    "externalPaymentId": "<string>",
    "externalUserId": "<string>",
    "gasPayer": "<string>",
    "items": [
        {
            "amount": 123,
            "amountExcludingTax": 123,
            "currency": "<string>",
            "description": "<string>",
            "name": "<string>",
            "quantity": 123,
            "tax": 123,
            "taxPercentage": 123,
            "unitAmountExcludingTax": 123
        }
    ],
    "metadata": {},
    "name": "<string>",
    "planId": 123,
    "redirectUrl": "<string>",
    "totalAmount": 123,
    "userId": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    gatewayId: 123,
    cancelUrl: '<string>',
    countryCode: '<string>',
    currency: '<string>',
    description: '<string>',
    email: '<string>',
    externalPaymentId: '<string>',
    externalUserId: '<string>',
    gasPayer: '<string>',
    items: [
      {
        amount: 123,
        amountExcludingTax: 123,
        currency: '<string>',
        description: '<string>',
        name: '<string>',
        quantity: 123,
        tax: 123,
        taxPercentage: 123,
        unitAmountExcludingTax: 123
      }
    ],
    metadata: {},
    name: '<string>',
    planId: 123,
    redirectUrl: '<string>',
    totalAmount: 123,
    userId: 123
  })
};

fetch('https://api.unibee.dev/merchant/subscription/payment/new', 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://api.unibee.dev/merchant/subscription/payment/new",
  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([
    'gatewayId' => 123,
    'cancelUrl' => '<string>',
    'countryCode' => '<string>',
    'currency' => '<string>',
    'description' => '<string>',
    'email' => '<string>',
    'externalPaymentId' => '<string>',
    'externalUserId' => '<string>',
    'gasPayer' => '<string>',
    'items' => [
        [
                'amount' => 123,
                'amountExcludingTax' => 123,
                'currency' => '<string>',
                'description' => '<string>',
                'name' => '<string>',
                'quantity' => 123,
                'tax' => 123,
                'taxPercentage' => 123,
                'unitAmountExcludingTax' => 123
        ]
    ],
    'metadata' => [
        
    ],
    'name' => '<string>',
    'planId' => 123,
    'redirectUrl' => '<string>',
    'totalAmount' => 123,
    'userId' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://api.unibee.dev/merchant/subscription/payment/new"

	payload := strings.NewReader("{\n  \"gatewayId\": 123,\n  \"cancelUrl\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"description\": \"<string>\",\n  \"email\": \"<string>\",\n  \"externalPaymentId\": \"<string>\",\n  \"externalUserId\": \"<string>\",\n  \"gasPayer\": \"<string>\",\n  \"items\": [\n    {\n      \"amount\": 123,\n      \"amountExcludingTax\": 123,\n      \"currency\": \"<string>\",\n      \"description\": \"<string>\",\n      \"name\": \"<string>\",\n      \"quantity\": 123,\n      \"tax\": 123,\n      \"taxPercentage\": 123,\n      \"unitAmountExcludingTax\": 123\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"planId\": 123,\n  \"redirectUrl\": \"<string>\",\n  \"totalAmount\": 123,\n  \"userId\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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://api.unibee.dev/merchant/subscription/payment/new")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"gatewayId\": 123,\n  \"cancelUrl\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"description\": \"<string>\",\n  \"email\": \"<string>\",\n  \"externalPaymentId\": \"<string>\",\n  \"externalUserId\": \"<string>\",\n  \"gasPayer\": \"<string>\",\n  \"items\": [\n    {\n      \"amount\": 123,\n      \"amountExcludingTax\": 123,\n      \"currency\": \"<string>\",\n      \"description\": \"<string>\",\n      \"name\": \"<string>\",\n      \"quantity\": 123,\n      \"tax\": 123,\n      \"taxPercentage\": 123,\n      \"unitAmountExcludingTax\": 123\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"planId\": 123,\n  \"redirectUrl\": \"<string>\",\n  \"totalAmount\": 123,\n  \"userId\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unibee.dev/merchant/subscription/payment/new")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"gatewayId\": 123,\n  \"cancelUrl\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"description\": \"<string>\",\n  \"email\": \"<string>\",\n  \"externalPaymentId\": \"<string>\",\n  \"externalUserId\": \"<string>\",\n  \"gasPayer\": \"<string>\",\n  \"items\": [\n    {\n      \"amount\": 123,\n      \"amountExcludingTax\": 123,\n      \"currency\": \"<string>\",\n      \"description\": \"<string>\",\n      \"name\": \"<string>\",\n      \"quantity\": 123,\n      \"tax\": 123,\n      \"taxPercentage\": 123,\n      \"unitAmountExcludingTax\": 123\n    }\n  ],\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"planId\": 123,\n  \"redirectUrl\": \"<string>\",\n  \"totalAmount\": 123,\n  \"userId\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "code": 123,
  "data": {
    "action": {},
    "externalPaymentId": "<string>",
    "link": "<string>",
    "paymentId": "<string>",
    "status": 123
  },
  "merchantId": 123,
  "message": "<string>",
  "redirect": "<string>",
  "requestId": "<string>"
}

Endpoint Overview

POST https://api.unibee.dev/merchant/subscription/payment/new New Subscription Payment

Authorization

All UniBee Merchant API requests require authentication via API key.

Header	Required	Description
`Authorization`	Yes	Bearer `<your_api_key>`
`Content-Type`	Yes	`application/json` (for request body)

Parameters

Parameters for this endpoint are listed below. The schema is also shown in the Try it panel.

Request body

Name	Type	Required	Description
`cancelUrl`	string	No	CancelUrl
`countryCode`	string	No	CountryCode
`currency`	string	No	Currency, either Currency&TotalAmount or PlanId needed
`description`	string	No	Description
`email`	string	No	Email, either ExternalUserId&Email or UserId needed
`externalPaymentId`	string	No	ExternalPaymentId should unique for payment
`externalUserId`	string	No	ExternalUserId, unique, either ExternalUserId&Email or UserId needed
`gasPayer`	string	No	who pay the gas, merchant\|user
`gatewayId`	integer	Yes	GatewayId
`items`	array	No	Items
`metadata`	object	No	Metadata，Map
`name`	string	No	Name
`planId`	integer	No	PlanId, either TotalAmount&Currency or PlanId needed
`redirectUrl`	string	No	Redirect Url
`totalAmount`	integer	No	Total PaymentAmount, Cent, either TotalAmount&Currency or PlanId needed
`userId`	integer	No	UserId, either ExternalUserId&Email or UserId needed

Request examples

cURL

curl -X POST "https://api.unibee.dev/merchant/subscription/payment/new" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "cancelUrl": "https://example.com",
  "countryCode": "",
  "currency": "",
  "description": "",
  "email": "user@example.com",
  "externalPaymentId": "id_example",
  "externalUserId": "id_example",
  "gasPayer": "",
  "gatewayId": 0,
  "items": [],
  "metadata": {},
  "name": "",
  "planId": 0,
  "redirectUrl": "https://example.com",
  "totalAmount": 0,
  "userId": 0
}'

Sandbox

curl -X POST "https://api-sandbox.unibee.top/merchant/subscription/payment/new" \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "cancelUrl": "https://example.com",
  "countryCode": "",
  "currency": "",
  "description": "",
  "email": "user@example.com",
  "externalPaymentId": "id_example",
  "externalUserId": "id_example",
  "gasPayer": "",
  "gatewayId": 0,
  "items": [],
  "metadata": {},
  "name": "",
  "planId": 0,
  "redirectUrl": "https://example.com",
  "totalAmount": 0,
  "userId": 0
}'

Response

Success responses return a JSON envelope with code, data, message, redirect, and requestId. code 0 indicates success.

Field	Type	Description
`code`	integer	Response code. `0` = success
`data`	object	Response payload
`data.action`	object
`data.externalPaymentId`	string	The external unique id of payment
`data.link`	string
`data.paymentId`	string	The unique id of payment
`data.status`	integer	Status, 10-Created\|20-Success\|30-Failed\|40-Cancelled
`message`	string	Human-readable message
`requestId`	string	Request ID for support

Error handling

HTTP status	Meaning
400	Bad request — invalid or missing parameters. Check `message` in the body.
401	Unauthorized — missing or invalid API key.
404	Not found — invalid path or resource.
500	Server error — retry with backoff.

When code in the response body is non-zero, check message for details. Use requestId when contacting support.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

gatewayId

integer<int64>

required

GatewayId

cancelUrl

string<string>

CancelUrl

countryCode

string<string>

CountryCode

currency

string<string>

Currency, either Currency&TotalAmount or PlanId needed

description

string<string>

Description

string<string>

Email, either ExternalUserId&Email or UserId needed

externalPaymentId

string<string>

ExternalPaymentId should unique for payment

externalUserId

string<string>

ExternalUserId, unique, either ExternalUserId&Email or UserId needed

gasPayer

string<string>

who pay the gas, merchant|user

items

object[]

Items

Show child attributes

metadata

object

Metadata，Map

Show child attributes

name

string<string>

Name

planId

integer<int64>

PlanId, either TotalAmount&Currency or PlanId needed

redirectUrl

string<string>

Redirect Url

totalAmount

integer<int64>

Total PaymentAmount, Cent, either TotalAmount&Currency or PlanId needed

userId

integer<int64>

UserId, either ExternalUserId&Email or UserId needed

Response

200 - application/json

code

integer<int>

data

object

Show child attributes

merchantId

integer<int64>

message

string<string>

redirect

string<string>

requestId

string<string>

Get Subscription Onetime Addon Purchase History List Get Subscription TimeLine List

Start Here

Core Concepts

Guides

Reference

Migration and Deployment

New Subscription Payment

Endpoint Overview

Authorization

Parameters

Request body

Request examples

cURL

Sandbox

Response

Error handling

Authorizations

Body

Response

​Endpoint Overview

​Authorization

​Parameters

​Request body

​Request examples

​cURL

​Sandbox

​Response

​Error handling

Authorizations

Body

Response

Endpoint Overview

Authorization

Parameters

Request body

Request examples

cURL

Sandbox

Response

Error handling