API > POST /v1/orders/paybylink

POST/v1/orders/paybylink

PROD

https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/paybylink

TEST

https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/paybylink

Generate a link to share with the customer to execute a payment. For more information, please refer to the dedicated page Pay-by-Link.

NOTES:

Through the Pay-By-Link service, it is possible to generate up to a maximum of 20 payment links per hour, while the Pay-By-Link Plus service allows the generation of 1000 links per hour.

PARAM HEADER

NAME

DESCRIPTION

FORMAT

		X-Api-Key	Authentication API Key.	String Format: uuid Example: 625b4884-38f8-11ed-a261-0242ac120002
		Correlation-Id	Unique identifier of the request.	String Format: uuid Example: 4935e818-38e0-11ed-a261-0242ac120002

PARAM PATH

NAME

DESCRIPTION

FORMAT

No param path

PARAM QUERY

NAME

DESCRIPTION

FORMAT

No param query

PARAM BODY

NAME

DESCRIPTION

FORMAT

order

Object containing the detail of the order.

Object

orderId

Merchant order id, unique in the merchant domain.

String
Max. length: 18
Example: btid2384983

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 in ISO 4217 code.

String
Example: EUR

customerId

Customer ID for this transaction.

String
Max. length: 27
Example: mcid97295873

description

Transaction description.

String
Max. length: 255
Example: TV 3423

customField

Additional transaction description.

String
Max. length: 255
Example: weekend promotion

customerInfo

Object containing the customer detail. Sending the content of this object increases the security level of the transaction, thus increasing the probability that two-factor authentication will not be requested in the payment.

Object

cardHolderName

Name and surname of the cardholder.

String
Max. length: 255
Example: Mauro Morandi

cardHolderEmail

Email of the cardholder.

String
Max. length: 255
Example: mauro.morandi@nexi.it

billingAddress

Object containing the detail of the customer's address.

Object

name	Name and surname.	String Max. length: 50 Example: Mario Rossi
street	Full address.	String Max. length: 50 Example: Piazza Maggiore, 1
additionalInfo	Additional info of address, for example floor.	String Max. length: 50 Example: Quinto Piano, Scala B
city	City.	String Min. length: 1 Max. length: 40 Example: Bologna
postCode	Postal code.	String Max. length: 16 Example: 40124
province	Code of province.	String Max. length: 3 Example: BO
country	State in ISO 3166-1 alpha-3 code. The parameter is required with the following alternative payment methods: - Bancontact: enhance "country" with "BEL". - Giropay: enhance "country" with "DEU". - Multibank: enhance "country" with "PRT".	String Min. length: 3 Max. length: 3 Example: ITA

shippingAddress

Object containing the detail of the customer's address.

Object

name	Name and surname.	String Max. length: 50 Example: Mario Rossi
street	Full address.	String Min. length: 1 Max. length: 50 Example: Piazza Maggiore, 1
additionalInfo	Additional info of address, for example floor.	String Max. length: 50 Example: Quinto Piano, Scala B
city	City.	String Min. length: 1 Max. length: 40 Example: Bologna
postCode	Postal code.	String Max. length: 16 Example: 40124
province	Code of province.	String Max. length: 3 Example: BO
country	State in ISO 3166-1 alpha-3 code.	String Min. length: 3 Max. length: 3 Example: ITA

mobilePhoneCountryCode

Prefix of the mobile phone.

String
Max. length: 4
Example: +39

mobilePhone

Mobile phone.

String
Max. length: 15
Example: 3280987654

homePhone

Home phone number provided by the Cardholder.

String
Max. length: 18
Example: +391231234567

workPhone

Work phone number provided by the Cardholder.

String
Max. length: 18
Example: 391231234567

cardHolderAcctInfo

Object containing information about the buyer's account.

Object

