XPay Build APIs

C#PHPNodeShell

Scroll down for code samples, example requests and responses.
Select a language for code samples from the tabs or the mobile navigation menu.

Create an order and initiates a payment through build functionality.

POST /api/orders/build

This service is targeted to ecommerce platforms requiring to implement the payment pages in line with their own dedicated UI style guidelines. The service will return a list of fields expressed in JSON format, to be translated into HTML by the ecommerce platform web app.

Parameters

X-API-KEYstringrequired
Correlation-Idstring (uuid)required
Mandatory field to be valued with a UUID to be renewed at every call. The purpose of the field is to allow referring to a specific call for any integration or maintenance activity.

Create an order and initiates a payment through build functionality.

C#
PHP
Node
Shell

var client = new RestClient("https:///{gateway_test}/api/v1/api/orders/build");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE");
request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request body

merchantUrlstringoptional
orderobjectoptional
- orderIdstringoptional
  Merchant order id, unique in the merchant domain
- amountstringoptional
  Transaction amount in smallest currency unit. 50 EUR is represented as 5000 (2 decimals) 50 JPY is represented as 50 (0 decimals)
- currencystringoptional
  Transaction currency. ISO 4217 alphabetic code
- customerIdstringoptional
  Customer label for this transaction
- descriptionstringoptional
  Transaction description
- customFieldstringoptional
  Additional transaction description
- customerInfoobjectoptional
  - cardHolderNamestringoptional
  - cardHolderEmailstringoptional
  - billingAddressobjectoptional
    namestringoptional
    streetstringoptional
    additionalInfostringoptional
    citystringoptional
    postCodestringoptional
    provincestringoptional
    countrystringoptional
    ISO 3166-1 alpha-3
  - shippingAddressobjectoptional
    namestringoptional
    streetstringoptional
    additionalInfostringoptional
    citystringoptional
    postCodestringoptional
    provincestringoptional
    countrystringoptional
    ISO 3166-1 alpha-3
  - mobilePhoneCountryCodestringoptional
  - mobilePhonestringoptional
  - homePhonestringoptional
    The home phone number provided by the Cardholder.
  - workPhonestringoptional
    The work phone number provided by the Cardholder.
  - cardHolderAcctInfoobjectoptional
    chAccDatestringoptional
    Date that the cardholder opened the account with the 3DS Requestor. ISO 8601 format
    chAccAgeIndicatorstringoptional
    Length of time that the cardholder has had the account with the 3DS Requestor.
    chAccChangeDatestringoptional
    Date that the cardholder's account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. ISO 8601 format
    chAccChangeIndicatorstringoptional
    Length of time since the cardholder's account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.
    chAccPwChangeDatestringoptional
    Date that cardholder's account with the 3DS Requestor had a password change or account reset. ISO 8601 format
    chAccPwChangeIndicatorstringoptional
    Indicates the length of time since the cardholder's account with the 3DS Requestor had a password change or account reset.
    nbPurchaseAccountnumberoptional
    Number of purchases with this cardholder account during the previous six months.
    destinationAddressUsageDatestringoptional
    Date when the shipping address used for this transaction was first used with the 3DS Requestor. ISO 8601 format
    destinationAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.
    destinationNameIndicatorstringoptional
    Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
    txnActivityDaynumberoptional
    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.
    txnActivityYearnumberoptional
    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.
    provisionAttemptsDaynumberoptional
    Number of Add Card attempts in the last 24 hours.
    suspiciousAccActivitystringoptional
    Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
    paymentAccAgeDatestringoptional
    Date that the payment account was enrolled in the cardholder's account with the 3DS Requestor. ISO 8601 format
    paymentAccIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3DS Requestor.
  - merchantRiskIndicatorobjectoptional
    deliveryEmailstringoptional
    For Electronic delivery, the email address to which the merchandise was delivered.
    deliveryTimeframestringoptional
    Indicates the merchandise delivery timeframe.
    giftCardAmountobjectoptional
    valuenumberoptional
    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).
    currencystringoptional
    For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.
    giftCardCountnumberoptional
    For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
    preOrderDatestringoptional
    For a pre-ordered purchase, the expected date that the merchandise will be available. ISO 8601 format
    preOrderPurchaseIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    reorderItemsIndicatorstringoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    shipIndicatorstringoptional
    Indicates shipping method chosen for the transaction.
- transactionSummaryarrayoptional
  - languagestringoptional
    Language to be used on the transaction summary details, ISO 639-2.
  - summaryListarrayoptional
    labelstringoptional
    label of the field
    valuestringoptional
    value
- installmentsarrayoptional
  - datestringoptional
    Installment time in ISO 8601 format.
  - amountstringoptional
    Installment amount.
- termsAndConditionsIdsarrayoptional
paymentSessionobjectoptional
- actionTypestringoptional
  PAY, VERIFY, PREAUTH
- amountstringoptional
  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)
