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:

1. Create a payment token.
2. Using the newly created payment token, send a /payout request as described in Payouts Using an Existing Payment Token.

Add Payment Token

Registering a BuyerId

1. 1. Register a buyerId, if relevant.
   2. If you do not have a buyerId registered in the Nuvei system for the user, register a buyerId by sending a /buyers/{buyer-id} request with the mandatory parameters including email, countryCode, firstName, and lastName.
      The request registers the buyerId in the Nuvei system, which is then used to generate a payment token.

Creating a Payment Token

1. Send a request with the 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