Skip to content

    XPay Build APIs

    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.

    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.

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

    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.

    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
    {
        "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"
                }
            }
        }
    }