Your journey begins by exchanging gateway credentials for a middleware token. This token (x-credentials) authenticates all subsequent requests for that specific gateway.

1. Call GET /api/gateway/list to find the exact system name for your gateway (e.g., "ncpv1").
2. Fetch the settings template with GET /api/{gateway_name}/settings. This shows the exact fields required to build your settings profile in the next step.
3. Submit your completed settings profile to POST /api/gateway/credentials and collect your middleware token from the response.
4. Cache the returned x-credentials token and refresh every 20 minutes to keep alive if unused. If token is used at least once per 20 minutes, there is no expiration.
• When using this site's API toolkit to send a credentails request, your token will be automatically saved as a variable for use in subsequent test calls across the API Explorer.
5. It is also suggested that integrators fetch and cache paymentMethods for the active gateway using /api/paymentmethod. Refresh periodically or on invalidation - never hard-code values.
• Note that paymentMethod is sent in all calls which setup a user interface for user payment to determine which interface to present.

This is the fundamental first step: exchange your gateway settings for a middleware token that you will use globally.

This workflow demonstrates a common credit card transaction that includes an automatically calculated surcharge via InterPayments.

1. Obtain your x-credentials token (with InterPayments) for your gateway (NCP in this example), ensuring the InterPayments fields are included in your settings profile.
2. (Optional) Pre-calculate the fee for customer disclosure using POST /api/surcharge/compute.
3. Request a hosted UI for user payment account entry with /api/transaction/processtransaction
   1. set amount and subtotalAmount accordingly
   2. set surchargeAmount to null (calculated/added automatically)
   3. set paymentMethod to the desired value from your cached gateway paymentMethod values
   4. set customerID and other billing details to further customize the user experience.
   5. set isConfirm=false to auto-close the iFrame at the end of the transactions or set isConfirm=true to keep it open (read only) and close as part of your workflow.
   • Regardless of the value set for isConfirm, the same response payload will still be sent through the iFrame message.
4. Use Reports - Inquire to retrieve the final transaction status and confirm the persisted surchargeAmount.

To trigger surcharge calculation, send subtotalAmount and set surchargeAmount: null in your Authorization request.

This workflow enables end-users to save (tokenize) a payment method for later authorization

1. Prompt user to enter payment method for vault storage using Account - Save.
   • Be sure to include the correct postal/ZIP code for accurate surcharge calculations.
2. Authorize vaulted payment method at a later time Process - Transaction.
• Use your gateway's "cc token" equivalent paymentMethod value to set paymentMethod in the request body.
• Set transactionType to "capture"
3. Confirm final status and amounts by calling Reports - Inquire.

The postal/ZIP code stored on the profile impacts surcharge outcomes for token-based payments.

Alternative Payment Method (APM) availability varies by gateway and a host of other factors. Please call api/gateway/paymentMethods to confirm values and availability for all paymentMethods.

1. Launch the hosted UI via POST ProcessTransaction, specifying the APM required in the request body and present the URL or HTML response to the user in an iFrame to complete payment.
2. The user completes the payment flow within the hosted UI.
3. Call GET Reports - Inquire to get the final, persisted transaction status and details from the middleware.

The SEPA flow remains in the same popup/iframe. Some other APMs may open a second window.

After a transaction is complete, you may need to reverse it. The correct action depends on whether the transaction has been settled.

1. If the transaction has not yet settled, reverse it using the appropriate Void endpoint (e.g., PayaConnect Void or NCP Void).
2. If the transaction has already settled, you must issue a Refund (e.g., PayaConnect Refund or NCP Refund).
3. In either case, use the Inquire endpoint (e.g., PayaConnect Inquire or NCP Inquire) to confirm the final status and amounts.

The middleware uses a two-layer response system. Your code should first check for middleware-level errors before parsing the gateway's response.

Layer 1: Middleware Validation Errors

These errors occur if your request fails initial validation before it can be sent to the gateway.

• 401 Unauthorized: Your x-credentials token is missing or invalid.
  Action: Ensure you are sending a valid token in the x-credentials header. Generate a new one if necessary.
• 422 Unprocessable Entity: Your request is valid JSON, but a required field is missing or a value has the wrong format. The response body will detail the specific error.
  Action: Correct the field(s) named in the error message and retry the request.
• 400 Bad Request: Your request body is not well-formed JSON.
  Action: Check your JSON for syntax errors like missing commas, quotes, or brackets.

Layer 2: Gateway Responses

If your request passes middleware validation, it is sent to the gateway. The middleware passes the gateway's response back to you transparently.

• 200 OK: The gateway successfully processed the request.
  Action: Parse the response body for the gateway's specific success payload, which includes the transactionID and final status.
• 402 Payment Required: The gateway rejected the transaction. The response body will contain the gateway's specific error message (e.g., "Declined," "Invalid Card Number").
  Action: Parse the gateway's error message and handle it appropriately (e.g., display a message to the user).

Certifying your Nuvei Payment Middleware integration ensures your ISV solution can securely and reliably execute all required transaction operations, in full compliance with Nuvei guidelines. Before production enablement, each essential transaction type included in your integration must be tested and certified.

Required Transaction Types for Certification

• Tokenization: Test transactions where sensitive card data is replaced with secure tokens for storage and future use, enhancing security and compliance.
• Authorization: Validate that a customer's payment method is active and has sufficient funds or credit. This step reserves the amount but does not transfer funds.
• Capture: Complete the payment by transferring reserved funds after authorization. Some gateways combine authorization and capture; others allow them separately.
• Sale (Auth + Capture): Combines authorization and capture in a single step, typically used for instant delivery of goods or services.
• Refund: Return funds to the customer after a completed sale. Test both full and partial refunds to ensure flexibility.
• Void: Cancel a previously authorized payment before capture—useful if an order is canceled before fulfillment.
• Reversal: Similar to a void, but may apply after settlement depending on the payment network. Important for dispute resolution and error correction.
• Declined Transaction: Simulate scenarios where payments are declined due to insufficient funds, expired cards, or incorrect data.
• 3DS Transaction Testing:

  • "Force Challenge" transaction with amount set to 151
  • "Frictionaless" transaction with cardholder name set to "CL‑BRW1"
  • "For more details on 3DS testing, see the sandbox testing section of this quickstart guide.
• Interpayments Surcharge Testing:

  • Credit Card transactions with expected surcharge
  • Debit Card transactions (no surcharge expected)

Note: Each transaction type relevant to your integration must be successfully tested and certified before production deployment.

Sandbox Testing & Gateway Alignment

While the Payment Middleware consolidates and simplifies many functions across gateways, transaction testing in sandbox environments requires alignment with each gateway's testing practices and test values. This section centralizes the essential test data and scenarios that integrators need across gateways.

Why It Matters

Validating that all transactions and related operations sent via Payment Middleware are received, recorded, and (when applicable) settled by your payment gateway protects against mapping errors, field mismatches, or lost webhooks and ensures that what your application sends is exactly what your gateway processes. Remember, the Payment Middleware is designed to centralize, streamline, and enhance your connection to the destination gateway and only knows which response was recieved for your request.

Path: api/Transaction/ProcessTransaction Open in SDK Studio

Path: api/Account/Save