- recurrenceobjectoptional
  - actionstringoptional
    NO_RECURRING, SUBSEQUENT_PAYMENT, CONTRACT_CREATION, CARD_SUBSTITUTION
  - contractIdstringoptional
  - contractTypestringoptional
    MIT_UNSCHEDULED, MIT_SCHEDULED, CIT
  - contractExpiryDatestringoptional
    Used with contractType MIT_SCHEDULED. ISO 8601 format
  - contractFrequencystringoptional
    Used with contractType MIT_SCHEDULED. Number of days
- captureTypestringoptional
  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.
  
  IMPLICIT, EXPLICIT
- exemptionsstringoptional
  NO_PREFERENCE, CHALLENGE_REQUESTED
- languagestringoptional
  Language to be used on the hosted payment page. ISO 639-2
- resultUrlstringoptional
  Merchant URL where the cardholder is redirected once the hosted payment completes
- cancelUrlstringoptional
  Merchant URL where the cardholder is redirected once the hosted payment is abandoned
- notificationUrlstringoptional
  Merchant URL where the gateway pushes notifications

Request body

{
    "merchantUrl": "https://merchanturl.it",
    "order": {
        "orderId": "btid2384983",
        "amount": "3545",
        "currency": "EUR",
        "customerId": "mcid97295873",
        "description": "TV LG 3423",
        "customField": "weekend promotion",
        "customerInfo": {
            "cardHolderName": "Mauro Morandi",
            "cardHolderEmail": "mauro.morandi@nexi.it",
            "billingAddress": {
                "name": "Mario Rossi",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "city": "Bologna",
                "postCode": "40124",
                "province": "BO",
                "country": "ITA"
            },
            "shippingAddress": {
                "name": "Mario Rossi",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "city": "Bologna",
                "postCode": "40124",
                "province": "BO",
                "country": "ITA"
            },
            "mobilePhoneCountryCode": "39",
            "mobilePhone": "3280987654",
            "homePhone": 391231234567,
            "workPhone": 391231234567,
            "cardHolderAcctInfo": {
                "chAccDate": "2019-02-11T00:00:00.000Z",
                "chAccAgeIndicator": "01",
                "chAccChangeDate": "2019-02-11T00:00:00.000Z",
                "chAccChangeIndicator": "01",
                "chAccPwChangeDate": "2019-02-11T00:00:00.000Z",
                "chAccPwChangeIndicator": "01",
                "nbPurchaseAccount": 0,
                "destinationAddressUsageDate": "2019-02-11T00:00:00.000Z",
                "destinationAddressUsageIndicator": "01",
                "destinationNameIndicator": "01",
                "txnActivityDay": 0,
                "txnActivityYear": 0,
                "provisionAttemptsDay": 0,
                "suspiciousAccActivity": "01",
                "paymentAccAgeDate": "2019-02-11T00:00:00.000Z",
                "paymentAccIndicator": "0"
            },
            "merchantRiskIndicator": {
                "deliveryEmail": "john.doe@email.com",
                "deliveryTimeframe": "01",
                "giftCardAmount": null,
                "giftCardCount": 0,
                "preOrderDate": "2019-02-11T00:00:00.000Z",
                "preOrderPurchaseIndicator": "01",
                "reorderItemsIndicator": "01",
                "shipIndicator": "01"
            }
        },
        "transactionSummary": [
            {
                "language": "eng",
                "summaryList": [
                    {
                        "label": "Number of people",
                        "value": "4"
                    }
                ]
            }
        ],
        "installments": [
            {
                "date": "2022-09-01T00:00:00.000Z",
                "amount": "350"
            }
        ],
        "termsAndConditionsIds": [
            "16dd6ac6-0791-4c72-b362-85f77f1728a2"
        ]
    },
    "paymentSession": {
        "actionType": "PAY",
        "amount": "3545",
        "recurrence": {
            "action": "NO_RECURRING",
            "contractId": "C2834987",
            "contractType": "MIT_UNSCHEDULED",
            "contractExpiryDate": "2023-03-16T00:00:00.000Z",
            "contractFrequency": "120"
        },
        "captureType": "EXPLICIT",
        "exemptions": "NO_PREFERENCE",
        "language": "ita",
        "resultUrl": "https://{merchant_result_url}",
        "cancelUrl": "https://{merchant_cancel_url}",
        "notificationUrl": "https://{merchant_notification_url}"
    }
}

Responses

200optional
In case of success, the service returns a list of fields to be rendered in the ecomm web app.
- sessionIdstringoptional
- securityTokenstringoptional
- fieldsarrayoptional
  - typestringoptional
  - classstringoptional
  - idstringoptional
  - srcstringoptional
400Invalid request dataoptional
- errorsarrayoptional
  - codestringoptional
  - descriptionstringoptional
401Unauthorizedoptional
500Internal Server Erroroptional
- errorsarrayoptional
  - codestringoptional
  - descriptionstringoptional

