Pay by Link

These endpoints allow you to create and manage payment links. Payment links are reusable or single-use payment URLs that can be shared with customers, supporting fixed or variable amounts, usage limits, and expiration dates.

Create a payment link

The POST /v2/payment-links endpoint creates a new payment link with payment template and link configuration. Payment links allow you to create reusable or single-use payment URLs that can be shared with customers. The link can have fixed or variable amounts, usage limits, and expiration dates.

SecurityBearer or BasicAuth

Request

Request Body schema: application/json
required

required	object (PaymentTemplate) The payment template containing payment details. The amount.currency is always required. For fixed amount payment links, both amount.currency and amount.value must be provided. For variable amount payment links where the payer provides the amount, omit amount.value.
	object (LinkConfig) Link configuration with usage limits and expiration.

Responses

200

Payment link created successfully

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

500

An unexpected or internal server error

post/v2/payment-links

Request samples

application/json

{"paymentTemplate": {"id": "pt-019daa05-dcf3-7920-87fc-53b36d58deea",
"amount": {"currency": "EUR",
"value": "10.00"
},
"localInstrument": "SEPA",
"creditor": {"iban": "GB29NWBK60161331926819",
"bic": "BOFIIE2D",
"name": "Customer Inc.",
"ultimateCreditorName": "Customer Inc.",
"address": {"addressLine": ["The Coach House"
],
"streetName": "221B",
"buildingNumber": "2C",
"postCode": "TR26 1EZ",
"townName": "Saint Ives",
"state": "Cornwall",
"district": "string",
"country": "GB"
},
"bankName": "string",
"accountVerificationId": "string"
},
"refId": "COFFEESHOP123",
"remittanceInformationPrimary": "Sweepco",
"remittanceInformationSecondary": "Secondary remittance information.",
"externalPsuReference": "psu external reference 12345",
"callbackUrl": "https://tpp.com/callback",
"chargeBearer": "CRED",
"confirmFunds": true,
"returnRefundAccount": true,
"onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
"risk": {"psuId": "0000789123",
"paymentContextCode": "PISP_PAYEE",
"paymentPurposeCode": "DVPM",
"merchantCategoryCode": "4812",
"beneficiaryAccountType": "BUSINESS",
"contractPresentIndicator": true,
"beneficiaryPrepopulatedIndicator": true,
"deliveryAddress": {"addressLine": ["Flat 2, The Red Lodge, 1 High Street"
],
"addressType": "BUSINESS",
"buildingNumber": "1",
"country": "GB",
"countrySubDivision": ["North Yorkshire"
],
"department": "1",
"postCode": "YO62 5JB",
"streetName": "High Street",
"subDepartment": "Flat 2",
"townName": "York"
}
}
},
"linkConfig": {"maxUsageCount": 100,
"perPaymentAmountLimit": "100.00",
"totalAmountLimit": "5000.00",
"expiresAt": "2026-12-31T23:59:59Z"
}
}

Response samples

application/json

