Payment Links

Payment links are reusable URLs that allow customers to pay for an order. Unlike standard orders that expire after a single failed attempt, payment links support multiple retry attempts, making them ideal for invoices, email-based payments, and scenarios where the customer may not pay immediately.

Key Features

Reusable: Customers can retry payment up to 25 times if previous attempts fail.
Long-lived: Default expiration is 30 days (configurable via expiration_period).
Shareable: Send the link via email, SMS, chat, or embed it on your website.

Creating a Payment Link

Send a POST request to /v1/paymentlinks/:

{
  "merchant_order_id": "my-order-id",
  "amount": 1295,
  "currency": "EUR",
  "description": "My payment link",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

Required Fields

Field	Description
`merchant_order_id`	Your own reference ID for the payment link
`amount`	Amount in cents (e.g., 12.95 EUR = `1295`)
`currency`	ISO 4217 currency code (e.g., `EUR`, `GBP`)

Optional Fields

Field	Description
`payment_methods`	Filter which payment methods are available
`description`	Description shown to the customer
`expiration_period`	ISO 8601 duration. Default is `P30D` (30 days)
`return_url`	URL to redirect the customer after successful payment
`webhook_url`	URL to receive status change notifications
`customer`	Customer details object (name, email, etc.)

[!TIP] Include the customer object with an email address if you want Cost+ to send the payment link to the customer automatically.

Retrieving a Payment Link

Send a GET request to /v1/paymentlinks/\{id\}/ to retrieve the current state of a payment link:

GET /v1/paymentlinks/pl_abc123.../

The response includes the payment link URL, current status, and details of any payment attempts.

Payment Link Statuses

Status	Description
`new`	The link has been created but no payment attempt has been made.
`processing`	A payment attempt is currently in progress.
`all_unsuccessful`	All payment attempts so far have failed. The customer can still retry (up to 25 attempts).
`completed`	Payment was successful. The link is no longer active.
`expired`	The link has expired before a successful payment was made.

[!NOTE] The all_unsuccessful status is not a final status. The customer can still attempt to pay again until either the payment succeeds, the maximum number of attempts (25) is reached, or the link expires.

[!WARNING] Once a payment link reaches the completed or expired status, it cannot be used again. Create a new payment link if the customer needs to pay again.

Example Workflow

Create a payment link via POST /v1/paymentlinks/.
Share the returned URL with your customer (e.g., via email).
The customer opens the link and completes payment.
Cost+ sends a webhook to your webhook_url when the status changes.
Verify the payment link status via GET /v1/paymentlinks/\{id\}/.
Fulfill the order once the status is completed.