> ## Documentation Index > Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a payment link > Creates a new payment link. The account must be enabled for card payments in the current mode. Returns `400 GATEWAY_NOT_CONFIGURED` when card payments are not configured. ## OpenAPI ````yaml /openapi/payment_links.yaml post /payment_links openapi: 3.0.3 info: title: Ionic Payment Links API version: '2026-05-01' description: > Shareable URLs that redirect buyers to a hosted checkout. A payment link (`pl_…`) is a reusable, configurable URL that redirects to a hosted checkout page where a buyer completes their purchase. Each link carries a set of line items priced from the product catalog, a collect configuration (which contact fields to gather), and optional branding, custom fields, and payment-intent overrides that apply when a checkout session starts from the link. All monetary amounts are integers in the currency's minor unit (for example cents for USD). Timestamps are Unix epoch seconds. Identifiers are opaque, prefixed strings: payment links are `pl_…`. Authentication uses a merchant secret key (`sk_…`) as a bearer token. Read endpoints require the `payment_links:read` permission; write endpoints require `payment_links:write`. The mode of the key (test or live) scopes which links it can see and mutate, and is reflected by each resource's `livemode` field. Mutating endpoints accept an optional `Idempotency-Key` header. Errors are returned as `{ "error": { "code": "...", "message": "..." } }`. servers: - url: '{baseUrl}/v1' variables: baseUrl: default: https://api.ionicfi.com description: API base URL for your environment. security: - secretKey: [] tags: - name: Payment Links description: Create, configure, and activate shareable checkout URLs. paths: /payment_links: post: tags: - Payment Links summary: Create a payment link description: | Creates a new payment link. The account must be enabled for card payments in the current mode. Returns `400 GATEWAY_NOT_CONFIGURED` when card payments are not configured. operationId: payment_links_create parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentLinkRequest' responses: '201': description: The created payment link. content: application/json: schema: $ref: '#/components/schemas/PaymentLink' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - payment_links:write components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation. schema: type: string maxLength: 255 schemas: CreatePaymentLinkRequest: type: object required: - name - currency - amount_total - line_items properties: name: type: string description: Display name shown on the hosted checkout. currency: type: string description: Three-letter ISO currency code. amount_total: type: integer description: Total in minor units (e.g. cents for USD). line_items: type: array description: Price references that make up the order. At least one required. items: $ref: '#/components/schemas/LineItem' description: type: string nullable: true description: Optional description shown on the checkout page. optional_items: type: array description: Add-on items the buyer can choose to include. items: $ref: '#/components/schemas/LineItem' collect_config: allOf: - $ref: '#/components/schemas/CollectConfig' nullable: true description: Contact-information fields to collect at checkout. custom_fields: type: array description: Merchant-defined data fields displayed to the buyer. items: $ref: '#/components/schemas/CustomField' submit_type: type: string nullable: true enum: - pay - book - donate description: Label for the checkout submit button. link_type: type: string nullable: true enum: - one_time - subscription - invoice description: The payment product surface this link represents. theme_id: type: string nullable: true description: Theme id to apply to the checkout page. branding: allOf: - $ref: '#/components/schemas/Branding' nullable: true success_url: type: string nullable: true description: URL to redirect to after a successful payment. cancel_url: type: string nullable: true description: URL to redirect to if the buyer cancels. payment_intent_data: allOf: - $ref: '#/components/schemas/PaymentIntentData' nullable: true description: >- Payment-intent overrides forwarded when a session is created from this link. inactive_message: type: string nullable: true description: Message shown on the checkout when the link is inactive. metadata: type: object additionalProperties: type: string PaymentLink: type: object required: - active - amount_total - cancel_url - collect_config - created_at - currency - description - id - inactive_message - line_items - link_type - livemode - merchant_id - metadata - name - object - submit_type - success_url - theme_id - updated_at - url properties: id: type: string description: Payment link identifier (`pl_…`). object: type: string enum: - payment_link merchant_id: type: string livemode: type: boolean description: True for live-mode links; false for test-mode. active: type: boolean description: False when deactivated; the hosted checkout shows an inactive state. name: type: string description: type: string nullable: true url: type: string description: The public checkout URL (`https://buy.ionicfi.com/c/…`). currency: type: string description: Three-letter ISO currency code. amount_total: type: integer description: Total in minor units. line_items: type: array items: $ref: '#/components/schemas/LineItem' optional_items: type: array items: $ref: '#/components/schemas/LineItem' description: Omitted when the link has no optional add-ons. collect_config: $ref: '#/components/schemas/CollectConfig' custom_fields: type: array items: $ref: '#/components/schemas/CustomField' description: Omitted when the link has no custom fields. submit_type: type: string nullable: true enum: - pay - book - donate link_type: type: string enum: - one_time - subscription - invoice theme_id: type: string nullable: true branding: allOf: - $ref: '#/components/schemas/Branding' nullable: true description: Omitted when no branding overrides are set. success_url: type: string nullable: true cancel_url: type: string nullable: true payment_intent_data: allOf: - $ref: '#/components/schemas/PaymentIntentData' nullable: true description: Omitted when no payment-intent overrides are set. inactive_message: type: string nullable: true metadata: type: object additionalProperties: type: string created_at: type: integer description: Unix epoch seconds. updated_at: type: integer LineItem: type: object required: - price_id - quantity properties: price_id: type: string description: Price id (`price_…`) from the product catalog. quantity: type: integer minimum: 1 adjustable_quantity: allOf: - $ref: '#/components/schemas/AdjustableQuantity' nullable: true description: When present, the buyer may adjust the quantity within these bounds. CollectConfig: type: object required: - email - name - phone - address - require_full_billing_address - require_phone - require_shipping_address - wallet_billing_mode description: Specifies which contact fields to collect at checkout and how. properties: email: type: string enum: - required - optional - hidden description: Collection mode for the buyer's email address. name: type: string enum: - required - optional - hidden description: Collection mode for the buyer's name. phone: type: string enum: - required - optional - hidden description: Collection mode for the buyer's phone number. address: type: string enum: - required - optional - hidden description: Collection mode for the buyer's billing address. require_full_billing_address: type: boolean description: When true, all billing-address sub-fields are required. require_shipping_address: type: boolean description: When true, a separate shipping address form is presented. require_phone: type: boolean description: When true, forces phone collection regardless of the `phone` mode. wallet_billing_mode: type: string enum: - min - full description: >- `min` requests minimal billing data from digital wallets; `full` requests the complete billing address. CustomField: type: object required: - key - label - field_type - required description: A merchant-defined field shown to the buyer at checkout. properties: key: type: string description: Unique identifier used to key the collected value. label: type: string description: Label displayed to the buyer. field_type: type: string enum: - text - numeric - dropdown description: >- `text` is a free-text input; `numeric` accepts numbers only; `dropdown` presents the `options` list. required: type: boolean description: Whether the buyer must fill this field to proceed. options: type: array items: type: string description: Choices for `dropdown` fields. Branding: type: object description: Visual overrides for the hosted checkout page. required: - background_color - border_radius - font_family - icon_url - logo_url - primary_color properties: logo_url: type: string nullable: true description: URL to a logo image. icon_url: type: string nullable: true description: URL to a favicon. primary_color: type: string nullable: true description: Primary brand color in hex (e.g. `#0066cc`). background_color: type: string nullable: true description: Page background color in hex. font_family: type: string nullable: true enum: - Inter - Roboto - Open Sans - Lato - Montserrat - Poppins - Source Sans Pro - Nunito - Raleway - Work Sans description: Font family for the hosted page. One of the supported families. border_radius: type: string nullable: true enum: - rounded - sharp - pill description: Corner style for form elements. PaymentIntentData: type: object description: >- Payment-intent configuration forwarded when a checkout session is created from this link. required: - capture_method - description - reference - setup_future_usage properties: capture_method: type: string nullable: true enum: - automatic - manual description: >- `automatic` captures immediately on confirmation; `manual` authorizes and requires a separate capture. setup_future_usage: type: string nullable: true enum: - on_session - off_session description: Whether the payment method should be saved for future use. metadata: type: object additionalProperties: type: string description: Key-value metadata forwarded to the payment intent. description: type: string nullable: true description: Description forwarded to the payment intent. reference: type: string nullable: true description: Your reference, copied to the PaymentIntent created from this link. Error: type: object properties: error: type: object properties: code: type: string description: A stable, machine-readable error code. message: type: string AdjustableQuantity: type: object required: - minimum - maximum properties: minimum: type: integer description: Minimum quantity the buyer may select. maximum: type: integer description: Maximum quantity the buyer may select. responses: BadRequest: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_REQUEST message: currency and amount_total are required when updating line_items Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The key lacks the required permission, or the merchant is not active. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests. Honour the `Retry-After` header before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: | The API could not return a successful response. For a mutating request, retrieve the resource before retrying because the operation may have completed. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: secretKey: type: http scheme: bearer description: 'A merchant secret key (`sk_…`) sent as `Authorization: Bearer `.' ````