No results

GET/v3/orders/paybylink

PROD
https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v3/orders/paybylink
TEST
https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v3/orders/paybylink

Retrieve a list of previously created PayByLink

PARAM HEADER
NAME DESCRIPTION FORMAT
Correlation-Id Mandatory field in UUID v4 format.
The purpose of this field is to trace the request across different systems, making debugging and request tracking easier.
 String
Format: uuid
Example: 123e4567-e89b-12d3-a456-426614174000
X-Api-Key Authentication API Key. String
Format: uuid
Example: 625b4884-38f8-11ed-a261-0242ac120002
PARAM PATH
NAME DESCRIPTION FORMAT
No param path
PARAM QUERY
NAME DESCRIPTION FORMAT
search Query parameter that can be expressed to match the following fields inside the entity.
Below a detail description of the fields searchable:
- linkId:
- description: The unique identifier of the Pay By Link.
- format: uuid
- type: string
- example: "99a172e5-423c-4648-9895-4cb5d1d43134"
- orderId:
- description: 'Merchant order id, unique in the merchant domain'
- example: btid2384983
- maxLength: 18
- type: string
- terminalId:
- type: string
- description: the terminal identifier
- example: '12345678'
- status:
- description: the paybylink status
- format:
- type: string
- example: "ACTIVE"
- enum:
- ACTIVE
- INACTIVE
- DELETED
- COMPLETED
- AmountType:
- description:
- format:
- type: string
- example: "FIXED"
- enum:
- FIXED
- OPEN
- PREDEFINED_VALUES
- amount:
- description: Paybylink amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
- example: '3545'
- type: string
- usage:
- type: integer
- example: 2
- description: >
Indicates how many times the pay-by-link has been used by consumers to initiate a payment. This value reflects the total number of successful attempts to access and use the link for payment purposes.
- PaymentType:
- type: string
- enum:
- ONE_PAYMENT
- MULTIPLE_PAYMENT
- UNLIMITED
 String
Example: To define the standard for the string search
sort Identifying the order of the elements to be returned. This contains the name of the field and the way of ordering (ASC, DESC).
Below a detail description of the fields sortable:.
- expirationDate
- orderId
 String
Example: To define the standard for the string sort
pageSize Maximum number of results to be returned per page Integer
Example: 10
page Page number Integer
Example: 1
PARAM BODY

NAME DESCRIPTION FORMAT
No param body
Arrow RESPONSE 200
OK - No Header for this response
BODY
NAME DESCRIPTION FORMAT
pagination Pagination information for the response.
 Object
page Current page number (1-based index).
 Integer
pageCount Total number of pages available based on the total items and page size.
 Integer
pageSize Number of items per page.
 Integer
total Total number of items matching the search criteria.
 Integer
paybylinks A list of pay-by-link payment objects that match the search criteria. Array
orderLight A lightweight representation of an order, containing only essential information. This is used in contexts where full order details are not necessary, such as in lists or summaries.
 Object
amount Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
 String
Example: 3545
currency Transaction currency. ISO 4217 alphabetic code
 String
Example: EUR
customField Additional transaction description String
Max. length: 255
Example: weekend promotion
customerInfo Customer information associated with the order.
 Object
cardHolderName Full name of the card holder String
Max. length: 255
Example: Mauro Morandi
description Transaction description String
Max. length: 255
Example: TV LG 3423
orderId Merchant order id, unique in the merchant domain String
Max. length: 27
Example: btid2384983
payByLinkSettings Settings for the pay-by-link payment. This object contains configuration options such as predefined amounts, expiration date, and payment type.
 Object
amountType The type of the amount that can be specified for the PayByLink. It can be either FIXED, meaning that the amount is predetermined and cannot be changed by the customer, or VARIABLE, meaning that the customer can choose the amount within the specified min and max limits.
 String
Default: FIXED
collectCustomerData Configuration for collecting customer data fields with their requirements and associated policies Object
fields Multiple customer data fields to collect with their requirements Array
field Available customer data fields that can be collected:
* cardHolderName - Full name of the card holder
* cardHolderEmail - Email address of the card holder
* phoneNumber - Phone number of the customer
* tin - Tax Identification Number
* billingAddress - Billing address details
* shippingAddress - Shipping address details
 String
requirement Requirement level for customer data collection:
* mandatory - Field must be provided by the customer
* optional - Field can be left empty by the customer
* hidden - Field is not displayed to the customer
 String
descriptions A list of descriptions that can be displayed on the payment page. Each description can be provided in multiple languages.
 Array
lang Language in ISO 639-2 three-letter code. String
Min. length: 3
Max. length: 3
Default: ITA
Example: ENG
title The title of the description, which can be used to summarize the content of the description.
 String
Max. length: 255
value A list of label-value pairs that provide details about the payment. Each pair consists of a label (e.g., "Number of people") and a corresponding value (e.g., "4").
 String
Max. length: 1000
expirationDateTime The date and time when the Pay By Link will expire. It is in ISO 8601 format. Up to 90 days from the current date.
 String
Example: 2023-12-31T23:59:59Z
image A URL to an image that will be displayed on the payment page. This can be used for branding purposes, such as displaying the merchant's logo.
 String
Max. length: 700000
imageType The type of the image, e.g., PNG, JPEG. This field is optional and can be used to specify the format of the image.
 String
maxAmount The maximum amount allowed for the payment link. This value is used to validate the payment amount entered by the customer.
 String
Example: 100
maxPayments The maximum number of payments allowed for the payment link. This value is used to limit the number of times a customer can make a payment using the link.
 String
Example: 12
minAmount The minimum amount allowed for the payment link. This value is used to validate the payment amount entered by the customer.
 String
Example: 10
paymentType The type of payment, which can be either a one-time payment or allow multiple payments within the same PayByLink.
 String
Default: ONE_PAYMENT
predefinedAmounts A semicolon-separated list of predefined amounts for the payment link. For example: "100;200;300".
 String
Example: 100;200;300
paybylinkLight A lightweight representation of a pay-by-link payment object, containing essential information for search results.
 Object
amount The amount of the payment in the smallest currency unit (e.g., cents for USD). String
creationDate The timestamp related to paybylink creation date in ISO 8601 format String
Example: 2022-09-01T01:20:00.001Z
donation Indicates whether the pay-by-link was generated for donation purposes. A value of `true` means the link is intended to be used for collecting donations.
 Boolean
Example: 1
link The unique URL for the pay-by-link payment. This link can be shared with customers to facilitate payments.
 String
linkId The unique identifier for the pay-by-link payment. This ID can be used for tracking and management purposes.
 String
status The status of the Pay By Link. It can be ACTIVE, INACTIVE, or DELETED. ACTIVE means the link is active and can be used for payments, INACTIVE means the link is not active and cannot be used for payments, DELETED means the link has been deleted.
 String
updateDate The timestamp related to paybylink update date in ISO 8601 format String
Example: 2022-10-01T01:20:00.001Z
usage Indicates how many times the pay-by-link has been used by consumers to initiate a payment. This value reflects the total number of successful attempts to access and use the link for payment purposes.
 Integer
Example: 2
Arrow RESPONSE 400
Missing or invalid Correlation-Id - No Header for this response
BODY
NAME DESCRIPTION FORMAT
error String
Arrow RESPONSE 401
Unauthorized - No Header and Body for this response
Arrow RESPONSE 403
Forbidden - No Header and Body for this response
Arrow RESPONSE 404
PayByLink not found for the given Correlation-Id - No Header for this response
BODY
NAME DESCRIPTION FORMAT
error String