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
• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_Epay_bg“
• deviceDetails class containing: ipAddress
• billingAddress class containing: firstName, lastName, country, email
• userDetails class containing: firstName, lastName, country, email

Example /payment Request

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "BGN",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_Epay_bg"
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "BG",
    "email": "[email protected]"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "BG",
    "email": "[email protected]"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "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": 42130161,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "1234567891234567891",
  "merchantSiteId": "242181",
  "version": "1.0",
  "sessionToken": "9aea428b-e9ec-4258-b4bc-b9448064cacc",
  "orderId": "43351551",
  "userTokenId": "Testy2",
  "paymentOption": {
    "redirectUrl": "https://apmtest.gate2shop.com/ppp/resources/cdn/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJFTkNPREVEIjoiVFVsT1BVUTROek00TnpnNU5qVUtTVTVXVDBsRFJUMDRNamN3TmpoR1FqRkJRVUl5UVRVeVFVWkNRa0UwUkVKRE5qSTFNRUV3TkFwQlRVOVZUbFE5TWpNMExqQXdDa05WVWxKRlRrTlpQVUpIVGdwRldGQmZWRWxOUlQweE1TNHdOeTR5TURJMElEQTJPak15T2pRNUNrUkZVME5TUFZSRlUxUXRVVUVLUlU1RFQwUkpUa2M5ZFhSbUxUZ0siLCJDSEVDS1NVTSI6IjdFQzgyMzhBNzMxM0JGMDM1Q0VENDIzNkU0REFFRTRENTZFQzMwODMiLCJQYWdlIjoicGF5bG9naW4iLCJVUkxfT0siOiJodHRwczovL2s4cy10bHYtY2wwLXFhMS5ndy00dS5jb20vYXBtL2Vhc3lwYXkvdjEvY29uc3VtZXJSZXR1cm4vODI3MDY4RkIxQUFCMkE1MkFGQkJBNERCQzYyNTBBMDQiLCJVUkxfQ0FOQ0VMIjoiaHR0cHM6Ly9rOHMtdGx2LWNsMC1xYTEuZ3ctNHUuY29tL2FwbS9lYXN5cGF5L3YxL2NvbnN1bWVyUmV0dXJuLzgyNzA2OEZCMUFBQjJBNTJBRkJCQTREQkM2MjUwQTA0IiwidXJsIjoiaHR0cHM6Ly9kZW1vLmVwYXkuYmcifQ.j_e5Z_xVIjdu3W2nFMCtN5_rHwrR5hPFWyTYOSYaU2pbKyp_IgG7A97ELghoSnhNAXtQXaEBvjQz_kbFZUQa2Ghny3gVksdEORqXZEn-m0E8fFR6RQf1CgbZzTz-03TLA1qOuvAff-zIpgSQhwkYKeSzOCE7wijGsXkFTuy4Lxy0flHZq4h0bPdvu0arqdsr-ihhQfIoQJOQhKAHB9pTwwI-Kd0toGK1rZ8ELDMvAXyoDYeJFC0-rVpAOj-3wwvtsXITDYjn3VpzWIgjhX6MiO_X4v8RgLou_O2LAEXIqhETxiTWCPRmsrPtdZyg08rJbFcnZFS1WauVUPpid0yO-Q",
    "userPaymentOptionId": "2153218811",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

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

Example Payment DMN with Status=APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43352851&userid=ScMigrationTest3&merchant_unique_id=97c10831-d399-48d7-8ea5-41f89619d2fa6&customData=56&productId=test_name_1&first_name=John&last_name=Doe&email=Johnp%40abv.bg&currency=BGN&pmDisplayName=D352762029&customField1=example.site&customField2=a2db82db-8186-44bb-a6d9-cb9f8f7ea25e&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=rnk_pr01&invoice_id=&address1=Test+Address&address2=&country=Bulgaria&state=&city=Sitee&zip=123+1J1&phone1=%2B15057731269&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=ePayMS-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=BG&shippingState=&shippingCity=Sitee&shippingAddress=Test+Address&shippingZip=123+1J1&shippingFirstName=John&shippingLastName=Doe&shippingPhone=%2B14161238888&shippingCell=%2B15057731269&shippingMail=Johnp%40abv.bg&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=242181&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_Epay_bg&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-07-09.09%3A03%3A01&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Siltoken&user_token=auto&userPaymentOptionId=2153266121&TransactionID=2610000000000040035&APMReferenceID=E6CC78B322AEED68165362A3A68FB230&orderTransactionId=24682611&totalAmount=1.00&dynamicDescriptor=static+test&item_name_1=test_name_1&item_number_1=&item_amount_1=1.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&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=&maskedNetworkTokenNumber=&upoRegistrationDate=20240626&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%5B%5D&sessionId=6bac453957045183483bbc63d448&responsechecksum=ad17c7c4687c88d9568bd34a429b7fdc&advanceResponseChecksum=4776416f414fc25a351d41e0b7bd9f09',

Example Payment DMN with Status=DECLINED

...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43352901&userid=ScMigrationTest3&merchant_unique_id=97c10831-d399-48d7-8ea5-41f89619d2fa6&customData=56&productId=test_name_1&first_name=John&last_name=Doe&email=Johnp%40abv.bg&currency=BGN&pmDisplayName=D352762029&customField1=example.site&customField2=a2db82db-8186-44bb-a6d9-cb9f8f7ea25e&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=rnk_pr01&invoice_id=&address1=Test+Address&address2=&country=Bulgaria&state=&city=Sitee&zip=M6T+1J1&phone1=%2B14161238888&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=ePayMS-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=BG&shippingState=&shippingCity=Ontario&shippingAddress=Test+Address&shippingZip=M6T+1J1&shippingFirstName=John&shippingLastName=Doe&shippingPhone=%2B14161238888&shippingCell=%2B14161238888&shippingMail=Johnp%40abv.bg&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=242181&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_Epay_bg&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-07-09.09%3A07%3A12&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Siltoken&user_token=auto&userPaymentOptionId=2153266121&TransactionID=2610000000000040038&APMReferenceID=0AB4F59483D07A41E6097CC54DA2FE06&orderTransactionId=24682621&totalAmount=1.00&dynamicDescriptor=static+test&item_name_1=test_name_1&item_number_1=&item_amount_1=1.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&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=&maskedNetworkTokenNumber=&upoRegistrationDate=20240626&type=DEPOSIT&clientRequestId=&relatedTransactionId=&sessionId=6bac453957045183483bbc63d448&responsechecksum=eb53f85449f924ba868e73260b27b999&advanceResponseChecksum=2899ad221b8402ae0fca4ad41cc24b9b',

Payout (Withdrawal) Flow

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 DMN that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

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 class containing:
  • paymentMethod: “apmgw_Epay_bg“
• deviceDetails class containing: ipAddress
• billingAddress class containing: firstName, lastName, country, email
• userDetails class containing: firstName, lastName, country, email

Example createPayment() Request

sfc.createPayment({

  sessionToken: "<sessiontoken>",
  paymentOption: {
    alternativePaymentMethod: {
      paymentMethod: "apmgw_Epay_bg",
      }     
  },
  deviceDetails:{
    ipAddress:"<customer's IP address>"
  },
  billingAddress: {
    firstName: "John",
    lastName: "Smith",
    country: "BG",
    email: "[email protected]"
  },
  userDetails: {
    firstName: "John",
    lastName: "Smith",
    country: "BG",
    email: "[email protected]"   },
}, 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.

Example Payment DMN with Status=APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43352851&userid=ScMigrationTest3&merchant_unique_id=97c10831-d399-48d7-8ea5-41f89619d2fa6&customData=56&productId=test_name_1&first_name=John&last_name=Doe&email=Johnp%40abv.bg&currency=BGN&pmDisplayName=D352762029&customField1=example.site&customField2=a2db82db-8186-44bb-a6d9-cb9f8f7ea25e&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=rnk_pr01&invoice_id=&address1=Test+Address&address2=&country=Bulgaria&state=&city=Sitee&zip=123+1J1&phone1=%2B15057731269&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=ePayMS-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=BG&shippingState=&shippingCity=Sitee&shippingAddress=Test+Address&shippingZip=123+1J1&shippingFirstName=John&shippingLastName=Doe&shippingPhone=%2B14161238888&shippingCell=%2B15057731269&shippingMail=Johnp%40abv.bg&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=242181&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_Epay_bg&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-07-09.09%3A03%3A01&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Siltoken&user_token=auto&userPaymentOptionId=2153266121&TransactionID=2610000000000040035&APMReferenceID=E6CC78B322AEED68165362A3A68FB230&orderTransactionId=24682611&totalAmount=1.00&dynamicDescriptor=static+test&item_name_1=test_name_1&item_number_1=&item_amount_1=1.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&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=&maskedNetworkTokenNumber=&upoRegistrationDate=20240626&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%5B%5D&sessionId=6bac453957045183483bbc63d448&responsechecksum=ad17c7c4687c88d9568bd34a429b7fdc&advanceResponseChecksum=4776416f414fc25a351d41e0b7bd9f09',

Example Payment DMN with Status=DECLINED

...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43352901&userid=ScMigrationTest3&merchant_unique_id=97c10831-d399-48d7-8ea5-41f89619d2fa6&customData=56&productId=test_name_1&first_name=John&last_name=Doe&email=Johnp%40abv.bg&currency=BGN&pmDisplayName=D352762029&customField1=example.site&customField2=a2db82db-8186-44bb-a6d9-cb9f8f7ea25e&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=rnk_pr01&invoice_id=&address1=Test+Address&address2=&country=Bulgaria&state=&city=Sitee&zip=M6T+1J1&phone1=%2B14161238888&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=ePayMS-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=BG&shippingState=&shippingCity=Ontario&shippingAddress=Test+Address&shippingZip=M6T+1J1&shippingFirstName=John&shippingLastName=Doe&shippingPhone=%2B14161238888&shippingCell=%2B14161238888&shippingMail=Johnp%40abv.bg&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=242181&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_Epay_bg&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-07-09.09%3A07%3A12&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Siltoken&user_token=auto&userPaymentOptionId=2153266121&TransactionID=2610000000000040038&APMReferenceID=0AB4F59483D07A41E6097CC54DA2FE06&orderTransactionId=24682621&totalAmount=1.00&dynamicDescriptor=static+test&item_name_1=test_name_1&item_number_1=&item_amount_1=1.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&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=&maskedNetworkTokenNumber=&upoRegistrationDate=20240626&type=DEPOSIT&clientRequestId=&relatedTransactionId=&sessionId=6bac453957045183483bbc63d448&responsechecksum=eb53f85449f924ba868e73260b27b999&advanceResponseChecksum=2899ad221b8402ae0fca4ad41cc24b9b',

Withdrawal Flow

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