chAccDate	Date of activation of the account on the merchant's website.	String Example: 2019-02-11
chAccAgeIndicator	Account age indicator on the merchant site: 01 = No account 02 = Created during this transaction 03 = Created in the last 30 days 04 = Created between 30 and 60 days ago 05 = Created before 60 days ago	String Example: 01
chAccChangeDate	Date of the last variation of the account on the merchant's website, including Billing or Shipping address, new payment account, or new user(s) added.	String Example: 2019-02-11
chAccChangeIndicator	Elapsed time since the last change to the buyer's account information on the merchant site, including Billing or Shipping address, new payment account, or new user(s) added. 01 = Created during this transaction 02 = Created in the last 30 days 03 = Created between 30 and 60 days ago 04 = Created before 60 days ago	String Example: 01
chAccPwChangeDate	Date of last account password change (including password reset).	String Example: 2019-02-11
chAccPwChangeIndicator	Time elapsed since the buyer's account performed a password change or account recovery: 01 = No account 02 = Created during this transaction 03 = In the last 30 days 04 = Between 30 and 60 days ago 05 = Before 60 days ago	String Example: 01
nbPurchaseAccount	Number of purchases of this account in the last 6 months.	Number Example: 0
destinationAddressUsageDate	Date of last use of this delivery address.	String Example: 2019-02-11
destinationAddressUsageIndicator	Indicates when the shipping address used for this transaction was used for the first time: 01 = Created during this transaction 02 = Created in the last 30 days 03 = Created between 30 and 60 days ago 04 = Created before 60 days ago	String Example: 01
destinationNameIndicator	Indicates if the name associated with the account matches the name listed for shipping: 01 = Account name identical to the shipping address name. 02 = Different account name from the shipping address name	String Example: 01
txnActivityDay	Number of transactions (successful and abandoned) for this account in the previous 24 hours.	Number Example: 0
txnActivityYear	Number of transactions (successful and abandoned) for this account in the previous year.	Number Example: 0
provisionAttemptsDay	Number of attempts to add a new card in the last 24 hours.	Number Example: 0
suspiciousAccActivity	Indicates whether the merchant has detected suspicious activity (including previous fraud) on the buyer's account: 01 = No suspicious activity verified. 02 = Suspicious activity detected	String Example: 01
paymentAccAgeDate	Payment account activation date.	String Example: 2019-02-11
paymentAccIndicator	Indicates when the buyer has entered the Payment account on the merchant's site: 01 = No account 02 = created during this transaction 03 = Created in the last 30 days 04 = Created between 30 and 60 days ago 05 = Created before 60 days ago	String Example: 0

merchantRiskIndicator

Object containing information relating to the purchase made.

Object

deliveryEmail

In case of purchase of virtual/digital products: email address to which the product is sent.

String
Example: john.doe@email.com

deliveryTimeframe

Indicator on the delivery period of the goods:
01 = Immediate Delivery (virtual/digital products).
02 = Same day delivery.
03 = Night delivery.
04 = Delivery in two or more days

String
Example: 01

giftCardAmount

Object containing information relating to the amount of gift cards or vouchers.

Object

		value	Value of the gift or prepaid card used for the transaction. The amount must be expressed in cents.	Number Example: 100
		currency	Transaction currency. ISO 4217 alphabetic code.	String Example: EUR

giftCardCount

Total number of individual prepaid or gift cards/codes purchased.

Number
Example: 2

preOrderDate

For a pre-ordered purchase, the expected date that the merchandise will be available.

String
Example: 2019-02-11

preOrderPurchaseIndicator

Indicates whether buyer is placing an order for merchandise with a future availability:
01 = Goods available.
02 = Future availability.

String
Example: 01

reorderItemsIndicator

Indicates whether the cardholder is reordering previously purchased merchandise:
01 = First order.
02 = Goods already purchased previously.

String
Example: 01

shipIndicator

Indicator on the type of delivery:
01 = Shipping to the billing address.
02 = Shipping to another address verified by the merchant.
03 = Delivery to a different address than the billing.
04 = Shipment or collection to the store (the address of the store must be indicated in the "destinationAddress" object).
05 = Virtual/digital goods, including online services, electronic gift certificates, recovery codes.
06 = Travel and event tickets (not sent).
07 = Other: for example games, digital services not sent, electronic media subscriptions

String
Example: 01

transactionSummary

Array containing the transaction summary.

Array

language

Language to be used on the transaction summary details, ISO 639-2.

String
Example: eng

summaryList

Array containing the summary list.

Array

		label	Label of the fields.	String Max. length: 50 Example: Number of people
		value	Value.	String Example: 4

termsAndConditionsIds

Facility T&C identifier array. Insertion of terms and conditions

Array

paymentSession

Object containing the payment details.

Object

actionType

Indicates the type of operation:
* PAY - performs a payment transaction
* VERIFY - performs a verify operation, without any charge, with the sole purpose of confirming the validity of the card data entered by the customer
* PREAUTH - performs a preauthorization operation

String
Example: PAY

amount

Amount of the first payment which may be less or equals to the order amount. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals).

String
Example: 3545

recurrence

Object containing the detail of the occurrence.

Object

