VIP Preferred (REST)

Home    APMs    VIP Preferred    VIP Preferred (REST)

On this page:

Introduction

GlobalPay (Pavilion Payments) provides the VIP Preferred APM, a payment processing solution that allows businesses to accept a wide range of electronic payments, including credit and debit cards, E-wallets, and bank transfers.

Purpose

This guide provides steps to integrate the VIP Preferred APM into your payment flows using the Nuvei REST API integration method.

Prerequisites and Notes

  • This document assumes that you have completed all account setup prerequisites, and are ready to integrate VIP Preferred into your payment flow.
  • The VIP Preferred payment method is supported only for US based customers, and all amounts sent/received are stated in US Dollars (USD).
  • Test credentials and testing procedures should be obtained directly from the APM providers.

Flows – REST API

The following sections describe “suggested” flows between you and VIP Preferred via the Nuvei REST API.
You are free to adapt these flows in any way.

REST FlowsDescriptionMain Method Used
Account InquiryCheck if the customer has an account with the specified APM provider: paymentOption.alternativePaymentMethod.paymentMethod, and retrieve account details, account balance, account limits, enrolled (registered) bank accounts, etc./getAccountDetails
EnrollEnroll (register/create) an account for the customer with the specified APM provider./enrollAccount
Add Bank AccountAdd a bank account to the customer’s VIP Preferred account./addBankAccount
Payment / Payout FlowPerform financial transactions for the customer with the APM provider.
For details, see the Financial Transactions topic.
  • /payment
  • /payout
  • /refundTransaction

VIP Preferred APM payment flows interact directly with the APM provider by bypassing Nuvei’s Digital Payments APM Gateway, which differs from Nuvei’s traditional APM flows.

REST Redirect Flows

Account Inquiry Flow

StepDescription
1Get the customer’s VIP Preferred account details:
Call /getAccountDetails to check if the customer already has a VIP Preferred account.
  • If the response returns ERROR, then the customer does not have an account yet – PROCEED to (2A).
  • If the response returns SUCCESS, and the customer’s account details, then they already have a VIP Preferred account – PROCEED to (2B).

VIP Preferred allows you to access customer accounts created by other merchants.
2BDisplay the VIP Preferred account details and balance, and the customer’s bank account/s enrolled (registered) in their VIP Preferred account. (END OF FLOW)

Enroll Flow

StepDescription
2AEnroll the customer: Call /enrollAccount and include the customer’s bank account details etc. to open a VIP Preferred account for the customer.
  • If the response returns SUCCESS, then the customer has successfully created a new VIP Preferred Account – PROCEED to (3A).
  • If the response returns ERROR, then try to resolve it in some way. (END OF FLOW)
3AGet the customer’s VIP Preferred account details:
Call /getAccountDetails to show the customer’s newly created VIP Preferred account.
  • If the response returns SUCCESS and the customer’s account details – PROCEED to (4A).
  • If the response returns ERROR, then something is wrong with the customer’s VIP Preferred account. (END OF FLOW)
4ADisplay the VIP Preferred account details and balance, and the customer’s bank account/s enrolled (registered) in their VIP Preferred account. (END OF FLOW)

Add Bank Account Flow

StepDescription
5Add Bank Account to the customer’s VIP Preferred account by calling the /addBankAccount request.
  • If the response returns SUCCESS, then the customer’s bank account was successfully added to their VIP Preferred Account – PROCEED (6).
  • If the response returns ERROR, then try to resolve it in some way – PROCEED to (6).
6Get the customer’s VIP Preferred account details:
Call getAccountDetails to show the customer’s VIP Preferred account.
  • If the response returns SUCCESS and the customer’s account details – PROCEED to (7).
  • If the response returns ERROR, then try to resolve it in some way. (END OF FLOW)
7Display the VIP Preferred account details and balance, and the customer’s bank account(s) enrolled (registered) in their VIP Preferred account. (END OF FLOW)

Payment / Payout Flow

StepDescription
8Perform a Financial Transaction (/payment, /refund, /payout) by calling the relevant request (/payment or /refund or /payout).
For details see the REST Financial Transactions section below.

Methods – REST API

The payment flow of the VIP Preferred APM differs from Nuvei’s traditional APM flow by bypassing Nuvei’s Digital Payments APM Gateway, and interacts directly with the APM providers.