{"paymentLink": {"id": "pl-019c8a02-a30e-7307-83da-7428239da59d",
"memberId": "m:member123:token456",
"status": "LINK_ACTIVE",
"createdAt": "2026-01-01T00:00:00Z",
"paymentTemplate": {"id": "pt-019daa05-dcf3-7920-87fc-53b36d58deea",
"amount": {"currency": "EUR",
"value": "10.00"
},
"localInstrument": "SEPA",
"creditor": {"iban": "GB29NWBK60161331926819",
"bic": "BOFIIE2D",
"name": "Customer Inc.",
"ultimateCreditorName": "Customer Inc.",
"address": {"addressLine": ["The Coach House"
],
"streetName": "221B",
"buildingNumber": "2C",
"postCode": "TR26 1EZ",
"townName": "Saint Ives",
"state": "Cornwall",
"district": "string",
"country": "GB"
},
"bankName": "string",
"accountVerificationId": "string"
},
"refId": "COFFEESHOP123",
"remittanceInformationPrimary": "Sweepco",
"remittanceInformationSecondary": "Secondary remittance information.",
"externalPsuReference": "psu external reference 12345",
"callbackUrl": "https://tpp.com/callback",
"chargeBearer": "CRED",
"confirmFunds": true,
"returnRefundAccount": true,
"onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
"risk": {"psuId": "0000789123",
"paymentContextCode": "PISP_PAYEE",
"paymentPurposeCode": "DVPM",
"merchantCategoryCode": "4812",
"beneficiaryAccountType": "BUSINESS",
"contractPresentIndicator": true,
"beneficiaryPrepopulatedIndicator": true,
"deliveryAddress": {"addressLine": ["Flat 2, The Red Lodge, 1 High Street"
],
"addressType": "BUSINESS",
"buildingNumber": "1",
"country": "GB",
"countrySubDivision": ["North Yorkshire"
],
"department": "1",
"postCode": "YO62 5JB",
"streetName": "High Street",
"subDepartment": "Flat 2",
"townName": "York"
}
}
},
"linkConfig": {"maxUsageCount": 100,
"perPaymentAmountLimit": "100.00",
"totalAmountLimit": "5000.00",
"expiresAt": "2026-12-31T23:59:59Z"
},
"url": "https://app.token.io/pay-by-link/pl-019c8a02-a30e-7307-83da-7428239da59d",
"currentUsage": {"remainingCount": 77,
"remainingAmount": "4100.00"
}
}
}

List payment links

The GET /v2/payment-links endpoint returns a list of payment links. At least one filter parameter must be provided. Results can be filtered by IDs, statuses, creation date range (createdAfter, createdBefore), expiration date range (expiresAfter, expiresBefore), external PSU reference, and on-behalf-of ID.

SecurityBearer or BasicAuth

Request

query Parameters

ids	Array of strings Filter by payment link ID list Example: ids=pl-019c8a02-a30e-7307-83da-7428239da59d&ids=pl-019f0d3a-9c4b-7a1e-8c2f-0b7d9a4e3c12
statuses	Array of strings (PaymentLinkStatusFilter) Filter by link statuses Items Enum: "LINK_ACTIVE" "LINK_EXPIRED" "LINK_CANCELED" "USAGE_LIMIT_REACHED" "AMOUNT_LIMIT_REACHED" Example: statuses=LINK_ACTIVE&statuses=LINK_EXPIRED
onBehalfOfId	string Filter by on behalf of ID Example: onBehalfOfId=c5a863bc-86f2-4418-a26f-25b24c7983c7
externalPsuReference	string (ExternalPsuReference) <= 64 characters Filter by external PSU Reference Example: externalPsuReference=customer_456789_coffee_order
createdAfter	string <date-time> Filter links created after this timestamp (in ISO 8601 format) Example: createdAfter=2026-01-01T00:00:00Z
createdBefore	string <date-time> Filter links created before this timestamp (in ISO 8601 format) Example: createdBefore=2026-01-01T00:00:00Z
expiresAfter	string <date-time> Filter links expiring after this timestamp (in ISO 8601 format) Example: expiresAfter=2026-01-01T00:00:00Z
expiresBefore	string <date-time> Filter links expiring before this timestamp (in ISO 8601 format) Example: expiresBefore=2026-01-01T00:00:00Z
limit	integer <int32> [ 1 .. 200 ] Maximum number of results to return
offset	string The offset for the current page. The offset is not required to fetch the first page. To fetch subsequent pages, use the 'nextOffset' value from the previous page response. Example: offset=019f0d6b-3e21-7c9a-9f04-6a2b8d1c7e53

Responses

200

List of payment links

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

500

An unexpected or internal server error

get/v2/payment-links

Request samples

Response samples

application/json

