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
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 "/".

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

{
...
"resultUrl":"https://merchant_result_url.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
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.

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
Max. length: 2048
Example: https://{merchant_notification_url}
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
Example: https://{gateway_hosted_page}
securityToken Token which may be used for validating the notifications related to this payment. String
Example: 2f0ea5059b41414ca3744fe672327d85
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