Nuvei supports the following VIP Preferred specific API methods:

REST MethodDescriptionREST Flows
/getAccountDetailsCheck if the customer has an account with the specified APM provider: paymentOption.alternativePaymentMethod.paymentMethod, and retrieve account details, account balance, account limits, enrolled (registered) bank accounts, etc.Account Inquiry
/enrollAccountEnroll (register/create) an account for the customer with the specified APM provider.Enroll
/addBankAccountAdd a bank account to the customer’s VIP Preferred account.Add Bank Account

/getAccountDetails

This method is called in the following steps of the REST flow:  1, 3A, 6.

This method queries the VIP Preferred server for details of the customer’s bank accounts and available balance registered in their VIP Preferred accounts.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Call the /getAccountDetails request using the sessionToken, the userId from your internal systems, and all the other relevant parameters.
3Successful response returns:
  • Account details and card balance etc.
  • status: "SUCCESS"
4Failed response returns:
  • Failed validation of the paymentMethod (if not apmgw_VIP_Preferred):
    status: "ERROR"
    reason: "Unsupported payment method"
    errCode: "1076"

  • Failed attempt to retrieve account details and card balance (no response from VIP Preferred):
    status: "ERROR"
    reason: "Communication error"
    errCode: "1038"

  • For any other errors (e.g., Failed validation of the Merchant credentials or sessionToken.):
    status: "ERROR"
    reason: "Balance retrieval error"
    errCode: "9091"
Example /getAccountDetails Request

paymentMethod under paymentOption.alternativePaymentMethod must be apmgw_VIP_Preferred.

{
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userId":"6303323",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_VIP_Preferred"
        }
    },
    "deviceDetails":{
        "deviceType":"TABLET",
        "deviceName":"iPad",
        "deviceOS":"iOS U",
        "browser":"safari U",
        "ipAddress":"<customer's IP address>"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "phone":"6175556309",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"[email protected]",
        "county":"Suffolk",
        "language":"en",
        "dateOfBirth":"2000-06-30",
        "identification":"987456982"
    }
}
Example /getAccountDetails SUCCESS Response
  • accountBalance – The available amount in USD in user’s VIP Preferred wallet.
  • accountLimit – The customer’s account limit as set in VIP Preferred.
{
    "reason":"",
    "clientRequestId":"I46ZEZ5KY",
    "bankAccounts":[
        {
            "routingNumber":"103112976",
            "bankName":"Arvest Bank",
            "accountNumber":"2452110170"
        }
    ],
    "internalRequestId":"17482661",
    "accountNumber":"7210521300",
    "userId":"6303323",
    "version":"1.0",
    "merchantSiteId":"126006",
    "accountLimit":"4500.00",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "sessionToken":"3478ab94-1865-4598-88e6-866779a913d7",
    "currency":"USD",
    "accountBalance":"4500.00",
    "status":"SUCCESS"
}
Example /getAccountDetails ERROR Response
  • paymentMethodErrorCode – The RSPCODE as returned by VIP Preferred.
  • paymentMethodErrorReason – The ERRMSG as returned by VIP Preferred.
{
    "reason":"Balance retrieval error",
    "clientRequestId":"KYO0XPMN5",
    "internalRequestId":"17482711",
    "userId":"6303323",
    "version":"1.0",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":"9091",
    "paymentMethodErrorCode":"91",
    "paymentMethodErrorReason":"Format error in IDNBR field.",
    "sessionToken":"8dc629aa-dfbb-40c2-8ac4-00391b147ba8",
    "status":"ERROR"
}

/enrollAccount

This method is called in the following step of the REST flows:  2A.

This method allows you to send the customer’s a bank account details to enroll them into a new VIP Preferred account.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Call the /enrollAccount request using the sessionToken, the userId from your internal systems, and all the other relevant parameters.
3Successful response returns:
  • The customer is enrolled to with a VIP Preferred Account.

  • status: "SUCCESS"
4Failed response returns:
  • Failed validation of the paymentMethod (if not apmgw_VIP_Preferred):
    status: "ERROR"
    reason: "Unsupported payment method"
    errCode: "1076"

  • Failed attempt to retrieve account details and card balance (no response from VIP Preferred):
    status: "ERROR"
    reason: "Communication error"
    errCode: "1038"

  • Failed attempt to enroll the customer (account already registered):
    status: "ERROR"
    reason: " Account already registered"
    errCode: "9094"

  • For any other errors (e.g., Failed validation of the Merchant credentials or sessionToken.):
    status: "ERROR"
    reason: "User account operation failed"
    errCode: "9092"
