No results

POST/orders/hpp

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

Initiating payment through the Hosted Payment Page solution, the API returns the URL to redirect the customer to complete the transaction. For more information, please refer to the dedicated page Hosted Payment Page.

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-plugin-name Plugin name String
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
No param query
PARAM BODY

createOrderRequest

NAME DESCRIPTION FORMAT
order Object containing the details of the order.
 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
customerId Customer identifier computed by the merchant to match the registered customer on the ecommerce platform.
Use only letters, digits, underscore (_), or hyphen (-).
 String
Max. length: 27
Example: mcid97295873
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
billingAddress Object containing the detail of the customer's address.
 Object
additionalInfo Additional info of address, for example floor.
Recommended maximum length: 50 characters.
 String
Example: Quinto Piano, Scala B
city City.
Recommended maximum length: 40 characters.
 String
Example: Bologna
country State in ISO 3166-1 alpha-3 code.
Recommended maximum length: 3 characters.
 String
Example: ITA
name Name and surname.
Recommended maximum length: 50 characters.
 String
Example: Mario Rossi
postCode Postal code.
Recommended maximum length: 16 characters.
 String
Example: 40124
province Code of province.
Recommended maximum length: 3 characters.
 String
Example: BO
street Full address.
Recommended maximum length: 50 characters.
 String
Example: Piazza Maggiore, 1
cardHolderAcctInfo Object containing information about the buyer's account.
 Object
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-11T00:00:00.000+0000
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
chAccDate Date of activation of the account on the merchant's website.
 String
Example: 2019-02-11T00:00:00.000+0000
chAccPwChangeDate Date of last account password change (including password reset).
 String
Example: 2019-02-11T00:00:00.000+0000
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
destinationAddressUsageDate Date of last use of this delivery address.
 String
Example: 2019-02-11T00:00:00.000+0000
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
nbPurchaseAccount Number of purchases of this account in the last 6 months.
 Integer
Example: 0
paymentAccAgeDate Payment account activation date.
 String
Example: 2019-02-11T00:00:00.000+0000
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
provisionAttemptsDay Number of attempts to add a new card in the last 24 hours.
 Integer
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
txnActivityDay Number of transactions (successful and abandoned) for this account in the previous 24 hours.
 Integer
Example: 0
txnActivityYear Number of transactions (successful and abandoned) for this account in the previous year.
 Integer
Example: 0
cardHolderEmail Email of the cardholder.
Recommended maximum length: 255 characters.
 String
Example: mauro.morandi@nexi.it
cardHolderName Name and surname of the cardholder.
Recommended maximum length: 255 characters.
 String
Example: Mauro Morandi
homePhone Home phone number provided by the Cardholder.
Recommended maximum length: 18 characters.
 String
Example: 391231234567
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 the total amount and currency of the prepaid or gift card(s) purchased.
 Object
currency For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.
EMVCO: giftCardCurr
 String
Example: EUR
value For prepaid or gift card purchase, the purchase amount total
of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).
EMVCO: giftCardAmount
 String
Max. length: 18
Example: 100
giftCardCount Total number of individual prepaid or gift cards/codes purchased.
 Integer
Example: 0
preOrderDate For a pre-ordered purchase, the expected date that the merchandise will be available.
 String
Example: 2019-02-11T00:00:00.000+0000
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
mobilePhone Mobile phone.
Recommended maximum length: 15 characters.
 String
Example: 3280987654
mobilePhoneCountryCode Prefix of the mobile phone.
Recommended maximum length: 4 characters.
 String
Example: +39
recontactConsent In certain scenarios, it is possible to collect the payer's consent to be recontacted by the merchant.
This field indicates whether the payer has given such consent.
 Boolean
shippingAddress Object containing the detail of the customer's address.
 Object
additionalInfo Additional info of address, for example floor.
Recommended maximum length: 50 characters.
 String
Example: Quinto Piano, Scala B
city City.
Recommended maximum length: 40 characters.
 String
Example: Bologna
country State in ISO 3166-1 alpha-3 code.
Recommended maximum length: 3 characters.
 String
Example: ITA
name Name and surname.
Recommended maximum length: 50 characters.
 String
Example: Mario Rossi
postCode Postal code.
Recommended maximum length: 16 characters.
 String
