Create payment link

Creates a new payment link for the authenticated merchant’s store. A payment link is a shareable, hosted payment page that can collect one or many payments in the configured currency.

The link is created as a PaymentRequests record of type PAYMENT_LINK. Every DTO field beyond the shared base fields is stored inside the request’s JSON Data blob and returned back via the presenter. The store is resolved from the authenticated principal (user.store_id); you do not pass a store id in the body.

Authentication

Send the merchant API key in the x-api-key header (alias x-account-api-key).
Requires scope Merchant.payment_link.create.
Optionally scope the key to a specific store/account with the x-application-account-id header (alias x-account-id) or the application_account_id / account_id query param.

Body (application/json)

Core fields (required): amount, currency, title, frecuency.

Conditional requirements enforced by validation:

frecuencyData is required when frecuency = RECURRING (must be a JSON string).
quantity (min 1) is required when allowCustomQuantity is false/absent; otherwise supply quantityRange ({ min, max }) when allowCustomQuantity is true.
limitNumberOfPayments is required when allowLimitNumberOfPayments is true.
customconfirmMessage is expected when showConfirmPage is true.
securityPin is expected when requirePinValidation is true.
pdfConfig is only validated when allowPartialPayment is true.

Buyer-detail collection fields (requestContactDetails, requestEmail, requestPhone, requestAddress, requestReference) accept a boolean OR one of the FieldRequirementStrategy enum values (REQUIRED, OPTIONAL, HIDDEN). fieldRequirementStrategy sets the global fallback strategy for fields set to true (defaults to REQUIRED).

Unknown properties are stripped by the global ValidationPipe (whitelist: true).

Response

Returns 201 Created with the presented PaymentLinkResponseDto (envelope fields + the payment-link data fields listed in PAYMENT_LINK_DATA_FIELDS).

The legacy paths POST /v1/payment-links and POST /v1/payment-link map to this same handler and remain for backward compatibility.

Notas: Deprecated alias paths POST /v1/payment-links and POST /v1/payment-link route to this same handler. The store id is taken from the authenticated principal (user.store_id), not the body. Only fields listed in PAYMENT_LINK_DATA_FIELDS are echoed back in the response; unknown body properties are stripped by the global whitelist ValidationPipe.

## Create payment link Creates a new **payment link** for the authenticated merchant's store. A payment link is a shareable, hosted payment page that can collect one or many payments in the configured currency. The link is created as a `PaymentRequests` record of type `PAYMENT_LINK`. Every DTO field beyond the shared base fields is stored inside the request's JSON `Data` blob and returned back via the presenter. The store is resolved from the authenticated principal (`user.store_id`); you do not pass a store id in the body. ### Authentication - Send the merchant API key in the **`x-api-key`** header (alias `x-account-api-key`). - Requires scope **`Merchant.payment_link.create`**. - Optionally scope the key to a specific store/account with the **`x-application-account-id`** header (alias `x-account-id`) or the `application_account_id` / `account_id` query param. ### Body (application/json) Core fields (required): `amount`, `currency`, `title`, `frecuency`. Conditional requirements enforced by validation: - `frecuencyData` is required when `frecuency = RECURRING` (must be a JSON string). - `quantity` (min 1) is required when `allowCustomQuantity` is false/absent; otherwise supply `quantityRange` ({ min, max }) when `allowCustomQuantity` is true. - `limitNumberOfPayments` is required when `allowLimitNumberOfPayments` is true. - `customconfirmMessage` is expected when `showConfirmPage` is true. - `securityPin` is expected when `requirePinValidation` is true. - `pdfConfig` is only validated when `allowPartialPayment` is true. Buyer-detail collection fields (`requestContactDetails`, `requestEmail`, `requestPhone`, `requestAddress`, `requestReference`) accept a boolean OR one of the `FieldRequirementStrategy` enum values (`REQUIRED`, `OPTIONAL`, `HIDDEN`). `fieldRequirementStrategy` sets the global fallback strategy for fields set to `true` (defaults to `REQUIRED`). Unknown properties are stripped by the global ValidationPipe (`whitelist: true`). ### Response Returns `201 Created` with the presented `PaymentLinkResponseDto` (envelope fields + the payment-link data fields listed in `PAYMENT_LINK_DATA_FIELDS`). ### Related / deprecated aliases The legacy paths `POST /v1/payment-links` and `POST /v1/payment-link` map to this same handler and remain for backward compatibility. --- **Notas:** Deprecated alias paths POST /v1/payment-links and POST /v1/payment-link route to this same handler. The store id is taken from the authenticated principal (user.store_id), not the body. Only fields listed in PAYMENT_LINK_DATA_FIELDS are echoed back in the response; unknown body properties are stripped by the global whitelist ValidationPipe.

Authentication

x-api-keystring

API Key authentication via header

Request

This endpoint expects an object.

amountdoubleRequired

currencystringRequired

titlestringRequired

frecuencystringRequired

ONE_TIME | MULTIPLE | RECURRING. frecuencyData (JSON string) becomes required when RECURRING.

quantityintegerRequired

Required unless allowCustomQuantity is true — in that case send quantityRange ({ min, max }) instead.