Skip to content

Payment Links

A payment link is a one-time-use URL that you create via API. When your customer opens the link, they see a hosted checkout page where they can pay via card or bank transfer.

Lifecycle

stateDiagram-v2
    [*] --> Unused: createLink
    Unused --> Used: Customer pays
    Unused --> Cancelled: Customer cancels
    Unused --> Deleted: deleteLink API call
    Used --> Refunded: refundPayment
Status Meaning
Unused Link created, not yet paid
Used Payment completed
Cancelled Customer cancelled (only if cancellable)
Deleted Merchant deleted the link via API

When you create a link, SecPaid returns a pay_link:

https://app.secpaid.com/payment?link_id=MTIzNDU=

The link_id query parameter is the base64-encoded linktopay_id from your database record.

Request Fields

Field Type Required Description
amount number Yes Payment amount in EUR. Must be > 0
recipient_note string No Your reference for this payment (e.g., invoice number, order ID). Appears in transaction lists and webhooks
callback_url string No Browser redirect URL after payment/cancellation. Accepts a full URL, an index into your configured list, or comma-separated URLs
payment_endpoint string No Server-to-server webhook URL(s). Accepts a URL, an index, or comma-separated
cancellable boolean No Whether customer can cancel. Default: true
bank_transfer string No Enable bank transfer as payment method ("true" / "false")
is_encryption string No Enable encrypted webhook payloads ("true" / "false")
encryption_key string No Custom AES-256-CBC key for this link's webhooks
bank_statement_description string No Text shown on the customer's bank statement
is_qr_link string No Whether this is a QR code link ("true" / "false")

Response Fields

When you create a link, SecPaid returns a full link object:

Field Type Description
id integer Unique link ID
pay_link string The payment URL you send to your customer
qr_img string Ready-to-use QR code image URL encoding the pay_link
amount number Payment amount in EUR
status string Always "Unused" on creation
is_cancellation string "No" = customer can cancel, "Yes" = cannot cancel
recipient_note string Your reference note
callback_url string Configured redirect URL(s)
paymentEndpoint string Configured webhook URL(s)
servicefee string Platform fee percentage applied to this link
bank_transfer string Whether bank transfer is enabled
is_split_link string "false" for regular links, "true" for split links
split_type string "normal" (proportional) or "absolute"
transaction_type string "Basic" for regular links, "Split" for split links
bank_statement_description string Description on customer's bank statement
is_qr_link string Whether QR code link
payment_config string Payment configuration
created_at string Creation timestamp (UTC)

Cancellable

Value Behavior
true (default) Customer sees a "Cancel" link on checkout. On cancel, callback_url is called with status=cancel
false No cancel option shown. Customer must close the browser tab to leave

Default

Links are cancellable by default. Set cancellable: false explicitly if you don't want customers to be able to cancel.

QR Code

Every payment link automatically generates a QR code image URL (qr_img in the response). You can embed this in invoices, emails, or point-of-sale displays.

Service Fee

The servicefee field in the response shows the platform fee percentage that will be deducted from this payment. This is configured at account level in your integration settings and cannot be changed per-link.

Callback & Notification

After payment, two notification mechanisms can fire:

  1. callback_url — Browser redirect (customer-facing)
  2. payment_endpoint — Server-to-server webhook (your backend)

See Webhooks & Callbacks for full details.