Create links

Create a link in the Unity Portal

Step 1: Access the payment link creation panel

1. In the Unity Portal, go to Pay by Link.
2. Click New Link in the top-right.

A side panel opens with the creation form.

Step 2: Configure the payment page

1. In the Payment page tab, fill in the General information section:
   • Merchant transaction ID: A unique identifier for this transaction.
   • Intent: The transaction intent. Learn more.
   • Amount and currency: Details about the payment amount and currency. Enter the transaction amount and select the currency code in ISO 4217 format.
   • Site: Select a site. Only sites that have the service activated are displayed. This selection determines which branding and settings apply.
   • Shopper country: The country code, in ISO 3166-1 alpha-2 format.
2. Next, complete the Link configuration section:
   • Link name: A human-readable link name. This is solely for display purposes in the Unity Portal, for easier identification.
   • Link type: The type of link to create.

     Note that with open-use links, you won't be able to perform merchant-initiated, card-on-file transactions, or any other operation that requires knowing the customer's identity.

   • Link validity: The number of hours until the link expires.
   • AVS: The type of AVS.
3. Optionally, choose which payment methods to accept with this specific link. By default, all payment methods configured for this site are accepted.
4. Next, click Add product in the Product info section. You'll need to enter a product name and optionally, add a product description and product image. Click Add to confirm.
   
5. Lastly, search for the shopper data fields that you'd like to make mandatory. Learn more about shopper data.

Step 3: Configure the after-payment page

In the After payment tab, choose between showing a confirmation page (default setting) or redirecting customers to your website URL. You can replace the message on the confirmation page with your own. Note that this isn't localised.

Step 4: Create the link

When you're done, click Create link to generate your payment link. If the button isn't active, then at least one required field is missing.

Your new payment link URL is displayed and ready to be used.

Step 5: Share the link

In the Action column, click the copy icon () to copy the URL or click ... > Generate QR code to create a QR code that you can either download or copy.

Make sure to review all configuration details before you share it with your customers.

Create a link via API

Request example

Use the following request to create a payment link.

curl -i -X POST \
  https://api-services.pxp.io/api/v1/paybylink \
  -H "Content-Type: application/json" \
  -H "Authorization: PXP-UST1 e0c3d199-0884-4ac7-ab8b-dc97cff87f7d:1725607935:A1B2C3D4E5F6789012345678901234567890ABCDEF1234567890ABCDEF123456" \
  -H "X-Request-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Client-Id: b14d0efd-b57f-470a-932d-c5d8517ff021" \
  -d '{
    "merchantTransactionId": "ORDER-2025-001",
    "amounts": {
      "transaction": 29.99,
      "currencyCode": "USD"
    },
    "products": [
      {
        "name": "Premium Widget",
        "description": "High-quality widget with advanced features",
        "productImageUrl": "https://example.com/product-image.jpg"
      }
    ],
    "linkConfiguration": {
      "type": "SingleUse",
      "name": "Invoice Payment Link",
      "expiresInHours": 72
    },
    "shopper": {
      "countryCode": "US",
      "merchantShopperId": "CUST_001",
      "shopperInputPreferences": {
        "email": true,
        "firstName": true,
        "lastName": true,
        "address": false
      }
    },
    "site": "site-1",
    "merchant": "merchant-1",
    "intent": "Purchase",
    "avs": {
      "type": "SkipAvs"
    },
    "allowedFundingTypes": {
      "cards": ["Visa", "Mastercard", "AmericanExpress"],
      "wallets": ["PayPal"]
    },
    "afterPaymentConfiguration": {
      "afterPaymentConfigurationType": "Redirect",
      "redirectUrl": "https://yourstore.com/payment-success",
      "customMessage": "Thank you for your purchase!"
    }
  }'

Body parameters

Response example

If your request is successful, you'll receive a 200 response containing the payment link details, including its url. You can now view and manage your payment link in the Unity Portal's Pay by Link section.

{
  "linkId": "06da69e0-b668-40b2-ba2f-6c505f08866c",
  "url": "https://paybylink.dev.pxp.io/06da69e0-b668-40b2-ba2f-6c505f08866c",
  "status": "Active",
  "expirationTimestamp": "2025-09-11T04:12:15.3044876Z",
  "site": "site-1",
  "amounts": {
    "transaction": 29.99,
    "currencyCode": "USD"
  },
  "merchantTransactionId": "ORDER-2025-001",
  "merchantShopperId": "CUST_001",
  "afterPaymentConfiguration": {
    "afterPaymentConfigurationType": "Redirect",
    "redirectUrl": "https://yourstore.com/payment-success",
    "customMessage": "Thank you for your purchase!"
  }
}

Response parameters

Best practices

Security

• Use appropriate link validity periods that aren't too long, for security reasons. For high-value transactions in particular, consider shorter expiration times.
• Use shopper IDs consistently for your returning customers.

Customer experience

• Include product information when possible.
• Choose appropriate shopper data collection. Only request the information you need.
• Provide clear instructions when sharing links.
• Include expiration information in communications.
• Offer alternative payment methods for expired links.
• Always test your links before sharing them with customers.
• Ensure your branding is professional and recognisable.