Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters including:

• userTokenId
• amount
• currency: “CHF“
• paymentOption.alternativePaymentMethod block containing:
  • paymentMethod: “apmgw_Swiss_Payouts“
• deviceDetails block containing: ipAddress
• userDetails block containing: firstName, lastName, address, city , zip, country must be CH

Example /payment Request

{
  "sessionToken": "111facde-82ce-2ca3-a689-cfde6142f901",
  "merchantId": "112233445566778899",
  "merchantSiteId": "112233",
  "clientRequestId": "TestCliendRequestID",
  "amount": "500",
  "currency": "CHF",
  "userTokenId": "TestToken03",
  "clientUniqueId": "TestClientUniqueID123",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_Swiss_Payouts"
    },
    "deviceDetails": {
      "ipAddress": "127.0.0.1"
    },
    "urlDetails": {
      "notificationUrl": "https://hkdk.events/y8uwj3x0mf2ba8"
    },
    "userDetails": {
      "firstName": "John",
      "lastName": "Smith",
      "Address": "123 Street",
      "city": "Bern",
      "zip": "12345",
      "country": "CH"
    },
    "timeStamp": "20250227101345",
    "checksum": "<calculated checksum>"
  }
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page, as well as a UPO (userPaymentOptionId) for use in future transactions.

Example /payment Response

{
  "internalRequestId": "8889726111",
  "status": "SUCCESS",
  "errCode": "0",
  "reason": "",
  "merchantId": "112233445566778899",
  "merchantSiteId": "112233",
  "version": "1.0",
  "clientRequestId": "TestCliendRequestID",
  "sessionToken": "111facde-82ce-2ca3-a689-cfde6142f901",
  "clientUniqueId": "TestClientUniqueID123",
  "orderId": "1975085111",
  "userTokenId": "TestToken03",
  "paymentOption": {
    "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/payment-details-88520.html?encryptedId=A8CD8CB8355E02A65A93B223CEBA3B36&sessionId=d9d04a928803f21da1017026b2cc&payloadUrl=https%3a%2f%2fservices.sandbox.safecharge.com%2fapm%2fklarpay%2fv1%2fgetQrPayloadAndFormat",
    "userPaymentOptionId": "605129111",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Payout (Withdrawal) Flow

Follow these steps to perform a payout using Nuvei REST API integration:

1. Register a userTokenId

A userTokenId is a field in the Nuvei system containing the user’s identifier in the merchant system.

If you do not have a userTokenId registered in the Nuvei system for this user, then register one by sending a /createUser request, including email, countryCode, firstName, and lastName.

Example /createUser Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "email":"[email protected]",
  "countryCode":"CH",
  "firstName":"John",
  "lastName":"Smith",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example /createUser Response

{
  "userId":78403498,
  "internalRequestId":552360538,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221108130736"
}

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

2. Create the UPO

Create a UPO by sending an /addUPOAPM request and include:

• userTokenId – Unique customer identifier in the merchant’s system.
• paymentMethodName: “apmgw_Swiss_Payouts“
• apmData block containing:
  • swissPayouts_bic – bank BIC
  • swissPayouts_iban – IBAN for the user’s bank account

Example /addUPOAPM Request

{
  "merchantSiteId": "<your merchantSiteId>",
  "merchantId": "<your merchantId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "timeStamp": "<YYYYMMDDHHmmss>",
  "apmData": {
    "swissPayouts_bic": "CRESCHZZ80A",
    "swissPayouts_iban": "CH5604835012345678009"
  },
  "paymentMethodName": "apmgw_Swiss_Payouts",
  "checksum": "<calculated checksum>"
}

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

Example /addUPOAPM Response

{
  "internalRequestId": 958495268,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "5970183043540730700",
  "merchantSiteId": "238459",
  "version": "1.0",
  "clientRequestId": "20240318091527",
  "userPaymentOptionId": 106005808
}

3. Send a /payout Request

Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

Example Payout DMN with Status=APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=&PPP_TransactionID=427690198&userid=Token0746085899&merchant_unique_id=20240318091604&customData=INT+Testing&productId=&first_name=&last_name=&email=¤cy=CHF&pmDisplayName=CH5604835012345678009&clientUniqueId=20240318091604&customField1=&customField2=&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=&noCVV=&acquirerId=&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=238459&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Swiss_Payouts&ID=&merchant_id=5970183043540730700&responseTimeStamp=2024-03-26.19%3A00%3A09&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=Token0746085899&userPaymentOptionId=106005808&TransactionID=711000000033401448&externalTransactionId=72237&totalAmount=1.23&dynamicDescriptor=ICE+Demo+Test&feeAmount=&houseNumber=&customCurrency=&externalToken_blockedCard=&externalToken_cardAcquirerId=&externalToken_cardAcquirerName=&externalToken_cardBin=&externalToken_cardBrandId=&externalToken_cardBrandName=&externalToken_cardExpiration=&externalToken_cardLength=&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=&cryptogram=&upoRegistrationDate=20240318&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=0b6e4176a3d8574c2532ce823568e3b7&advanceResponseChecksum=cdb409ae72d3b3a7eaef535bbee72af8',

Follow these steps to perform a payment using Nuvei Web SDK integration.

1. Initiate a Session

Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call.

2. Initialize the Web SDK

Instantiate the Web SDK with the sessionToken received from the server call to /openOrder.

3. Create an APM Payment

Send a createPayment() request with its mandatory parameters including:

• paymentOption.alternativePaymentMethod block containing:
  • paymentMethod: “apmgw_Swiss_Payouts“
• deviceDetails block containing: ipAddress
• userDetails block containing: firstName, lastName, address, city , zip, country must be CH

Example createPayment() Request

sfc.createPayment({
  sessionToken: "<sessiontoken>",
  paymentOption: {
    alternativePaymentMethod: {
      "paymentMethod": "apmgw_Swiss_Payouts"
    }
  },
  deviceDetails: {
    ipAddress: "<customer's IP address>"
  },
  userDetails: {
    firstName: "John",
    lastName: "Smith",
    address: "123 Street",
    city: "Bern",
    Zip: "12345",
    country: "CH"
  },
}, function(res) {
  console.log(res);
});

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /openOrder request.

Withdrawal Flow

For information about the Withdrawal flow for WebSDK, see Withdrawal.