---
title: "Create a new payment link (Partner or Merchant authentication)"
method: POST
path: "/api/v1/payment-links"
tags: ["Payment Links"]
---

# Create a new payment link (Partner or Merchant authentication)

`POST /api/v1/payment-links`

Create a new payment link (Partner or Merchant authentication)

## Request body

- PaymentLinkCreateInput
  - `merchant_id` string, uuid — Required for Partner authentication, forbidden for Merchant authentication
  - `order` object, required
    - `amount` integer, required — Amount in minor units (e.g., cents)
    - `currency` string, required — ISO 4217 currency code
    - `payment_reference` string, required — Up to 18 chars, appears on customer bank statement
    - `order_id` string — Merchant's order identifier
    - `locale` string — BCP-47 locale tag
    - `test_transaction` boolean — Flag to force sandbox mode
  - `metadata` object — Optional metadata to attach to the payment link
  - `redirect_urls` object
    - `success_url` string, uri, required — URL to redirect customer to after successful payment (HTTPS required in production)
    - `failure_url` string, uri, required — URL to redirect customer to after failed payment (HTTPS required in production)

## Response `201`

Created

- PaymentLinkCreateResponse
  - `success` boolean, required — Indicates if the request was successful
  - `data` object, required
    - `link_id` string, uuid, required — Internal payment link identifier (for reference only)
    - `payment_link_url` string, uri, required — Full URL to share with customer. Contains a secure 64-char hex token (not the link_id). Token is only returned once.
    - `expires_at` string, date-time, required — ISO 8601 timestamp when link expires
    - `status` 'active', required — Payment link status

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

## Changes

- **2026-06-16** `b372e7d5563d` — 4 breaking, 2 warning, 5 info
  - the `order/currency` request property's minLength was increased from `0` to `3`
  - added the pattern `^[A-Za-z]{3}$` to the request property `order/currency`
  - added the pattern property `^(.*)$` to the `metadata` request property
  - the `error/code` response's property type/format changed from `string`/`` to ``/`` for status `400`
  - …7 more
- **2026-02-28** `ecd256fe0106` — 1 info
  - endpoint added
- **2025-11-02** `919eb7a392aa` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/banqzinc/apis/quidkey-api/changes/api/v1/payment-links/post.md)

---

[API](https://skmtc.dev/banqzinc/apis/quidkey-api.md) · [All operations](https://skmtc.dev/banqzinc/apis/quidkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/banqzinc/quidkey-api/revisions/f86d2bdbcb08/schema)