No results

POST/reservations

PROD
https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/reservations
TEST
https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1/reservations

Create reservation.

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
reservation Object containing the reservation details. Object
reservationId Merchant reservation id, unique in the merchant domain. String
Max. length: 27
Example: btid2384983
status Possible values:
- ACTIVE
- CANCELED
 String
Example: ACTIVE
creationDate The timestamp related to structure creation dall'esercente. String
Example: 2022-08-01
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
deposit Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals). String
Example: 3500
description Transaction description. String
Max. length: 255
Example: Prenotazione camera - Cefalù
reservationType Possible values:
- PREPAID_REFUNDABLE: reservation is paid in advace for the service that will be provided and it can be refundable.
- PREPAID_NOT_REFUNDABLE: reservation is paid in advace for the service that will be provided and it can not be refundable.
- GUARANTEED_NOSHOW: reservation, through a card verification without charge to the customer. If the customer does not show up at the property, it is possible to charge the cost of the first night of stay.
- GUARANTEED_PENALTY: reservation, through a card verification without charge to the customer. An automatic charge of the predetermined penalty is made in case a guest does not show up at the property.
- BUNDLE: booking of a package containing several services provided by the same structure, for example stay + excursion + restaurant + tourist bus.
 String
Example: GUARANTEED
structureId Structure identifier unique in the merchant domain. String
Min. length: 1
Max. length: 36
Example: 99a172e5-423c-4648-9895-4cb5d1d43134
termsAndConditionsIds Facility T&C identifier array. Insertion of terms and conditions Array
checkInDate Check in time in ISO 8601 format. String
Example: 2022-09-01
checkInFromTime Check in from time to be intended as a local time of the structure. String
Max. length: 11
Example: 09:00
checkInToTime Check in to time to be intended as a local time of the structure. String
Max. length: 11
Example: 20:00
checkOutDate Check out time in ISO 8601 format. String
Example: 2022-09-05
checkOutFromTime Check out from time to be intended as a local time of the structure. String
Max. length: 11
Example: 09:00
checkOutToTime Check out to time to be intended as a local time of the structure. String
Max. length: 11
Example: 20:00
reservationPeriod Number of days or night for the reservation. String
Max. length: 4
Example: 4
customerNumber Number of people for the reservation. String
Max. length: 4
Example: 2
customerName The name of the reservation holder. String
Max. length: 255
Example: Mario
customerSurname The surname of the reservation holder. String
Max. length: 255
Example: Rossi
linkExpirationDate Expiration date for Paybylink. String
Example: 2022-09-01
collectionType Accounting typology:
- INSTANT
- DELAYED
- INSTALLMENT: delayed
Delayed and installment Collection
 String
Example: INSTANT
customerId Customer identifier for this transaction. String
Max. length: 27
Example: mcid97295873
customField Additional transaction description. String
Max. length: 255
Example: weekend promotion
customerTaxCode The tax code of the customer. String
Max. length: 21
Example: SVTTRP95P03C478T
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
installments Array containing the detail of the installments. Mandatory with "collectionType" set to "INSTALLMENT". Array
date Installment time. String
Example: 2022-09-01
amount Installment amount. String
Example: 350
type Possible values:
- AUTOMATIC: installments will be made automatically by XPay.
- MANUAL: installments will be made manually by the merchant.
 String
Example: AUTOMATIC
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
CancelationDetails Object containing the details for canceling the reservation. Object
dataType Type of date within which it is possible to cancel the reservation. Possible values:
- DATE
- HOUR_FROM_CHECKIN
- DAY_FROM_CHECKIN
 String
Example: HOUR_FROM_CHECKIN
cancellationCondition Array containing details on cancellation fees. Array
dataTypeValue The value of the selected data type. String
Example: 2
value The value for the penalty amount or percentage of refund. String
Example: 5000
Arrow RESPONSE 200
Success - No Header for this response
BODY
NAME DESCRIPTION FORMAT
reservationId Merchant reservation id, unique in the merchant domain String
Example: btid2384983
Arrow 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
Arrow RESPONSE 401
Unauthorized - No Header and Body for this response
Arrow 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