action	Defines the type of contract to use for payment: * NO_RECURRING - without contract * SUBSEQUENT_PAYMENT - use of an already created contract * CONTRACT_CREATION - contract creation * CARD_SUBSTITUTION -	String Example: NO_RECURRING
contractId	Contract ID.	String Min. length: 1 Max. length: 18 Example: C2834987
contractType	* MIT_UNSCHEDULED - once the card has been tokenized, the merchant will carry out subsequent charges with an undefined frequency * MIT_SCHEDULED - once the card has been tokenized, the merchant will carry out subsequent debits with a defined frequency (eg first of each month) * CIT - the card is tokenized to allow the cardholder to make subsequent payments faster. Unlike MIT transactions, the merchant will not have the ability to make direct debits on these tokenized cards, as the subsequent CIT payment is subject to authentication (SCA) by the cardholder	String Example: MIT_UNSCHEDULED
contractExpiryDate	Used with contractType MIT_SCHEDULED.	String Example: 2023-03-16
contractFrequency	Used with contractType MIT_SCHEDULED. Number of days.	String Max. length: 4 Example: 120

captureType

Overwrites the default confirmation method of the terminal, for card payments only:
* IMPLICIT - automatic confirmation
* EXPLICIT - authorization only

Default value depends on the terminal configuration.
    1. Terminal set to EXPLICIT:
        a. if the captureType is EXPLICIT the capture will be EXPLICIT
        b. if the captureType is null the capture will be EXPLICIT
        c. if the captureType is IMPLICIT the capture will be IMPLICIT

    2. Terminal set to IMPLICIT:
        a. if the captureType is EXPLICIT the capture will be an error
        b. if the captureType is null the capture will be IMPLICIT
        c. if the captureType is IMPLICIT the capture will be IMPLICIT

String
Example: EXPLICIT

exemptions

NO_PREFERENCE, CHALLENGE_REQUESTED

String
Default: NO_PREFERENCE
Example: NO_PREFERENCE

language

Language to be used on the hosted payment page. ISO 639-2.

String
Default: ita
Example: ita

paymentService

If present, the payment page is displayed allowing the user to make the payment only with the circuits or payment methods indicated. The possible values are indicated in the table PaymentService encoding.

String

resultUrl

Merchant URL to which the cardholder is redirected once the payment is completed.
The value of the field:
- Must start with "http://" or "https://".
- Standard ports 80 or 443 must be used.
- Must not end with a slash "/".

String
Max. length: 2048
Example: https://{merchant_result_url}

cancelUrl

Merchant URL where the cardholder is redirected once the hosted payment is abandoned.
The value of the field:
- Must start with "http://" or "https://".
- Standard ports 80 or 443 must be used.
- Must not end with a slash "/".

String
Max. length: 2048
Example: https://{merchant_cancel_url}

notificationUrl

Address to which the outcome of the transaction with relative parameters is sent, in server to server mode with the POST method.
The value of the field:
- Must start with “http://” or “https://”.
- Standard ports 80 or 443 must be used.
- Must not end with a slash "/".
- A public certificate must be used.
- Must not be authenticated.

The content of the notification is detailed in the section Notification.

String
Max. length: 2048
Example: https://{merchant_notification_url}

expirationDate

Expiration date. Maximum 90 days after the link creation.

String
Example: 2022-09-01

RESPONSE 200

Link generated successful - No Header for this response

BODY

NAME

DESCRIPTION

FORMAT

paymentLink

Object containing the details of the Pay-By-Link link.

Object

amount	Transaction amount in smallest currency unit. 5000 corresponds to 50,00 €. Expressed in the currency of the payment.	String Example: 100
expirationDate	Expiration date of the Pay-By-Link link.	String
link	Payment URL for Pay-By-Link.	String
linkId	Identifier of the Pay-By-Link link.	String
paidByOperationId	Operation identifier associated with payment through Pay-By-Link link.	String
status	Status of the Pay-By-Link link, possible values: - ACTIVE - DELETED - EXPIRED - INACTIVE	String

securityToken

Token which may be used for validating the notifications related to this payment.

String
Example: 2f0ea5059b41414ca3744fe672327d85

RESPONSE 400

Invalid request data - No Header for this response

BODY

NAME

DESCRIPTION

FORMAT

errors

Array containing the errors list. The possible values are shown in the table Error codes.

Array

		code	Error code.	String Example: GW0001
		description	Error description.	String Example: Invalid merchant URL

RESPONSE 401

Unauthorized - No Header and Body for this response

RESPONSE 500

Internal Server Error - No Header for this response

BODY

NAME

DESCRIPTION

FORMAT

errors

Array containing the errors list. The possible values are shown in the table Error codes.

Array

		code	Error code.	String Example: GW0001
		description	Error description.	String Example: Invalid merchant URL