PayByLink API

PayByLink API (1.0.0)

This is an API reference for the PayByLink service. The PayByLink API enables you to programmatically generate secure payment links for your customers with comprehensive configuration options for payment methods, customer data collection, and post-payment behaviours.

Download OpenAPI description

links.json

links.yaml

Servers

Production environment

https://api-services.pxp.io/api/v1/

Sandbox environment

https://api-services.test.pxp.io/api/v1/

Create a payment link

Request

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.

Security

PXP-UST1

Headers

X-Request-Idstring(uuid)required

UUID v4 request identifier.

Example: 550e8400-e29b-41d4-a716-446655440000

X-Client-Idstringrequired

Your merchant client identifier.

Example: b14d0efd-b57f-470a-932d-c5d8517ff021

Bodyapplication/jsonrequired

merchantTransactionIdstring<= 50 charactersrequired

A unique identifier for this transaction.

Example: "ORDER-2025-001"

amountsobject(PaymentAmounts)required

Details about the payment amount and currency.

amounts.transactionnumber(decimal)>= 0.01required

The transaction amount.

Example: 29.99

amounts.currencyCodestring= 3 characters^[A-Z]{3}$required

The currency code, in ISO 4217 format.

Example: "USD"

productsArray of objects(Product)non-emptyrequired

Array of product information for display on the payment page.

products[].namestring<= 100 charactersrequired

The product name.

Example: "Premium Widget"

products[].descriptionstring<= 500 characters

The product description.

Example: "High-quality widget with advanced features"

products[].productImageUrlstring(uri)^https://

The URL of the product image.

Example: "https://example.com/product-image.jpg"

linkConfigurationobject(LinkConfiguration)required

Details about the link behaviour.

linkConfiguration.typestringrequired

The type of link to create.

Enum"SingleUse""OpenUse"

Example: "SingleUse"

linkConfiguration.namestring<= 100 characters

A human-readable link name. This is solely for display purposes in the Unity Portal, for easier identification.

Example: "Invoice Payment Link"

linkConfiguration.expiresInHoursinteger>= 1

The number of hours until the link expires.

Example: 72

shopperobject(Shopper)required

Details about the customer.

shopper.countryCodestring= 2 characters^[A-Z]{2}$required

ISO 3166-1 alpha-2 country code

Example: "US"

shopper.merchantShopperIdstring

Your internal customer ID.

Example: "CUST_001"

shopper.shopperInputPreferencesobject(ShopperInputPreferences)

Details about the shopper input preferences.

sitestringrequired

Your merchant site identifier from your PXP configuration.

Example: "site-1"

merchantstringrequired

Your merchant identifier from your PXP configuration.

Example: "merchant-1"

intentstringrequired

The transaction intent. Learn more.

Enum"Purchase""Authorisation""EstimatedAuthorisation"

Example: "Purchase"

avsobject(AddressVerificationSystem)required

Details about the AVS.

avs.typestringrequired

The type of AVS.

Enum"EnableAvsCustomerProvidedAddress""EnableAvsMerchantProvidedAddress""SkipAvs"

Example: "SkipAvs"

avs.addressVerificationobject(AddressVerification)

Pre-filled address verification data (required when AVS type is EnableAvsMerchantProvidedAddress)

allowedFundingTypesobject(AllowedFundingTypes)

Details about the allowed funding types.

afterPaymentConfigurationobject(AfterPaymentConfiguration)

Details about the post-payment behaviour.

curl -i -X POST \
  https://api-services.pxp.io/api/v1/paybylink \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -H 'X-Client-Id: b14d0efd-b57f-470a-932d-c5d8517ff021' \
  -H 'X-Request-Id: 550e8400-e29b-41d4-a716-446655440000' \
  -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": false,
        "phoneNumber": false,
        "firstName": false,
        "lastName": false,
        "address": false,
        "dateOfBirth": false,
        "customerNumber": false,
        "productSpecifications": false
      }
    },
    "site": "site-1",
    "merchant": "merchant-1",
    "intent": "Purchase",
    "avs": {
      "type": "SkipAvs",
      "addressVerification": {
        "countryCode": "US",
        "houseNumberOrName": "123 Main Street",
        "postalCode": "12345"
      }
    },
    "allowedFundingTypes": {
      "cards": [
        "Visa",
        "Mastercard"
      ],
      "wallets": [
        "PayPal"
      ]
    },
    "afterPaymentConfiguration": {
      "afterPaymentConfigurationType": "Redirect",
      "redirectUrl": "https://yourstore.com/payment-success",
      "customMessage": "Thank you for your purchase!"
    }
  }'

Responses

Payment link created successfully

Bodyapplication/json

linkIdstring(uuid)

The unique payment link identifier generated by PXP. Use this for tracking and management operations.

Example: "06da69e0-b668-40b2-ba2f-6c505f08866c"

urlstring(uri)

The complete payment link URL that you can share with customers. This is the link customers will use to make their payment.

Example: "https://paybylink.dev.pxp.io/06da69e0-b668-40b2-ba2f-6c505f08866c"

statusstring

The current status of the payment link.

Enum"Active""Cancelled""Completed""Expired""Error"

Example: "Active"

expirationTimestampstring(date-time)

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"

sitestring

The site identifier used in the request, confirming the merchant configuration.

Example: "site-1"

amountsobject(PaymentAmounts)

Details about the payment amount and currency.

merchantTransactionIdstring

Your transaction identifier from the request, used for reconciliation and tracking.

Example: "ORDER-2025-001"

merchantShopperIdstring

The customer identifier, if provided in the request.

Example: "CUST_001"

afterPaymentConfigurationobject(AfterPaymentConfiguration)

Details about the post-payment behaviour.

Response

application/json

{
  "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": 180,
    "currencyCode": "USD"
  },
  "merchantTransactionId": "bbb958c6-37bc-47e3-8dd3-6122d4e361d5",
  "merchantShopperId": "CUST_001",
  "afterPaymentConfiguration": {
    "afterPaymentConfigurationType": "Redirect",
    "redirectUrl": "https://localhost:5325/api/v1/paybylink",
    "customMessage": "custom message"
  }
}

PayByLink API (1.0.0)

Create a payment link

RequestExpand all

Responses

Was this helpful?

Request