---
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

---

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