Overview

A payout (withdrawal) transfers funds from the merchant’s account to a user’s (customer’s) account, without any connection to a previous transaction; for example, to pay out winnings. Gaming and Forex merchants often use payouts because their users sometimes withdraw more funds than they deposit.

Using the REST API 2.0 integration method, merchants can perform payouts with or without an existing payment token, as described in the following sections:

Payouts Using an Existing Payment Token
Card Payouts Without an Existing Payment Token
APM Payouts Without an Existing Payment Token

Payouts Using an Existing Payment Token

To perform a payout using a payment token generated by a previous /payment or /payout request, send a /payout request with its mandatory parameters including:

• buyerDetails.buyerId
• Previously generated paymentTokenId.
• For APM payouts, buyerDetails class containing APM-specific mandatory user details.

Example /payout Request with Payment Token

{
  "processingEntityId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 60,
  "currency": "EUR",
  "paymentOption": {
    "paymentToken": {
      "paymentTokenId": "abc123def456ghi789jkl012mno345pq"
    }
  },
  "buyerDetails": {
    "buyerId": "buyerId123",
    "firstName": "John",
    "lastName": "JSmith",
    "companyName": "Nuvei Corp",
    "locale": "bg-BG",
    "dateOfBirth": "1978-01-01",
    "email": "[email protected]",
    "phone": "+1234567889",
    "billingAddress": {
      "state": "TX",
      "city": "Austin",
      "zip": "78652",
      "countryCode": "US"
    },
    "shippingAddress": {
      "sameAsBilling": true
    }
  }
}

Example /payout Response with Payment Token

{
  "payoutId": "2da02e63315b48d3b0877847b62d1598",
  "transactionId": "8110000000009216430",
  "amount": 60,
  "currency": "EUR",
  "authCode": "111061",
  "paymentOption": {
    "card": {
      "cardHolderName": "John JSmith",
      "maskedCardNumber": "4****6892",
      "bin": "444449",
      "last4Digits": "6892",
      "expirationMonth": "12",
      "expirationYear": "25",
      "acquirerId": "19",
      "cardType": "Credit",
      "cardBrand": "VISA",
      "paymentTokenId": "abc123def456ghi789jkl012mno345pq"
    }
  },
  "result": {
    "status": "approved"
  }
}

After the transaction is processed, Nuvei sends a webhook that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

Card Payouts Without an Existing Payment Token

PCI-certified merchants can use this flow to perform a payout for a new user or for an existing user registering new card details.

Send a /payout request with its mandatory parameters including:

• buyerDetails.buyerId
• paymentOption.card class containing card details.
  
  Gaming and Gambling merchants who wish to process a card payout transaction must provide paymentOption.card.cardHolderName in the /payout request. Without this parameter, the payout might be rejected by the card schemes.

Example /payout Request

 {
  "processingEntityId": "processingEntityId",
  "amount": 60,
  "currency": "EUR",
  "isMoto" : true,
  "paymentOption": {
    "card": {
      "cardHolderName": "John Doe",
      "cardNumber": "4444493318246892",
      "expirationMonth": "12",
      "expirationYear": "2025",
      "cvv": "090"
    },
    "store":"buyerToken"
  },
    "buyerDetails": {
        "buyerId": "test1233ssw2",
        "firstName": "John",
        "lastName": "JSmith",
        "companyName": "Nuvei Corp",
        "locale": "bg-BG",
        "dateOfBirth": "1978-01-01",
        "email": "[email protected]",
        "phone": "+1234567889",
        "billingAddress": {
            "state": "TX",
            "city": "Austin",
            "zip": "78652",
            "countryCode": "US"
        },
        "shippingAddress": {
            "sameAsBilling": true
        }
    }
}

The response returns an encrypted paymentTokenId representing the user’s card that can be used in future transactions.

Example /payout Response

{
    "payoutId": "7984ea7762434697b4c24b8438492b6a",
    "transactionId": "8110000000009216106",
    "amount": 60,
    "currency": "EUR",
    "authCode": "111673",
    "paymentOption": {
        "card": {
            "cardHolderName": "John Doe",
            "maskedCardNumber": "4****6892",
            "bin": "444449",
            "last4Digits": "6892",
            "expirationMonth": "12",
            "expirationYear": "25",
            "acquirerId": "19",
            "cardType": "Credit",
            "cardBrand": "VISA",
            "paymentTokenId": "3433b21598b844a9a4380c8c34ad7dcb"
        }
    },
    "result": {
        "status": "approved"
    }
}

After the transaction is processed, Nuvei sends a webhook (see Webhooks) that includes the result of the transaction to the URL provided in urlDetails.webhookUrl, which Nuvei recommends including in the /payout request.

APM Payouts Without an Existing Payment Token

APM /payout requests can be performed with an APM or a paymentTokenId. If a paymentTokenId from a previously generated request is not available, create a payment token using the following method:

• Create a payment token (See Payment Tokens). Then, using the newly created payment token, send a /payout request as described in Payouts Using an Existing Payment Token.

Add Payment Token

Create a payment token, as described in Creating a Payment Token for an APM.

If relevant, it is preferable that a merchant uses the buyerId generated from a payment transaction that was previously performed. If so, the merchant should proceed to do a payout as follows:

1. Register a buyerId (if necessary)

A buyerId is a parameter in the Nuvei system containing the user’s identifier in the merchant system.

If you do not have a buyerId registered in the Nuvei system for this user, then register one by sending a /buyers/{buyer-id} request with its mandatory parameters including email, countryCode, firstName, and lastName.

For more details, see Buyer Management.

The request registers the buyerId in the Nuvei system, which is then used to generate a payment token.

2. Create the Payment Token

Create a payment token by sending a request with its mandatory parameters including:

• buyerId – The unique user identifier in your system.
• alternativePaymentMethod.name – “<APM name>“
• alternativePaymentMethod.data

Example /POST /payment-tokens Request

For example, the following parameters are required to create a payment token for the ACH APM:

• name: “ach“
• data class containing:
  • accountNumber
  • routingNumber
  Code samples are available in Creating a Payment Token for an APM.