Example: 40124
province Code of province.
Recommended maximum length: 3 characters.
 String
Example: BO
street Full address.
Recommended maximum length: 50 characters.
 String
Example: Piazza Maggiore, 1
tin Tax Identification Number is collected in certain scenarios, such as donations, to comply with tax regulations. It is an identifier used in many countries for tax purposes.
 String
Max. length: 32
Example: 12345678901
workPhone Work phone number provided by the Cardholder.
Recommended maximum length: 18 characters.
 String
Example: 391231234567
description Transaction description
 String
Max. length: 255
Example: TV LG 3423
invoiceId The Invoice ID. It must contain only supported characters: alphanumeric, underscore (_), minus (-), or plus (+) with a maximum length of 30 characters.
This field is optional.
[rif. ISOv93 127.98]
 String
Max. length: 30
orderId Merchant order identifier, unique in the merchant domain.
The maximum length is 27 characters. To comply with payment circuit specifications, it is strongly recommended to use an orderId of up to 18 characters.
A good uniqueness strategy is to combine a stable merchant or channel prefix with a monotonic sequence, timestamp, or platform order reference, avoiding reuse for different payments.
 String
Max. length: 27
Example: btid2384983
plan Object containing the details of the plan description.
You can see the plan created through the "subscription" menu in your backoffice.
Based on the different `planType` values, the plan can be used for different purposes:
- FIXED: each installment has the same amount and specified due dates.
- VARIABLE: each installment can have a different amount and specified due dates.
- ACQUIRER_AGREEMENT: managed by the acquirer agreement, the number of installments and the amount of each installment is defined by the acquirer.
 Object
contractId Contract identifier.
The value must be between 1 and 18 characters long. To keep it unique, use a stable merchant or channel prefix together with a monotonic sequence, timestamp, or platform contract reference, avoiding reuse for different recurring contracts.
 String
Min. length: 1
Max. length: 18
Example: C2834987
planType Possible values:
- FIXED: each installment has the same amount and specified due dates.
- VARIABLE: each installment can have a different amount and specified due dates.
- ACQUIRER_AGREEMENT: managed by the acquirer agreement, the number of installments and the amount of each installment is defined by the acquirer.
 String
status Possible values:
- ACTIVE: the plan is active and can be used for transactions.
- INACTIVE: the plan is inactive and cannot be used for transactions.
- COMPLETED: the plan has been completed and all installments have been paid.
 String
totalAmount Total amount of the plan in smallest currency unit.
The currency applied is the one from the order.
 String
products Products list in cart (also known as a shopping cart) as a virtual representation of the items a customer
selects while shopping on an online store.
Please note: for KLARNA payments, the product list is mandatory and the total amount of the order must match the sum of the product's prices.
 Array
description A detailed explanation of the product that provides essential information to help customers and payment processors
understand what is being purchased
 String
Max. length: 255
Example: The Nike Air Zoom Pegasus 39 is designed for runners seeking comfort and responsiveness. Featuring a lightweight, breathable mesh upper, these shoes are built to keep your feet cool and dry throughout your run.
itemCategory Different categories of items that can be processed:
- PHYSICAL: A tangible item, such as a product or merchandise.
- DISCOUNT: A reduction in the total price of the order.
- SHIPPING_FEE: The cost associated with delivering the order.
- DIGITAL: An intangible item, such as an e-book or software.
- GIFT_CARD: A prepaid card that can be used for future purchases.
- STORE_CREDIT: Credit issued by the store, often for returns or promotions.
- SURCHARGE: An additional fee added to the order.
 String
Example: DIGITAL
name The product name that is displayed to the customer. It should be clear and concise to help the customer understand what they are purchasing
 String
Max. length: 255
Example: Nike Air Zoom Pegasus 39 Running Shoes
price The product price per unit in the smallest currency unit.
- 50 EUR is represented as 5000 (2 decimals)
- 50 JPY is represented as 50 (0 decimals).
The product's currency matches the currency specified in the order.
The price is not strictly related to the order amount.
 String
Example: 1000
quantity The number of units the customer intends to buy
 Integer
Example: 2
sku Stock Keeping Unit. It is a unique identifier or code assigned to each product or item
sold by a retailer or e-commerce store
 String
Max. length: 64
Example: RUN-NIK-AZP39-BLK-10
termsAndConditionsIds Facility T&C identifier array. Insertion of terms and conditions
 Array
