> ## Documentation Index > Fetch the complete documentation index at: https://docs.unibee.dev/llms.txt > Use this file to discover all available pages before exploring further. # New Subscription Payment ## 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 `` | | `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 ```bash theme={null} 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 ```bash theme={null} 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. ## OpenAPI ````yaml post /merchant/subscription/payment/new openapi: 3.0.0 info: description: UniBee Api Server license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html title: OpenAPI UniBee version: daily,buildtime:202603161017 servers: - url: https://api.unibee.dev - url: https://api-sandbox.unibee.top security: - Authorization: [] paths: /merchant/subscription/payment/new: post: tags: - Subscription Payment summary: New Subscription Payment requestBody: content: application/json: schema: $ref: >- #/components/schemas/unibee.api.merchant.subscription.NewPaymentReq required: true responses: '200': content: application/json: schema: properties: code: format: int properties: {} type: integer data: properties: action: $ref: >- #/components/schemas/github.com.gogf.gf.v2.encoding.gjson.Json externalPaymentId: description: The external unique id of payment format: string properties: {} type: string link: format: string properties: {} type: string paymentId: description: The unique id of payment format: string properties: {} type: string status: description: Status, 10-Created|20-Success|30-Failed|40-Cancelled format: int properties: {} type: integer type: object merchantId: format: int64 properties: {} type: integer message: format: string properties: {} type: string redirect: format: string properties: {} type: string requestId: format: string properties: {} type: string type: object description: '' components: schemas: unibee.api.merchant.subscription.NewPaymentReq: properties: cancelUrl: description: CancelUrl format: string properties: {} type: string countryCode: description: CountryCode format: string properties: {} type: string currency: description: Currency, either Currency&TotalAmount or PlanId needed format: string properties: {} type: string description: description: Description format: string properties: {} type: string email: description: Email, either ExternalUserId&Email or UserId needed format: string properties: {} type: string externalPaymentId: description: ExternalPaymentId should unique for payment format: string properties: {} type: string externalUserId: description: ExternalUserId, unique, either ExternalUserId&Email or UserId needed format: string properties: {} type: string gasPayer: description: who pay the gas, merchant|user format: string properties: {} type: string gatewayId: description: GatewayId format: int64 properties: {} type: integer items: description: Items format: '[]*payment.Item' items: $ref: '#/components/schemas/unibee.api.merchant.payment.Item' properties: {} type: array metadata: additionalProperties: $ref: '#/components/schemas/interface' description: Metadata，Map format: map[string]interface {} properties: {} type: object name: description: Name format: string properties: {} type: string planId: description: PlanId, either TotalAmount&Currency or PlanId needed format: int64 properties: {} type: integer redirectUrl: description: Redirect Url format: string properties: {} type: string totalAmount: description: >- Total PaymentAmount, Cent, either TotalAmount&Currency or PlanId needed format: int64 properties: {} type: integer userId: description: UserId, either ExternalUserId&Email or UserId needed format: int64 properties: {} type: integer required: - gatewayId type: object github.com.gogf.gf.v2.encoding.gjson.Json: properties: {} type: object unibee.api.merchant.payment.Item: properties: amount: description: >- item total amount, sum(item.amount) should equal to totalAmount, cent format: int64 properties: {} type: integer amountExcludingTax: description: amountExcludingTax = unitAmountExcludingTax * quantity format: int64 properties: {} type: integer currency: description: The item currency of payment format: string properties: {} type: string description: description: The item description of payment format: string properties: {} type: string name: description: The item name of payment format: string properties: {} type: string quantity: description: The item quantity of payment format: int64 properties: {} type: integer tax: description: tax = amount - amountExcludingTax format: int64 properties: {} type: integer taxPercentage: description: The tax percentage of payment，1000 = 10% format: int64 properties: {} type: integer unitAmountExcludingTax: format: int64 properties: {} type: integer required: - amount type: object interface: properties: {} type: object securitySchemes: Authorization: bearerFormat: JWT scheme: bearer type: http ````