Create a New Link with Custom Rules

Send a POST request to create a payment link that includes merchant-defined custom field values. The merchantDefinedFieldValues array maps each custom field to a value using the definitionId returned when you created the field definition.

Prerequisites

Create at least one custom field definition using the Create a Default Custom Rule API. The id field in that response is the value to supply as definitionId in requests on this page.

Sending the Request

For environment base URLs, see Endpoints: Pay by Link.

Endpoint

POST /ipl/v2/payment-links

Example

{  "processingInformation": {    "linkType": "PURCHASE",    "requestPhone": false,    "requestShipping": false  },  "purchaseInformation": {    "purchaseNumber": "MY-LINK-001",    "expirationDate": "2050-08-11"  },  "orderInformation": {    "amountDetails": {      "totalAmount": "50.00",      "currency": "USD",      "taxDetails": {        "type": "State Tax",        "amount": "0.0",        "rate": "0.0"      }    },    "lineItems": [      {        "productSku": "SKU001",        "productName": "My Product",        "quantity": "1",        "unitPrice": "50.00",        "totalAmount": "50.00"      }    ]  },  "merchantDefinedFieldValues": [    {      "definitionId": 400000000001,      "value": "my-customer-ref-123"    }  ]}

{  "id": "MY-LINK-001",  "status": "ACTIVE",  "processingInformation": {    "linkType": "PURCHASE",    "requestPhone": false,    "requestShipping": false  },  "purchaseInformation": {    "purchaseNumber": "MY-LINK-001",    "expirationDate": "2050-08-11",    "createdDate": "2026-03-06T10:00:00.000",    "paymentLink": "https://pay.company.com/ipl/abc123..."  },  "orderInformation": {    "amountDetails": {      "totalAmount": 50.0,      "currency": "USD"    },    "lineItems": [      {        "productSku": "SKU001",        "productName": "My Product",        "quantity": 1,        "unitPrice": 50.0,        "totalAmount": 50.0      }    ]  },  "merchantDefinedFieldValuesWithDefinition": [    {      "definitionId": 400000000001,      "fieldType": "Text",      "label": "Customer Reference",      "customerVisible": true,      "referenceType": "Purchase",      "merchantDefinedDataIndex": 1,      "value": "my-customer-ref-123"    }  ]}

Required Fields

merchantDefinedFieldValues[].definitionId integer

The ID of the custom field definition to populate.

merchantDefinedFieldValues[].value string

The value to set for this field on the link.

No additional optional fields beyond the standard payment link fields. See Create a Fixed-Price Link for the full list of optional payment link fields.

The `merchantDefinedFieldValues` Array

Each entry in the array includes:

merchantDefinedFieldValues[] Entry Fields

definitionId integer

The ID of the custom field definition to populate.

value string

The value to set for this field on the link.

Response

A successful response returns HTTP 201. The response includes merchantDefinedFieldValuesWithDefinition, which echoes back the submitted custom field values together with their full definition metadata. Use value to confirm the submitted value was accepted. Store the id from the response to retrieve or update this link later.

Was this page helpful?

Last published: October 28, 2026