transactionSummary Transaction summary list, containing the details of the transaction.
 Array
language Language in ISO 639-2 three-letter code. String
Min. length: 3
Max. length: 3
Default: ITA
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
Max. length: 50
Example: 4
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
Default: PAY
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
cancelUrl Merchant URL where the cardholder is redirected once the hosted payment is abandoned.
The value of the field:
- Must start with "https://".
- Can contain path and query string parameters.
 String
Min. length: 1
Max. length: 2048
Example: https://merchant.example.com/cancel?orderId=btid2384983
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
Example: NO_PREFERENCE
fundTransfer Optional field containing information about the fund transfer Object
recipient Information about the transfer recipient/sender Object
address Object containing the detail of the customer's address.
 Object
additionalInfo Additional info of address, for example floor.
Recommended maximum length: 50 characters.
 String
Example: Quinto Piano, Scala B
city City.
Recommended maximum length: 40 characters.
 String
Example: Bologna
country State in ISO 3166-1 alpha-3 code.
Recommended maximum length: 3 characters.
 String
Example: ITA
name Name and surname.
Recommended maximum length: 50 characters.
 String
Example: Mario Rossi
postCode Postal code.
Recommended maximum length: 16 characters.
 String
Example: 40124
province Code of province.
Recommended maximum length: 3 characters.
 String
Example: BO
street Full address.
Recommended maximum length: 50 characters.
 String
Example: Piazza Maggiore, 1
companyName Company name of the transfer recipient/sender (required if customerType is not INDIVIDUAL) String
Max. length: 100
Example: John Doe Inc.
customerType Type of the transfer recipient/sender String
Example: INDIVIDUAL
dateOfBirth Date of birth of the transfer recipient/sender in ISO 8601 format. String
email Email of the transfer recipient/sender String
Max. length: 255
Example: john.doe@example.com
firstName First name of the transfer recipient/sender (only for customerType INDIVIDUAL) String
Max. length: 50
Example: John
identityDocument Information about the identity document of the transfer recipient/sender Object
documentNumber Identity document number String
Max. length: 50
Example: 123456789
documentType Type of the identity document String
Example: PASSPORT
issuingCountry ISO 3166-1 alpha-3 String
Example: ITA
lastName Last name of the transfer recipient/sender (only for customerType INDIVIDUAL) String
Max. length: 50
Example: Doe
paymentInstrumentInfo Payment instrument information String
Example: ***6152
phoneNumber Phone number of the transfer recipient/sender String
Max. length: 20
Example: +1234567890
sender Information about the transfer recipient/sender Object
address Object containing the detail of the customer's address.
 Object
additionalInfo Additional info of address, for example floor.
Recommended maximum length: 50 characters.
 String
Example: Quinto Piano, Scala B
city City.
Recommended maximum length: 40 characters.
 String
Example: Bologna
country State in ISO 3166-1 alpha-3 code.
Recommended maximum length: 3 characters.
 String
Example: ITA
name Name and surname.
Recommended maximum length: 50 characters.
 String
Example: Mario Rossi
postCode Postal code.
Recommended maximum length: 16 characters.
 String
Example: 40124
province Code of province.
Recommended maximum length: 3 characters.
 String
Example: BO
street Full address.
Recommended maximum length: 50 characters.
 String
Example: Piazza Maggiore, 1
companyName Company name of the transfer recipient/sender (required if customerType is not INDIVIDUAL) String
Max. length: 100
Example: John Doe Inc.
customerType Type of the transfer recipient/sender String
Example: INDIVIDUAL
dateOfBirth Date of birth of the transfer recipient/sender in ISO 8601 format. String
email Email of the transfer recipient/sender String
Max. length: 255
Example: john.doe@example.com
firstName First name of the transfer recipient/sender (only for customerType INDIVIDUAL) String
Max. length: 50
Example: John
identityDocument Information about the identity document of the transfer recipient/sender Object
documentNumber Identity document number String
Max. length: 50
Example: 123456789
documentType Type of the identity document String
Example: PASSPORT
issuingCountry ISO 3166-1 alpha-3 String
Example: ITA
lastName Last name of the transfer recipient/sender (only for customerType INDIVIDUAL) String
Max. length: 50
Example: Doe
paymentInstrumentInfo Payment instrument information String
Example: ***6152
phoneNumber Phone number of the transfer recipient/sender String
Max. length: 20
Example: +1234567890
transferType Type of the fund transfer String
Example: AFT
language Language in ISO 639-2 three-letter code. String
Min. length: 3
Max. length: 3
Default: ITA
Example: ENG
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 "https://".
- Can contain path and query string parameters.
- A public certificate must be used.
- Must not be authenticated.

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

