Skip to main content
Once you’ve created and shared a payment link, you can track its status, receive webhook notifications when a payment completes, and manage your links through the API. Retrieve a payment link by its ID to check the current status. 
curl 'https://core.quidkey.com/api/v1/payment-links/LINK_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Response

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merchant": {
      "id": "m1234567-abcd-ef01-2345-678901234567",
      "brand_name": "Acme Corp"
    },
    "amount": "50.00",
    "currency": "EUR",
    "payment_reference": "INV-2024-001",
    "order_id": null,
    "status": "used",
    "link_type": "single_use",
    "views_count": 3,
    "first_viewed_at": "2024-04-01T14:30:00.000Z",
    "expires_at": "2024-04-07T12:00:00.000Z",
    "created_at": "2024-03-31T12:00:00.000Z",
    "transaction_id": "t9876543-dcba-fe01-2345-678901234567",
    "locale": "en",
    "metadata": null,
    "payment_link_url": "https://core.quidkey.com/payment-link/a1b2c3d4e5f6...",
    "redirect_urls": null
  }
}

​
Response Fields

FieldDescription
statusCurrent link status: active, used, expired, or cancelled
views_countNumber of times the checkout page has been opened
first_viewed_atWhen the link was first opened (null if never viewed)
transaction_idThe resulting transaction ID when payment is complete (null otherwise)
payment_link_urlThe shareable URL (recovered from encrypted storage)
Link-to-transaction navigation: When transaction_id is present, you can use it to look up the full transaction details in the Quidkey Console or via the API.

​
Status Transitions

Payment link status changes are driven by customer actions and system events:
TransitionTrigger
ACTIVE → USEDThe customer’s bank confirms the payment (callback). Single-use links only.
ACTIVE → EXPIREDThe link passes its expires_at time. Checked on demand when the link is accessed.
ACTIVE → CANCELLEDYou cancel the link via the API.
Expiry is checked on demand. Quidkey marks a link as expired when it is next accessed (via the public checkout page or the API), not via a background job. This means a link’s status in the database may show active until someone accesses it after the expiry time.

​
Redirect URLs

If you provided redirect_urls when creating the payment link, the customer is redirected to your URLs instead of Quidkey’s default pages. Quidkey appends query parameters to help you correlate the redirect:
ParameterDescription
statussuccess or failed
payment_referenceThe payment reference from the link
order_idYour order ID (if provided at creation)
Example redirect after successful payment: 
https://yoursite.com/payment/success?status=success&payment_reference=INV-2024-001&order_id=ORD-123
Custom redirects are informational only. Do not use them to confirm payment status. Always use webhooks or the API to verify that payment was actually completed. A customer could manually navigate to your success URL without paying.

​
Webhook Notifications

When a payment is completed through a payment link, you receive the same webhook notification as payments made through the Embedded Flow. The webhook payload includes the transaction details. To set up webhooks, see the Webhook documentation. Retrieve all payment links with optional filtering and pagination. 
# List all active links
curl 'https://core.quidkey.com/api/v1/payment-links?status=active&limit=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# Search by payment reference
curl 'https://core.quidkey.com/api/v1/payment-links?search=INV-2024' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Query Parameters

ParameterTypeDefaultDescription
statusstringnoneFilter by status: active, used, expired, cancelled
searchstringnoneSearch by payment reference or order ID
merchant_idstringnoneFilter by merchant ID (partner authentication only)
pageinteger1Page number (1-based)
limitinteger20Items per page (max 100)

​
Paginated Response

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-...",
      "merchant": { "id": "m1234...", "brand_name": "Acme Corp" },
      "amount": "50.00",
      "currency": "EUR",
      "payment_reference": "INV-2024-001",
      "order_id": null,
      "status": "active",
      "link_type": "single_use",
      "views_count": 0,
      "first_viewed_at": null,
      "expires_at": "2024-04-07T12:00:00.000Z",
      "created_at": "2024-03-31T12:00:00.000Z",
      "transaction_id": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

​
Error Handling

Payment link endpoints return consistent error responses:
StatusError CodeMeaning
404PAYMENT_LINK_NOT_FOUNDToken or ID does not match any link
410PAYMENT_LINK_NOT_ACTIVELink is used, expired, or cancelled
400INVALID_INPUTRequest validation failed
401UNAUTHORIZEDMissing or invalid authentication
Expired links return details, not errors. The public GET /payment-links/:token/details endpoint returns the link with status: "expired" rather than throwing an error. This allows the checkout page to show an appropriate message to the customer.

​
Next Steps

Overview

Hosted Checkout overview and lifecycle

Create a Checkout Link

Generate and share your first checkout link

Webhook Setup

Configure webhooks to receive payment notifications

API Reference

Full endpoint documentation with interactive playground