# Create a payment link

Generate a secure payment link for customers. Supports both single-use and multi-use payment links with comprehensive configuration options for payment methods, customer data collection, and post-payment behaviours.

Endpoint: POST /links
Version: 1.0.0
Security: PXP-UST1

## Header parameters:

  - `X-Request-Id` (string, required)
    UUID v4 request identifier.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `X-Client-Id` (string, required)
    Your merchant client identifier.
    Example: "b14d0efd-b57f-470a-932d-c5d8517ff021"

## Request fields (application/json):

  - `merchantTransactionId` (string, required)
    A unique identifier for this transaction.
    Example: "ORDER-2025-001"

  - `amounts` (object, required)
    Details about the payment amount and currency.

  - `amounts.transaction` (number, required)
    The transaction amount.
    Example: 29.99

  - `amounts.currencyCode` (string, required)
    The currency code, in ISO 4217 format.
    Example: "USD"

  - `products` (array, required)
    Array of product information for display on the payment page.

  - `products.name` (string, required)
    The product name.
    Example: "Premium Widget"

  - `products.description` (string)
    The product description.
    Example: "High-quality widget with advanced features"

  - `products.productImageUrl` (string)
    The URL of the product image.
    Example: "https://example.com/product-image.jpg"

  - `linkConfiguration` (object, required)
    Details about the link behaviour.

  - `linkConfiguration.type` (string, required)
    The type of link to create.
    Enum: "SingleUse", "OpenUse"

  - `linkConfiguration.name` (string)
    A human-readable link name. This is solely for display purposes in the Unity Portal, for easier identification.
    Example: "Invoice Payment Link"

  - `linkConfiguration.expiresInHours` (integer)
    The number of hours until the link expires.
    Example: 72

  - `shopper` (object, required)
    Details about the customer.

  - `shopper.countryCode` (string, required)
    The country code, in ISO 3166-1 alpha-2 format.
    Example: "US"

  - `shopper.merchantShopperId` (string)
    Your internal customer ID.
    Example: "CUST_001"

  - `shopper.shopperInputPreferences` (object)
    Details about the shopper input preferences.

  - `shopper.shopperInputPreferences.email` (boolean)
    Whether to require the customer's email address.

  - `shopper.shopperInputPreferences.phoneNumber` (boolean)
    Whether to require the customer's phone number.

  - `shopper.shopperInputPreferences.firstName` (boolean)
    Whether to require the customer's first name.

  - `shopper.shopperInputPreferences.lastName` (boolean)
    Whether to require the customer's last name.

  - `shopper.shopperInputPreferences.address` (boolean)
    Whether to require the customer's address.

  - `shopper.shopperInputPreferences.dateOfBirth` (boolean)
    Whether to require the customer's date of birth.

  - `shopper.shopperInputPreferences.customerNumber` (boolean)
    Whether to require the customer's reference number.

  - `shopper.shopperInputPreferences.productSpecifications` (boolean)
    Whether to require product-specific fields.

  - `site` (string, required)
    Your merchant site identifier from your PXP configuration.
    Example: "site-1"

  - `merchant` (string, required)
    Your merchant identifier from your PXP configuration.
    Example: "merchant-1"

  - `intent` (string, required)
    The transaction intent. [Learn more](how-it-works#intents).
    Enum: "Purchase", "Authorisation", "EstimatedAuthorisation"

  - `avs` (object, required)
    Details about the AVS.

  - `avs.type` (string, required)
    The type of AVS.
    Enum: "EnableAvsCustomerProvidedAddress", "EnableAvsMerchantProvidedAddress", "SkipAvs"

  - `avs.addressVerification` (object)
    Pre-filled address verification data. This is required when the AVS type is EnableAvsMerchantProvidedAddress.

  - `avs.addressVerification.countryCode` (string, required)
    The country code, in ISO 3166-1 alpha-2 format.
    Example: "US"

  - `avs.addressVerification.houseNumberOrName` (string, required)
    The house number or building name.
    Example: "123 Main Street"

  - `avs.addressVerification.postalCode` (string, required)
    The postal/ZIP code.
    Example: "12345"

  - `allowedFundingTypes` (object)
    Details about the allowed funding types.

  - `allowedFundingTypes.cards` (array)
    The list of allowed card types.
    Enum: "Visa", "Mastercard", "AmericanExpress", "Diners"

  - `allowedFundingTypes.wallets` (array)
    The list of allowed wallets.
    Enum: "PayPal", "ApplePay"

  - `afterPaymentConfiguration` (object)
    Details about the post-payment behaviour.

  - `afterPaymentConfiguration.afterPaymentConfigurationType` (string, required)
    The type of post-payment experience.
    Enum: "ConfirmationPage", "Redirect"

  - `afterPaymentConfiguration.redirectUrl` (string)
    The HTTPS URL to redirect the customer to. This is required if afterPaymentConfigurationType is set to Redirect.
    Example: "https://yourstore.com/payment-success"

  - `afterPaymentConfiguration.customMessage` (string)
    The custom message to display on the confirmation page. This only applies if afterPaymentConfigurationType is set to ConfirmationPage.
    Example: "Thank you for your purchase!"

## Response 200 fields (application/json):

  - `linkId` (string)
    The unique payment link identifier generated by PXP. Use this for tracking and management operations.
    Example: "06da69e0-b668-40b2-ba2f-6c505f08866c"

  - `url` (string)
    The complete payment link URL that you can share with customers. This is the link customers will use to make their payment.
    Example: "https://links.dev.pxp.io/06da69e0-b668-40b2-ba2f-6c505f08866c"

  - `status` (string)
    The current status of the payment link.
    Enum: "Active", "Cancelled", "Completed", "Expired", "Error"

  - `expirationTimestamp` (string)
    The date and time when the link expires, in UTC. After this time, the link will no longer accept payments.
    Example: "2025-09-11T04:12:15.3044876Z"

  - `site` (string)
    The site identifier used in the request, confirming the merchant configuration.
    Example: "site-1"

  - `amounts` (object)
    Details about the payment amount and currency.

  - `amounts.transaction` (number, required)
    The transaction amount.
    Example: 29.99

  - `amounts.currencyCode` (string, required)
    The currency code, in ISO 4217 format.
    Example: "USD"

  - `merchantTransactionId` (string)
    Your transaction identifier from the request, used for reconciliation and tracking.
    Example: "ORDER-2025-001"

  - `merchantShopperId` (string)
    The customer identifier, if provided in the request.
    Example: "CUST_001"

  - `afterPaymentConfiguration` (object)
    Details about the post-payment behaviour.

  - `afterPaymentConfiguration.afterPaymentConfigurationType` (string, required)
    The type of post-payment experience.
    Enum: "ConfirmationPage", "Redirect"

  - `afterPaymentConfiguration.redirectUrl` (string)
    The HTTPS URL to redirect the customer to. This is required if afterPaymentConfigurationType is set to Redirect.
    Example: "https://yourstore.com/payment-success"

  - `afterPaymentConfiguration.customMessage` (string)
    The custom message to display on the confirmation page. This only applies if afterPaymentConfigurationType is set to ConfirmationPage.
    Example: "Thank you for your purchase!"

## Response 400 fields (application/json):

  - `errorCode` (string, required)
    The error code returned for the operation.
    Example: "INVALID_REQUEST"

  - `errorReason` (string, required)
    The error reason returned for the operation.
    Example: "One or more validation errors occurred."

  - `correlationId` (string, required)
    The unique reference generated by the PSP to locate the error.
    Example: "38f49f03-8e42-46db-9f3d-da3428a039be"

  - `details` (array)
    Additional error details
    Example: ["'amounts' - The amounts field is required.","'products' - The products field is required."]

## Response 401 fields (application/json):

  - `errorCode` (string, required)
    The error code returned for the operation.
    Example: "INVALID_REQUEST"

  - `errorReason` (string, required)
    The error reason returned for the operation.
    Example: "One or more validation errors occurred."

  - `correlationId` (string, required)
    The unique reference generated by the PSP to locate the error.
    Example: "38f49f03-8e42-46db-9f3d-da3428a039be"

  - `details` (array)
    Additional error details
    Example: ["'amounts' - The amounts field is required.","'products' - The products field is required."]

## Response 404 fields (application/json):

  - `errorCode` (string, required)
    The error code returned for the operation.
    Example: "INVALID_REQUEST"

  - `errorReason` (string, required)
    The error reason returned for the operation.
    Example: "One or more validation errors occurred."

  - `correlationId` (string, required)
    The unique reference generated by the PSP to locate the error.
    Example: "38f49f03-8e42-46db-9f3d-da3428a039be"

  - `details` (array)
    Additional error details
    Example: ["'amounts' - The amounts field is required.","'products' - The products field is required."]

## Response 500 fields (application/json):

  - `errorCode` (string, required)
    The error code returned for the operation.
    Example: "INVALID_REQUEST"

  - `errorReason` (string, required)
    The error reason returned for the operation.
    Example: "One or more validation errors occurred."

  - `correlationId` (string, required)
    The unique reference generated by the PSP to locate the error.
    Example: "38f49f03-8e42-46db-9f3d-da3428a039be"

  - `details` (array)
    Additional error details
    Example: ["'amounts' - The amounts field is required.","'products' - The products field is required."]