Example /enrollAccount Request

paymentMethod under paymentOption.alternativePaymentMethod must be apmgw_VIP_Preferred.

{
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userId":"259",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_VIP_Preferred"
        }
    },
    "deviceDetails":{
        "deviceType":"TABLET",
        "deviceName":"iPad",
        "deviceOS":"iOS U",
        "browser":"safari U",
        "ipAddress":"<customer's IP address>"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "phone":"6175556309",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"[email protected]",
        "county":"Suffolk",
        "language":"en",
        "dateOfBirth":"2000-06-30",
        "identification":"987456982"
    },
    "bankAccount":{
        "bankName":"",
        "accountNumber":"234598345869",
        "routingNumber":"348794869"
    },
    "documentDetails":{
        "documentNumber":"12345678",
        "type":"DL",
        "validTo":"0626",
        "issuingState":"MA"
    },
    "urlDetails":{
        "notificationUrl":"<URL to which DMNs are sent>"
    }
}
Example /enrollAccount SUCCESS Response
  • accountNumber – The ID of the Account in VIP Preferred; CARDNO as returned by VIP Preferred.
  • accountBalance – The available amount in USD in User’s VIP Preferred account; AVAIL as returned by VIP Preferred.
  • accountLimit – The customer’s account limit as set in VIP Preferred; LIMIT as returned by VIP Preferred.
{
    "reason":"",
    "clientRequestId":"I46ZEZ5KY",
    "internalRequestId":"17482661",
    "accountNumber":"7210521300",
    "userId":"6303323",
    "version":"1.0",
    "merchantSiteId":"126006",
    "accountLimit":"4500.00",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "sessionToken":"3478ab94-1865-4598-88e6-866779a913d7",
    "currency":"USD",
    "accountBalance":"4500.00",
    "status":"SUCCESS"
}
Example /enrollAccount ERROR Response
  • paymentMethodErrorCode – The RSPCODE as returned by VIP Preferred.
  • paymentMethodErrorReason – The ERRMSG as returned by VIP Preferred.
{
    "reason":"User account operation failed",
    "clientRequestId":"KYO0XPMN5",
    "internalRequestId":"17482711",
    "userId":"6303323",
    "version":"1.0",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":"9092",
    "paymentMethodErrorCode":"91",
    "paymentMethodErrorReason":"Format error in IDNBR field.",
    "sessionToken":"8dc629aa-dfbb-40c2-8ac4-00391b147ba8",
    "status":"ERROR"
}

/addBankAccount

This method is called in the following step of the REST flows:  5.

This method allows you to add a bank account to a VIP Preferred account on behalf of the customer.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Call the /addBankAccount request using the sessionToken, the userId from your internal systems, and all the other relevant parameters.
3Successful response returns:
  • The bank account is added to the VIP Preferred Account.
  • "status": "SUCCESS"
4Failed response returns:
  • Failed validation of the paymentMethod (if not apmgw_VIP_Preferred):
    status: "ERROR"
    reason: "Unsupported payment method"
    errCode: "1076"

  • Failed attempt to retrieve account details and card balance (no response from VIP Preferred):
    status: "ERROR"
    reason: "Communication error"
    errCode: "1038"

  • Failed attempt to add bank account:
    status: "ERROR"
    reason: "Add Bank Account failed"
    errCode: "9095"

  • For any other errors (e.g., Failed validation of the Merchant credentials or sessionToken.):
    status: "ERROR"
    reason: "Account not found"
    errCode: "9093"
Example /addBankAccount Request

paymentMethod under paymentOption.alternativePaymentMethod must be apmgw_VIP_Preferred.

