--- title: Payment Links description: Create and manage payment links for orders and invoices. --- # Payment Links Create and manage payment links for orders and invoices. ## [GET /payment-links](/api-reference/payment-links#tag/payment-links/GET/payment-links) List payment links Get a list of payment links. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Query parameters - `status` (`array of PaymentLinkStatus`, optional) — Filter by payment link status. - `customerId` (`string`, optional) — Filter by customer ID. - `orderId` (`string`, optional) — Filter by order ID. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ### Responses #### 200 List of payment links. Type: `object` - `items` (`array of PaymentLink`, required) - `paymentLinkId` (`string`, required, example j47ac10b-58cc-4372-a567-0e02b2c3d479) — Unique identifier for the payment link. - `orderId` (`string`, optional, example 44567801-a504-4f09-8089-31ea78bc239b) — The order this payment link collects payment for. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer this payment link collects payment from. - `paymentProvider` (`enum`, optional, one of STRIPE, BILLOGRAM, example STRIPE) — Payment service provider that processes the transaction. - `paymentProfileId` (`string`, optional, example 6ba7b810-9dad-11d1-80b4-00c04fd430c8) — The saved payment method pre-selected for the customer, if any. - `hostedUrl` (`string`, required, uri, example https://checkout.yourapp.com/pay/j47ac10b-58cc-4372-a567-0e02b2c3d479) — The URL where customers can complete their payment. - `status` (`enum`, required, one of ACTIVE, EXPIRED, COMPLETED, CANCELED, FAILED) — Current status of a payment link. - ACTIVE: The link is open and the customer can complete payment. - EXPIRED: The link expired before payment was completed. - COMPLETED: Payment through the link succeeded. - CANCELED: The link was canceled and can no longer be used. - FAILED: Payment through the link failed. - `description` (`string`, optional, example Pay your monthly subscription) — Optional description displayed on the payment page. - `paymentIntentId` (`string`, optional, example 64870b5c-fb61-4c9a-955a-e148e0826c20) — The payment intent that collected the payment, available once the link has been paid. - `completedAt` (`string`, optional, date-time, example 2024-01-15T14:30:00Z) — When the payment was completed, if the link has been paid. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment link was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the payment link was last updated. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/payment-links \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [POST /payment-links](/api-reference/payment-links#tag/payment-links/POST/payment-links) Create payment link Create a new payment link that can be shared with customers to collect payments. Payment links provide a hosted checkout experience without requiring integration with payment widgets or handling sensitive payment data directly. The order must be complete and ready for submission — an order that would fail submission validation is rejected before any payment is collected. Once the payment succeeds, the order is submitted automatically. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `orderId` (`string`, optional, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier of the order to create a payment link for. Either orderId or invoiceId must be provided, not both. - `invoiceId` (`string`, optional, example 123e4567-e89b-12d3-a456-426614174000) — The unique identifier of the invoice to create a payment link for. Either orderId or invoiceId must be provided, not both. Invoice payment links are not yet available in all environments. - `paymentProfileId` (`string`, optional, example 6ba7b810-9dad-11d1-80b4-00c04fd430c8) — A previously saved payment method to prefill on the payment page, for returning customers. - `savePaymentProfile` (`boolean`, optional, example true) — Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false. - `setAsDefaultPaymentProfile` (`boolean`, optional, example false) — Whether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated or for the initial order. Defaults to false. - `description` (`string`, optional, example Payment for Telness mobile subscription) — Optional description to display on the payment page. - `grantAutopayConsent` (`boolean`, optional, example false) — Whether the customer consents to being charged automatically for future renewals. Only applicable if savePaymentProfile is true. Automatic charging also requires a usable default payment profile. Defaults to false. - `returnUrl` (`string`, optional, uri, example https://your-domain.com/success) — URL to redirect customers to after successful payment. - `cancelUrl` (`string`, optional, uri, example https://your-domain.com/cancel) — URL to redirect customers to if they cancel the payment. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ### Responses #### 201 Payment link created successfully. Type: [PaymentLink](/api-reference/models.md#models/PaymentLink) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/payment-links \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "description": "Pay for your mobile subscription order", "savePaymentProfile": true, "returnUrl": "https://example.com/order/confirmation", "cancelUrl": "https://example.com/order/checkout" }' ``` ## [GET /payment-links/{paymentLinkId}](/api-reference/payment-links#tag/payment-links/GET/payment-links/{paymentLinkId}) Get payment link Retrieve details of a specific payment link. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `paymentLinkId` (`string`, required) — The unique identifier for the payment link. ### Responses #### 200 Payment link details. Type: [PaymentLink](/api-reference/models.md#models/PaymentLink) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/payment-links/PAYMENT_LINK_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [POST /payment-links/{paymentLinkId}/cancel](/api-reference/payment-links#tag/payment-links/POST/payment-links/{paymentLinkId}/cancel) Cancel payment link Cancel an active payment link, preventing further payment attempts through the link. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `paymentLinkId` (`string`, required) — The unique identifier for the payment link. ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Responses #### 200 Payment link details. Type: [PaymentLink](/api-reference/models.md#models/PaymentLink) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/payment-links/PAYMENT_LINK_ID/cancel \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ```