Payment Links

Create and manage payment links for orders and invoices.

List payment links

GET/payment-links

Get a list of payment links.

Query parameters

statusarray of PaymentLinkStatus

Filter by payment link status.

customerIdstring

Filter by customer ID.

orderIdstring

Filter by order ID.

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

Responses

200

List of payment links.

application/json

List of payment links.

object

itemsarray of PaymentLinkrequired

Show child attributes

paymentLinkIdstringrequired

Unique identifier for the payment link.

orderIdstring

The order this payment link collects payment for.

customerIdstring

The customer this payment link collects payment from.

paymentProviderenum<string>

Payment service provider that processes the transaction.

values

STRIPE
BILLOGRAM

paymentProfileIdstring

The saved payment method pre-selected for the customer, if any.

hostedUrlstringurirequired

The URL where customers can complete their payment.

statusenum<string>required

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.

values

ACTIVE
EXPIRED
COMPLETED
CANCELED
FAILED

descriptionstring

Optional description displayed on the payment page.

paymentIntentIdstring

The payment intent that collected the payment, available once the link has been paid.

completedAtstringdate-time

When the payment was completed, if the link has been paid.

createdAtstringdate-timerequired

When the payment link was created.

updatedAtstringdate-timerequired

When the payment link was last updated.

metadataobject with string keys

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.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /payment-links

curl https://apiv2.example.com/api/v2/payment-links \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/payment-links', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/payment-links",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/payment-links"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "items": [
    {
      "paymentLinkId": "j47ac10b-58cc-4372-a567-0e02b2c3d479",
      "orderId": "44567801-a504-4f09-8089-31ea78bc239b",
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "paymentProvider": "STRIPE",
      "paymentProfileId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "hostedUrl": "https://checkout.yourapp.com/pay/j47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "ACTIVE",
      "description": "Pay your monthly subscription",
      "paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
      "completedAt": "2024-01-15T14:30:00Z",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z",
      "metadata": {
        "propertyName": "string"
      }
    }
  ]
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Create payment link

POST/payment-links

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.

Headers

X-Idempotency-Keystringmax 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.

BodyCreatePaymentLinkRequestrequiredapplication/json

Request to create a new payment link for processing payment for an order or invoice. Either orderId or invoiceId must be provided, not both.

orderIdstring

The unique identifier of the order to create a payment link for. Either orderId or invoiceId must be provided, not both.

invoiceIdstring

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.

paymentProfileIdstring

A previously saved payment method to prefill on the payment page, for returning customers.

savePaymentProfileboolean

Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.

setAsDefaultPaymentProfileboolean

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.

descriptionstring

Optional description to display on the payment page.

grantAutopayConsentboolean

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.

returnUrlstringuri

URL to redirect customers to after successful payment.

cancelUrlstringuri

URL to redirect customers to if they cancel the payment.

metadataobject with string keys

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.

Show child attributes

*string

Responses

201

Payment link created successfully.

application/json

Payment link created successfully.

objectPaymentLink

A shareable hosted payment page that collects payment for an order at the customer's convenience. Create one when the customer is not in an active checkout flow — for example to send by email or SMS — and anyone with the URL can complete the payment.

Use a payment session instead when the customer is present in your checkout and should be redirected to pay immediately. Both collect against the order's underlying payment intent, which records the resulting charges and refunds.

paymentLinkIdstringrequired

Unique identifier for the payment link.

orderIdstring

The order this payment link collects payment for.

customerIdstring

The customer this payment link collects payment from.

paymentProviderenum<string>

Payment service provider that processes the transaction.

values

STRIPE
BILLOGRAM

paymentProfileIdstring

The saved payment method pre-selected for the customer, if any.

hostedUrlstringurirequired

The URL where customers can complete their payment.

statusenum<string>required

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.

values

ACTIVE
EXPIRED
COMPLETED
CANCELED
FAILED

descriptionstring

Optional description displayed on the payment page.

paymentIntentIdstring

The payment intent that collected the payment, available once the link has been paid.

completedAtstringdate-time

When the payment was completed, if the link has been paid.

createdAtstringdate-timerequired

When the payment link was created.

updatedAtstringdate-timerequired

When the payment link was last updated.

metadataobject with string keys

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.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /payment-links

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"
}'

fetch('https://apiv2.example.com/api/v2/payment-links', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/payment-links",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "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"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/payment-links"

	payload := strings.NewReader(`{
  "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"
}`)

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

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "paymentLinkId": "j47ac10b-58cc-4372-a567-0e02b2c3d479",
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
  "paymentProvider": "STRIPE",
  "hostedUrl": "https://checkout.example.com/pay/j47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "ACTIVE",
  "description": "Pay for your mobile subscription order",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get payment link

GET/payment-links/{paymentLinkId}

Retrieve details of a specific payment link.

Path parameters

paymentLinkIdstringrequired

The unique identifier for the payment link.

Responses

200

Payment link details.

application/json

Payment link details.

objectPaymentLink

A shareable hosted payment page that collects payment for an order at the customer's convenience. Create one when the customer is not in an active checkout flow — for example to send by email or SMS — and anyone with the URL can complete the payment.

Use a payment session instead when the customer is present in your checkout and should be redirected to pay immediately. Both collect against the order's underlying payment intent, which records the resulting charges and refunds.

paymentLinkIdstringrequired

Unique identifier for the payment link.

orderIdstring

The order this payment link collects payment for.

customerIdstring

The customer this payment link collects payment from.

paymentProviderenum<string>

Payment service provider that processes the transaction.

values

STRIPE
BILLOGRAM

paymentProfileIdstring

The saved payment method pre-selected for the customer, if any.

hostedUrlstringurirequired

The URL where customers can complete their payment.

statusenum<string>required

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.

values

ACTIVE
EXPIRED
COMPLETED
CANCELED
FAILED

descriptionstring

Optional description displayed on the payment page.

paymentIntentIdstring

The payment intent that collected the payment, available once the link has been paid.

completedAtstringdate-time

When the payment was completed, if the link has been paid.

createdAtstringdate-timerequired

When the payment link was created.

updatedAtstringdate-timerequired

When the payment link was last updated.

metadataobject with string keys

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.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /payment-links/{paymentLinkId}

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'

fetch('https://apiv2.example.com/api/v2/payment-links/PAYMENT_LINK_ID', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/payment-links/PAYMENT_LINK_ID",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/payment-links/PAYMENT_LINK_ID"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "paymentLinkId": "j47ac10b-58cc-4372-a567-0e02b2c3d479",
  "orderId": "44567801-a504-4f09-8089-31ea78bc239b",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "paymentProvider": "STRIPE",
  "paymentProfileId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "hostedUrl": "https://checkout.yourapp.com/pay/j47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "ACTIVE",
  "description": "Pay your monthly subscription",
  "paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
  "completedAt": "2024-01-15T14:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Cancel payment link

POST/payment-links/{paymentLinkId}/cancel

Cancel an active payment link, preventing further payment attempts through the link.

Path parameters

paymentLinkIdstringrequired

The unique identifier for the payment link.

Headers

X-Idempotency-Keystringmax 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.

application/json

Payment link details.

objectPaymentLink

A shareable hosted payment page that collects payment for an order at the customer's convenience. Create one when the customer is not in an active checkout flow — for example to send by email or SMS — and anyone with the URL can complete the payment.

Use a payment session instead when the customer is present in your checkout and should be redirected to pay immediately. Both collect against the order's underlying payment intent, which records the resulting charges and refunds.

paymentLinkIdstringrequired

Unique identifier for the payment link.

orderIdstring

The order this payment link collects payment for.

customerIdstring

The customer this payment link collects payment from.

paymentProviderenum<string>

Payment service provider that processes the transaction.

values

STRIPE
BILLOGRAM

paymentProfileIdstring

The saved payment method pre-selected for the customer, if any.

hostedUrlstringurirequired

The URL where customers can complete their payment.

statusenum<string>required

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.

values

ACTIVE
EXPIRED
COMPLETED
CANCELED
FAILED

descriptionstring

Optional description displayed on the payment page.

paymentIntentIdstring

The payment intent that collected the payment, available once the link has been paid.

completedAtstringdate-time

When the payment was completed, if the link has been paid.

createdAtstringdate-timerequired

When the payment link was created.

updatedAtstringdate-timerequired

When the payment link was last updated.

metadataobject with string keys

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.

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use code for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. Stable across releases, safe to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /payment-links/{paymentLinkId}/cancel

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'

fetch('https://apiv2.example.com/api/v2/payment-links/PAYMENT_LINK_ID/cancel', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.post(
    "https://apiv2.example.com/api/v2/payment-links/PAYMENT_LINK_ID/cancel",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/payment-links/PAYMENT_LINK_ID/cancel"

	req, _ := http.NewRequest("POST", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "paymentLinkId": "j47ac10b-58cc-4372-a567-0e02b2c3d479",
  "orderId": "44567801-a504-4f09-8089-31ea78bc239b",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "paymentProvider": "STRIPE",
  "paymentProfileId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "hostedUrl": "https://checkout.yourapp.com/pay/j47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "ACTIVE",
  "description": "Pay your monthly subscription",
  "paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
  "completedAt": "2024-01-15T14:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z",
  "metadata": {
    "propertyName": "string"
  }
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Payment Links

List payment links

Query parameters

Responses

Create payment link

Headers

Body·CreatePaymentLinkRequestrequiredapplication/json

Responses

Get payment link

Path parameters

Responses

Cancel payment link

Path parameters

Headers

Responses

BodyCreatePaymentLinkRequestrequiredapplication/json