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.
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 thetransactionId
of the original payment transaction.currency
– Must match the original transaction currency.amount
–- The
amount
must not exceed the original saleamount
. - The sum of this
amount
plus all previous partial refunds must not exceed the original saleamount
.
- The
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
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=¤cy=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=¤cy=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¤cy=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¤cy=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