{
    "sessionId": "sessionId",
    "securityToken": "security token",
    "fields": [
        {
            "type": "text",
            "class": "cardData",
            "id": "cardholderName",
            "src": "https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264"
        }
    ]
}

Finalize a payment.

POST /api/build/finalize_payment

This service is targeted to ecommerce platforms in order to finalize the payment.

Parameters

X-API-KEYstringrequired
Correlation-Idstring (uuid)required
Mandatory field to be valued with a UUID to be renewed at every call. The purpose of the field is to allow referring to a specific call for any integration or maintenance activity.

Finalize a payment.

C#
PHP
Node
Shell

var client = new RestClient("https:///{gateway_test}/api/v1/api/build/finalize_payment");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE");
request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request body

sessionIdstringoptional

Request body

{
    "sessionId": "052211e8/+54cc/4e0a"
}

Responses

200optional
In case of success, the service returns the specific status based on the state machine
- statestringoptional
  CARD_DATA_COLLECTION, PAYMENT_METHOD_SELECTION, READY_FOR_PAYMENT, REDIRECTED_TO_EXTERNAL_DOMAIN, PAYMENT_COMPLETE
- urlstringoptional
- operationobjectoptional
  - orderIdstringoptional
    Merchant order id, unique in the merchant domain
  - operationIdstringoptional
  - channelstringoptional
    It indicates the originating channel:
    
    ECOMMERCE - carholder initiated operation through an online channel.
    
    POS - carholder initiated operation through a physical POS.
    
    BACKOFFICE - merchant initiated operation. It includes post operations and MIT.
    
    ECOMMERCE, POS, BACKOFFICE
  - operationTypestringoptional
    It indicates the purpose of the request:
    
    AUTHORIZATION - any authorization with explicit capture
    
    CAPTURE - a captured authorization or an implicit captured payment
    
    VOID - reversal of an authorization
    
    REFUND - refund of a captured amount
    
    CANCEL - the rollback of an capture, refund.
    
    AUTHORIZATION, CAPTURE, VOID, REFUND, CANCEL
  - operationResultstringoptional
    Transaction output:
    
    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
    
    AUTHORIZED, EXECUTED, DECLINED, DENIED_BY_RISK, THREEDS_VALIDATED, THREEDS_FAILED, PENDING, CANCELED, VOIDED, REFUNDED, FAILED
  - operationTimestringoptional
    Operation time in ISO 8601 format
  - paymentMethodstringoptional
    
    CARD - Any card circuit
    
    APM - Alternative payment method
    
    CARD, APM
  - paymentCircuitstringoptional
    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.
  - paymentInstrumentInfostringoptional
    Payment instrument information
  - paymentEndToEndIdstringoptional
    It is defined by the circuit to uniquely identify the transaction. Required for circuid reconciliation purposes.
  - cancelledOperationIdstringoptional
    Operation id to be undone
  - operationAmountstringoptional
    Operation amount in the payment currency
  - operationCurrencystringoptional
    Payment currency
  - customerInfoobjectoptional
    cardHolderNamestringoptional
    cardHolderEmailstringoptional
    billingAddressobjectoptional
    namestringoptional
    streetstringoptional
    additionalInfostringoptional
    citystringoptional
    postCodestringoptional
    provincestringoptional
    countrystringoptional
    ISO 3166-1 alpha-3
    shippingAddressobjectoptional
    namestringoptional
    streetstringoptional
    additionalInfostringoptional
    citystringoptional
    postCodestringoptional
    provincestringoptional
    countrystringoptional
    ISO 3166-1 alpha-3
    mobilePhoneCountryCodestringoptional
    mobilePhonestringoptional
    homePhonestringoptional
    The home phone number provided by the Cardholder.
    workPhonestringoptional
    The work phone number provided by the Cardholder.
    cardHolderAcctInfoobjectoptional
    chAccDatestringoptional
    Date that the cardholder opened the account with the 3DS Requestor. ISO 8601 format
    chAccAgeIndicatorstringoptional
    Length of time that the cardholder has had the account with the 3DS Requestor.
    chAccChangeDatestringoptional
    Date that the cardholder's account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. ISO 8601 format
    chAccChangeIndicatorstringoptional
    Length of time since the cardholder's account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.
    chAccPwChangeDatestringoptional
    Date that cardholder's account with the 3DS Requestor had a password change or account reset. ISO 8601 format
    chAccPwChangeIndicatorstringoptional
    Indicates the length of time since the cardholder's account with the 3DS Requestor had a password change or account reset.
    nbPurchaseAccountnumberoptional
    Number of purchases with this cardholder account during the previous six months.
    destinationAddressUsageDatestringoptional
    Date when the shipping address used for this transaction was first used with the 3DS Requestor. ISO 8601 format
    destinationAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.
    destinationNameIndicatorstringoptional
    Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
    txnActivityDaynumberoptional
    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.
    txnActivityYearnumberoptional
    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.
    provisionAttemptsDaynumberoptional
    Number of Add Card attempts in the last 24 hours.
    suspiciousAccActivitystringoptional
    Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
    paymentAccAgeDatestringoptional
    Date that the payment account was enrolled in the cardholder's account with the 3DS Requestor. ISO 8601 format
    paymentAccIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3DS Requestor.
    merchantRiskIndicatorobjectoptional
    deliveryEmailstringoptional
    For Electronic delivery, the email address to which the merchandise was delivered.
    deliveryTimeframestringoptional
    Indicates the merchandise delivery timeframe.
    giftCardAmountobjectoptional
    valuenumberoptional
    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).
    currencystringoptional
    For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.
    giftCardCountnumberoptional
    For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
    preOrderDatestringoptional
    For a pre-ordered purchase, the expected date that the merchandise will be available. ISO 8601 format
    preOrderPurchaseIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    reorderItemsIndicatorstringoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    shipIndicatorstringoptional
    Indicates shipping method chosen for the transaction.
  - warningsarrayoptional
    codestringoptional
    descriptionstringoptional
  - paymentLinkIdstringoptional
    PayByLink id used for correlating this operation with the original link.
  - additionalDataobjectoptional
    Map of additional fields specific to the chosen payment method
