Skip to main content

Create a New Link with Custom Rules

Overview

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

Endpoint: POST /ipl/v2/payment-links

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

For India Production, use the base URL.

Required Fields

merchantDefinedFieldValues[].definitionId

The ID of the custom field definition to populate.

merchantDefinedFieldValues[].value

The value to set for this field on the link.

Optional Fields

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:

definitionId

The ID of the custom field definition to populate.

value

The value to set for this field on the link.

Example

Production:

POST /ipl/v2/payment-links

Test:

POST /ipl/v2/payment-links
{  "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.cybersource.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"    }  ]}

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.

Last published: September 29, 2026