• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
    • Choosing an Integration Method
  • Accept Payment
    • Payment Page
      • Quick Start
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Checkout
      • Quick Start
        • UI Customization
        • Payment Customization
        • Advanced Controls
        • Checkout Examples
      • Server-to-Server
      • Payment Scenarios
      • Mobile SDKs (Beta Release)
        • Android Mobile SDK (Beta Release)
        • iOS Mobile SDK (Beta Release)
      • Flow Diagrams
      • Plugins
        • Magento
          • Rebilling with Magento
        • WooCommerce
          • Rebilling with WooCommerce
        • PrestaShop
          • PrestaShop with Web SDK
          • PrestaShop with Checkout
        • OpenCart
        • Shopify (via AsiaBill)
        • Mirakl
        • Salesforce
        • SAP
        • WIX
      • Marketplaces
    • Features
      • Authentication
      • Financial Operations
        • Refund
        • Void
        • Auth and Settle
        • Partial Approval
        • Currency Conversion (DCC and MCP)
        • Payout
      • Card Operations
        • Card-on-File
        • PCI and Tokenization
        • Zero-Authorization
        • Merchant-Initiated Transactions (MIT)
        • Blocking Cards
      • Subscription (Rebilling)
      • 3D-Secure
        • 3D-Secure Explained
        • 3DS Implementations
          • 3DS MPI-Only Web SDK
          • 3DS MPI-Only REST
          • 3DS External MPI
          • 3DS Responses
        • 3DS Functions
          • 3D-Secure Fingerprinting
          • 3D-Secure Authentication Challenge
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
    • Guides
      • Testing Cards, APIs and APMs
        • Testing Cards
        • Testing APIs with Postman
        • Testing APMs
      • Response Handling
      • Alternative Payment Guides (APMs)
      • Airline Ticket Guides
        • Airline Addendum
        • External Authorization Addendum
      • Payment Facilitators (PayFac)
      • Cashier
        • Cashier Events Guide
        • Cashier Features
      • Withdrawal Guide
      • Risk Guide
        • Nuvei Services
        • Transaction Types
        • Credits and Payouts
        • Fraud to Sale Programs
        • Compliance Programs
        • Chargebacks
      • eKYC Guide
      • Server SDKs
        • Java SDK
        • .NET SDK
        • PHP SDK
        • Node.JS SDK
      • Fast Track Onboarding Developer Guide
      • Currency Conversion Guides
        • Multiple Currency Pricing (MCP)
        • Dynamic Currency Conversion (DCC)
          • DCC in Cashier or Payment Page
          • DCC in REST API Workflows
          • DCC in Web SDK Workflows
      • Website Compliance Guides
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    Payout

    On this page:
    • Overview
    • Payouts for Credit Cards
      • For Cards Using UPO
      • Using cardData
    • Payouts for APM Accounts
      • For APMs Using UPO
      • APMs Without Initial UPO
        • Add UPO /addUPOAPM
        • Add UPO /accountCapture

    Overview

    A payout allows you to transfer funds from your account to the user’s (customer) account, for example to payout winnings or refunds.

    Payouts are often used by merchants dealing with gaming or Forex, where users sometimes withdraw more funds from their account than they deposit.

    Follow the steps to implement the relevant payout integrations:

    • Payouts for Credit Cards
    • Payouts for APM Accounts
    Prerequisites and Notes

    Contact Nuvei Support to configure your merchant account to use the payout flow.

    Supported Products

    These Nuvei platforms support payouts:

    ProductPayout Support
    CashierYES
    RESTYES
    webSDKNO
    checkoutNO

    Payouts for Credit Cards

    You can perform a payout for credit cards using these flows:

    • Payout for Card Using UPO
      Perform a payout for an existing user using a UPO (which contains the user’s previously stored card details).
    • Payout Using cardData
      (This flow is only relevant for PCI certified merchants.)
      You can use this flow for new users or for existing users to register a new credit card account.

    For Cards Using UPO

    You can perform a payout using a previously captured UPO.
    For example where the UPO was returned from a previous /payment (deposit) or /payout request.

    Send a /payout request (click the link for the mandatory parameters) and include:

    • userTokenId
    • A previously generated userPaymentOptionId.
    • APM provider specific input fields: See the specific APM provider in the APM Payouts Input Fields table.
    • (Optional) If you include a urlDetails.notificationUrl, then Nuvei will also return a DMN containing detailed request and transaction results.
    Example /payout Request with UPO
    {
      "merchantId": "<your merchantId>",
      "merchantSiteId": "<your merchantSiteId>",
      "userTokenId": "<unique user identifier in merchant system>",
      "clientUniqueId": "<unique transaction ID in merchant system>",
      "clientRequestId": "<unique request ID in merchant system>",
      "amount": "200",
      "currency": "USD",
      "userPaymentOption": {
        "userPaymentOptionId": "<UPO received from a previous request>"
      },  
      "deviceDetails": {
        "ipAddress": "127.0.0.1"
      },
      "timeStamp": "<YYYYMMDDHHmmss>",
      "checksum": "<calculated checksum>"
    }

    Using cardData

    This flow is only applicable to merchants who are PCI certified and can send clear text card details in their requests.

    You can use this flow for new users or for existing users to register a new credit card account.

    Send a /payout request (click the link for the mandatory parameters) and include:

    • userTokenId
    • A cardData block containing the card details, as shown below.
    • APM provider specific input fields: See the specific APM provider in the APM Payouts Input Fields table.
    • (Optional) If you include a urlDetails.notificationUrl, then Nuvei will also return a DMN containing detailed request and transaction results.
    Example /payout Request with the cardData Block
    {
      "merchantId": "<your merchantId>",
      "merchantSiteId": "<your merchantSiteId>",
      "userTokenId": "<unique user identifier in merchant system>",
      "clientUniqueId": "<unique transaction ID in merchant system>",
      "clientRequestId": "<unique request ID in merchant system>",
      "amount": "200",
      "currency": "USD",
      "userPaymentOption": {
        "cardData":{
          "cardNumber": "4000027891380961",
          "cardHolderName": "CL-BRW1",
          "expirationMonth": "12",
          "expirationYear": "2025"
        }
      },  
      "deviceDetails": {
        "ipAddress": "127.0.0.1"
      },
      "timeStamp": "<YYYYMMDDHHmmss>",
      "checksum": "<calculated checksum>"
    }

    Payouts for APM Accounts

    You can perform a payout to a user’s (customer) APM account using these flows:

    • For APMs Using UPO
      Perform a payout for an existing user using a UPO (which contains the user’s previously stored APM account details).
    • APMs Without UPO
      If you do not have a UPO for the user’s APM account, then first create a UPO manually using one of these two options:

    For APMs Using UPO

    Perform a payout for an existing user using a UPO (which contains the user’s previously stored APM account details).

    Send a /payout request (click the link for the mandatory parameters) and include:

    • userTokenId
    • userPaymentOption.userPaymentOptionId
    • APM provider specific input fields: See the specific APM provider in the APM Payouts Input Fields table.
    • (Optional) If you include a urlDetails.notificationUrl, then Nuvei will also return a DMN containing detailed request and transaction results.
    Example /payout Request for APM Using UPO
    {
      "merchantId":"<your merchantId>",
      "merchantSiteId":"<your merchantSiteId>",
      "clientUniqueId":"<unique transaction ID in merchant system>",
      "userTokenId":"<unique user identifier in merchant system>",
      "amount":"100",
      "currency":"BRL",
      "userPaymentOption":{
        "userPaymentOptionId":"<Generated UPO from a previous request>"
      },
      "deviceDetails":{
        "ipAddress":"127.0.0.1" 
      },
      "timeStamp":"<YYYYMMDDHHmmss>",
      "checksum":"<calculated checksum>"
    }

    The request is processed and returns the transactionStatus: "APPROVED" or "DECLINED".

    Example /payout Response
    {
      "reason": "",
      "transactionStatus": "APPROVED",
      "clientRequestId": "W1Q3SBGE4",
      "internalRequestId": 17817071,
      "version": "1.0",
      "transactionId": "2110000000004333013",
      "merchantSiteId": "126006",
      "merchantId": "2502136204546424962",
      "clientUniqueId": "695701003",
      "errCode": 0,
      "userPaymentOptionId": "8119601",
      "paymentMethodErrorCode": "0",
      "userTokenId": "CEBQK9OVSLJA",
      "externalTransactionId": "2110000000068709",
      "status": "SUCCESS"
    }

    APMs Without Initial UPO

    A UPO contains a user’s APM account details, and is normally generated and returned after a /payment (deposit) request.

    Payout (/payout) requests for APM accounts can only be performed using a UPO.

    If you do not have a UPO for the user’s APM account, then follow these steps:

    1. Create a UPO manually using one of these two options:
      • Add UPO Using /addUPOAPM
        This method is used for most APM providers.
      • Add UPO Using /accountCapture
        This method is only used for some APM providers (see the list in the Account Details Capture topic).
    2.  Use the newly created UPO as described in the Payout for APM Using UPO topic.

    Add UPO /addUPOAPM

    This method is used for most APM providers.
    Create a new UPO for your user by using the /addUPOAPM method as follows:

    1. Register a userTokenId

    A userTokenId is a field in the Nuvei system containing the user’s identifier that you use in your (merchant) system.

    If you do not have a userTokenId registered in the Nuvei system for this user, then register one as follows.
    Send a /createUser request (click the link for the mandatory parameters) and include an email address.

    Example /createUser Request
    {
      "merchantId": "<your merchantId>",
      "merchantSiteId": "<your merchantSiteId>",
      "clientRequestId": "<unique request ID in merchant system>",
      "userTokenId": "<unique user identifier in merchant system>",
      "email":"john.smith@email.com",
      "countryCode":"US",
      "firstName":"John",
      "lastName":"Smith",
      "timeStamp": "<YYYYMMDDHHmmss>",
      "checksum": "<calculated checksum>"
    }

    The request returns a userTokenId, which is needed to generate a UPO in the next step.

    2. Create the UPO

    Create a UPO by sending an /addUPOAPM request (click the link for the mandatory parameters) and include:

    • "userTokenId" – The unique user identifier in your system.
    • "paymentMethodName":"apmgw_<APM provider name>"
    • APM provider specific input fields: See the specific APM provider in the APM Payouts Input Fields table.
    Example /addUPOAPM Request

    For example, these are the parameters required to create a UPO for a PIX_payouts APM account:

    • "paymentMethodName":"apmgw_PIX_payouts"
    • "apmData"."pix_accountNum":"<user's PIX Payout account number>"
    {
      "merchantId":"<your merchantId>",
      "merchantSiteId":"<your merchantSiteId>",
      "clientRequestId":"<unique request ID in merchant system>",
      "userTokenId":"<unique user identifier in merchant system>",
      "paymentMethodName":"apmgw_PIX_payouts",
      "apmData":{
        "pix_accountNum":"37625536000102"
      },
      "timeStamp":"<YYYYMMDDHHmmss>",
      "checksum":"<calculated checksum>"
    }

    The request should return an encrypted userPaymentOptionId (UPO) representing the user’s APM account details.

    Example /addUPOAPM Response
    {
      "reason":"",
      "merchantId":"2502136204546424962",
      "errCode":0,
      "clientRequestId":"HWMTWQ2RT",
      "userPaymentOptionId":8119601,
      "internalRequestId":17817221,
      "version":"1.0",
      "status":"SUCCESS",
      "merchantSiteId":"126006"
    }

    Add UPO /accountCapture

    Some APM providers have rigorous validations for the input fields required to authenticate user account details. To streamline your user experience, Nuvei provides an APM account details capture method (the /accountCapture method) to help you collect and validate the input fields for those APM providers.

    See the Account Details Capture topic for a list of the supported APMs providers, and how to use the /accountCapture method.

    2022 Nuvei. All rights reserved.