• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
< BACK TO HOME
  • Online Payments
    • Introduction
    • Choosing an Integration Method
    • Payment Scenarios
    • Flow Diagrams
  • Accept Payment
    • Payment Page (Cashier)
      • Quick Start
      • Input Parameters
      • Output Parameters
      • Payment Page Features
      • Cashier
        • Cashier Events Guide
        • Cashier Features
        • Withdrawal Guide
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Simply Connect
      • Quick Start
        • UI Customization
        • Payment Customization
        • Advanced Controls
        • Simply Connect Examples
      • Server-to-Server
        • REST 1.0
        • Server SDKs
          • Java SDK
          • .NET SDK
          • PHP SDK
          • Node.JS SDK
      • Mobile SDKs (Beta Release)
        • Android Mobile SDK (Beta Release)
        • iOS Mobile SDK (Beta Release)
      • Marketplaces
      • Self Track
    • Features
      • Authentication
      • Financial Operations
        • Refund
        • Void
        • Auth and Settle
        • Partial Approval
        • Currency Conversion: DCC and MCP
          • Multiple Currency Pricing (MCP)
          • Dynamic Currency Conversion (DCC)
            • DCC in Cashier or Payment Page
            • DCC in REST API Workflows
            • DCC in Web SDK Workflows
        • Payout
        • AFT (Account Funding Transactions)
      • Card Operations
        • Card-on-File
        • PCI and Tokenization
        • Zero-Authorization
        • Merchant-Initiated Transactions (MIT)
        • Blocking Cards
      • Subscriptions (Rebilling)
      • 3D-Secure
        • 3D-Secure Explained
        • 3DS Implementations
          • 3DS MPI-Only Web SDK
          • 3DS MPI-Only REST
          • 3DS External MPI
          • 3DS Responses
          • Challenges and Exemptions
        • 3DS Functions
          • 3D-Secure Fingerprinting
          • 3D-Secure Authentication Challenge
      • Addendums
        • Airline
          • External Authorization
    • Integration
      • Testing Cards, APIs and APMs
        • Testing Cards
        • Testing APMs
        • Testing APIs with Postman
      • Response Handling
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
      • Payment Facilitators (PayFac)
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    Refund

    On this page:
    • Overview
    • Card Refund
    • Unreferenced Refunds
      • Using Full Card Details
      • Using UPO
    • APM Refunds

    Overview

    You can refund funds from your (merchant) bank account to customer accounts for:

    • Successful deposit/payment transactions that were settled by Nuvei.
    • “Unreferenced refunds” transactions that were not settled by Nuvei.

    A refund can be performed through the Control Panel as described in Operations > Refund.

    You can use Postman to run a full “Simple Sale Payment and Partial Refund” workflow simulation in the Nuvei sandbox environment.

    To install Postman and the relevant simulation collection, follow the steps in the Testing APIs with Postman topic.

    Card Refund

    To perform a refund via REST API, send a /refundTransaction API request with its mandatory parameters and include these parameters:

    • relatedTransactionId – This is the transactionId of the original payment transaction.
    • currency – Must match the original transaction currency.
    • amount –
      • The amount must not exceed the original sale amount.
      • The sum of this amount plus all previous partial refunds must not exceed the original sale amount.

        This is one of the reasons why this method is not suitable for refunding payouts and winnings.

    Example /refundTransaction Request
    {
      "merchantId": "<your merchantId>",
      "merchantSiteId": "<your merchantSiteId>",
      "clientUniqueId": "<unique transaction ID in merchant system>",
      "amount": "200",
      "currency": "USD",
      "relatedTransactionId": "<transactionId returned from /payment>",
      "timeStamp": "<YYYYMMDDHHmmss>",
      "checksum": "<calculated checksum>"
    }
    //Initialize the SDK (see https://docs.nuvei.com/?p=53233)
    
    <?php
    //refundTransaction
    $refundResponse = $safeCharge->getPaymentService()->refundTransaction([
      'clientUniqueId'          => '<unique transaction ID in merchant system>',
      'amount'                  => '200',
      'currency'                => 'USD',
      'relatedTransactionId'    => '<transactionId returned from /payment>',
    ]);
    ?>
    //Initialize the SDK (see https://docs.nuvei.com/?p=29433)
    
    {
      String clientUniqueId = "<unique transaction ID in merchant system>";
      String clientRequestId = "<unique request ID in merchant system>";
      String currency = "USD";
      String amount = "200";
      String relatedTransactionId = "<transactionId returned from /payment>";
    
      Safecharge safecharge = new Safecharge();
      SafechargeResponse response = safecharge.refundTransaction(clientUniqueId, clientRequestId, null, amount, null, null, currency, null, null, null, relatedTransactionId, null);
    }
    //Initialize the SDK (see https://docs.nuvei.com/?p=48413)
    
    var response = safecharge.RefundTransaction(
      "US",
      "200",
      relatedTransactionId: "<transactionId returned from /payment>",
      clientRequestId: "<unique request ID in merchant system>",
      clientUniqueId: "<unique transaction ID in merchant system>");
    //Initialize the SDK (see https://docs.nuvei.com/?p=53443)
    
    safecharge.paymentService.refundTransaction({
      clientRequestId     : "<unique request ID in merchant system>",
      clientUniqueId      : "<unique transaction ID in merchant system>",
      amount              : "200",
      currency            : "USD",
      relatedTransactionId: "<transactionId returned from /payment>",
    }, function (stlErr, stlRes, reqData) {
        console.log(stlErr, stlRes);
    });
    Example /refundTransaction Response
    {
      "reason":"",
      "ccCardNumber":"4****1164",
      "bin":"407239",
      "ccExpYear":"22",
      "customData":"",
      "merchantSiteId":"126006",
      "gwExtendedErrorCode":0,
      "merchantId":"2502136204546424962",
      "externalTransactionId":"",
      "acquirerId":"103",
      "cardBrand":"VISA",
      "authCode":"169410",
      "transactionStatus":"APPROVED",
      "clientRequestId":"IV96ZBARW",
      "cardType":"Debit",
      "ccExpMonth":"12",
      "internalRequestId":17771151,
      "AVSCode":"",
      "version":"1.0",
      "transactionId":"2110000000004302220",
      "CVV2Reply":"",
      "transactionType":"Credit",
      "issuerCountry":"US",
      "gwErrorCode":0,
      "clientUniqueId":"695701003",
      "errCode":0,
      "last4Digits":"1164",
      "status":"SUCCESS"
    }

    Unreferenced Refunds

    You can process “unreferenced refunds” for transactions that were not settled by Nuvei, with no need for a related transaction ID (relatedTransactionId). This can be done in two ways:

    • Using Full Card Details
    • Using UPO

    To activate this feature, contact your Nuvei Account Manager to configure your account to process “unreferenced refunds”.

    Using Full Card Details

    In some cases, it is required to allow the merchant to refund funds by providing the full card details. For example, when the original transaction was processed by another PSP, and you would like Nuvei to process the refund.

    To do this, send a /refundTransaction request with the full card details (no relatedTransactionId is required), as shown below.

    Example of a Full Card Details Request
    {
      "merchantId": "<your merchantId>",
      "merchantSiteId": "<your merchantSiteId>",
      "clientRequestId": "<unique request ID in merchant system>",
      "clientUniqueId": "<unique transaction ID in merchant system>",
      "amount": "200",
      "currency": "GBP",
      "paymentOption": {
        "card": {
          "cardNumber": "4000027891380961",
          "cardHolderName": "John Smith",
          "expirationMonth": "12",
          "expirationYear": "2030",
          "CVV": "217"
        }
      },
      "timeStamp": "<YYYYMMDDHHmmss>",
      "checksum": "<calculated checksum>"
    }
    Example of a Full Card Details Response
    {
      "reason": "",
      "ccCardNumber": "4****1164",
      "bin": "407239",
      "ccExpYear": "22",
      "customData": "Custom Data",
      "merchantSiteId": "126006",
      "gwExtendedErrorCode": 0,
      "merchantId": "2502136204546424962",
      "externalTransactionId": "",
      "acquirerId": "103",
      "cardBrand": "VISA",
      "authCode": "169410",
      "transactionStatus": "APPROVED",
      "clientRequestId": "IV96ZBARW",
      "cardType": "Debit",
      "ccExpMonth": "12",
      "internalRequestId": 17771151,
      "AVSCode": "",
      "version": "1.0",
      "transactionId": "2110000000004302220",
      "CVV2Reply": "",
      "transactionType": "Credit",
      "issuerCountry": "US",
      "gwErrorCode": 0,
      "clientUniqueId": "695701003",
      "errCode": 0,
      "last4Digits": "1164",
      "status": "SUCCESS"
    }
    DMN Response
    ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=36282591&userid=&merchant_unique_id=695701003&customData=Custom+Data%21&productId=06GNX0A059ME&first_name=&last_name=&email=&currency=GBP&clientUniqueId=695701003&cardType=Debit&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=John+Smith&cardNumber=4****1164&bin=407239&acquirerId=103&acquirerBank=Safecharge+Acquirer+-+Visa&expMonth=12&expYear=22&Token=bwAwAE8AVQBNADQARwAwAHYAZwAuAEEAVABRAHQAaQBMAGgAdABSADoAWQAuAG0AWABHAFUATgA1ACwAZwBrADoAOwAnAHIAWABgAC4AfABLAEMAMwA%3D&tokenId=847632660&AuthCode=169410&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=&ID=&merchant_id=2502136204546424962&responseTimeStamp=2021-08-15.09%3A29%3A06&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=fRjy5hTt1YrEv7Bsc%2BKs8YYosMc%3D&transactionType=Credit&externalEmail=&cardCompany=VISA&userPaymentOptionId=&TransactionID=2110000000004302220&totalAmount=6.0&dynamicDescriptor=CashierAPIDescriptor&feeAmount=&houseNumber=&customCurrency=&type=DEPOSIT&clientRequestId=IV96ZBARW&relatedTransactionId=&responsechecksum=689f4041f536c7c561b8cd2b4c2ffec8&advanceResponseChecksum=8902f2b98538ea4637663d247c175bb7

    Using UPO

    If the User Payment Option (UPO) feature is activated in your Nuvei merchant account, then you can process unreferenced refund transactions (/refundTransaction) by including the userTokenId and userPaymentOptionId parameters. This allows you to refund funds to a customer account without re-collecting the payment option details (see User Payment Management).

    Example of a UPO Request
    {
      "merchantId": "<your merchantId>",
      "merchantSiteId": "<your merchantSiteId>",
      "clientRequestId": "<unique request ID in merchant system>",
      "clientUniqueId": "<unique transaction ID in merchant system>",
      "userTokenId": "<unique customer identifier in merchant system>",
      "amount": "100",
      "currency": "EUR",
      "paymentOption": {
        "userPaymentOptionId": "<UPO received from previous deposit>"
      },
      "timeStamp": "<YYYYMMDDHHmmss>",
      "checksum": "<calculated checksum>"
    }
    Example of a UPO Response
    {
      "reason": "",
      "ccCardNumber": "5****8729",
      "bin": "525569",
      "ccExpYear": "25",
      "customData": "Custom Data",
      "merchantSiteId": "126006",
      "gwExtendedErrorCode": 0,
      "isPrepaid": "false",
      "merchantId": "2502136204546424962",
      "externalTransactionId": "",
      "acquirerId": "29",
      "cardBrand": "MASTERCARD",
      "issuerBankName": "",
      "authCode": "0553287",
      "issuerDeclineCode": "",
      "transactionStatus": "APPROVED",
      "clientRequestId": "EX032W24D",
      "ccExpMonth": "12",
      "internalRequestId": 21117971,
      "AVSCode": "",
      "version": "1.0",
      "transactionId": "2110000000006791575",
      "CVV2Reply": "",
      "transactionType": "Credit",
      "gwErrorCode": 0,
      "clientUniqueId": "695701003",
      "errCode": 0,
      "userPaymentOptionId": 8303451,
      "issuerDeclineReason": "",
      "last4Digits": "8729",
      "status": "SUCCESS"
    }
    DMN Response
    ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=37896471&userid=Q6DQKHKVAYKB&merchant_unique_id=695701003&customData=Custom+Data%21&productId=404UTD0X1ZN8&first_name=&last_name=&email=&currency=EUR&clientUniqueId=695701003&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=CL-BRW1&cardNumber=5****8729&bin=525569&noCVV=&acquirerId=29&acquirerBank=WorldPay+Direct&expMonth=12&expYear=25&Token=SABHAEcAMABQAEYAUAAwAGQAMABGAFAARgBSAHIASgA1AE0AbwAsACkALQBwAEEAMwBFAHcASAByACwAQQAmAD8AXwAnAHwAMgBpAGcANABPAHkAUAAtACQAMwAxAGEAOABjAD4AMwA%3D&tokenId=1047838320&AuthCode=0553287&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=cc_card&ID=&merchant_id=2502136204546424962&responseTimeStamp=2022-08-02.05%3A35%3A40&buyButtonProductId=&webMasterId=104P01&appliedPromotions=&uniqueCC=14bF8%2BAvFF6Rpln7brmYhTNAZAU%3D&transactionType=Credit&externalEmail=&cardCompany=MasterCard&user_token_id=Q6DQKHKVAYKB&userPaymentOptionId=8303451&TransactionID=2110000000006791575&externalAccountDescription=nameOnCard%3ACL-BRW1&totalAmount=10.37&dynamicDescriptor=CashierAPIDescriptor&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=20220801&type=DEPOSIT&clientRequestId=EX032W24D&relatedTransactionId=&lastFourDigits=8729&responsechecksum=c350d6d5a96156c8a8ff30de924d6fa3&advanceResponseChecksum=596bf9ab7cbfb83d3b5ede534aff6d0c

    APM Refunds

    For most APM refunds (e.g., PayPal), the system returns a response containing transactionStatus (APPROVED, DECLINED, or ERROR).

    Some APMs, depending on the provider, may return Status=PENDING. In this case, wait for a DMN response containing transactionStatus (APPROVED or DECLINED) that is sent by the system.

    Example DMN for APM Refund with Status=APPROVED
    ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=37972511&userid=UID&merchant_unique_id=0DEXOI3OMEFP&customData=QA+test+merchant&productId=PID&first_name=John&last_name=Doe&email=JD%40nuvei.com&currency=EUR&clientUniqueId=0DEXOI3OMEFP&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Hamilton+15&address2=15&country=Spain&state=&city=Hannover&zip=07208&phone1=&phone2=&phone3=&client_ip=127.0.0.1&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=3111&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_Bizum&ID=&merchant_id=4972436454212160565&responseTimeStamp=2022-08-26.10%3A29%3A25&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Refund&externalEmail=&cardCompany=&eci=&user_token_id=NuveiTest_&user_token=auto&userPaymentOptionId=8200841&TransactionID=2110000000007052698&totalAmount=1.0&dynamicDescriptor=QA+Test+site&item_name_1=ItemName&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=&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=20220629&type=DEPOSIT&clientRequestId=&relatedTransactionId=2110000000007045936&originalTransactionPaymentMethod=apmgw_Bizum&originalTransactionAmount=10.0&originalTransactionCurrency=EUR&responsechecksum=cc1bf0d3f8f2d0b3146939927e22c356&advanceResponseChecksum=6e9ef281b91ad2c443d581617f7e1b63
    Example DMN for APM Refund with Status=PENDING
    ppp_status=PENDING&Status=PENDING&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=37972511&userid=UID&merchant_unique_id=0DEXOI3OMEFP&customData=QA+test+merchant&productId=R8VX8RD64OQB&first_name=John&last_name=Doe&email=JD%40nuvei.com&currency=EUR&clientUniqueId=0DEXOI3OMEFP&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Hamilton+15&address2=15&country=Spain&state=&city=Hannover&zip=07208&phone1=&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&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=3111&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_Bizum&ID=&merchant_id=4972436454212160565&responseTimeStamp=2022-08-26.10%3A29%3A24&buyButtonProductId=&webMasterId=Q3B60MS8529W&appliedPromotions=&uniqueCC=null&transactionType=Refund&externalEmail=&cardCompany=&user_token_id=NuveiTest_&user_token=auto&userPaymentOptionId=8200841&TransactionID=2110000000007052698&totalAmount=1.0&dynamicDescriptor=QA+Test+site&item_name_1=ItemName&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=&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=20220629&type=DEPOSIT&clientRequestId=T5SIY085I&relatedTransactionId=2110000000007045936&originalTransactionPaymentMethod=apmgw_Bizum&originalTransactionAmount=10.0&originalTransactionCurrency=EUR&responsechecksum=789be09b96b16a7786b48ad4e4bfa679&advanceResponseChecksum=ddc8cd7f506d71185bc789f9b89f8e98
    2023 Nuvei. All rights reserved.