{
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userId":"6303323",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_VIP_Preferred"
        }
    },
    "bankAccount":{
        "bankName":"American Bank",
        "accountNumber":"9920035637",
        "routingNumber":"103112976"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "phone":"6175556309",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"[email protected]",
        "county":"Suffolk",
        "language":"en",
        "dateOfBirth":"2000-06-30",
        "identification":"987456982"
    },
    "deviceDetails":{
        "deviceType":"DESKTOP",
        "deviceName":"iPhone 5s",
        "deviceOS":"iOS 10.2",
        "browser":"safari",
        "ipAddress":"<customer's IP address>"
    }
}
Example /addBankAccount SUCCESS Response
{
    "bankAccount":{
        "routingNumber":"103112976",
        "bankName":"ARVEST BANK",
        "accountNumber":"9920035637"
    },
    "reason":"",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "clientRequestId":"TXZZXKX5U",
    "sessionToken":"4bbaa973-ab1a-47b8-ad79-92c42beba19d",
    "internalRequestId":"17483621",
    "userId":"6303323",
    "version":"1.0",
    "status":"SUCCESS",
    "merchantSiteId":"126006"
}
Example /addBankAccount ERROR Response #1
{
    "reason":"Account not found",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":"9093",
    "clientRequestId":"JJXD6REHF",
    "sessionToken":"f339c30e-61f3-4293-a77f-115fd27d92aa",
    "internalRequestId":"17483651",
    "userId":"6303323",
    "version":"1.0",
    "status":"ERROR",
    "merchantSiteId":"126006"
}
Example /addBankAccount ERROR Response #2
  • paymentMethodErrorCode – The RSPCODE as returned by VIP Preferred.
  • paymentMethodErrorReason – The ERRMSG as returned by VIP Preferred.
{
    "reason":"Add Bank Account failed",
    "clientRequestId":"9BLOA9URS",
    "internalRequestId":"17483671",
    "userId":"6303323",
    "version":"1.0",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":"9095",
    "paymentMethodErrorCode":"91",
    "paymentMethodErrorReason":"Format error in CHKRTG field.",
    "sessionToken":"892bf0fd-e6cf-440c-8c3e-b624b6d8afef",
    "status":"ERROR"
}

REST Financial Transactions

This topic provides details for (VIP Preferred: step 8).

You can use Nuvei’s API methods to perform financial transactions with the GlobalPay (Pavilion Payments) provider for the VIP Preferred APM, which include the methods below:

  • Sending /payment (deposit transaction) Requests

‎For /payment with VIP Preferred requests, you can send a REST API /payment request by supplying either:

    • The customer’s actual bank account details (not a UPO), of a bank account which is already enrolled (registered) it the customer’s VIP Preferred account.
      See the Payment with VIP Preferred (without sending a UPO) topic.
    • Sending an existing UPO payment method, which specifies one of the customer’s bank accounts enrolled (registered) with VIP Preferred (and allow the customer to select one of the other enrolled (registered) bank accounts, if they wish).
      See the Payment with VIP Preferred (sending a UPO) topic.
  • Sending /payout (withdrawal transaction) Requests

For /payout with VIP Preferred requests, see the Payout with VIP Preferred topic.

  • Sending /refundTransaction Requests

For /refund with VIP Preferred requests, refer to the Refund topic in the Developer Portal, and use the <transactionId returned from the /payment request> as the relatedTransactionId.

Payment without UPO – REST

You can send REST API /payment requests, and include the additional VIP Preferred parameters, as described in the steps below.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request.
2Use /getAccountDetails to retrieve details of the customer’s bank accounts enrolled (registered) in their VIP Preferred account.
3Display these bank accounts to the customer, for them to select a bank account.
4Call the /payment request using the sessionToken, the userTokenId, and the additional VIP Preferred parameters to include, (which should include the bank account that the customer selected) shown below.

  • If the API /payment request is "APPROVED", and there is no pre-existing UPO (userPaymentOptionId) associated with the customer’s VIP Preferred account and that bank account, then a new UPO record is created using the account details supplied in the /payment request.

  • If the API /payment request is "APPROVED", and there is a pre-existing UPO associated with the customer’s VIP Preferred account and a different bank account, then that UPO record is updated with the bank account details provided in the successful /payment request.

  • If the transaction was not approved, and there is a pre-existing UPO associated with the customer’s VIP Preferred account, then that UPO record is not updated with the account details supplied in the /payment request. The account details in the UPO record remain as they were before sending the API /payment request.

  • If there is no userTokenId registered for this customer, then send a /createUser request, to register one.
    For further assistance, contact a member of Nuvei’s technical team.
