Overview

This topic describes how to implement “partial approval” payment transactions using Nuvei products.

“Partial approval” payment transactions are a way to help customers who are unable to complete a purchase/deposit transaction due to a lack of approval from their issuing bank, or insufficient balance on their prepaid card.

A partial approval workflow has the following implementation steps:

1. Submit a payment request using your integration method (see Implementation).
2. Sometimes the request for the “original amount” is not approved by the issuer, but they do approve a “partial amount”. In that case, notify your customer of the partial approval (for example due to lack of funds) to ensure compliance with applicable laws and standards governing your business, as well as for “user experience” purposes.
3. Once a transaction is approved with less funds than is required to complete the requested deposit/purchase, the transaction for the partial amount is processed and submitted for approval. The payment response returns the authorized amount.
4. The remaining amount is charged using other payment methods (another prepaid card, PayPal, Google Pay, etc.).

In addition:

• You can give your customers the option to cancel the submitted partial transaction. If they choose to cancel, then you need to send a reversal transaction to reimburse the funds previously charged to the customer (see Reversing a Partial Approval).
• You can ask Nuvei to configure a limitation for partial approval requests, which voids transactions when the approved amount is below the specified minimum amount.

Implementation

Payment Page/Cashier

If you use the Payment Page/Cashier integration method, the Partial Approval feature must be activated by Nuvei’s Integration Support Team during your onboarding process.

Example of a Payment Page with Partial Approval Enabled

Example DMN with partialApprovalStatus=PENDING

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=382906158&userid=&merchant_unique_id=&customData=VentsiT&productId=Cashier+Test+product&first_name=test&last_name=test&email=UserID_8290970953%40gmail.com¤cy=USD&isPrepaid=false&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=test&address2=&country=United+Kingdom&state=&city=test&zip=123456&phone1=123456&phone2=&phone3=&client_ip=157.167.61.180&nameOnCard=test+user&cardNumber=4****4475&bin=400099&noCVV=&acquirerId=19&acquirerBank=Nuvei+Demo+Bank&expMonth=02&expYear=25&Token=TQBlAFEAZAAwAFAAbgBQAFAAUABuAEYAVABSAHEAVgAxAHYARgAwAFYANgBPAHgAQABaADoAPQA3AF0AKwA%2BAEAAXgA3AGsAWwAsAC4AVQApAF8AYgBCAE0AaAA8AEoAYwBbAGcAMwA%3D&tokenId=36163047&AuthCode=111768&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=233298&merchant_status=&action=&requestVersion=4.0.0&message=Success&merchantLocale=en_GB&unknownParameters=&payment_method=cc_card&ID=&merchant_id=6985937360161129049&responseTimeStamp=2023-08-09.10%3A22%3A07&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=gpZOHPFG0BTY9Sa18YnVO1D3muw%3D&transactionType=Sale&externalEmail=&cardCompany=Visa&test=1&eci=&user_token_id=UserID_8290970953&user_token=auto&userPaymentOptionId=94103388&TransactionID=711000000025062655&LifeCycleId=711000000025062655&3Dflow=1&orderTransactionId=1216273388&totalAmount=5&dynamicDescriptor=test&item_name_1=Cashier+Test+product&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=20230809&isPartialApproval=1&requestedAmount=10&requestedCurrency=USD&type=DEPOSIT&clientRequestId=&relatedTransactionId=&partialApprovalStatus=PENDING&lastFourDigits=4475&sessionId=9c2a546ddc8c56065561af4ba945&responsechecksum=c800ea2757cc29b5d42b833ac922fd104cef9de78408394d3fb7136f97982882&advanceResponseChecksum=0bf01f6e803fe205047136eaf344437f8190d31c4ae9f003790c1deb40cd1e2f',

Example DMN with partialApprovalStatus=APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=382906158&userid=&merchant_unique_id=&customData=VentsiT&productId=Cashier+Test+product&first_name=test&last_name=test&email=UserID_8290970953%40gmail.com¤cy=USD&isPrepaid=false&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=test&address2=&country=United+Kingdom&state=&city=test&zip=123456&phone1=123456&phone2=&phone3=&client_ip=157.167.61.180&nameOnCard=test+user&cardNumber=4****4475&bin=400099&noCVV=&acquirerId=19&acquirerBank=Nuvei+Demo+Bank&expMonth=02&expYear=25&Token=TQBlAFEAZAAwAFAAbgBQAFAAUABuAEYAVABSAHEAVgAxAHYARgAwAFYANgBPAHgAQABaADoAPQA3AF0AKwA%2BAEAAXgA3AGsAWwAsAC4AVQApAF8AYgBCAE0AaAA8AEoAYwBbAGcAMwA%3D&tokenId=36163047&AuthCode=111768&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=233298&merchant_status=&action=&requestVersion=4.0.0&message=Success&merchantLocale=en_GB&unknownParameters=&payment_method=cc_card&ID=&merchant_id=6985937360161129049&responseTimeStamp=2023-08-09.10%3A22%3A07&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=gpZOHPFG0BTY9Sa18YnVO1D3muw%3D&transactionType=Sale&externalEmail=&cardCompany=Visa&test=1&eci=&user_token_id=UserID_8290970953&user_token=auto&userPaymentOptionId=94103388&TransactionID=711000000025062655&LifeCycleId=711000000025062655&3Dflow=1&orderTransactionId=1216273388&totalAmount=5&dynamicDescriptor=test&item_name_1=Cashier+Test+product&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=20230809&isPartialApproval=1&requestedAmount=10&requestedCurrency=USD&type=DEPOSIT&clientRequestId=&relatedTransactionId=&partialApprovalStatus=APPROVED&lastFourDigits=4475&sessionId=9c2a546ddc8c56065561af4ba945&responsechecksum=c800ea2757cc29b5d42b833ac922fd104cef9de78408394d3fb7136f97982882&advanceResponseChecksum=0bf01f6e803fe205047136eaf344437f8190d31c4ae9f003790c1deb40cd1e2f',