- fieldSetobjectoptional
  - sessionIdstringoptional
  - securityTokenstringoptional
  - fieldsarrayoptional
    typestringoptional
    classstringoptional
    idstringoptional
    srcstringoptional
400Invalid request dataoptional
- errorsarrayoptional
  - codestringoptional
  - descriptionstringoptional
401Unauthorizedoptional
500Internal Server Erroroptional
- errorsarrayoptional
  - codestringoptional
  - descriptionstringoptional

PAYMENT_COMPLETE
REDIRECTED_TO_EXTERNAL_DOMAIN_APM
REDIRECTED_TO_EXTERNAL_DOMAIN_CHALLENGE
400
500

{
    "state": "PAYMENT_COMPLETE",
    "operation": {
        "orderId": "btid2384983",
        "operationId": "3470744",
        "channel": "ECOMMERCE",
        "operationType": "CAPTURE",
        "operationResult": "AUTHORIZED",
        "operationTime": "2022-09-01T01:20:00.001Z",
        "paymentMethod": "CARD",
        "paymentCircuit": "VISA",
        "paymentInstrumentInfo": "***6152",
        "paymentEndToEndId": "e723hedsdew",
        "cancelledOperationId": "",
        "operationAmount": "3545",
        "operationCurrency": "EUR",
        "customerInfo": {
            "cardHolderName": "Mauro Morandi",
            "cardHolderEmail": "mauro.morandi@nexi.it",
            "billingAddress": {
                "name": "Mario Rossi",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "city": "Bologna",
                "postCode": "40124",
                "province": "BO",
                "country": "ITA"
            },
            "shippingAddress": {
                "name": "Mario Rossi",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "city": "Bologna",
                "postCode": "40124",
                "province": "BO",
                "country": "ITA"
            },
            "mobilePhoneCountryCode": "39",
            "mobilePhone": "3280987654",
            "homePhone": "391231234567",
            "workPhone": "391231234567",
            "cardHolderAcctInfo": {
                "chAccDate": "2019-02-11",
                "chAccAgeIndicator": "01",
                "chAccChangeDate": "2019-02-11",
                "chAccChangeIndicator": "01",
                "chAccPwChangeDate": "2019-02-11",
                "chAccPwChangeIndicator": "01",
                "nbPurchaseAccount": 0,
                "destinationAddressUsageDate": "2019-02-11",
                "destinationAddressUsageIndicator": "01",
                "destinationNameIndicator": "01",
                "txnActivityDay": 0,
                "txnActivityYear": 0,
                "provisionAttemptsDay": 0,
                "suspiciousAccActivity": "01",
                "paymentAccAgeDate": "2019-02-11",
                "paymentAccIndicator": "0"
            },
            "merchantRiskIndicator": {
                "deliveryEmail": "john.doe@email.com",
                "deliveryTimeframe": "01",
                "giftCardAmount": null,
                "giftCardCount": 0,
                "preOrderDate": "2019-02-11",
                "preOrderPurchaseIndicator": "01",
                "reorderItemsIndicator": "01",
                "shipIndicator": "01"
            }
        },
        "warnings": [
            {
                "code": "TRA001",
                "description": "3DS warning"
            }
        ],
        "paymentLinkId": "234244353",
        "additionalData": {
            "authorizationCode": "647189",
            "cardCountry": "ITA",
            "threeDS": "FULL_SECURE",
            "schemaTID": "MCS01198U",
            "multiCurrencyConversion": {
                "amount": "2662",
                "currency": "JPY",
                "exchangeRate": "0.007510523"
            }
        }
    }
}

Cancel a payment.

POST /api/build/cancel