5After processing the transaction, if urlDetails.notificationUrl was provided in the request, then Nuvei returns a DMN that includes the result of the transaction.
See an example DMN Response below.

Additional Parameters to Include

Include the following additional parameters in the paymentOption.alternativePaymentMethod class, as shown below:

ParameterMandatoryNotes
paymentMethodY"apmgw_VIP_Preferred"
globalpay_accountIdY""
globalpay_bankAccountYThe customer bank account used here must already be enrolled (registered) in the customer’s VIP Preferred account. (There can be up to four customer bank accounts enrolled (registered).)

Should contain both the "" and "" separated by "-"
globalpay_firstNameY""
globalpay_lastNameY""
globalpay_phoneY""
userTokenIdConditional(Mandatory – Can use either userTokenId or userId but not both.)

Use userTokenId if you use a UPO. Should contain the same value used for account creation.
userIdConditional(Mandatory – Can use either userTokenId or userId but not both.)

The ID of the customer in the Merchant system.

Use userId if you do not use a UPO.

Should contain the same value used for account creation.
Example /payment Request (without UPO)
{
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "userTokenId":"<unique customer identifier in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "currency":"USD",
    "amount":"10",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_VIP_Preferred",
            "globalpay_accountId":"7210521300",
            "globalpay_bankAccount":"9920035637-103112976",
            "globalpay_firstName":"Ruthe",
            "globalpay_lastName":"Croft",
            "globalpay_phone":"3126122528"
        }
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "cell":"6175553333",
        "phone":"6175551414",
        "zip":"02460",
        "city":" Boston",
        "country":"US",
        "state":"MA",
        "email":"[email protected]",
        "county":"Suffolk"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"[email protected]",
        "phone":"6175551414",
        "cell":"6175553333",
        "dateOfBirth":"2000-06-30",
        "address":"22 Main Street",
        "city":"Boston",
        "zip":"02460",
        "county":"Suffolk",
        "state":"MA",
        "country":"US",
        "language":"en"
    },
    "urlDetails":{
        "notificationUrl":"<URL to which DMNs are sent>"
    },
    "customSiteName":"<CustomSiteName>",
    "productId":"<productId>",
    "customData":"<customData>",
    "webMasterId":"<webMasterId>",
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
Example /payment Response (without UPO)
{
    "reason":"",
    "orderId":"36234271",
    "transactionStatus":"APPROVED",
    "clientRequestId":"D3QXJ5WSY",
    "internalRequestId":17661361,
    "merchantDetails":{
        "customField1":"customField1-value",
        "customField2":"customField2-value"
    },
    "version":"1.0",
    "transactionId":"2110000000004199299",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"1IPI7UOKBO8I",
    "errCode":0,
    "paymentOption":{
        "userPaymentOptionId":"8053541",
        "card":{
            
        }
    },
    "sessionToken":"f6c58916-7861-449e-9f4b-bdfd5f63178c",
    "userTokenId":"0Q985E8VVFS5",
    "status":"SUCCESS"
}
Example /payment DMN Response (without UPO)
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=36234271&userid=0Q985E8VVFS5&merchant_unique_id=1IPI7UOKBO8I&customData=Custom+Data+Inserted%21&productId=&first_name=john&last_name=Vxbfcfwoii&email=fihay.ymfgd%40fwfla.mq&currency=USD&clientUniqueId=1IPI7UOKBO8I&customField1=customField1-value&customField2=customField2-value&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=22+Automation+Str.+Updated.&address2=&country=United+States&state=&city=Boston+Updated&zip=CH+233242U&phone1=3459873345&phone2=&phone3=&client_ip=192.168.2.38&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=****3323&AvsCode=&Cvv2Reply=&shippingCountry=US&shippingState=&shippingCity=Shipping+City+Updated&shippingAddress=33+Shipping+Str.+Updated.&shippingZip=SDC+33334U&shippingFirstName=john&shippingLastName=Uvnoirngbg&shippingPhone=359888576900&shippingCell=359887576903&shippingMail=gmwch.bphmv%40ducdb.qz&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=126006&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_VIP_Preferred&ID=&merchant_id=2502136204546424962&responseTimeStamp=2021-07-28.11%3A36%3A12&buyButtonProductId=&webMasterId=8U9W5ZSIAA1J&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=0Q985E8VVFS5&userPaymentOptionId=8053541&TransactionID=2110000000004199299&ExternalaccountID=****1300&externalTransactionId=2110000000065430&APMReferenceID=C6CBDF5E19C29D8279F37E1AD4FE50A5&orderTransactionId=18075051&totalAmount=10.00&dynamicDescriptor=MerchantNameDescriptor123456789101112131415&item_name_1=Item+1U&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20210728&shippingCounty=SCountyU&type=DEPOSIT&clientRequestId=D3QXJ5WSY&relatedTransactionId=&responsechecksum=1ce64c2a9e2ec264a855c127376b7920&advanceResponseChecksum=059c99bfa51eb73dcb11af73f516df2a',