{"paymentLinks": [{"id": "pl-019c8a02-a30e-7307-83da-7428239da59d",
"memberId": "m:member123:token456",
"status": "LINK_ACTIVE",
"createdAt": "2026-01-01T00:00:00Z",
"paymentTemplate": {"id": "pt-019daa05-dcf3-7920-87fc-53b36d58deea",
"amount": {"currency": "EUR",
"value": "10.00"
},
"localInstrument": "SEPA",
"creditor": {"iban": "GB29NWBK60161331926819",
"bic": "BOFIIE2D",
"name": "Customer Inc.",
"ultimateCreditorName": "Customer Inc.",
"address": {"addressLine": ["The Coach House"
],
"streetName": "221B",
"buildingNumber": "2C",
"postCode": "TR26 1EZ",
"townName": "Saint Ives",
"state": "Cornwall",
"district": "string",
"country": "GB"
},
"bankName": "string",
"accountVerificationId": "string"
},
"refId": "COFFEESHOP123",
"remittanceInformationPrimary": "Sweepco",
"remittanceInformationSecondary": "Secondary remittance information.",
"externalPsuReference": "psu external reference 12345",
"callbackUrl": "https://tpp.com/callback",
"chargeBearer": "CRED",
"confirmFunds": true,
"returnRefundAccount": true,
"onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
"risk": {"psuId": "0000789123",
"paymentContextCode": "PISP_PAYEE",
"paymentPurposeCode": "DVPM",
"merchantCategoryCode": "4812",
"beneficiaryAccountType": "BUSINESS",
"contractPresentIndicator": true,
"beneficiaryPrepopulatedIndicator": true,
"deliveryAddress": {"addressLine": ["Flat 2, The Red Lodge, 1 High Street"
],
"addressType": "BUSINESS",
"buildingNumber": "1",
"country": "GB",
"countrySubDivision": ["North Yorkshire"
],
"department": "1",
"postCode": "YO62 5JB",
"streetName": "High Street",
"subDepartment": "Flat 2",
"townName": "York"
}
}
},
"linkConfig": {"maxUsageCount": 100,
"perPaymentAmountLimit": "100.00",
"totalAmountLimit": "5000.00",
"expiresAt": "2026-12-31T23:59:59Z"
},
"url": "https://app.token.io/pay-by-link/pl-019c8a02-a30e-7307-83da-7428239da59d",
"currentUsage": {"remainingCount": 77,
"remainingAmount": "4100.00"
}
}
],
"pageInfo": {"limit": 20,
"offset": "LerV6Jmex",
"nextOffset": "KgwG8Qkat",
"haveMore": false
}
}

Get payment link details

The GET /v2/payment-links/{paymentLinkId} endpoint retrieves detailed information about a specific payment link including current usage statistics.

SecurityBearer or BasicAuth

Request

path Parameters

paymentLinkId

required

string

Payment link ID

Example: pl-019c8a02-a30e-7307-83da-7428239da59d

Responses

200

Payment link details

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

404

The requested payment link was not found

500

An unexpected or internal server error

get/v2/payment-links/{paymentLinkId}

Request samples

Response samples

application/json

{"paymentLink": {"id": "pl-019c8a02-a30e-7307-83da-7428239da59d",
"memberId": "m:member123:token456",
"status": "LINK_ACTIVE",
"createdAt": "2026-01-01T00:00:00Z",
"paymentTemplate": {"id": "pt-019daa05-dcf3-7920-87fc-53b36d58deea",
"amount": {"currency": "EUR",
"value": "10.00"
},
"localInstrument": "SEPA",
"creditor": {"iban": "GB29NWBK60161331926819",
"bic": "BOFIIE2D",
"name": "Customer Inc.",
"ultimateCreditorName": "Customer Inc.",
"address": {"addressLine": ["The Coach House"
],
"streetName": "221B",
"buildingNumber": "2C",
"postCode": "TR26 1EZ",
"townName": "Saint Ives",
"state": "Cornwall",
"district": "string",
"country": "GB"
},
"bankName": "string",
"accountVerificationId": "string"
},
"refId": "COFFEESHOP123",
"remittanceInformationPrimary": "Sweepco",
"remittanceInformationSecondary": "Secondary remittance information.",
"externalPsuReference": "psu external reference 12345",
"callbackUrl": "https://tpp.com/callback",
"chargeBearer": "CRED",
"confirmFunds": true,
"returnRefundAccount": true,
"onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
"risk": {"psuId": "0000789123",
"paymentContextCode": "PISP_PAYEE",
"paymentPurposeCode": "DVPM",
"merchantCategoryCode": "4812",
"beneficiaryAccountType": "BUSINESS",
"contractPresentIndicator": true,
"beneficiaryPrepopulatedIndicator": true,
"deliveryAddress": {"addressLine": ["Flat 2, The Red Lodge, 1 High Street"
],
"addressType": "BUSINESS",
"buildingNumber": "1",
"country": "GB",
"countrySubDivision": ["North Yorkshire"
],
"department": "1",
"postCode": "YO62 5JB",
"streetName": "High Street",
"subDepartment": "Flat 2",
"townName": "York"
}
}
},
"linkConfig": {"maxUsageCount": 100,
"perPaymentAmountLimit": "100.00",
"totalAmountLimit": "5000.00",
"expiresAt": "2026-12-31T23:59:59Z"
},
"url": "https://app.token.io/pay-by-link/pl-019c8a02-a30e-7307-83da-7428239da59d",
"currentUsage": {"remainingCount": 77,
"remainingAmount": "4100.00"
}
}
}