This service is targeted to ecommerce platforms in order to cancel the payment.

Parameters

X-API-KEYstringrequired
Correlation-Idstring (uuid)required
Mandatory field to be valued with a UUID to be renewed at every call. The purpose of the field is to allow referring to a specific call for any integration or maintenance activity.

Cancel a payment.

C#
PHP
Node
Shell

var client = new RestClient("https:///{gateway_test}/api/v1/api/build/cancel");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE");
request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request body

sessionIdstringoptional

Request body

{
    "sessionId": "052211e8/+54cc/4e0a"
}

Responses

200optional
In case of success, the service returns the specific status based on the state machine
- statestringoptional
  CARD_DATA_COLLECTION, PAYMENT_METHOD_SELECTION, READY_FOR_PAYMENT, REDIRECTED_TO_EXTERNAL_DOMAIN, PAYMENT_COMPLETE
- urlstringoptional
- operationobjectoptional
  - orderIdstringoptional
    Merchant order id, unique in the merchant domain
  - operationIdstringoptional
  - channelstringoptional
    It indicates the originating channel:
    
    ECOMMERCE - carholder initiated operation through an online channel.
    
    POS - carholder initiated operation through a physical POS.
    
    BACKOFFICE - merchant initiated operation. It includes post operations and MIT.
    
    ECOMMERCE, POS, BACKOFFICE
  - operationTypestringoptional
    It indicates the purpose of the request:
    
    AUTHORIZATION - any authorization with explicit capture
    
    CAPTURE - a captured authorization or an implicit captured payment
    
    VOID - reversal of an authorization
    
    REFUND - refund of a captured amount
    
    CANCEL - the rollback of an capture, refund.
    
    AUTHORIZATION, CAPTURE, VOID, REFUND, CANCEL
  - operationResultstringoptional
    Transaction output:
    
    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
    
    AUTHORIZED, EXECUTED, DECLINED, DENIED_BY_RISK, THREEDS_VALIDATED, THREEDS_FAILED, PENDING, CANCELED, VOIDED, REFUNDED, FAILED
  - operationTimestringoptional
    Operation time in ISO 8601 format
  - paymentMethodstringoptional
    
    CARD - Any card circuit
    
    APM - Alternative payment method
    
    CARD, APM
  - paymentCircuitstringoptional
    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.
  - paymentInstrumentInfostringoptional
    Payment instrument information
  - paymentEndToEndIdstringoptional
    It is defined by the circuit to uniquely identify the transaction. Required for circuid reconciliation purposes.
  - cancelledOperationIdstringoptional
    Operation id to be undone
  - operationAmountstringoptional
    Operation amount in the payment currency
  - operationCurrencystringoptional
    Payment currency
  - customerInfoobjectoptional
    cardHolderNamestringoptional
    cardHolderEmailstringoptional
    billingAddressobjectoptional
    namestringoptional
    streetstringoptional
    additionalInfostringoptional
    citystringoptional
    postCodestringoptional
    provincestringoptional
    countrystringoptional
    ISO 3166-1 alpha-3
    shippingAddressobjectoptional
    namestringoptional
    streetstringoptional
    additionalInfostringoptional
    citystringoptional
    postCodestringoptional
    provincestringoptional
    countrystringoptional
    ISO 3166-1 alpha-3
    mobilePhoneCountryCodestringoptional
    mobilePhonestringoptional
    homePhonestringoptional
    The home phone number provided by the Cardholder.
    workPhonestringoptional
    The work phone number provided by the Cardholder.
    cardHolderAcctInfoobjectoptional
    chAccDatestringoptional
    Date that the cardholder opened the account with the 3DS Requestor. ISO 8601 format
    chAccAgeIndicatorstringoptional
    Length of time that the cardholder has had the account with the 3DS Requestor.
    chAccChangeDatestringoptional
    Date that the cardholder's account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. ISO 8601 format
    chAccChangeIndicatorstringoptional
    Length of time since the cardholder's account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.
    chAccPwChangeDatestringoptional
    Date that cardholder's account with the 3DS Requestor had a password change or account reset. ISO 8601 format
    chAccPwChangeIndicatorstringoptional
    Indicates the length of time since the cardholder's account with the 3DS Requestor had a password change or account reset.
    nbPurchaseAccountnumberoptional
    Number of purchases with this cardholder account during the previous six months.
    destinationAddressUsageDatestringoptional
    Date when the shipping address used for this transaction was first used with the 3DS Requestor. ISO 8601 format
    destinationAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.
    destinationNameIndicatorstringoptional
    Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
    txnActivityDaynumberoptional
    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.
    txnActivityYearnumberoptional
    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.
    provisionAttemptsDaynumberoptional
    Number of Add Card attempts in the last 24 hours.
    suspiciousAccActivitystringoptional
    Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
    paymentAccAgeDatestringoptional
    Date that the payment account was enrolled in the cardholder's account with the 3DS Requestor. ISO 8601 format
    paymentAccIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3DS Requestor.
    merchantRiskIndicatorobjectoptional
    deliveryEmailstringoptional
    For Electronic delivery, the email address to which the merchandise was delivered.
    deliveryTimeframestringoptional
    Indicates the merchandise delivery timeframe.
    giftCardAmountobjectoptional
    valuenumberoptional
    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).
    currencystringoptional
    For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.
    giftCardCountnumberoptional
    For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
    preOrderDatestringoptional
    For a pre-ordered purchase, the expected date that the merchandise will be available. ISO 8601 format
    preOrderPurchaseIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    reorderItemsIndicatorstringoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    shipIndicatorstringoptional
    Indicates shipping method chosen for the transaction.
  - warningsarrayoptional
    codestringoptional
    descriptionstringoptional
  - paymentLinkIdstringoptional
    PayByLink id used for correlating this operation with the original link.
  - additionalDataobjectoptional
    Map of additional fields specific to the chosen payment method
