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

Overview

Card Refund

Example /refundTransaction Request

Example /refundTransaction Response

Unreferenced Refunds

Using Full Card Details

Example of a Full Card Details Request

Example of a Full Card Details Response

DMN Response

Using UPO

Example of a UPO Request

Example of a UPO Response

DMN Response

APM Refunds

Example DMN for APM Refund with Status=APPROVED

Example DMN for APM Refund with Status=PENDING

Example `/refundTransaction` Request

Example `/refundTransaction` Response

Example DMN for APM Refund with `Status=APPROVED`

Example DMN for APM Refund with `Status=PENDING`