Use this method to return a paginated list of payment links linked to a processing terminal.
Note: If you want to view the details of a specific payment link and you have its paymentLinkId, use our Retrieve Payment Link method.
Use query parameters to filter the list of results that we return, for example, to search for only active links or multi-use links.
Our gateway returns the following information about each payment link in the list:
type - Indicates whether the link can be used only once or if it can be used multiple times.
authType - Indicates whether the transaction is a sale or a pre-authorization.
paymentMethods - Indicates the payment method that the merchant accepts.
charge - Indicates whether the merchant or the customer enters the amount for the transaction.
status - Indicates if the payment link is active.
For each payment link, we also return a paymentLinkId, which you can use for follow-on actions.
Parameters
Name
In
Type
Description
processingTerminalIdRequired
path
string
Unique identifier that we assigned to the terminal.
merchantReference
query
string
Filter results by the unique identifier that the merchant assigned to the payment link.
linkType
query
string
Filter results by the type of link. Send a value of <code>singleUse</code> or <code>multiUse</code>.
chargeType
query
string
Filter results by the user that entered the amount. Send one of the following values:
<code>prompt</code> - Customer entered the amount.
<code>preset</code> - Merchant entered the amount.
status
query
string
Filter results by the status of the payment link. Send a value of <code>active</code>, <code>completed</code>,<code>deactived</code>, or <code>expired</code>.
recipientName
query
string
Filter results by the customer's name.
recipientEmail
query
string
Filter results by the customer's email address.
createdOn
query
string
Filter results by the link's created date. Send a value in YYYY-MM-DD format.
expiresOn
query
string
Filter results by the link's expiry date. Send a value in YYYY-MM-DD format.
before
query
string
Return the previous page of results before the value that you specify.
You can’t send the before parameter in the same request as the after parameter.
after
query
string
Return the next page of results after the value that you specify.
You can’t send the after parameter in the same request as the before parameter.
limit
query
integer
Limit the maximum number of results that we return for each page.
Responses
Successful request. Returns a paginated list of payment links.
Number of results we returned on this page. Note: This might not be the total number of results that match your query.
hasMorebooleanrequired
Indicates whether there is another page of results available.
limitintegerrequired
Maximum number of results that we return for each page.
linksobject[]
Reference links to navigate to the previous page of results or to the next page of results.
hrefstringrequired
URL of the target resource.
methodstringrequired
HTTP method that you need to use with the target resource.
relstringrequired
Indicates the relationship between the current resource and the target resource.
dataobject[]required
Array of polymorphic objects that contains payment link information. The value of the type parameter determines which variant you should use: 'multiUse' - Create a link that the merchant can use to take multiple payments. 'singleUse' - Create a link that the merchant can use for only one payment.
multiUseobject
Object that contains information about a multi-use payment link.
assetsobject
Object that contains shareable assets for the payment link.
paymentButtonstringhtmlrequired
HTML code for the payment link. You can embed the HTML code in the merchant's website.
paymentUrlstringrequired
URL of the payment link.
authTypestringrequired
Type of transaction.salepreAuthorization
createdOnstringdate
Date that the merchant created the link. The format of this value is YYYY-MM-DD.
credentialOnFileobject
Object that contains information about saving the customer’s payment details.
mitAgreementstring
Indicates how the merchant can use the customer’s card details, as agreed by the customer: unscheduled Transactions for a fixed or variable amount that are run at a certain pre-defined event. recurring Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don’t have a fixed duration and run until the customer cancels the agreement. installment Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. Note: If you send a value for mitAgreement, you must send the standingInstructions object in the paymentOrder object.unscheduledrecurringinstallment
tokenizeboolean
Indicates if our gateway should tokenize the customer’s payment details as part of the transaction.
customLabelsobject[]
Array of customLabel objects. Note: You can change the label of the payment button only.
elementstring
Element that you want to provide a custom label for.paymentButton
labelstring
Custom label to display on the element.1–24 chars
expiresOnstringdate
Last date that the customer can use the payment link. The format of this value is YYYY-MM-DD. Note: If you don't provide an expiration date, the default expiration period applies. You can change the default expiration period on the Self-Care Portal.
merchantReferencestringrequired
Unique identifier that the merchant assigned to the payment.1–48 chars
orderobjectrequired
Object that contains information about the order.
chargeobjectrequired
Polymorphic object that indicates who enters the amount for the payment link. The value of the type parameter determines which variant you should use: prompt Customer enters the amount. preset Merchant sets the amount.
promptobject
Object that contains information about the charge when the customer enters the amount of the transaction.
currencystringrequired
Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
typestringrequired
prompt
presetobject
Object that contains information about the charge when the merchant enters the amount of the transaction.
amountintegerint64required
Total amount of the transaction. The value is in the currency's lowest denomination, for example, cents.
currencystringrequired
Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
typestringrequired
preset
descriptionstring
A brief description of the transaction.≤ 1024 chars
paymentLinkIdstring
Unique identifier that we assigned to the payment link.10–10 chars
paymentMethodsstring[]required
Payment methods that the merchant accepts. Note: If a payment is a pre-authorization, the customer must pay by card.
statusstring
Status of the payment link. The value is one of the following: active Payment link is active. completed Customer has paid. deactivated Merchant has deactivated the link. expired Payment link has expired.activecompleteddeactivatedexpired
typestringrequired
Type of link. The merchant can use a multi-use link to take multiple payments.multiUse
singleUseobject
Object that contains information about a single-use payment link.
assetsobject
Object that contains shareable assets for the payment link.
paymentButtonstringhtmlrequired
HTML code for the payment link. You can embed the HTML code in the merchant's website.
paymentUrlstringrequired
URL of the payment link.
authTypestringrequired
Type of transaction.salepreAuthorization
createdOnstringdate
Date that the merchant created the link. The format of this value is YYYY-MM-DD.
credentialOnFileobject
Object that contains information about saving the customer’s payment details.
mitAgreementstring
Indicates how the merchant can use the customer’s card details, as agreed by the customer: unscheduled Transactions for a fixed or variable amount that are run at a certain pre-defined event. recurring Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don’t have a fixed duration and run until the customer cancels the agreement. installment Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. Note: If you send a value for mitAgreement, you must send the standingInstructions object in the paymentOrder object.unscheduledrecurringinstallment
tokenizeboolean
Indicates if our gateway should tokenize the customer’s payment details as part of the transaction.
customLabelsobject[]
Array of customLabel objects. Note: You can change the label of the payment button only.
elementstring
Element that you want to provide a custom label for.paymentButton
labelstring
Custom label to display on the element.1–24 chars
expiresOnstringdaterequired
Last date that the customer can use the payment link. The format of this value is YYYY-MM-DD.
merchantReferencestringrequired
Unique identifier that the merchant assigned to the payment.1–48 chars
orderobjectrequired
Object that contains information about the order.
chargeobjectrequired
Polymorphic object that indicates who enters the amount for the payment link. The value of the type parameter determines which variant you should use: prompt Customer enters the amount. preset Merchant sets the amount.
promptobject
Object that contains information about the charge when the customer enters the amount of the transaction.
currencystringrequired
Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
typestringrequired
prompt
presetobject
Object that contains information about the charge when the merchant enters the amount of the transaction.
amountintegerint64required
Total amount of the transaction. The value is in the currency's lowest denomination, for example, cents.
currencystringrequired
Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
typestringrequired
preset
descriptionstring
A brief description of the transaction.≤ 1024 chars
orderIdstringrequired
Unique identifier that the merchant assigned to the order.1–24 chars
paymentLinkIdstring
Unique identifier that we assigned to the payment link.10–10 chars
paymentMethodsstring[]required
Payment methods that the merchant accepts. Note: If the payment is a pre-authorization, the customer must pay by card.
statusstring
Status of the payment link. The value is one of the following: active Payment link is active. completed Customer has paid. deactivated Merchant has deactivated the link. expired Payment link has expired.activecompleteddeactivatedexpired
typestringrequired
Type of link. The merchant can use this link for only one payment.singleUse
Invalid request
400 Bad Request · application/problem+json
{"detail":"One or more validation errors occurred, see error section for more info","errors":[{"detail":"invalid date","message":"Expected time, got '' for start_time","parameter":"start_time"}],"status":400,"title":"Bad request","type":"https://docs.payroc.com/api/errors#bad-request"}
Response schema · 8 fields
detailstringrequired
Explanation of the problem
errorsobject[]
detailstring
Short detail of the validation errors
messagestring
Error message
parameterstring
The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type
Identity could not be verified
401 Unauthorized · application/problem+json
{"detail":"Your identity could not be verified","status":401,"title":"Not Authorized","type":"https://docs.payroc.com/api/errors#not-authorized"}
Response schema · 4 fields
detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type
Do not have permissions to perform this action
403 Forbidden · application/problem+json
{"detail":"You do not have the required permissions to perform this action","instance":"https://api.payroc.com/v1/exampleResource/3","resource":"exampleResource","status":403,"title":"Forbidden","type":"https://docs.payroc.com/api/errors#forbidden"}
Response schema · 6 fields
detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type
Resource not found
404 Not Found · application/problem+json
{"detail":"Resource not found","resource":"(The Type of the Resource)","status":404,"title":"Not found","type":"https://docs.payroc.com/api/errors#not-found"}
Response schema · 5 fields
detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type
Not acceptable
406 Not Acceptable · application/problem+json
{"detail":"Resource does not support the representation requested","status":406,"title":"Not acceptable","type":"https://docs.payroc.com/api/errors#not-acceptable"}
Response schema · 4 fields
detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type
An error has occured
500 Internal Server Error · application/problem+json
{"detail":"We are unable to process your request at this time","errors":[{"message":"Service offline"}],"status":500,"title":"Api error","type":"https://docs.payroc.com/api/errors#api-error"}