- fieldSetobjectoptional
  - sessionIdstringoptional
  - securityTokenstringoptional
  - fieldsarrayoptional
    typestringoptional
    classstringoptional
    idstringoptional
    srcstringoptional
400Invalid request dataoptional
- errorsarrayoptional
  - codestringoptional
  - descriptionstringoptional
401Unauthorizedoptional
500Internal Server Erroroptional
- errorsarrayoptional
  - codestringoptional
  - descriptionstringoptional

{
    "state": "CARD_DATA_COLLECTION",
    "url": "https://{3DS-Ares-Url}",
    "operation": {
        "orderId": "btid2384983",
        "operationId": "3470744",
        "channel": "ECOMMERCE",
        "operationType": "CAPTURE",
        "operationResult": "AUTHORIZED",
        "operationTime": "2022-09-01T01:20:00.001Z",
        "paymentMethod": "CARD",
        "paymentCircuit": "VISA",
        "paymentInstrumentInfo": "***6152",
        "paymentEndToEndId": "e723hedsdew",
        "cancelledOperationId": "",
        "operationAmount": "3545",
        "operationCurrency": "EUR",
        "customerInfo": {
            "cardHolderName": "Mauro Morandi",
            "cardHolderEmail": "mauro.morandi@nexi.it",
            "billingAddress": {
                "name": "Mario Rossi",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "city": "Bologna",
                "postCode": "40124",
                "province": "BO",
                "country": "ITA"
            },
            "shippingAddress": {
                "name": "Mario Rossi",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "city": "Bologna",
                "postCode": "40124",
                "province": "BO",
                "country": "ITA"
            },
            "mobilePhoneCountryCode": "39",
            "mobilePhone": "3280987654",
            "homePhone": 391231234567,
            "workPhone": 391231234567,
            "cardHolderAcctInfo": {
                "chAccDate": "2019-02-11T00:00:00.000Z",
                "chAccAgeIndicator": "01",
                "chAccChangeDate": "2019-02-11T00:00:00.000Z",
                "chAccChangeIndicator": "01",
                "chAccPwChangeDate": "2019-02-11T00:00:00.000Z",
                "chAccPwChangeIndicator": "01",
                "nbPurchaseAccount": 0,
                "destinationAddressUsageDate": "2019-02-11T00:00:00.000Z",
                "destinationAddressUsageIndicator": "01",
                "destinationNameIndicator": "01",
                "txnActivityDay": 0,
                "txnActivityYear": 0,
                "provisionAttemptsDay": 0,
                "suspiciousAccActivity": "01",
                "paymentAccAgeDate": "2019-02-11T00:00:00.000Z",
                "paymentAccIndicator": "0"
            },
            "merchantRiskIndicator": {
                "deliveryEmail": "john.doe@email.com",
                "deliveryTimeframe": "01",
                "giftCardAmount": null,
                "giftCardCount": 0,
                "preOrderDate": "2019-02-11T00:00:00.000Z",
                "preOrderPurchaseIndicator": "01",
                "reorderItemsIndicator": "01",
                "shipIndicator": "01"
            }
        },
        "warnings": [
            {
                "code": "TRA001",
                "description": "3DS warning"
            }
        ],
        "paymentLinkId": "234244353",
        "additionalData": {
            "authorizationCode": "647189",
            "cardCountry": "ITA",
            "threeDS": "FULL_SECURE",
            "schemaTID": "MCS01198U",
            "multiCurrencyConversion": {
                "amount": "2662",
                "currency": "JPY",
                "exchangeRate": "0.007510523"
            }
        }
    },
    "fieldSet": {
        "sessionId": "sessionId",
        "securityToken": "security token",
        "fields": [
            {
                "type": "text",
                "class": "cardData",
                "id": "cardholderName",
                "src": "https://<fe>/field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264"
            }
        ]
    }
}

Get current payment state.

GET /api/build/state

