Nuvei Integration

Nuvei (formerly SafeCharge) is a global payment technology provider offering a wide range of payment methods and acquiring capabilities. LostChurn connects to Nuvei using your Merchant ID, Secret Key, and Site ID, and processes webhook notifications (DMN - Direct Merchant Notifications) to detect and recover failed recurring payments.

Prerequisites

• An active Nuvei account with access to the Nuvei Control Panel
• Your Nuvei Merchant ID, Merchant Site ID, and Secret Key
• Access to the Nuvei Control Panel with admin or technical permissions
• A LostChurn account with at least one workspace created

Connection Steps

1. Log in to the Nuvei Control Panel.
2. Navigate to Settings > Merchant Sites and select your site.
3. Note your Merchant ID and Merchant Site ID (visible at the top of the page).
4. Navigate to Settings > My Account > API Keys (or request your Secret Key from your Nuvei account manager if it is not visible in the Control Panel).
5. Copy your Secret Key.
6. In your LostChurn dashboard, go to Settings > Integrations and click Connect Nuvei.
7. Enter your Merchant ID, Merchant Site ID, and Secret Key.
8. Select your environment: Integration (Test) or Production.
9. Click Save and Verify. LostChurn makes a test API call (getSessionToken) to confirm the credentials are valid.

Webhook Configuration

Nuvei uses Direct Merchant Notifications (DMN) to push transaction results to your server.

1. In the Nuvei Control Panel, navigate to Settings > Merchant Sites and select your site.
2. Under DMN (Direct Merchant Notifications), locate the Notification URL field.
3. Set the Notification URL to:

   https://webhooks.lostchurn.com/v1/nuvei

4. Enable the following notification types (if configurable):
   • Payment notifications (approvals and declines)
   • Subscription notifications (creation, update, cancellation)
   • Refund notifications
   • Chargeback notifications
5. Click Save.

Alternatively, contact your Nuvei account manager to configure the DMN URL on your behalf if the self-service option is not available for your account.

DMN Verification

Nuvei DMN notifications include an advanceResponseChecksum field in the JSON body. The checksum is a SHA-256 hash of the concatenation: secretKey + merchantId + merchantSiteId + TransactionID + totalAmount + currency. LostChurn recomputes this checksum using your Secret Key and compares it against the provided value using a timing-safe comparison. Notifications with missing or invalid checksums are rejected with a 401 response.

Verify Connection

1. Nuvei does not provide a built-in "send test notification" button in the Control Panel.
2. To verify the connection, process a test transaction in the Nuvei Integration (test) environment:
   • Use the Nuvei Cashier or API to process a payment with one of Nuvei's test card numbers:
     • Card 4000027891380961 with amount 1.00 to simulate a successful payment.
     • Card 4000023104662535 with amount 1.00 to simulate a soft decline.
3. In your LostChurn dashboard, navigate to Events and confirm the transaction event appears.

A successful connection shows a green Connected badge on the Nuvei card in Settings > Integrations.

Supported Events

Provider-Specific Notes

Integration vs. Production Environment

Nuvei provides two environments:

• Integration (ppp-test.nuvei.com): Test transactions with simulated processing. No real charges.
• Production (secure.safecharge.com): Real transactions with real payment methods.

Each environment requires its own credentials. Connect both to LostChurn to test your recovery configuration before going live.

Decline Reason Codes

Nuvei provides both gateway-level and processor-level decline reasons. LostChurn maps these to its internal taxonomy:

• Decline: Generic soft decline, retry eligible after delay.
• Insufficient Funds: Retry on a different day.
• Expired Card: Triggers dunning email for payment method update.
• Do Not Honor: Issuer decline, retry eligible after delay.
• Restricted Card: Triggers dunning email requesting alternative payment method.
• Fraud Suspicion: No automatic retry, flagged for merchant review.

The gwErrorReason and paymentMethodErrorReason fields in DMN payloads provide the most specific decline information. LostChurn uses both to determine the optimal recovery strategy.

Rebilling (Recurring Payments)

Nuvei handles recurring payments through its Rebilling feature. Key considerations:

• Rebilling plans are managed through Nuvei's API or Control Panel.
• LostChurn monitors rebilling payment outcomes via DMN notifications.
• When a rebilling payment fails, LostChurn can initiate a retry using Nuvei's payment API with the stored User Payment Option (UPO).

User Payment Options (UPO)

Nuvei stores customer payment methods as User Payment Options (UPOs). When executing retries, LostChurn references the customer's UPO to charge their stored payment method without requiring re-entry of card details.

Alternative Payment Methods

Nuvei supports a wide range of alternative payment methods (APMs) beyond cards, including e-wallets, bank transfers, and local payment methods. LostChurn processes failures from all payment methods but retry capabilities may vary:

• Cards: Full retry support.
• E-wallets (Skrill, Neteller, etc.): Retry depends on the wallet provider's API.
• Bank transfers: Typically no automated retry; dunning email directs customer to initiate a new payment.

Rate Limits

Nuvei recommends keeping API requests under 50 per second. LostChurn throttles retry attempts to stay within this limit. For high-volume merchants, Nuvei can provision higher rate limits upon request. Contact your Nuvei account manager and LostChurn support to coordinate.

Cashier Integration

If you use Nuvei's hosted Cashier for payment collection, LostChurn can generate a pre-authenticated Cashier link for dunning emails, allowing customers to update their payment method through Nuvei's hosted page rather than entering details directly on your site.

Automatic Payment Retry

LostChurn can automatically retry failed Nuvei payments using the server-to-server Payment API. Key details:

• Retry method: Executes a payment via POST /ppp/api/v1/payment using the stored User Payment Option (UPO).
• UPO support: Uses the userPaymentOptionId from the original failed transaction. Ensure UPO tokenization is enabled in your Nuvei account.
• Authentication: Uses SHA-256 checksum verification (concatenation of merchantId, merchantSiteId, clientRequestId, amount, currency, timestamp, and secret key).
• Decline handling: Retry eligibility is determined by the gwErrorReason and gwExtendedErrorCode. Generic declines and insufficient funds are retry-eligible; expired card and fraud-related declines trigger dunning only.
• Gateway cascade: Nuvei participates in LostChurn's multi-gateway cascade. If a retry fails on Nuvei, the system can automatically attempt recovery through another connected PSP.
• APM retries: Card-based UPOs support full automatic retry. E-wallet and bank transfer failures fall back to dunning communications with a payment update link.