REST API

To process a partial approval transaction, the /payment API request should be sent with the isPartialApproval input parameter.

Possible values:

• 1 – Allow partial approval
• 0 – Not allow partial approval

The /payment request returns a response that includes the partialApproval class containing these parameters:

• requestedAmount (String, 12) – The original amount requested.
• requestedCurrency (String, 3) – The currency of the original request.
• processedAmount (String, 12) – The amount that was actually deposited in the transaction.
• processedCurrency (String, 3) – The currency used in the processed transaction request.

Web SDK

To implement Partial Approval when you are integrated using the Nuvei Web SDK method (refer to Web SDK Quick Start), do the following:

1. Send an /openOrder API request and include isPartialApproval: “1“, as shown below.
   

   Example /openOrder Request

   {
     "merchantSiteId": "<your merchantSiteId>",
     "merchantId": "<your merchantId>",
     "clientRequestId": "<unique request ID in merchant system>",
     "timeStamp": "<YYYYMMDDHHmmss>",
     "checksum": "<calculated checksum>",
     "userTokenId": "<unique customer identifier in merchant system>",
     "transactionType": "Auth",
     "currency": "USD",
     "amount": "300",
     "isPartialApproval": "1",
     "deviceDetails": {
       "ipAddress": "<customer's IP address>"
     },
     "billingAddress": {
       "email": "[email protected]",
       "country": "US"
     }
   }

2. After the customer enters their payment details on your payment form and submits it for payment, send a createPayment() request.
3. Once the createPayment() request is processed, you receive a response containing the partialApproval class and the payment status, as well as a DMN. You can also receive this information by sending a /getPaymentStatus request.
   

   Example Response

   {
     "gwExtendedErrorCode": 0,
     "gwErrorCode": 0,
     "issuerDeclineCode": "",
     "issuerDeclineReason": "",
     "authCode": "111884",
     "transactionType": "Auth",
     "transactionStatus": "APPROVED",
     "userTokenId": "ran@sc",
     "transactionId": "711000000015442640",
     "paymentOption": {
       "card": {
         "uniqueCC": "gpZOHPFG0BTY9Sa18YnVO1D3muw=",
         "threeD": {
           "isLiabilityOnIssuer": "0"
         }
       }
     },
     "partialApproval": {
       "requestedAmount": "300.0",
       "requestedCurrency": "USD",
       "processedAmount": "150.0",
       "processedCurrency": "USD"
     },
     "currency": "USD",
     "amount": "150.0",
     "sessionToken": "d0d5e0d6-4be1-4cf0-8cb6-77cd04f10621",
     "internalRequestId": 514528548,
     "status": "SUCCESS",
     "errCode": 0,
     "reason": "",
     "merchantSiteId": "204388",
     "version": "1.0"
   }

Simply Connect

Partial Approval can be implemented when you are integrated using the Simply Connect product (checkout() method). For the payment flow, refer to Simply Connect Quick Start.

1. Send an /openOrder API request and include isPartialApproval: “1“.
   See the Example /openOrder Request above.
2. After the customer enters their payment details on your payment form and submits it for payment, send a checkout() request.
3. Once the checkout() request is processed, you receive a response containing the partialApproval class and the payment status, as well as a DMN. You can also receive this information by sending a /getPaymentStatus request.
   See the Example Response above.

Reversing a Partial Approval

A situation may arise where the customer is not interested in continuing with a transaction if it can only be performed partially. Since the partial approval is authenticated automatically, you should be prepared for this scenario and offer the customer the option to back out of the transaction.

REST API

A partial approval transaction can be reversed through the REST API by sending a /voidTransaction API request.

Cashier Deposit Page

Once the deposit transaction has been activated and partially approved, the Payment Page allows the customer to void the partially approved transaction by opening the Confirmation dialog that includes a Cancel Transaction button. The customer has two minutes to decide whether to confirm the partial approval or cancel it:

• Pressing Cancel Transaction triggers the execution of a void transaction for the partially approved amount and currency, and a DMN is sent to you.
• Pressing OK sends a confirmation DMN to you.