API > GET /reservations/{reservationId}

GET/reservations/{reservationId}

PROD

https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/reservations/{reservationId}

TEST

https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1/reservations/{reservationId}

Find reservation by ID.

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

reservationId

Merchant reservation id

String
Example: btid2384983

PARAM QUERY

NAME

DESCRIPTION

FORMAT

No param query

PARAM BODY

NAME

DESCRIPTION

FORMAT

No param body

RESPONSE 200

Reservation found - No Header for this response

BODY

NAME

DESCRIPTION

FORMAT

reservationStatus

Object containing the details of the reservation status.

Object

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

authorizedAmount

Authorized amount.

String
Example: 3545

capturedAmount

Captured amount.

String
Example: 3545

lastOperationType

It indicates the purpose of the request:
- AUTHORIZATION - payment authorization.
- CAPTURE - capture of the authorized amount.
- VOID - reversal of an authorization.
- REFUND - refund of a captured amount.
- CANCEL - the rollback of an capture, refund.
- CARD_VERIFICATION - verify operation, without any charge, with the sole purpose of confirming the validity of the card data entered by the customer.
- NOSHOW - noshow operation (reserved for Disputeless service).
- INCREMENTAL - incremental operation (reserved for Disputeless service).
- DELAY_CHARGE - delay charge operation (reserved for the Disputeless service).

String
Example: CAPTURE

lastOperationTime

Operation time.

String
Example: 2022-08-01T16:32:22.038Z

operations

Array containing the details of the operations performed.

Array

orderId

Merchant order id, unique in the merchant domain.

String
Max. length: 18
Example: btid2384983

operationId

Operation ID.

String
Example: 3470744

channel

It indicates the originating channel:
* ECOMMERCE - cardholder initiated operation through an online channel.
* POS - cardholder initiated operation through a physical POS.
* BACKOFFICE - merchant initiated operation. It includes post operations and MIT.

String
Example: ECOMMERCE

channelDetail

Identify the type of service from which the operation originated, it can take the following values:
- "HOSTED_PAYMENT_PAGE": Hosted Payment Page solution with redirect to checkout page, no-show operation, incremental, delay charge.
- "SERVER_TO_SERVER": server-to-server 3-step solution, XPay Build.
- "MERCHANT_INITIATED_TRANSACTION": recurring payment.
- "PAY_BY_LINK": payment operation via Pay-By-Link link.
- "MOTO": payment operation via MOTO service.
- "POST_PAYMENT_OPERATION": capture, refund, cancel operation.
- "PRE_PAYMENT_OPERATION": card verification operation.

String

operationType

String
Example: CAPTURE

operationResult

Outcome of the operation:
* AUTHORIZED - Payment authorized
* EXECUTED - Payment confirmed, verification successfully executed
* DECLINED - Declined by the Issuer during the authorization phase
* DENIED_BY_RISK - Negative outcome of the transaction risk analysis
* THREEDS_VALIDATED - 3DS authentication OK or 3DS skipped (non-secure payment)
* THREEDS_FAILED - cancellation or authentication failure during 3DS
* PENDING - Payment ongoing. Follow up notifications are expected
* CANCELED - Canceled by the cardholder
* VOIDED - Online reversal of the full authorized amount
* REFUNDED - Full or partial amount refunded
* FAILED - Payment failed due to technical reasons

String
Example: AUTHORIZED

operationTime

Operation time.

String
Example: 2022-09-01T01:20:00.001Z

paymentMethod

* CARD - Any card circuit
* APM - Alternative payment method

String
Example: CARD

paymentCircuit

one of the payment circuit values returned by the GET payment_methods web service VISA, MC, AMEX, DINERS, GOOGLE_PAY, APPLE_PAY, PAYPAL, BANCONTACT, BANCOMAT_PAY, MYBANK, PIS, AMAZON_PAY, ALIPAY etc.

String
Example: VISA

paymentInstrumentInfo

Payment instrument information.

String
Example: ***6152

paymentEndToEndId

It is defined by the circuit to uniquely identify the transaction. Required for circuid reconciliation purposes.

String
Max. length: 35
Example: e723hedsdew

cancelledOperationId

Operation ID to be undone.

String
Example: 321312

operationAmount

Operation amount in the payment currency.

String
Example: 3545

operationCurrency

Transaction currency. ISO 4217 alphabetic code.

String
Example: EUR

customerInfo

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

String
Example: 01

warnings

Array containing the list of warnings.

Array

		code	Warning code.	String Example: TRA001
		description	Warning description.	String Example: 3DS warning

paymentLinkId

PayByLink ID used for correlating this operation with the original link.

String
Example: 234244353

additionalData

Map of additional fields specific to the selected payment method.

It is recommended not to introduce constraints on the 'additionalData' object, as maintenance and enhancement activities may result in changes to its parameters.

Object
Example: {"authorizationCode":"647189","cardCountry":"ITA","threeDS":"FULL_SECURE","schemaTID":"MCS01198U","multiCurrencyConversion":{"amount":"2662","currency":"JPY","exchangeRate":"0.007510523"}}

paymentLinks

Array containing the payment links list.

Array

linkId	Unique identifier for this link.	String Example: 92864835
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
expirationDate	Expiration date.	String Example: 2022-09-01
link	Link to be shared with the customer for doing the payment.	String Example: https://{gateway_hosted_page}
paidByOperationId	Operation ID identifying the successful payment related to this link.	String Example: 3470744

RESPONSE 404

Not found - No Header and Body for this response

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