It is advisable to avoid setting the "notificationUrl" and "resultUrl" parameters with the same value as they serve different purposes: the former is interpreted by a webhook, while the latter is handled by the browser through redirection. These two destinations serve distinct purposes and may interpret responses differently.
 String
Min. length: 1
Max. length: 2048
Example: https://merchant.example.com/notification?orderId=btid2384983
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
Example: GOOGLEPAY
recurrence Object containing the detail of the recurrence.
 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: CONTRACT_CREATION
contractExpiryDate Used with contractType MIT_SCHEDULED.
 String
contractFrequency Used with contractType MIT_SCHEDULED. Number of days.
 String
Max. length: 4
Example: 120
contractId Contract identifier.
The value must be between 1 and 18 characters long. To keep it unique, use a stable merchant or channel prefix together with a monotonic sequence, timestamp, or platform contract reference, avoiding reuse for different recurring contracts.
 String
Min. length: 1
Max. length: 18
Example: C2834987
contractType It indicates the available options for subsequent payments:
* CIT - the contract can be used only for subsequent payments initiated by the customer.
* MIT_SCHEDULED - the contract can be used for scheduled merchant-initiated transactions. The number of days between one payment and another must be equal to or greater than the value of `contractFrequency`.
* MIT_UNSCHEDULED - the contract can be used for unscheduled merchant initiated transactions. The contractFrequency has no effect in this case.
 String
Example: CIT
resultUrl Merchant URL to which the cardholder is redirected once the payment is completed.
The value of the field:
- Must start with "https://".
- Can contain path and query string parameters.

For proper outcome management, this address must contain the order reference within it (value of the "orderId" parameter):

{
...
"resultUrl":"https://merchant.example.com/orderId"
...
}

This way, at the end of the transaction, the customer will be redirected to the aforementioned URL with the order identifier. This will enable the ecommerce site to call the GET /orders/{orderId} API to verify the transaction outcome.

It is advisable to avoid setting the "notificationUrl" and "resultUrl" parameters with the same value as they serve different purposes: the former is interpreted by a webhook, while the latter is handled by the browser through redirection. These two destinations serve distinct purposes and may interpret responses differently.
 String
Min. length: 1
Max. length: 2048
Example: https://merchant.example.com/result?orderId=btid2384983
Arrow RESPONSE 200
Payment initialization successful - No Header for this response
BODY
NAME DESCRIPTION FORMAT
hostedPage URL of the hosted payment page. Redirect the payment flow to this URL.
 String
securityToken Security token used by the merchant to validate the source of the notification. String
Example: f3b2c1d4e5a6b7c8d9e0f1a2b3c4d5e6
warnings Array containing the warnings list.
 Array
code Warning code. String
Example: TRA001
description Warning description. String
Example: 3DS warning
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 404
Not Found - 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

NOTES:
  • Through the Hosted Payment Page, in addition to normal payments, it is possible to perform pre-authorizations.
  • Below are the values that the "operationResult" field can assume when using HPP mode:
    • AUTHORIZED
    • EXECUTED
    • DECLINED
    • CANCELED
    • THREEDS_FAILED
    • DENIED_BY_RISK
    • FAILED
    • PENDING
  • In the URL returned in the "hostedPage" response parameter, do not consider the "paymentId" field (e.g. "hostedPage": "https://xpaysandbox.nexigroup.com/monetaweb/page/hosted/2/html?paymentid=308663495709661749"), as it may change during the payment flow. Therefore, it is recommended not to apply any logic to the parameters received in the query string.
  • It is not possible to modify the payment session timeout using the HPP solution: the duration is fixed at 15 minutes, which matches the validity of the URL returned in the "hostedPage" response parameter. Once the URL has expired, the user will see a Nexi error page displaying the message: "We are sorry, the session has expired or is invalid".