Deactivate payment link

The DELETE /v2/payment-links/{paymentLinkId} endpoint deactivates a payment link, preventing further usage. Only active payment links can be deactivated.

SecurityBearer or BasicAuth

Request

path Parameters

paymentLinkId

required

string

Payment link ID

Example: pl-019c8a02-a30e-7307-83da-7428239da59d

Responses

200

Payment link deactivated successfully

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

404

The requested payment link was not found

409

Payment link cannot be deactivated

500

An unexpected or internal server error

delete/v2/payment-links/{paymentLinkId}

Request samples

Response samples

application/json

{"paymentLink": {"id": "pl-019c8a02-a30e-7307-83da-7428239da59d",
"memberId": "m:member123:token456",
"status": "LINK_ACTIVE",
"createdAt": "2026-01-01T00:00:00Z",
"paymentTemplate": {"id": "pt-019daa05-dcf3-7920-87fc-53b36d58deea",
"amount": {"currency": "EUR",
"value": "10.00"
},
"localInstrument": "SEPA",
"creditor": {"iban": "GB29NWBK60161331926819",
"bic": "BOFIIE2D",
"name": "Customer Inc.",
"ultimateCreditorName": "Customer Inc.",
"address": {"addressLine": ["The Coach House"
],
"streetName": "221B",
"buildingNumber": "2C",
"postCode": "TR26 1EZ",
"townName": "Saint Ives",
"state": "Cornwall",
"district": "string",
"country": "GB"
},
"bankName": "string",
"accountVerificationId": "string"
},
"refId": "COFFEESHOP123",
"remittanceInformationPrimary": "Sweepco",
"remittanceInformationSecondary": "Secondary remittance information.",
"externalPsuReference": "psu external reference 12345",
"callbackUrl": "https://tpp.com/callback",
"chargeBearer": "CRED",
"confirmFunds": true,
"returnRefundAccount": true,
"onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
"risk": {"psuId": "0000789123",
"paymentContextCode": "PISP_PAYEE",
"paymentPurposeCode": "DVPM",
"merchantCategoryCode": "4812",
"beneficiaryAccountType": "BUSINESS",
"contractPresentIndicator": true,
"beneficiaryPrepopulatedIndicator": true,
"deliveryAddress": {"addressLine": ["Flat 2, The Red Lodge, 1 High Street"
],
"addressType": "BUSINESS",
"buildingNumber": "1",
"country": "GB",
"countrySubDivision": ["North Yorkshire"
],
"department": "1",
"postCode": "YO62 5JB",
"streetName": "High Street",
"subDepartment": "Flat 2",
"townName": "York"
}
}
},
"linkConfig": {"maxUsageCount": 100,
"perPaymentAmountLimit": "100.00",
"totalAmountLimit": "5000.00",
"expiresAt": "2026-12-31T23:59:59Z"
},
"url": "https://app.token.io/pay-by-link/pl-019c8a02-a30e-7307-83da-7428239da59d",
"currentUsage": {"remainingCount": 77,
"remainingAmount": "4100.00"
}
}
}

➔ Next to Account on File

Pay by Link

Create a payment link

Request Body schema: application/jsonrequired

List payment links

query Parameters

Get payment link details

path Parameters

Deactivate payment link

path Parameters

Request Body schema: application/json
required