Payment with UPO – REST

This section describes sending a payment API request using an existing UPO payment method, and allowing the customer to select a different bank account.

The VIP Preferred account can have up to four customer bank accounts enrolled (registered) in it. A UPO (user payment option) payment method token can only contain one customer bank account.

When you use a Nuvei UPO (user payment option) to specify the payment method in payment API request, you need to allow the customer to choose which one of their customer bank accounts (enrolled (registered) in their VIP Preferred account) to use in the request.

Therefore, if the customer wishes to change their default customer bank account number specified in the UPO, you need to provide them with a way to do that.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request to retrieve a new sessionToken.
See an example /getSessionToken below.
2Use /getAccountDetails to retrieve details of the customer’s bank accounts enrolled (registered) in their VIP Preferred account.
See an example /getAccountDetails below.
3Display these bank accounts to the customer, for them to select a new default bank account.
4If the customer selected a bank account that is not the current default (as specified in the UPO record), then send an /editUPOAPM request to replace the bank account in the Nuvei UPO, (to be used in the next step – sending the payment API request).

See an example /editUPOAPM below.
5Call the /payment request using the sessionToken, userTokenId, and the existing userPaymentOptionId (UPO payment method).
See an example /payment below.
6After processing the transaction, if a urlDetails.notificationUrl parameter was provided in the request, then Nuvei returns a Direct Merchant Notification (DMN) that includes the result of the transaction.
See an example DMN Response below.
Example /getSessionToken Request (with UPO)
{
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
Example /getSessionToken Response (with UPO)
{
    "reason":"",
    "merchantId":"2502136204546424962",
    "errCode":0,
    "clientRequestId":"NH48LYQFY",
    "sessionToken":"743d4c3f-364c-4c1a-83be-99c1935abbac",
    "internalRequestId":17717111,
    "version":"1.0",
    "status":"SUCCESS",
    "merchantSiteId":"126006"
}
Example /getAccountDetails Request (with UPO)
{
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userId":"6303323",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_VIP_Preferred"
        }
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "phone":"6175551414",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"[email protected]",
        "county":"Suffolk",
        "language":"en",
        "dateOfBirth":"2000-06-30",
        "identification":"123456789"
    },
    "deviceDetails":{
        "deviceType":"DESKTOP",
        "deviceName":"iPhone 5s",
        "deviceOS":"iOS 10.2",
        "browser":"safari",
        "ipAddress":"<customer's IP address>"
    }
}
Example /getAccountDetails Response (with UPO)
{
    "reason":"",
    "clientRequestId":"NH48LYQFY",
    "bankAccounts":[
        {
            "routingNumber":"103112976",
            "bankName":"Arvest Bank",
            "accountNumber":"2452110170"
        },
        {
            "routingNumber":"103112976",
            "bankName":"Arvest Bank",
            "accountNumber":"2452110171"
        },
        {
            "routingNumber":"103112976",
            "bankName":"Arvest Bank",
            "accountNumber":"9920035630"
        },
        {
            "routingNumber":"103112976",
            "bankName":"Arvest Bank",
            "accountNumber":"9920035637"
        }
    ],
    "internalRequestId":17717121,
    "accountNumber":"7210521300",
    "userId":"6303323",
    "version":"1.0",
    "merchantSiteId":"126006",
    "accountLimit":"4500.00",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "sessionToken":"743d4c3f-364c-4c1a-83be-99c1935abbac",
    "currency":"USD",
    "accountBalance":"4450.00",
    "status":"SUCCESS"
}
Example /editUPOAPM Request (with UPO)

Account data is sent in “name-value pairs” in the apmData class. See example below.

