> ## Documentation Index > Fetch the complete documentation index at: https://docs.orsunpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a merchant-scoped payment link > Creates a link in the authenticated API key’s live/test mode that the merchant can share with a buyer. Money is a decimal string in major units within the currency exponent. Idempotency-Key is required: a retry with the same key and body returns the stored answer with Idempotency-Replayed: true. ## OpenAPI ````yaml /openapi.json post /v1/payment-links openapi: 3.1.0 info: contact: name: OrsunPay description: >- Server-to-server merchant payments. Money is always a decimal string in major units. title: OrsunPay Merchant API version: '1.0' servers: [] security: [] tags: - description: Poll stored merchant transaction status name: Transactions - description: Create merchant sales and payouts name: Payments - description: Request refunds and read stored refund outcomes name: Refunds - description: Signed merchant event deliveries name: Webhooks - description: Create, list and deactivate shareable merchant payment links name: Payment links paths: /v1/payment-links: post: tags: - Payment links summary: Create a merchant-scoped payment link description: >- Creates a link in the authenticated API key’s live/test mode that the merchant can share with a buyer. Money is a decimal string in major units within the currency exponent. Idempotency-Key is required: a retry with the same key and body returns the stored answer with Idempotency-Replayed: true. operationId: createPaymentLink parameters: - description: >- 1–255 printable ASCII characters without spaces. Reuse for retries; replay responses carry Idempotency-Replayed: true. in: header name: Idempotency-Key required: true schema: example: 0b6f2c1e-4c7a-4a43-9a51-6a4b1d7e9f10 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePaymentLinkRequestDto' required: true responses: '201': content: application/json: example: amount: '12.34' createdAt: '2026-10-11T10:00:00.000Z' currency: EUR description: Order payment expired: false expiresAt: '2026-10-18T10:00:00.000Z' failureUrl: https://shop.example.com/failure id: pl_01j9a6d6dqevssvyw7s97pkrga isActive: true livemode: true maxUses: 1 merchantId: mer_example metadata: cartId: cart_example reusable: false slug: aBcDeFgHiJkLmNoPqRsTuVwX status: ACTIVE successUrl: https://shop.example.com/success url: https://pay.example.com/l/aBcDeFgHiJkLmNoPqRsTuVwX usesCount: 0 schema: $ref: '#/components/schemas/PaymentLinkResponseDto' description: Link created, or the stored answer for a replayed Idempotency-Key headers: RateLimit: description: >- Remaining requests (r) and seconds to reset/full refill (t), per evaluated policy. Absent when disabled; merchant quota is omitted during Redis outages, while IP/auth protection uses replica memory. schema: example: '"merchant";r=37;t=4' type: string RateLimit-Policy: description: >- Evaluated policies (draft-ietf-httpapi-ratelimit-headers-11). q is burst quota; w is the full refill window in seconds. schema: example: '"merchant";q=100;w=5' type: string '400': content: application/json: examples: invalidAmount: summary: Amount beyond the currency exponent value: error: PAYMENT_LINK_INVALID_AMOUNT errorCode: PAYMENT_LINK_INVALID_AMOUNT message: amount has more decimals than EUR allows status: false statusCode: 400 invalidKey: summary: Missing Idempotency-Key value: error: IDEMPOTENCY_KEY_INVALID errorCode: IDEMPOTENCY_KEY_INVALID message: Idempotency-Key is required status: false statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/ApiErrorResponseDto' - $ref: '#/components/schemas/ValidationErrorResponseDto' description: >- Body validation, IDEMPOTENCY_KEY_INVALID, or a PAYMENT_LINK_* code: INVALID_AMOUNT, UNSUPPORTED_CURRENCY, INVALID_EXPIRY, INVALID_MAX_USES, REDIRECT_URL_NOT_ALLOWED, METADATA_TOO_LARGE, INVALID_TEXT. '401': content: application/json: example: error: Unauthorized message: Invalid API key statusCode: 401 schema: $ref: '#/components/schemas/UnauthorizedErrorResponseDto' description: Missing or invalid API key '409': content: application/json: example: error: IDEMPOTENCY_IN_PROGRESS errorCode: IDEMPOTENCY_IN_PROGRESS idempotencyKey: 0b6f2c1e-4c7a-4a43-9a51-6a4b1d7e9f10 message: >- A request with this Idempotency-Key is still being processed; retry later status: false statusCode: 409 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: IDEMPOTENCY_IN_PROGRESS; retry with the same key after Retry-After. headers: Retry-After: description: Seconds to wait before retrying with the same key schema: example: '1' type: string '422': content: application/json: example: error: IDEMPOTENCY_KEY_REUSED errorCode: IDEMPOTENCY_KEY_REUSED idempotencyKey: 0b6f2c1e-4c7a-4a43-9a51-6a4b1d7e9f10 message: >- Idempotency-Key was already used with a different request; use a new key for a new request status: false statusCode: 422 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: IDEMPOTENCY_KEY_REUSED with another body or endpoint. '429': content: application/json: example: error: RATE_LIMITED errorCode: RATE_LIMITED message: Too many requests. Retry after the indicated delay. status: false statusCode: 429 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- RATE_LIMITED: IP, merchant or failed-auth quota exhausted, or auth-in-flight concurrency pressure (Retry-After: 1). Wait Retry-After seconds and retry with the same Idempotency-Key. headers: RateLimit: description: >- Remaining requests (r) and seconds to reset/full refill (t), per evaluated policy. Absent when disabled; merchant quota is omitted during Redis outages, while IP/auth protection uses replica memory. schema: example: '"merchant";r=37;t=4' type: string RateLimit-Policy: description: >- Evaluated policies (draft-ietf-httpapi-ratelimit-headers-11). q is burst quota; w is the full refill window in seconds. schema: example: '"merchant";q=100;w=5' type: string Retry-After: description: Minimum delay in whole seconds before retrying. schema: example: 1 minimum: 1 type: integer '502': content: application/json: example: error: UPSTREAM_UNAVAILABLE errorCode: UPSTREAM_UNAVAILABLE message: Payment links are temporarily unavailable status: false statusCode: 502 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- UPSTREAM_ERROR / UPSTREAM_UNAVAILABLE: the payment core failed or is unreachable '503': content: application/json: example: error: Service Unavailable message: API_KEY_VALIDATION_UNAVAILABLE statusCode: 503 schema: $ref: '#/components/schemas/AuthenticationUnavailableResponseDto' description: API key validation is temporarily unavailable; retry later '504': content: application/json: example: error: UPSTREAM_TIMEOUT errorCode: UPSTREAM_TIMEOUT message: The payment core did not answer in time status: false statusCode: 504 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: 'UPSTREAM_TIMEOUT: no answer in time; a create may still complete' security: - X-API-Key: [] components: schemas: CreatePaymentLinkRequestDto: properties: amount: description: >- Positive decimal string in major units, within the currency exponent. example: '12.34' pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$ type: string currency: example: EUR type: string description: example: Order payment maxLength: 500 type: string expiresAt: description: ISO-8601 timestamp with explicit Z or ±hh:mm offset. format: date-time type: string failureUrl: example: https://shop.example.com/failure maxLength: 2048 type: string maxUses: description: >- Defaults to 1 for a single-use link; unlimited when reusable and omitted. maximum: 1000000 minimum: 1 type: number metadata: additionalProperties: true description: JSON object, at most 16 KiB. type: object reusable: default: false type: boolean successUrl: example: https://shop.example.com/success maxLength: 2048 type: string required: - amount - currency type: object PaymentLinkResponseDto: properties: amount: example: '12.34' pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$ type: string createdAt: format: date-time type: string currency: example: EUR type: string description: anyOf: - type: string - type: 'null' expired: type: boolean expiresAt: anyOf: - format: date-time type: string - type: 'null' failureUrl: anyOf: - type: string - type: 'null' id: example: pl_01j9a6d6dqevssvyw7s97pkrga type: string isActive: type: boolean livemode: description: The live/test mode inherited from the authenticated API key. example: true type: boolean maxUses: anyOf: - type: number - type: 'null' merchantId: type: string metadata: additionalProperties: true type: object reusable: type: boolean slug: pattern: ^[A-Za-z0-9]{24}$ type: string status: enum: - ACTIVE - INACTIVE - EXPIRED - EXHAUSTED type: string successUrl: anyOf: - type: string - type: 'null' url: anyOf: - description: Null when hosted checkout is disabled. example: https://pay.example.com/l/aBcDeFgHiJkLmNoPqRsTuVwX type: string - type: 'null' usesCount: type: number required: - livemode - id - merchantId - slug - amount - currency - description - reusable - maxUses - usesCount - expiresAt - successUrl - failureUrl - metadata - isActive - expired - status - createdAt - url type: object ApiErrorResponseDto: properties: error: description: Same as errorCode example: DUPLICATE_ORDER_ID type: string errorCode: description: >- Machine-readable, extensible code. Known values: ADYEN_REFUSED, CARD_DATA_NOT_ACCEPTED, RATE_LIMITED, PAYMENT_LINK_INVALID_AMOUNT, PAYMENT_LINK_UNSUPPORTED_CURRENCY, PAYMENT_LINK_INVALID_EXPIRY, PAYMENT_LINK_INVALID_MAX_USES, PAYMENT_LINK_REDIRECT_URL_NOT_ALLOWED, PAYMENT_LINK_METADATA_TOO_LARGE, PAYMENT_LINK_INVALID_TEXT, PAYMENT_LINK_NOT_FOUND, PAYMENT_LINK_INVALID_LIMIT, PAYMENT_LINK_INVALID_CURSOR, API_KEY_ROTATION_REQUIRED, ORDER_ID_RESERVED, NO_CREDENTIALS_FOR_MODE, LIVEMODE_MISMATCH, PSP_OUTCOME_UNKNOWN, PAYMENT_METHOD_REQUIRED, PAYMENT_METHOD_INPUT_WITHOUT_METHOD, NO_PAYMENT_METHODS, IDEMPOTENCY_KEY_INVALID, DUPLICATE_ORDER_ID, IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED, UPSTREAM_ERROR, UPSTREAM_UNAVAILABLE, UPSTREAM_TIMEOUT, REFUND_INVALID_AMOUNT, REFUND_INVALID_REASON, REFUND_INVALID_METADATA, REFUND_INPUT_INVALID, REFUND_EXCEEDS_AMOUNT, TRANSACTION_NOT_REFUNDABLE, REFUND_NOT_FOUND, REFUND_NOT_SUPPORTED, IDEMPOTENCY_LEASE_LOST, REFUND_SERVICE_UNAVAILABLE. New codes may be added; clients must handle unknown values. example: DUPLICATE_ORDER_ID type: string existingTransactionId: description: >- DUPLICATE_ORDER_ID only: the transaction that already uses this orderId example: tr_x8k2p0q5scocndpejk0nud75q type: string fields: description: >- Invalid or missing buyer contact fields for CUSTOMER_CONTACT_REQUIRED example: - customer.email - customer.country items: type: string type: array idempotencyKey: description: IDEMPOTENCY_* errors only example: 0b6f2c1e-4c7a-4a43-9a51-6a4b1d7e9f10 type: string message: example: A transaction with orderId "A-1001" already exists for this merchant type: string orderId: description: DUPLICATE_ORDER_ID only example: A-1001 type: string status: example: false type: boolean statusCode: example: 409 type: number required: - status - statusCode - errorCode - error - message type: object ValidationErrorResponseDto: properties: error: example: Bad Request type: string message: example: - >- amount must be a decimal string in major units, e.g. "12.30"; JSON numbers are not accepted for money (got 12.3) items: type: string type: array statusCode: example: 400 type: number required: - statusCode - error - message type: object UnauthorizedErrorResponseDto: properties: error: example: Unauthorized type: string errorCode: description: Stable authentication error code when available example: API_KEY_ROTATION_REQUIRED type: string message: example: Invalid API key type: string statusCode: description: HTTP status when included by the error handler example: 401 type: number required: - message type: object AuthenticationUnavailableResponseDto: properties: error: example: Service Unavailable type: string message: example: API_KEY_VALIDATION_UNAVAILABLE type: string statusCode: example: 503 type: number required: - statusCode - error - message type: object securitySchemes: X-API-Key: in: header name: x-api-key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.