Create payment link

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.