> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a top-up payment link > Mints a Razorpay-hosted Payment Link for `amount_rupees` plus GST. Open or forward the `short_url`; when it is paid, `base` is added to **this API key's workspace wallet** — the same balance `GET /billing/balance` reports. Poll `GET /billing/topup/links/{payment_order_id}` to learn when the credit lands; there is no callback. Links expire 24 hours after creation. At most 5 open links per account at once (a link is open until it is paid, expires, or a payment attempt is made on it); a sixth returns `409 OPEN_ORDER_LIMIT`. Link creation is also limited to 10 per hour per account (`429`); the 5-link cap is the limit you will hit first. The link always credits your own wallet. Do not forward it to your end-customers as a way to bill them — the money lands in your account, not theirs, and a chargeback on their card is charged back to you. ## OpenAPI ````yaml /openapi.json post /billing/topup/links openapi: 3.1.0 info: title: Vocobase API version: '2.0' description: >- API for managing voice AI agents, documents, and calls on the Vocobase platform. servers: - url: https://api.vocobase.com/api/v2 description: Production security: - bearerAuth: [] tags: - name: Config description: >- Read and update account configuration, webhook settings, and telephony credentials. - name: Agents description: Create, read, update, and delete voice AI agents. - name: Voices description: >- List voice tiers, available voices, and stream preview audio for agent configuration. - name: Documents description: Upload, manage, and delete knowledge base documents. - name: Agent Documents description: Link and unlink documents to agents for knowledge base integration. - name: Calls description: Initiate outbound calls and view call history. - name: Phone Numbers description: >- Import DIDs, assign agents for inbound routing, and re-sync carrier Application bindings. - name: Inbound Routing Policies description: >- Define pre-answer routing decisions for inbound calls before AI sessions are created. - name: Telephony Connections description: Create, list, rename, and disconnect named V2 telephony connections. - name: VoiceLink Management description: Manage VoiceLink reseller clients, DID mapping, and readiness sync. - name: Projects description: Organize agents into projects. Every agent belongs to exactly one project. - name: Dictionaries description: Speech-recognition dictionary CRUD and agent attachment. - name: Sessions description: Browser-initiated WebRTC voice sessions for in-app voice agents. - name: Campaigns description: Batch outbound calling. - name: Billing description: Balance, transactions, and usage summaries. - name: Custom Functions description: HTTP endpoints the agent can call mid-conversation. - name: Extraction Sets description: Reusable sets of post-call extraction fields. - name: Lifecycle Hooks description: Automatic pre-call and post-call integration steps. - name: Messaging description: Bring-your-own WhatsApp sending. - name: Integration Logs description: Audit trail for integration calls. - name: Connectors description: Catalog of tools an agent can be connected to. - name: Customers description: B2B2B sub-tenants and their tool connections. - name: Agent Tools description: Binding connectors and connections to an agent. paths: /billing/topup/links: post: tags: - Billing summary: Create a top-up payment link description: >- Mints a Razorpay-hosted Payment Link for `amount_rupees` plus GST. Open or forward the `short_url`; when it is paid, `base` is added to **this API key's workspace wallet** — the same balance `GET /billing/balance` reports. Poll `GET /billing/topup/links/{payment_order_id}` to learn when the credit lands; there is no callback. Links expire 24 hours after creation. At most 5 open links per account at once (a link is open until it is paid, expires, or a payment attempt is made on it); a sixth returns `409 OPEN_ORDER_LIMIT`. Link creation is also limited to 10 per hour per account (`429`); the 5-link cap is the limit you will hit first. The link always credits your own wallet. Do not forward it to your end-customers as a way to bill them — the money lands in your account, not theirs, and a chargeback on their card is charged back to you. operationId: createTopupLink requestBody: required: true content: application/json: schema: type: object required: - amount_rupees properties: amount_rupees: type: integer description: >- Whole rupees to add to the wallet, before GST. Must be within the `min` and `max` returned by `GET /billing/topup/config`. Send a JSON number, not a string. example: amount_rupees: 5000 responses: '201': description: Link created. content: application/json: schema: type: object properties: success: type: boolean const: true data: type: object properties: payment_order_id: type: string format: uuid description: Use this to poll status. short_url: type: string format: uri description: Razorpay-hosted checkout page. expires_at: type: string format: date-time base: type: number description: Rupees, to two decimal places. gst: type: number description: Rupees, to two decimal places. total: type: number description: Rupees, to two decimal places. example: success: true data: payment_order_id: 0d5d3d3a-5a1f-4b7f-9a4c-1234567890ab short_url: https://rzp.io/i/abc123 expires_at: '2026-09-07T10:00:00.000Z' base: 5000 gst: 900 total: 5900 '400': description: '`INVALID_AMOUNT` — not a whole number, or outside `min`..`max`.' content: application/json: example: success: false error: code: INVALID_AMOUNT message: amount_rupees must be a whole number between 1000 and 400000 '401': $ref: '#/components/responses/Unauthorized' '409': description: >- `OPEN_ORDER_LIMIT` — 5 unpaid links are already open. Wait for one to be paid or to expire. content: application/json: example: success: false error: code: OPEN_ORDER_LIMIT message: At most 5 unpaid top-up links may be open at once '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError' '502': description: >- `RAZORPAY_LINK_CREATE_FAILED` — the payment provider did not accept the link. Safe to retry, but back off: if the provider timed out, the attempt may still hold one of the 5 open-link slots for up to 24 hours. `PAYMENT_ORDER_PATCH_FAILED` — the link was created but could not be recorded; no `short_url` is returned. Mint a new link. content: application/json: example: success: false error: code: RAZORPAY_LINK_CREATE_FAILED message: Payment provider did not accept the top-up link components: responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key RateLimitExceeded: description: Per-account rate limit exceeded. Retry after a short backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: RATE_LIMITED message: Rate limit exceeded. Retry after 60 seconds. InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred schemas: ErrorResponse: type: object properties: success: type: boolean const: false error: type: object properties: code: type: string message: type: string required: - code - message required: - success - error securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key in format: `rg_live_xxxx`. Pass as a Bearer token in the Authorization header. ````