{
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "userTokenId":"<unique customer identifier in merchant system>",
    "userPaymentOptionId":"8042741",
    "apmData":{
        "globalpay_accountId":"7210521300",
        "globalpay_bankAccount":"2452110170-103112976",
        "globalpay_firstName":"John",
        "globalpay_lastName":"Smith",
        "globalpay_phone":"6175551414"
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "phone":"6175551414",
        "zip":"02460",
        "city":"Boston",
        "countryCode":"US",
        "state":"MA",
        "email":"[email protected]",
        "county":"Suffolk"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
Example /editUPOAPM Response (with UPO)
{
    "reason":"",
    "merchantId":"2502136204546424962",
    "errCode":0,
    "clientRequestId":"NH48LYQFY",
    "internalRequestId":17717131,
    "version":"1.0",
    "status":"SUCCESS",
    "merchantSiteId":"126006"
}
Example /payment Request (with UPO)
{
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "userTokenId":"<unique customer identifier in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "currency":"USD",
    "amount":"10",
    "items":[
        {
            "name":"Item 1U",
            "price":"10",
            "quantity":"1"
        }
    ],
    "paymentOption":{
        "userPaymentOptionId":"8042741"
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "address":"22 Main Street",
        "cell":"6175553333",
        "phone":"6175551414",
        "zip":"02460",
        "city":"Boston",
        "country":"US",
        "state":"MA",
        "email":"[email protected]"
    },
    "userDetails":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"[email protected]",
        "phone":"6175551414",
        "cell":"6175553333",
        "dateOfBirth":"2000-06-30",
        "address":"22 Main Street",
        "city":"Boston",
        "zip":"02460",
        "county":"Suffolk",
        "state":"MA",
        "country":"US",
        "language":"en"
    },
    "deviceDetails":{
        "deviceType":"DESKTOP",
        "deviceName":"iPhone 5s",
        "deviceOS":"iOS 10.2",
        "browser":"safari",
        "ipAddress":"<customer's IP address>"
    },
    "urlDetails":{
        "notificationUrl":"<URL to which DMNs are sent>"
    },
    "customSiteName":"<customSiteName>",
    "productId":"<productId>",
    "customData":"<customData>",
    "webMasterId":"<webMasterId>",
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
Example /payment Response (with UPO)
{
    "reason":"",
    "orderId":"36254821",
    "transactionStatus":"APPROVED",
    "clientRequestId":"NH48LYQFY",
    "internalRequestId":17717141,
    "merchantDetails":{
        "customField1":"customField1-value",
        "customField2":"customField2-value"
    },
    "version":"1.0",
    "transactionId":"2110000000004236011",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"V0IU0NN0BUCT",
    "errCode":0,
    "paymentOption":{
        "userPaymentOptionId":"8042741",
        "card":{
            
        }
    },
    "sessionToken":"743d4c3f-364c-4c1a-83be-99c1935abbac",
    "userTokenId":"2W6PC7YVS0PV",
    "status":"SUCCESS"
}
Example /payment DMN Response (with UPO)
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=36254811&userid=2W6PC7YVS0PV&merchant_unique_id=EWCVQS79F1TS&customData=Custom+Data+Inserted%21&productId=&first_name=John&last_name=Smith&email=jhahn.jhnui%40srzaw.cb&currency=USD&clientUniqueId=EWCVQS79F1TS&customField1=customField1-value&customField2=customField2-value&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=340689+Billing+Str.+Updated.&address2=&country=United+States&state=&city=Billing+City+Updated&zip=BNE+4895U&phone1=359888797070&phone2=&phone3=&client_ip=192.168.2.38&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&AuthCode=****3323&AvsCode=&Cvv2Reply=&shippingCountry=US&shippingState=&shippingCity=Shipping+City+Updated&shippingAddress=33+Shipping+Str.+Updated.&shippingZip=SDC+33334U&shippingFirstName=john&shippingLastName=Uvnoirngbg&shippingPhone=359888576900&shippingCell=359887576903&shippingMail=gmwch.bphmv%40ducdb.qz&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=126006&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_VIP_Preferred&ID=&merchant_id=2502136204546424962&responseTimeStamp=2021-08-04.10%3A11%3A17&buyButtonProductId=&webMasterId=ZRDJ8IKUZAY6&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=2W6PC7YVS0PV&userPaymentOptionId=8042741&TransactionID=2110000000004235928&ExternalaccountID=****1300&externalTransactionId=2110000000066297&APMReferenceID=5658A61A51859A87FC6CADE0DAB997B3&orderTransactionId=18080791&totalAmount=10.00&dynamicDescriptor=MerchantNameDescriptor123456789101112131415&item_name_1=Item+1U&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20210712&shippingCounty=SCountyU&type=DEPOSIT&clientRequestId=ERW34E0R7&relatedTransactionId=&responsechecksum=2d011cc9c0a1990c67d795395d7fcb07&advanceResponseChecksum=139390d0a691c91ec1c193aedd475106',

Payout – REST

You can send REST API /payout requests (withdrawal transactions) for VIP Preferred, as described in the steps below.

StepDescription
1Generate a sessionToken by sending a /getSessionToken request to retrieve a new sessionToken.
See an example /getSessionToken.
2Use /getAccountDetails to retrieve details of the customer’s bank accounts enrolled (registered) in their VIP Preferred account.
See an example /getAccountDetails.
3Display these bank accounts to the customer, for them to select a new default bank account.
4If the customer selected a bank account that is not the current default (as specified in the UPO record), then send an /editUPOAPM request to replace the bank account in the Nuvei UPO, (to be used in the next step – sending the payment API request).

See an example /editUPOAPM.
5Call the /payout request and include the relevant userPaymentOptionId.

See an example /payout below.
6After processing the transaction, if a urlDetails.notificationUrl parameter was provided in the request, then Nuvei returns a Direct Merchant Notification (DMN) that includes the result of the transaction.
See an example DMN Response below.

Press here for more information about updating and/or adding user details.

Example /payout Request
{
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "userTokenId":"G480LNG2WYJ7",
    "clientUniqueId":"<unique customer identifier in merchant system>",
    "clientRequestId":"<unique request ID in merchant system>",
    "currency":"USD",
    "amount":"35",
    "userPaymentOption":{
        "userPaymentOptionId":"8042761"
    },
    "deviceDetails":{
        "deviceType":"DESKTOP",
        "deviceName":"iPhone 5s",
        "deviceOS":"iOS 10.2",
        "browser":"safari",
        "ipAddress":"<customer's IP address>"
    },
    "merchantDetails":{
        "customField1":"customField1-value",
        "customField2":"customField2-value"
    },
    "comment":"This is a comment",
    "urlDetails":{
        "notificationUrl":"<URL to which DMNs are sent>"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
Example /payout Response
{
    "reason":"",
    "transactionStatus":"APPROVED",
    "clientRequestId":"P5S49XKXW",
    "internalRequestId":17661371,
    "merchantDetails":{
        "customField1":"customField1-value",
        "customField2":"customField2-value"
    },
    "version":"1.0",
    "transactionId":"2110000000004199304",
    "merchantSiteId":"126006",
    "merchantId":"2502136204546424962",
    "clientUniqueId":"695701003",
    "errCode":0,
    "userPaymentOptionId":"8042761",
    "paymentMethodErrorCode":"0",
    "userTokenId":"G480LNG2WYJ7",
    "externalTransactionId":"2110000000065431",
    "status":"SUCCESS"
}
Example /payout DMN Response
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=36234281&userid=G480LNG2WYJ7&merchant_unique_id=695701003&customData=Custom+Data+Inserted&productId=&first_name=&last_name=&email=&currency=USD&clientUniqueId=695701003&customField1=customField1-value&customField2=customField2-value&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&acquirerId=null&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=126006&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_VIP_Preferred&ID=&merchant_id=2502136204546424962&responseTimeStamp=2021-07-28.11%3A39%3A29&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=null&transactionType=Credit&externalEmail=&cardCompany=&user_token_id=G480LNG2WYJ7&userPaymentOptionId=8042761&TransactionID=2110000000004199304&externalTransactionId=2110000000065431&totalAmount=35.0&dynamicDescriptor=Cashier+API&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20210712&type=DEPOSIT&clientRequestId=P5S49XKXW&relatedTransactionId=&responsechecksum=5446cc906f162a5e9eb34848942eb0b7&advanceResponseChecksum=b3f376ba2b970751af497b922d8daa34',
Last update iconLast modified September 2024