---
updatedAt: 2026-10-09T06:00:06.000Z
agentTools:
  projectIndex: https://developer.spreedly.com/llms.txt
---

# Nuvei REST gateway guide

## [Nuvei REST fact sheet](https://developer.spreedly.com/docs/nuvei-factsheet)

## Adding a Nuvei REST gateway

To add a [Nuvei](https://nuvei.com/) Gateway

```xml
curl https://core.spreedly.com/v1/gateways.xml \
  -u '{environment_key}:{access_secret}' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>nuvei</gateway_type>
        <merchant_id>Your merchant id</merchant_id>
        <merchant_site_id>Your merchant site id</merchant_site_id>
    		<secret_key>Your secret key</secret_key>
      </gateway>'
```

```xml
<gateway>
  <token>2FB23SDPYZ997SPM9NGNM8BFN0</token>
  <gateway_type>nuvei</gateway_type>
  <name>Nuvei</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">true</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
    <supports_card_scheme_ntid type="boolean">true</supports_card_scheme_ntid>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>user_token_id</gateway_specific_field>
	  <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>is_partial_approval</gateway_specific_field>
    <gateway_specific_field>save_payment_method</gateway_specific_field>
    <gateway_specific_field>is_payout</gateway_specific_field>
    <gateway_specific_field>is_aft</gateway_specific_field>
    <gateway_specific_field>aft_recipient_first_name</gateway_specific_field>
    <gateway_specific_field>aft_recipient_last_name</gateway_specific_field>
    <gateway_specific_field>aft_recipient_address</gateway_specific_field>
    <gateway_specific_field>user_details</gateway_specific_field>
    <gateway_specific_field>use_pre_auth</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>bank_account</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2024-10-31T15:19:34Z</created_at>
  <updated_at type="dateTime">2024-10-31T15:19:34Z</updated_at>
</gateway>
```

To learn more about creating and managing gateways in our Marketplace, review the [Gateway user guide](https://developer.spreedly.com/docs/gateway-user-guide). For gateways not included in the Marketplace, review the steps below.

### Create a gateway

Visit your [Connections](https://app.spreedly.com/gateways/all) area to review all gateways and add new ones. When creating your gateways, select the gateway name and authentication mode (if prompted) before completing required fields. Select :ballot\_box\_with\_check:Sandbox to create a gateway in Sandbox mode, for processing test card data and transactions in your Spreedly environment.

<Image align="center" src="https://files.readme.io/bd7e72c-Screenshot_2024-05-14_at_2.18.13_PM.png" />

## Gateway Specific Fields

When interacting with a Nuvei gateway to run transactions, there are several gateway specific fields you can specify.

When making any request you can specify `user_token_id`; this maps to the gateway's `userTokenId` field. It is the unique customer identifier the in merchant system. It is a **required** field for processing [Payouts](https://docs.nuvei.com/documentation/features/financial-operations/payout/) through Spreedly's [General Credit transaction type](https://developer.spreedly.com/reference/general-credit-transaction), for Store, Third-party token purchase, authorize transactions and for Merchant Initiated Transactions (MIT).

When making purchase/payment request to process a partial approval transaction, you should specify `is_partial_approval`  as `true` (boolean); this maps to the gateway's `isPartialApproval` field.

When making any request you can specify `idempotency_key` that maps to the gateway's `clientRequestId` field. It is a unique identifier used to prevent duplicate transactions. If a request is retried with a key used in the last 24 hours, Nuvei will block the duplicate to prevent a double charge and return error message

When making any request you can specify `save_payment_method` to `false` (boolean) to override the default store/register of the payment method.

When making a [3DS Gateway Specific](https://developer.spreedly.com/docs/3ds2-gateway-specific) request you can specify `force_3d_secure`field, as `true` or `false` (boolean), this maps to the gateway's `challengePreference` field to set `01 – Challenge` or `02 – Exemption`values.

When making any request especially for [Stored Credentials](https://developer.spreedly.com/docs/stored-credentials) you can specify `authentication_only_type` field, this maps to the gateway's `authenticationOnlyType` field. The allowed vales are `RECURRING`, `INSTALLMENTS` or `ADDCARD`.

When making 3DS Global requests you can specify `challenge_preference`; this maps to the gateway's `challengePreference` field. The use of this parameter is only for "advanced" situations to force 3DS exemptions or challenges.

When making 3DS Global requests you can specify `exemption_request_reason`; this maps to the gateway's `exemptionRequestReason` field. The use of this parameter is required if `challengePreference`= `ExemptionRequest`. Possible values: `AddCard`, `AccountVerification`, `LowValuePayment`, or `TransactionRiskAnalysis`.

When making any request, you can specify Gateway Specific Field `is_aft` as `true` (boolean), which allows [Account Funding Transactions (AFTs)](https://docs.nuvei.com/documentation/features/financial-operations/aft/) to be sent. For more information, please refer to the [Gateway's AFT guide.](https://docs.nuvei.com/documentation/features/financial-operations/aft/). In addition to supporting non-domestic AFT requests, you should send the recipient information in the following Gateway Specific Fields: `aft_recipient_first_name` , `aft_recipient_last_name`, `aft_recipient_address`,`user_details,aft_recipient_middle_name, aft_recipient_address_line_2, aft_recipient_street, aft_recipient_city, aft_recipient_state_code, aft_recipient_zip, aft_recipient_country_code, aft_recipient_phone_number, aft_recipient_email, aft_recipient_date_of_birth, aft_recipient_account_reference, aft_recipient_identification_type_code, aft_recipient_identification_value, aft_sender_identification_type_code, aft_recipient_card_holder_entity_type`,`and aft_sender_identification_value.`

When making a payout request, you have to specify Gateway specific fields `is_payout` as `true` (boolean) and the `user_details` which allows payout to be sent. For more information, refer to the [Gateway's Payout guide.](https://docs.nuvei.com/documentation/features/financial-operations/payout/?highlight=payout)

When initiating a Pre-Auth transaction to place a temporary hold on the cardholder’s funds, please send the optional field`use_pre_auth` set as `true` (boolean). For more information regarding Pre-Auth transactions, please refer to the [Auth and Settle guide](https://docs.nuvei.com/documentation/features/financial-operations/auth-and-settle/).

To support refund transactions involving Mastercard, merchants can pass the `instant_refund` boolean flag to trigger a fast-fund reversal; the outcome of this request is returned in the transaction response via the `is_instant_refund_successful` gateway specific response field.

The `user_details` gateway specific field can used for payout or aft related transactions. The expected structure of this field is a hash that includes nested optional fields. Please refer to the userDetails class on the [payout guide](https://docs.nuvei.com/api/main/indexMain_v1_0.html?json#payout) and [payment guide](https://docs.nuvei.com/api/main/indexMain_v1_0.html?json#payment) for more details. The below nested fields can be used for either transaction types unless noted otherwise. For specific examples, please refer to the AFT and Payout sections.

* `first_name`
* `last_name`
* `address`
* `identification`
* `phone`
* `zip`
* `city`
* `country`
* `state`
* `email`
* `county` (AFT only, omit on OCT/Payouts)
* `language` (AFT only, omit on OCT/Payouts)
* `street_number` (AFT only, omit on OCT/Payouts)
* For AFT transactions, please use:
  * `date_of_birth` in **YYYY-MM-DD** string format (required)
* For OCT/Payout transactions, please use:
  * `birth_date` in **YYYY-MM-DD** string format (required)\ <br />

When making any request with amount `0` you can specify `perform_name_verification` field, which allows Cardholder Name Verification, For more information, please refer to the [Gateway's guide](https://docs.nuvei.com/documentation/features/card-operations/cardholder-name-verification/).

## Idempotent Requests

To prevent duplicate transactions on Nuvei REST, it is necessary to pass the gateway-specific field `idempotency_key`. This key must be a unique value and ensures that a transaction is only executed once.

Nuvei REST treats a duplicate request as a conflict and prevents the same transaction from being authorized more than once.

* **Initial Request:** For a unique `idempotency_key`, Nuvei processes the transaction normally and returns a success response
* **Duplicate Request:** If a request is retried with a key that was used within the last 24 hours, Nuvei will block the attempt to prevent a double charge. Unlike a standard retry, the second response will indicate a failure with the message: "There is another transaction with this clientRequestId." and return Error Code 1089.

In order to successfully use the `idempotency_key` feature on Nuvei REST, the following conditions must be met:

* **Key Uniqueness:** The key must be unique per intent. Reusing a key with different transaction parameters (e.g., a different amount) will result in a validation error.
* **Retries:** If you receive a 1089 error, do not continue retrying. Instead, you should query the original transaction status using the order\_id or the Spreedly transaction\_token from your first attempt to confirm the final result.

## Network Tokenization and Third-Party Tokens

Spreedly supports Network Tokenization, enabling the processing of transactions using network-certified tokens for Visa and Mastercard.

Spreedly also supports Third-Party Tokens when processing payments through the Nuvei REST gateway. To ensure successful processing, merchants must pass the `user_token_id` as a Gateway Specific Field (GSF) for all store, purchase, and authorize requests involving third-party tokens. This field is mandatory for Nuvei to correctly map the external token to the merchant's account.

## Stored Credentials

Spreedly supports the Stored Credential framework for Nuvei REST. For any Authorize or Purchase request, you need to include two fields which tell Spreedly a little bit more about the nature of the transaction. For more details, refer the [Stored Credentials](https://developer.spreedly.com/docs/stored-credentials) guide on Spreedly. Along with the below fields, `user_token_id` is a required field for carrying out Merchant Initiated Transactions (MIT).

* `stored_credential_initiator `
* `stored_credential_reason_type`

## Third-party 3D Secure Auth Data

Spreedly will automatically handle the field mapping for sending third-party 3DS2 authentication data to Nuvei. For more information about how to use this feature, see the [3DS2 Third-party Authentication Guide](https://developer.spreedly.com/edit/using-third-party-3ds2-providers). Spreedly fields map to the relevant Nuvei fields as described in the following table. Please see [Nuvei’s third-party 3DS2 documentation ](https://docs.nuvei.com/documentation/features/3d-secure-2/3ds-implementations/3ds-external-mpi/)for detailed descriptions of each of these fields and when to use them.

| Spreedly field                      | Nuvei field              |
| :---------------------------------- | :----------------------- |
| `eci`                               | `eci`                    |
| `cavv`                              | `cavv`                   |
| `ds_transaction_id`                 | `dsTransId`              |
| `challenge_preference` **(GSF)**    | `challengePreference`    |
| `exemption_request_reason`**(GSF)** | `exemptionRequestReason` |

### 3DS Request

```xml xml
curl https://core.spreedly.test/v1/gateways/{gateway_token}/purchase.xml \
-u '{environment_key}:{access_secret}' \
-H 'Content-Type: application/xml' \
-d '<transaction>
    <amount>100</amount>
    <currency_code>USD</currency_code>
    <payment_method_token>EyjG8inHFr89M2R06xIb1YOOYt6</payment_method_token>
    <email>test@gmail.com</email>
    <retain_on_success>true</retain_on_success>
    <ip>127.0.0.1</ip>
    <three_ds>
        <ecommerce_indicator>05</ecommerce_indicator>
        <authentication_value>e1E3SN0xF1lDp9js723iASu3wrA=</authentication_value>
        <directory_server_transaction_id>ODUzNTYzOTcwODU5NzY3Qw==</directory_server_transaction_id>
    </three_ds>
</transaction>
'
```

### Response

```xml X
<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2024-11-06T14:22:12Z</created_at>
  <updated_at type="dateTime">2024-11-06T14:22:17Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>PHe4ytVmRe8UOr5xhVX87TV0XZS</token>
  <transaction_type>Purchase</transaction_type>
  <order_id>b421eb9d6f02579156027af691cebe6c69d7c93c601896694d7f3c55c8af518d</order_id>
  <ip>127.0.0.1</ip>
  <description nil="true"/>
  <email>test@gmail.com</email>
  <merchant_name_descriptor nil="true"/>
  <merchant_location_descriptor nil="true"/>
  <merchant_profile_key nil="true"/>
  <gateway_specific_fields nil="true"/>
  <gateway_specific_response_fields>
    <nuvei>
      <requested_amount>100</requested_amount>
      <requested_currency>USD</requested_currency>
      <procceed_amount>100</procceed_amount>
      <procceed_currency>USD</procceed_currency>
    </nuvei>
  </gateway_specific_response_fields>
  <gateway_transaction_id>7110000000006278761</gateway_transaction_id>
  <sub_merchant_key nil="true"/>
  <gateway_latency_ms type="integer">1667</gateway_latency_ms>
  <warning nil="true"/>
  <application_id nil="true"/>
  <risk_data nil="true"/>
  <merchant_metadata nil="true"/>
  <customer_data nil="true"/>
  <order_data nil="true"/>
  <workflow_key nil="true"/>
  <amount type="integer">100</amount>
  <local_amount nil="true"/>
  <currency_code>USD</currency_code>
  <retain_on_success type="boolean">true</retain_on_success>
  <payment_method_added type="boolean">false</payment_method_added>
  <smart_routed type="boolean">false</smart_routed>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <stored_credential_alternate_gateway nil="true"/>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>6X8XDF3ZR68DJSN2QP9RF3266Z</gateway_token>
  <gateway_type>nuvei</gateway_type>
  <shipping_address>
    <name>Apple Smith</name>
    <address1>12345 Example Way</address1>
    <address2 nil="true"/>
    <city>Atlanta</city>
    <state>GA</state>
    <zip>30301</zip>
    <country>US</country>
    <phone_number nil="true"/>
  </shipping_address>
  <response>
    <success type="boolean">true</success>
    <message>APPROVED</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code>0</error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2024-11-06T14:22:15Z</created_at>
    <updated_at type="dateTime">2024-11-06T14:22:17Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>EyjG8inHFr89M2R06xIb1YOOYt6</token>
    <created_at type="dateTime">2024-11-06T13:30:18Z</created_at>
    <updated_at type="dateTime">2024-11-06T14:07:54Z</updated_at>
    <email>john.smith@example.com</email>
    <data nil="true"/>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <metadata>
      <key>testing apple pay</key>
      <another_key type="integer">123</another_key>
      <final_key type="boolean">true</final_key>
    </metadata>
    <callback_url nil="true"/>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Apple</first_name>
    <last_name>Smith</last_name>
    <month type="integer">12</month>
    <year type="integer">2028</year>
    <full_name>Apple Smith</full_name>
    <address1>12345 Example Way</address1>
    <address2 nil="true"/>
    <city>Atlanta</city>
    <state>GA</state>
    <zip>30301</zip>
    <country>USA</country>
    <phone_number nil="true"/>
    <company nil="true"/>
    <shipping_address1>12345 Example Way</shipping_address1>
    <shipping_address2 nil="true"/>
    <shipping_city>Atlanta</shipping_city>
    <shipping_state>GA</shipping_state>
    <shipping_zip>30301</shipping_zip>
    <shipping_country>USA</shipping_country>
    <shipping_phone_number nil="true"/>
    <eligible_for_card_updater type="boolean">false</eligible_for_card_updater>
    <payment_method_type>apple_pay</payment_method_type>
    <stored_credential_usage>
      <scheme_issued>
        <original_network_transaction_id nil="true"/>
        <network_transaction_id nil="true"/>
      </scheme_issued>
      <nuvei>
        <original_network_transaction_id nil="true"/>
        <network_transaction_id nil="true"/>
      </nuvei>
    </stored_credential_usage>
    <errors>
    </errors>
  </payment_method>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
```

<Table align={["left"]}>
  <thead>
    <tr>
      <th>
        Additional notes
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        For every transaction, Nuvei requires an **IP** value to be sent. Ensure that the `ip` field is always included in the body of the request.

        To make a straightforward purchase, simply omit the `three_ds` object from your request.
      </td>
    </tr>
  </tbody>
</Table>

## ACH/ Bank Account Transactions

<Table align={["left"]}>
  <thead>
    <tr>
      <th>
        Additional notes
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        * ACH only supports US-based IPs. IP addresses outside the US do not work.
      </td>
    </tr>

    <tr>
      <td>
        * In addition to payment request responses, the system sends [Direct Merchant Notifications (DMNs)](https://docs.nuvei.com/?p=233345)  containing the transaction processing results to a specified `notificationUrl` provided
      </td>
    </tr>

    <tr>
      <td>
        *  The SEC code is derived from the customer’s account type
      </td>
    </tr>
  </tbody>
</Table>

ACH only supports US-based IPs. IP addresses outside the US do not work and the Transactions are conducted in US Dollars.

The first time a customer uses a bank account, Nuvei captures their bank account details and stores these details in an encrypted UPO (User Payment Option) record in the Nuvei system for use in future transactions.

`notificationUrl` is required for Payouts and ACH. Specifies the URL where Nuvei sends Direct Merchant Notifications (DMN) for transaction status updates. Mapped to Nuvei’s urlDetails.notificationUrl.

Nuvei REST does not support direct Payouts (General Credits) using raw Bank Account/ACH details in a single step. To perform a payout to a bank account:

* **Store the Payment Method:** Use storage method to vault the ACH details with Nuvei first.
* **Process as Third-Party Token:** Execute the `general_credit` transaction using the resulting third-party payment method token.

### Testing

To create a bank account (ACH) payment method, consider the following values and refer to the [Spreedly API ](https://docs.spreedly.com/reference/api/v1/?json#create-bank-account)for detailed guidance.

* Amount must be 1.25
* Country must be US and include a state

### Fields mapping

| Spreedly field               | Nuvei field                   |
| :--------------------------- | :---------------------------- |
| `routing_number`             | `RoutingNumber`               |
| `account_number`             | `AccountNumber`               |
| `notification_url` **(GSF)** | `urlDetails.notification_url` |
| `billing_address.country`    | `billingAddress.country`      |
| `billing_address.state`      | `billingAddress.state`        |
| `ip`                         | `deviceDetails.ipAddress`     |

The `notification_url` should be sent as a Gateway Specific Field.

### ACH Request

```xml
curl https://core.spreedly.test/v1/gateways/{gateway_token}/purchase.xml \
-u '{environment_key}:{access_secret}' \
-H 'Content-Type: application/xml' \
-d '<transaction>
    <bank_account>
        <first_name>Joe</first_name>
        <last_name>Smith</last_name>
        <bank_routing_number>021000021</bank_routing_number>
        <bank_account_number>9876543210</bank_account_number>
    </bank_account>
    <amount>100</amount>
    <currency_code>USD</currency_code>
    <order_id>{{$guid}}</order_id>
    <email>test@gmail.com</email>
    <retain_on_success>true</retain_on_success>
    <billing_address>
        <country>US</country>
        <state>MA</state>
    </billing_address>
    <ip>127.0.0.1</ip>
</transaction>
'
```

## Google Pay

Since Spreedly decrypts the Google Pay token, you need to collect the following details from Google Pay:

Payment Data: This includes the `signature`, `protocolVersion`, and `signedMessage` provided by Google Pay. These values represent the tokenized card information and the cryptogram.

Spreedly will decrypt the Google Pay data and automatically handle the mapping of the necessary fields for the required Nuvei fields, including `externalTokenProvider`, `cryptogram`, and `eciProvider`, as well as the basic card data.

### Google Pay Request

```xml
curl https://core.spreedly.test/v1/gateways/6X8XDF3ZR68DJSN2QP9RF3266Z/purchase.xml \
-u '1B58V8AYEG8HRB4C5QE075WM3T:T9DcGB1kYyLQjlR8aQKHnbwOGowWsbeETPif2UPLEBDQVqm03Mu3UavnpMpqgwfy' \
-H 'Content-Type: application/xml' \
-d '<transaction>
    <google_pay>
        <payment_data>
            <signature>YOUR_SIGNATURE</signature>
            <protocolVersion>YOUR_PROTOCOL_VERSION</protocolVersion>
            <signedMessage>YOUR_SIGNED_MESSAGE</signedMessage>
        </payment_data>
        <first_name>Cure</first_name>
        <last_name>Tester</last_name>
        <country>USA</country>
        <number>4761344136141390</number> <!-- success -->
        <verification_value>123</verification_value>
    </google_pay>
    <amount>100</amount>
    <currency_code>USD</currency_code>
    <order_id>{{$guid}}</order_id>
    <email>test@gmail.com</email>
    <retain_on_success>true</retain_on_success>
    <ip>127.0.0.1</ip>
</transaction>
'
```

## CardHolder Name Verification

Nuvei supports card scheme services that verify the name a customer provides to a merchant and matches the cardholder name on file with the card issuer. These services provide an additional security check during card onboarding and pre-transaction checks, when `amount=0`.

When Making a cardholder name verification you should to send the Gateway Specific Field (GSF) `perform_name_verification` as `true` (boolean), this maps to the gateway's `cardHolderNameVerification.performNameVerification` field.

### Gateway Specific Response Fields

A response from Nuvei *may* contain the following fields:

| Nuvei GSRF                         | Possible values                                                                                     |
| :--------------------------------- | :-------------------------------------------------------------------------------------------------- |
| `name_verification_request_result` | `NameVerificationPerformed`<br />`NameVerificationNotPerformed`<br />`NameVerificationNotSupported` |
| `name_verification_result`         | `Match`, `PartialMatch`, `NoMatch`, `Unverified`                                                    |
| `first_name_verification_result`   | `Match`, `PartialMatch`, `NoMatch`, `Unverified`                                                    |
| `middle_name_verification_result`  | `Match`, `PartialMatch`, `NoMatch`, `Unverified`                                                    |
| `last_name_verification_result`    | `Match`, `PartialMatch`, `NoMatch`, `Unverifed`                                                     |
| `authorization_code`               | The code generated by the processor that provides details on decline or approval                    |

If `name_verification_request_result`: `"NameVerificationNotPerformed"` or `"NameVerificationNotSupported"`, the only possible value for each of the four Verification Result parameters is `Unverified`.

## Account Funding Transactions (AFTs)

An Account Funding Transaction (AFT) pulls funds from a card and deposits or transfers those funds into another account.

AFTs are relevant only for merchants offering funding transactions. To begin using AFTs, contact Nuvei to configure your merchant account to use this transaction type

When Making a AFT transaction you should to send the Gateway Specific Fields (GSF) `is_aft` as `true` (boolean) and the `user_details`(hash), this will map the next required fields.

| Spreedly field                                 | Nuvei field                               |
| :--------------------------------------------- | :---------------------------------------- |
| `aft_recipient_first_name` (GSF)               | `recipientDetails.firstName`              |
| `aft_recipient_middle_name` (GSF)              | `recipientDetails.middleName`             |
| `aft_recipient_last_name` (GSF)                | `recipientDetails.lastName`               |
| `aft_recipient_address` (GSF)                  | `recipientDetails.address`                |
| `aft_recipient_address_line_2` (GSF)           | `recipientDetails.addressLine2`           |
| `aft_recipient_street` (GSF)                   | `recipientDetails.street`                 |
| `aft_recipient_city` (GSF)                     | `recipientDetails.city`                   |
| `aft_recipient_state_code` (GSF)               | `recipientDetails.state`                  |
| `aft_recipient_zip` (GSF)                      | `recipientDetails.zip`                    |
| `aft_recipient_country_code` (GSF)             | `recipientDetails.country`                |
| `aft_recipient_phone_number` (GSF)             | `recipientDetails.phoneNumber`            |
| `aft_recipient_email` (GSF)                    | `recipientDetails.email`                  |
| `aft_recipient_account_reference` (GSF)        | `recipientDetails.accountReference`       |
| `aft_recipient_identification_type_code` (GSF) | `recipientDetails.identificationTypeCode` |
| `aft_recipient_identification_value` (GSF)     | `recipientDetails.identificationValue`    |
| `aft_recipient_card_holder_entity_type `(GSF)  | `recipientDetails.cardHolderEntityType`   |

* For **non-domestic** AFT requests, they must contain the sender details to be marked by Nuvei for AFT.

### Gateway Specific Response Fields

* `is_aft`: true
* `is_aft_overriden`: true

### AFT request

```xml xml
`curl https://core.spreedly.test/v1/gateways/{gateway_token}/purchase.xml \
-u '{environment_key}:{access_secret}' \
-H 'Content-Type: application/xml' \
-d '<transaction>
    <amount>100</amount>
    <currency_code>USD</currency_code>
    <payment_method_token>E5g6rB46gli2vupsXjyxQfaRbaz</payment_method_token>
    <email>test@gmail.com</email>
    <retain_on_success>true</retain_on_success>
    <ip>127.0.0.1</ip>
    <gateway_specific_fields>
      <nuvei>
        <user_token_id>123456</user_token_id>
        <is_aft>true</is_aft>
        <aft_recipient_first_name>John</aft_recipient_first_name>
        <aft_recipient_middle_name>Q</aft_recipient_middle_name>
        <aft_recipient_last_name>Doe</aft_recipient_last_name>
        <aft_recipient_address>12345</aft_recipient_address>
        <aft_recipient_address_line_2>Apt 4</aft_recipient_address_line_2>
        <aft_recipient_street>Main St</aft_recipient_street>
        <aft_recipient_city>Boston</aft_recipient_city>
        <aft_recipient_state_code>MA</aft_recipient_state_code>
        <aft_recipient_zip>02110</aft_recipient_zip>
        <aft_recipient_country_code>US</aft_recipient_country_code>
        <aft_recipient_phone_number>6175551212</aft_recipient_phone_number>
        <aft_recipient_email>recipient@example.com</aft_recipient_email>
        <aft_recipient_date_of_birth>1990-01-02</aft_recipient_date_of_birth>
        <aft_recipient_account_reference>ACC123</aft_recipient_account_reference>
        <aft_recipient_identification_type_code>PASN</aft_recipient_identification_type_code>
        <aft_recipient_identification_value>P1234567</aft_recipient_identification_value>
        <aft_sender_identification_type_code>NTID</aft_sender_identification_type_code>
        <aft_sender_identification_value>ID998877</aft_sender_identification_value>
        <user_details>
          <first_name>john</first_name>
          <last_name>doe</last_name>
          <address>123 address</address>
          <identification>123456789</identification>
          <phone>1231231234</phone>
          <zip>11111</zip>
          <city>city</city>
          <country>US</country>
          <state>NY</state>
          <email>email@mail.com</email>
          <county>county</county>
          <language>EN</language>
          <street_number>12345</street_number>
          <date_of_birth>1990-09-01</date_of_birth>
        </user_details>
      </nuvei>
    </gateway_specific_fields>
</transaction>
'
```

## Verify transaction

A merchant may want to perform a zero-authorization card transaction in order to verify if a credit card is a chargeable card and available for purchases.

Verify transactions can be used in order to:

* Store card details for future use
* Add a card (card registration)
* Verify a card

When making a [verify](https://docs.spreedly.com/reference/api/v1/#verify) request Spreedly sets the  `amount`: 0 and `transactionType`: Auth. The  `authentication_only_type` GSF should be included in the request. Below lists the possible values for `authentication_only_type`.

| Values                | Description                                                                                                                            |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| `RECURRING`           | For when multiple transactions are submitted by the Merchant separately based on an agreement between the Merchant and the cardholder. |
| `INSTALLMENTS`        | For when a single transaction is divided into multiple charges.                                                                        |
| `ADDCARD`             | For when a cardholder adds their card to be used for future transactions                                                               |
| `MAINTAINCARD`        | For when a Merchant wants to verify that an existing card is still valid.                                                              |
| `ACCOUNTVERIFICATION` | For a verification different than those listed above.                                                                                  |

## Payouts

* Nuvei supports sending payout requests with no connection to a previous transaction.  Aka unreferenced refund. Please refer to [ Nuvei documentation](https://docs.nuvei.com/api/main/indexMain_v1_0.html?json#payout) for further details.

  * `is_payout`  **GSF** is required
  * `user_details` **GSF**

### Payout request

```xml
`curl https://core.spreedly.test/v1/gateways/{gateway_token}/general_credit.xml \
-u '{environment_key}:{access_secret}' \
-H 'Content-Type: application/xml' \
-d '<transaction>
    <amount>100</amount>
    <currency_code>USD</currency_code>
    <payment_method_token>E5g6rB46gli2vupsXjyxQfaRbaz</payment_method_token>
    <email>test@gmail.com</email>
    <retain_on_success>true</retain_on_success>
    <ip>127.0.0.1</ip>
    <gateway_specific_fields>
      <nuvei>
        <user_token_id>123456</user_token_id>
        <is_payout>true</is_payout>
        <user_details>
          <first_name>john</first_name>
          <last_name>doe</last_name>
          <address>123 address</address>
          <identification>123456789</identification>
          <phone>1231231234</phone>
          <zip>11111</zip>
          <city>city</city>
          <country>US</country>
          <state>NY</state>
          <email>email@mail.com</email>
          <birth_date>1990-09-01</birth_date>
        </user_details>
      </nuvei>
    </gateway_specific_fields>
</transaction>
'
```

### Response

```xml
`<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2024-11-27T20:17:31Z</created_at>
  <updated_at type="dateTime">2024-11-27T20:17:37Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>HZoag0dNJfNTWnSKpuocbz6qC1G</token>
  <transaction_type>GeneralCredit</transaction_type>
  <order_id nil="true"/>
  <ip>127.0.0.1</ip>
  <description nil="true"/>
  <email>test@gmail.com</email>
  <merchant_name_descriptor nil="true"/>
  <merchant_location_descriptor nil="true"/>
  <merchant_profile_key nil="true"/>
  <gateway_specific_fields>
    <nuvei>
      <user_token_id>123456</user_token_id>
      <is_payout>true</is_payout>
    </nuvei>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
    <nuvei>
      <requested_amount>100</requested_amount>
      <requested_currency>USD</requested_currency>
      <procceed_amount>100</procceed_amount>
      <procceed_currency>USD</procceed_currency>
      <user_payment_option_id>133567018</user_payment_option_id>
      <network_transaction_id>7110000000007208682</network_transaction_id>
    </nuvei>
  </gateway_specific_response_fields>
  <gateway_transaction_id>7110000000007208682</gateway_transaction_id>
  <sub_merchant_key nil="true"/>
  <gateway_latency_ms type="integer">1839</gateway_latency_ms>
  <warning nil="true"/>
  <application_id nil="true"/>
  <risk_data nil="true"/>
  <merchant_metadata nil="true"/>
  <customer_data nil="true"/>
  <order_data nil="true"/>
  <workflow_key nil="true"/>
  <amount type="integer">100</amount>
  <local_amount nil="true"/>
  <currency_code>USD</currency_code>
  <retain_on_success type="boolean">true</retain_on_success>
  <payment_method_added type="boolean">false</payment_method_added>
  <smart_routed type="boolean">false</smart_routed>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <stored_credential_alternate_gateway nil="true"/>
  <populate_mit_fields type="boolean">false</populate_mit_fields>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>6GA3HM28GD8T9SPDQ54981HZ1B</gateway_token>
  <gateway_type>nuvei</gateway_type>
  <shipping_address>
    <name>Cure Tester</name>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
  </shipping_address>
  <response>
    <success type="boolean">true</success>
    <message>APPROVED</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code>0</error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2024-11-27T20:17:35Z</created_at>
    <updated_at type="dateTime">2024-11-27T20:17:37Z</updated_at>
    <network_transaction_id>7110000000007208682</network_transaction_id>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>E5g6rB46gli2vupsXjyxQfaRbaz</token>
    <created_at type="dateTime">2024-11-26T19:47:14Z</created_at>
    <updated_at type="dateTime">2024-11-26T21:48:58Z</updated_at>
    <email>test@gmail.com</email>
    <data nil="true"/>
    <storage_state>retained</storage_state>
    <test type="boolean">false</test>
    <metadata nil="true"/>
    <callback_url nil="true"/>
    <last_four_digits>6034</last_four_digits>
    <first_six_digits>510108</first_six_digits>
    <card_type>master</card_type>
    <first_name>Cure</first_name>
    <last_name>Tester</last_name>
    <month type="integer">9</month>
    <year type="integer">2035</year>
    <address1>157 Simonis Loaf</address1>
    <address2>Apartment 4</address2>
    <city>Marilietown</city>
    <state>NJ</state>
    <zip>31331</zip>
    <country>USA</country>
    <phone_number>919.331.3313</phone_number>
    <company nil="true"/>
    <full_name>Cure Tester</full_name>
    <eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
    <shipping_address1 nil="true"/>
    <shipping_address2 nil="true"/>
    <shipping_city nil="true"/>
    <shipping_state nil="true"/>
    <shipping_zip nil="true"/>
    <shipping_country nil="true"/>
    <shipping_phone_number nil="true"/>
    <issuer_identification_number>51010810</issuer_identification_number>
    <click_to_pay type="boolean">false</click_to_pay>
    <managed type="boolean">true</managed>
    <payment_method_type>credit_card</payment_method_type>
    <stored_credential_usage>
      <scheme_issued>
        <original_network_transaction_id>7110000000007132934</original_network_transaction_id>
        <network_transaction_id>7110000000007208682</network_transaction_id>
      </scheme_issued>
      <nuvei>
        <original_network_transaction_id>7110000000007132934</original_network_transaction_id>
        <network_transaction_id>7110000000007208682</network_transaction_id>
      </nuvei>
    </stored_credential_usage>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-6034</number>
    <bin_metadata>
      <message>BIN Metadata is available only to Advanced Vault enrolled customers and payment methods. Reach out to your account representative for more details.</message>
    </bin_metadata>
    <fingerprint nil="true"/>
  </payment_method>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
```

To make a payout request with connection to a previous transaction, you have to send a normal refund request. To get more information see Spreedly Api reference [Partial Refund](https://docs.spreedly.com/reference/api/v1/#partial-amount81) and [full amount refund](https://docs.spreedly.com/reference/api/v1/#full-amount80)

Note: For all asynchronous transactions (ACH and Payouts), you must pass the `notification_url` as a Gateway Specific Field to receive webhook callbacks. Failure to pass this field will result in transactions completing without status notifications, requiring manual polling

### Payout with Google and Apple pay

Spreedly supports sending payout requests for Google and Apple pay, to get more details see [Nuvei Documentation](https://docs.nuvei.com/documentation/global-guides/google-pay/google-pay-integration/google-pay-integration-3ds/?highlight=google%20pay)

Required GSF's

| Spreedly field           | Nuvei field           |
| :----------------------- | :-------------------- |
| `user_payment_option_id` | `userPaymentOptionId` |
| `notification_url`       | `notificationUrl`     |

* `userPaymentOptionId` => user\_payment\_option\_id
* `notificationUrl` => notification\_url

### Gateway Specific Response Fields

A response from Nuvei may contain the following fields:

| GSRF                               | Description                                                                                        |
| :--------------------------------- | :------------------------------------------------------------------------------------------------- |
| `requested_amount`                 | The original amount requested in a partial approval transactions                                   |
| `requested_currency`               | The currency of the original requested in a partial approval transactions                          |
| `procceed_amount`                  | The amount that was actually deposited in the partial approval transaction.                        |
| `procceed_currency`                | The currency used in the processed transaction request.                                            |
| `user_payment_option_id`           | Payment identifier received from previous deposit                                                  |
| `network_transaction_id`           | Transaction identifier received from previous request                                              |
| `is_aft`                           | Indicates whether the transaction was processed as a Sale (False) or as an AFT transaction (True). |
| `is_aft_overriden`                 | Merchant can submit Sales and AFT transactions or Merchant can only submit AFT transactions        |
| `name_verification_request_result` | Name verification result in a Cardholder Name Verification                                         |
| `name_verification_result`         | Name verification result in a Cardholder Name Verification                                         |
| `first_name_verification_result`   | First Name verification result in a Cardholder Name Verification                                   |
| `middle_name_verification_result`  | Middle Name verification result in a Cardholder Name Verification                                  |
| `last_name_verification_result`    | Last Name verification result in a Cardholder Name Verification                                    |