API > POST /orders/build | Payment Gateway

POST/orders/build

PROD

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

TEST

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

Create an order and initiate the payment using the XPay Build solution.

WARNING: for the proper functioning of XPay Build solution, it is necessary for the browser used to allow the use of third-party cookies.

PARAM HEADER

NAME

DESCRIPTION

FORMAT

		X-Api-Key	Authentication API Key.	String Format: uuid
		Correlation-Id	Unique identifier of the request.	String Format: uuid

PARAM PATH

NAME

DESCRIPTION

FORMAT

No param path

PARAM QUERY

NAME

DESCRIPTION

FORMAT

No param query

PARAM BODY

NAME

DESCRIPTION

FORMAT

merchantUrl

Address of the e-commerce website that will host the iframes for collecting card data returned by XPay.
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 "/".
- Must consist only of the communication protocol (https://) and the domain of the website.
- Must not contain any parameters or indication of the path to the resource.
Incorrect configuration of this parameter results in the malfunctioning of the fields designated for collecting card data.

Example of correct address:
- https://merchanturl.it

Examples of incorrect addresses:
- merchanturl.it
- https://merchanturl.it/
- https://merchanturl.it/xyz
- https://merchanturl.it/xyz?p=1

String

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}

RESPONSE 200

The request returns an object containing the iframes corresponding to the card payment method and the APMs active on the merchant's terminal. - No Header for this response

BODY

NAME

DESCRIPTION

FORMAT

sessionId

Session identifier.

String
Example: sessionId

securityToken

Security token for the transaction.

String
Example: security token

fields

Array of objects containing the iframes corresponding to the payment methods active on the merchant's terminal.

Array

type	Type of field, possible values: - ACTION: field that requires an action by the cardholder on the iframe, in this case the click on the component.	String Example: ACTION
class	Field class, possible values: - APM - CARD	String Example: CARD
id	Field identifier.	String Example: PAY_WITH_CARD
src	Iframe URL dedicated to the payment method.	String Example: https:///field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264

state

Transaction status. Possible values:
- CARD_DATA_COLLECTION: the customer has chosen payment by card. The "fieldSet" object containing the iframes for collecting the card data is returned.
- PAYMENT_METHOD_SELECTION: the customer must proceed with the choice of payment method. The "fieldSet" object containing the payment method iframes is returned.
- READY_FOR_PAYMENT: payment ready to be executed, it is necessary to call the API POST /build/finalize_payment.
- REDIRECTED_TO_EXTERNAL_DOMAIN - The url to perform 3D Secure authentication has been provided. The "url" parameter is returned.
- PAYMENT_COMPLETE: Payment has been completed. The "operation" object is returned.
- GDI_VERIFICATION: only with version 2 of XPay Build. The GET build/state request has been invoked during the GDI verification. It is necessary to display a page containing the hidden internal frame.

String

url

Indirizzo per fase 3D Secure.

String
Example: https:apm_url.it

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