This service is targeted to ecommerce platforms in order to retrieve the payment status.

Parameters

X-API-KEYstringrequired
Correlation-Idstring (uuid)required
Mandatory field to be valued with a UUID to be renewed at every call. The purpose of the field is to allow referring to a specific call for any integration or maintenance activity.
sessionIdstringrequired
the value of the payment session identifier

Get current payment state.

C#
PHP
Node
Shell

var client = new RestClient("https:///{gateway_test}/api/v1/api/build/state?sessionId=SOME_STRING_VALUE");
var request = new RestRequest(Method.GET);
request.AddHeader("Correlation-Id", "SOME_STRING_VALUE");
request.AddHeader("X-API-KEY", "REPLACE_KEY_VALUE");
IRestResponse response = client.Execute(request);

Responses

200optional
In case of success, the service returns a list of fields to be rendered in the ecomm web app.
- statestringoptional
  CARD_DATA_COLLECTION, PAYMENT_METHOD_SELECTION, READY_FOR_PAYMENT, REDIRECTED_TO_EXTERNAL_DOMAIN, PAYMENT_COMPLETE
- urlstringoptional
- operationobjectoptional
  - orderIdstringoptional
    Merchant order id, unique in the merchant domain
  - operationIdstringoptional
  - channelstringoptional
    It indicates the originating channel:
    
    ECOMMERCE - carholder initiated operation through an online channel.
    
    POS - carholder initiated operation through a physical POS.
    
    BACKOFFICE - merchant initiated operation. It includes post operations and MIT.
    
    ECOMMERCE, POS, BACKOFFICE
  - operationTypestringoptional
    It indicates the purpose of the request:
    
    AUTHORIZATION - any authorization with explicit capture
    
    CAPTURE - a captured authorization or an implicit captured payment
    
    VOID - reversal of an authorization
    
    REFUND - refund of a captured amount
    
    CANCEL - the rollback of an capture, refund.
    
    AUTHORIZATION, CAPTURE, VOID, REFUND, CANCEL
  - operationResultstringoptional
    Transaction output:
    
    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
    
    AUTHORIZED, EXECUTED, DECLINED, DENIED_BY_RISK, THREEDS_VALIDATED, THREEDS_FAILED, PENDING, CANCELED, VOIDED, REFUNDED, FAILED
  - operationTimestringoptional
    Operation time in ISO 8601 format
  - paymentMethodstringoptional
    
    CARD - Any card circuit
    
    APM - Alternative payment method
    
    CARD, APM
  - paymentCircuitstringoptional
    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.
  - paymentInstrumentInfostringoptional
    Payment instrument information
  - paymentEndToEndIdstringoptional
    It is defined by the circuit to uniquely identify the transaction. Required for circuid reconciliation purposes.
  - cancelledOperationIdstringoptional
    Operation id to be undone
  - operationAmountstringoptional
    Operation amount in the payment currency
  - operationCurrencystringoptional
    Payment currency
  - customerInfoobjectoptional
    cardHolderNamestringoptional
    cardHolderEmailstringoptional
    billingAddressobjectoptional
    namestringoptional
    streetstringoptional
    additionalInfostringoptional
    citystringoptional
    postCodestringoptional
    provincestringoptional
    countrystringoptional
    ISO 3166-1 alpha-3
    shippingAddressobjectoptional
    namestringoptional
    streetstringoptional
    additionalInfostringoptional
    citystringoptional
    postCodestringoptional
    provincestringoptional
    countrystringoptional
    ISO 3166-1 alpha-3
    mobilePhoneCountryCodestringoptional
    mobilePhonestringoptional
    homePhonestringoptional
    The home phone number provided by the Cardholder.
    workPhonestringoptional
    The work phone number provided by the Cardholder.
    cardHolderAcctInfoobjectoptional
    chAccDatestringoptional
    Date that the cardholder opened the account with the 3DS Requestor. ISO 8601 format
    chAccAgeIndicatorstringoptional
    Length of time that the cardholder has had the account with the 3DS Requestor.
    chAccChangeDatestringoptional
    Date that the cardholder's account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. ISO 8601 format
    chAccChangeIndicatorstringoptional
    Length of time since the cardholder's account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.
    chAccPwChangeDatestringoptional
    Date that cardholder's account with the 3DS Requestor had a password change or account reset. ISO 8601 format
    chAccPwChangeIndicatorstringoptional
    Indicates the length of time since the cardholder's account with the 3DS Requestor had a password change or account reset.
    nbPurchaseAccountnumberoptional
    Number of purchases with this cardholder account during the previous six months.
    destinationAddressUsageDatestringoptional
    Date when the shipping address used for this transaction was first used with the 3DS Requestor. ISO 8601 format
    destinationAddressUsageIndicatorstringoptional
    Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.
    destinationNameIndicatorstringoptional
    Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
    txnActivityDaynumberoptional
    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.
    txnActivityYearnumberoptional
    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.
    provisionAttemptsDaynumberoptional
    Number of Add Card attempts in the last 24 hours.
    suspiciousAccActivitystringoptional
    Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
    paymentAccAgeDatestringoptional
    Date that the payment account was enrolled in the cardholder's account with the 3DS Requestor. ISO 8601 format
    paymentAccIndicatorstringoptional
    Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3DS Requestor.
    merchantRiskIndicatorobjectoptional
    deliveryEmailstringoptional
    For Electronic delivery, the email address to which the merchandise was delivered.
    deliveryTimeframestringoptional
    Indicates the merchandise delivery timeframe.
    giftCardAmountobjectoptional
    valuenumberoptional
    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).
    currencystringoptional
    For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.
    giftCardCountnumberoptional
    For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
    preOrderDatestringoptional
    For a pre-ordered purchase, the expected date that the merchandise will be available. ISO 8601 format
    preOrderPurchaseIndicatorstringoptional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    reorderItemsIndicatorstringoptional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    shipIndicatorstringoptional
    Indicates shipping method chosen for the transaction.
  - warningsarrayoptional
    codestringoptional
    descriptionstringoptional
  - paymentLinkIdstringoptional
    PayByLink id used for correlating this operation with the original link.
  - additionalDataobjectoptional
    Map of additional fields specific to the chosen payment method
