Skip to main content
Create a checkout link in one API call, then share the URL with your customer via any channel.

​
Prerequisites

  • A Quidkey merchant account with client_id and client_secret
  • An active access token (see Authentication)

​
Step 1: Authenticate

Get an access token using your credentials. 
curl -X POST 'https://core.quidkey.com/api/v1/oauth2/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'
Call POST /api/v1/payment-links with the payment details. 
curl -X POST 'https://core.quidkey.com/api/v1/payment-links' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "amount": 5000,
      "currency": "EUR",
      "payment_reference": "INV-2024-001"
    }
  }'

​
Response

{
  "success": true,
  "data": {
    "link_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "payment_link_url": "https://core.quidkey.com/payment-link/a1b2c3d4e5f6...",
    "expires_at": "2024-04-07T12:00:00.000Z",
    "status": "active"
  }
}
Save the payment_link_url. This is the URL you’ll share with your customer. The token in the URL is only returned once at creation time.
Send the payment_link_url to your customer through any channel:
  • Email: include in invoice emails or payment reminders
  • SMS: send a short message with the link
  • Messaging apps: WhatsApp, Telegram, or any chat platform
  • In-person: display as text or generate a QR code
When the customer clicks the link, they’ll see a Quidkey-hosted checkout page where they can complete the payment. See Checkout Experience for details.

​
Request Body Reference

FieldTypeRequiredDescription
order.amountintegerYesAmount in minor units (cents). 5000 = €50.00
order.currencystringYesISO 4217 currency code (e.g., EUR, GBP)
order.payment_referencestringYesUp to 18 characters. Appears on the customer’s bank statement.
order.order_idstringNoYour internal order identifier for reconciliation
order.localestringNoBCP-47 locale tag (e.g., en, pt, es). Default: en
merchant_idstringNoRequired for Partner authentication. UUID of the target merchant.
metadataobjectNoArbitrary key-value pairs to attach to the link
redirect_urlsobjectNoCustom redirect URLs after payment. See Redirect URLs.
redirect_urls.success_urlstringConditionalURL to redirect customer to after successful payment. Required if redirect_urls is provided.
redirect_urls.failure_urlstringConditionalURL to redirect customer to after failed payment. Required if redirect_urls is provided.
Amount format: Use minor units (cents). 1000 = €10.00, 5000 = €50.00. This is the same format used by Stripe and the Embedded Flow.

​
Redirect URLs

By default, after payment customers are redirected to a Quidkey-hosted thank you or failure page. To send customers back to your own site, provide custom redirect URLs at creation time. 
curl -X POST 'https://core.quidkey.com/api/v1/payment-links' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "amount": 5000,
      "currency": "EUR",
      "payment_reference": "INV-2024-001"
    },
    "redirect_urls": {
      "success_url": "https://yoursite.com/payment/success",
      "failure_url": "https://yoursite.com/payment/failure"
    }
  }'
When custom redirect URLs are provided, Quidkey appends query parameters so you can correlate the redirect on your side:
ParameterDescription
statussuccess or failed
payment_referenceThe payment reference from the link
order_idYour order ID (if provided at creation)
For example, after a successful payment the customer would be redirected to: 
https://yoursite.com/payment/success?status=success&payment_reference=INV-2024-001
Both success_url and failure_url must be provided together. You cannot set only one. If redirect_urls is omitted, customers are redirected to Quidkey’s default pages.
Webhooks still fire regardless of redirect URL configuration. Custom redirects only affect where the customer’s browser is sent. Your backend still receives the webhook notification as normal. See After Payment for webhook details.
By default, payment links are single-use: they transition to USED after a customer completes payment. You can also create reusable links that stay active for multiple payments.
Link type configuration (single_use vs reusable) is currently set at the system level. Contact support if you need reusable links for your use case (e.g., donation pages, recurring invoices).
Payment links expire after 7 days by default. The expiry timestamp is returned in the expires_at field of the creation response. When a customer opens an expired link, the checkout page displays an expiry message instead of the payment form. See Link Lifecycle for all status transitions.

​
Next Steps

Checkout Experience

See what your customers see when they open a payment link

After Payment

Track status, handle webhooks, and manage your links

API Reference

Full endpoint documentation with interactive playground

Overview

Hosted Checkout overview and lifecycle