- fieldSetobjectoptional
  - sessionIdstringoptional
  - securityTokenstringoptional
  - fieldsarrayoptional
    typestringoptional
    classstringoptional
    idstringoptional
    srcstringoptional
400Invalid request dataoptional
- errorsarrayoptional
  - codestringoptional
  - descriptionstringoptional
401Unauthorizedoptional
500Internal Server Erroroptional
- errorsarrayoptional
  - codestringoptional
  - descriptionstringoptional

PAYMENT_COMPLETE
READY_FOR_PAYMENT
CARD_DATA_COLLECTION
400
500

{
    "state": "PAYMENT_COMPLETE",
    "operation": {
        "orderId": "btid2384983",
        "operationId": "3470744",
        "channel": "ECOMMERCE",
        "operationType": "CAPTURE",
        "operationResult": "AUTHORIZED",
        "operationTime": "2022-09-01T01:20:00.001Z",
        "paymentMethod": "CARD",
        "paymentCircuit": "VISA",
        "paymentInstrumentInfo": "***6152",
        "paymentEndToEndId": "e723hedsdew",
        "cancelledOperationId": "",
        "operationAmount": "3545",
        "operationCurrency": "EUR",
        "customerInfo": {
            "cardHolderName": "Mauro Morandi",
            "cardHolderEmail": "mauro.morandi@nexi.it",
            "billingAddress": {
                "name": "Mario Rossi",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "city": "Bologna",
                "postCode": "40124",
                "province": "BO",
                "country": "ITA"
            },
            "shippingAddress": {
                "name": "Mario Rossi",
                "street": "Piazza Maggiore, 1",
                "additionalInfo": "Quinto Piano, Scala B",
                "city": "Bologna",
                "postCode": "40124",
                "province": "BO",
                "country": "ITA"
            },
            "mobilePhoneCountryCode": "39",
            "mobilePhone": "3280987654",
            "homePhone": "391231234567",
            "workPhone": "391231234567",
            "cardHolderAcctInfo": {
                "chAccDate": "2019-02-11",
                "chAccAgeIndicator": "01",
                "chAccChangeDate": "2019-02-11",
                "chAccChangeIndicator": "01",
                "chAccPwChangeDate": "2019-02-11",
                "chAccPwChangeIndicator": "01",
                "nbPurchaseAccount": 0,
                "destinationAddressUsageDate": "2019-02-11",
                "destinationAddressUsageIndicator": "01",
                "destinationNameIndicator": "01",
                "txnActivityDay": 0,
                "txnActivityYear": 0,
                "provisionAttemptsDay": 0,
                "suspiciousAccActivity": "01",
                "paymentAccAgeDate": "2019-02-11",
                "paymentAccIndicator": "0"
            },
            "merchantRiskIndicator": {
                "deliveryEmail": "john.doe@email.com",
                "deliveryTimeframe": "01",
                "giftCardAmount": null,
                "giftCardCount": 0,
                "preOrderDate": "2019-02-11",
                "preOrderPurchaseIndicator": "01",
                "reorderItemsIndicator": "01",
                "shipIndicator": "01"
            }
        },
        "warnings": [
            {
                "code": "TRA001",
                "description": "3DS warning"
            }
        ],
        "paymentLinkId": "234244353",
        "additionalData": {
            "authorizationCode": "647189",
            "cardCountry": "ITA",
            "threeDS": "FULL_SECURE",
            "schemaTID": "MCS01198U",
            "multiCurrencyConversion": {
                "amount": "2662",
                "currency": "JPY",
                "exchangeRate": "0.007510523"
            }
        }
    }
}