On this page:

Overview

Nuvei supports transactions with cards that can be used with a global card scheme and with a national card scheme or network. For example, in Belgium, Bancontact cards that are co-badged with Visa or with Mastercard/Maestro.

Card Scheme Transaction Type Support

	Mastercard	Bancontact (Belgium)
Sale
Auth
Pre-Authorization
Zero Authorization
Void
Refund
Payout		Only REST API
OCT
AFT	Only in the EU

If the national card scheme does not support the transaction type, Nuvei automatically processes the transaction with the global scheme. Also, for example, Bancontact can only process transactions in EUR.

Implementation

The following Nuvei integration methods support co-badged card transactions:

REST API
Web SDK with Nuvei Fields Payments
Simply Connect Payments

For test card data, see Testing Cards.

REST API

Payment (Deposit) Flow

Follow these steps to perform a payment with a co-badged card using Nuvei REST API integration:

1. Generate a `sessionToken`

Press here for details.

2. Render a Payment Form

Render a form on the merchant’s payment page that collects card details.

Send a /getCardDetails API request. If the response includes secondaryBrand, allow the user to select the brand with which to process the payment. If the merchant is using 3D-Secure authentication values received from an external MPI (3rd-Party) provider, do not allow the user to select a brand.

If the user chooses an existing UPO associated with a co-badged card, allow the user to change the preferred brand.

3. (Optional) Initialize 3D-Secure

If you are not using a 3D-Secure flow, then skip to sending a /payment request.

Send an /initPayment request with its mandatory parameters and either full card details or an existing UPO. In either case, include the paymentOption.card class with selectedBrand. Make sure the selectedBrand supports the specified currency.

Example `/initPayment` Request – Full Card Details

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in your system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "currency": "EUR",
  "amount": "200",
  "paymentOption": {
    "card": {
      "cardNumber": "<Co-badged Bancontact card number>",
      "cardHolderName": "CL-BRW1",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "CVV": "217",
      "selectedBrand": "Bancontact",
      "threeD": {
        "methodNotificationUrl": "<methodNotificationURL>"
      }
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  }
}

The response includes processedBrand.

Example `/initPayment` Response

{
  "orderId": "276984098",
  "userTokenId": "<unique customer identifier in your system>",
  "transactionId": "1110000000011280648",
  "transactionType": "InitAuth3D",
  "transactionStatus": "APPROVED",
  "gwErrorCode": 0,
  "gwExtendedErrorCode": 0,
  "paymentOption": {
    "card": {
      "ccCardNumber": "4****0961",
      "bin": "400002",
      "last4Digits": "0961",
      "ccExpMonth": "12",
      "ccExpYear": "30",
      "cardType": "Credit",
      "issuerCountry": "BE",
      "processedBrand": "Bancontact",
      "threeD": {
        "methodUrl": "https://3dsn.sandbox.nuvei.com/ThreeDSMethod/api/ThreeDSMethod/threeDSMethodURL",
        "version": "2.1.0",
        "v2supported": "true",
        "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjMzY2I0ODA0LTA0YmQtNDRhOC1hNmYzLTIxMjRmMDUwM2M3MSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
        "directoryServerId": "A000000003",
        "directoryServerPublicKey": "rsa;MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAst+HGfPPsX3p6HHEQ9YzourlQj16Nscmm13Cp7cZe4dZB2oWnJqZ7oh/pEoEoOAxBw1x4NFgXKTKdHAeu3VBNVw8SwMTdIC+X16VV+3VIyPbUvJXFp3QoR8WUwPB3F1Lb9SMFNS95boYDZKIOdPW0cP1dRi7pFugsBUZDCP/H3nFfBFHMCBoga+P3AHGj5y8RVpv0hS9jaIsYjX+i58B61OGCB7D0AiADNZJuFzw2+xpNkt6NJJF66FPO8qIh8xR2xGVDf7TtCbss/CugLRgSqKab9YRB8/TBTcy5bxj6O8HD6aL2zGLcMY9dCobXxCodLEtMjJdVL8N+iZrsI2gtwIDAQAB",
        "serverTransId": "33cb4804-04bd-44a8-a6f3-2124f0503c71"
      }
    }
  },
  "customData": "",
  "sessionToken": "3b2126a2-6778-4214-a8c4-269915d5b1e4",
  "internalRequestId": 234842078,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "427583496191624621",
  "merchantSiteId": "142033",
  "version": "1.0",
  "clientRequestId": "20210125143714"
}

4. Send a `/payment` Request

Send a /payment request with its mandatory parameters and either full card details or an existing UPO. In either case, include the paymentOption.card class and paymentOption.card.selectedBrand.

Example `/payment` Request – Full Card Details for 3D-Secure v2

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "EUR",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "paymentOption": {
    "card": {
      "cardNumber": "<Bancontact co-badged card number>",
      "cardHolderName": "CL-BRW1",
      "expirationMonth": "12",
      "expirationYear": "2030"
      "selectedBrand": "Bancontact",
      "threeD": {
        "methodCompletionInd": "Y",
        "version": "2.1.0",
        "notificationURL": "<notificationURL>",
        "merchantURL": "<merchantURL>",
        "platformType": "02",
        "v2AdditionalParams": {
          "challengeWindowSize": "05"
        },
        "browserDetails": {
          "acceptHeader": "text/html,application/xhtml+xml",
          "ip": "192.168.1.11",
          "javaEnabled": "TRUE",
          "javaScriptEnabled": "TRUE",
          "language": "EN",
          "colorDepth": "48",
          "screenHeight": "400",
          "screenWidth": "600",
          "timeZone": "0",
          "userAgent": "Mozilla"
        }
      }
    }
  },
  "relatedTransactionId": "<transactionId returned from initPayment>",
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "BE",
    "email": "[email protected]"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "address": "22 Main Street",
    "city": "Brussels",
    "country": "BE",
    "email": "[email protected]",
    "phone": "323094526617",
    "zip": "1000",
    "dateOfBirth": "2000-06-30",
    "gender": "Male"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response includes processedBrand.

Example `/payment` Response

{
  "internalRequestId": 80296351849,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "5555385017539610145",
  "merchantSiteId": "288139",
  "version": "1.0",
  "clientRequestId": "Pay1-0722.182826",
  "sessionToken": "9f3ab64d-2fd9-478d-9b82-abf24fe5a13e",
  "clientUniqueId": "Pay-0722.1828",
  "orderId": "65168189559",
  "userTokenId": "Kc-01",
  "paymentOption": {
    "userPaymentOptionId": "4358108418",
    "card": {
      "ccCardNumber": "6****6004",
      "bin": "670307",
      "last4Digits": "6004",
      "ccExpMonth": "12",
      "ccExpYear": "30",
      "acquirerId": "512",
      "cvv2Reply": "",
      "avsCode": "",
      "cardType": "Debit",
      "cardBrand": "VISA",
      "issuerBankName": "BELFIUS BANK N.V. / BELFIUS BA",
      "issuerCountry": "BE",
      "processedBrand": "Bancontact",
      "isPrepaid": "false"
    }
  },
  "transactionStatus": "REDIRECT",
  "gwErrorCode": 0,
  "gwExtendedErrorCode": 0,
  "issuerDeclineCode": "",
  "issuerDeclineReason": "",
  "transactionType": "Auth3D",
  "transactionId": "1120000001657324139",
  "externalTransactionId": "",
  "authCode": "",
  "customData": "",
  "externalSchemeTransactionId": "",
  "merchantAdviceCode": ""
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request. The DMN includes secondaryCardBrand, selectedCardBrand, and processedCardBrand.

Example Payment DMN for Co-badged Card

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43342601&userid=MXKB1IAZ2EGG&merchant_unique_id=695701003&customData=&productId=O01P6N29ADQ5&first_name=John&last_name=Smith&email=john.smith%40email.com&currency=EUR&pmDisplayName=6****8026&clientUniqueId=695701003&cardType=Debit&isPrepaid=false&cardIssuerCountry=BE&customField1=customField1-valueU&customField2=customField2-valueU&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=221B+Baker+Street&address2=&country=BE&state=&city=Brussels&zip=1000&phone1=323094526617&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=CL-BRW1&cardNumber=6****6004&bin=670375&noCVV=&acquirerId=99&acquirerBank=Nuvei+Acquirer+-+MasterCard&expMonth=12&expYear=30&Token=ZgBlAEcAUAAwAG4AZABkADAAbgBQADAAcABxAG0AMgBJAFQAUABUAEsAMAA4AGsAXgBNAFgAdABpADUAdABZAGIAUgB0ACUAQwA5AE8ATABQACcAeAAvAGIASAB1ADIAVgBYADcAMwA%3D&tokenId=222207473&AuthCode=470110&AvsCode=S&Cvv2Reply=M&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=2024-07-05.12%3A23%3A00&buyButtonProductId=&webMasterId=H3OXP1Q7HZ3H&appliedPromotions=&uniqueCC=tLrP2elAk%2FMe1q8w7n0reTbb9D0%3D&transactionType=Auth&externalEmail=&cardCompany=Maestro&user_token_id=MXKB1IAZ2EGG&userPaymentOptionId=2153280701&TransactionID=2110000000014283503&externalAccountDescription=nameOnCard%3ACL-BRW1&finalFraudDecision=Accept&fraudScore=0&totalAmount=35.0&dynamicDescriptor=Darin+Cashier+API+U&item_name_1=Item+1U&item_number_1=&item_amount_1=35.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=&maskedNetworkTokenNumber=&upoRegistrationDate=20240705&shippingCounty=&type=DEPOSIT&autoSettleMode=TIME&clientRequestId=HJL20J87N&relatedTransactionId=&secondaryCardBrand=BancontactCard&selectedCardBrand=BancontactAcquirer&processedCardBrand=BancontactAcquirer&lastFourDigits=6004&responsechecksum=b7032891cea1e079bede5f544afc459b&advanceResponseChecksum=bac3c78b2b0f4663e35b1bcb162cb667',

Merchant-Initiated Transactions (MITs)

If Nuvei is processing the initial MIT, the merchant provides selectedBrand in the /initPayment and /payment requests.
If Nuvei is processing a subsequent MIT transaction and also processed the initial transaction, the merchant does not need to provide selectedBrand in the subsequent transaction.
If another payment service provider (PSP) processed the initial transaction, the card scheme determines whether Nuvei can process a subsequent MIT transaction. For example, Bancontact does not support Nuvei processing a subsequent MIT transaction when another PSP processed the initial transaction.

For more information about MITs, see Merchant-Initiated Transactions (MITs).

Payout (Withdrawal) Flow

Follow these steps to perform a payout with a co-badged card using Nuvei REST API integration:

1. Render a Payout Form

Render a form on the merchant’s payout page that collects card details.

Send a /getCardDetails API request. If the response includes a secondaryBrand, allow the user to select the brand with which to process the payout.

If the user chooses an existing UPO associated with a co-badged card, allow the user to change the preferred brand.

2. Send a `/payout` Request

Send a /payout request with its mandatory parameters and either full card details or an existing UPO. In either case, include the cardData class and cardData.selectedBrand.

Example `/payout` Request – Full Card Details

{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique user identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "EUR",
  "cardData": {
    "cardNumber": "<Bancontact co-badged card number>",
    "cardHolderName": "CL-BRW1",
    "expirationMonth": "12",
    "expirationYear": "2030"
    "selectedBrand": "Bancontact"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response includes processedBrand.

Example `/payout` Response

{
  "userTokenId": "EV013",
  "clientUniqueId": "20230329125742",
  "transactionStatus": "APPROVED",
  "gwErrorCode": 0,
  "gwExtendedErrorCode": 0,
  "userPaymentOptionId": "80244118",
  "externalTransactionId": "",
  "transactionId": "711000000021780909",
  "cardData": {
    "acquirerId": "19",
    "visaDirect": "NO",
    "processedBrand": "Bancontact"
  },
  "internalRequestId": 639118498,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "979047831696752006",
  "merchantSiteId": "217268",
  "version": "1.0"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request. The DMN includes secondaryCardBrand, selectedCardBrand, and processedCardBrand.

Example Payout DMN for Co-badged Card

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43342601&userid=MXKB1IAZ2EGG&merchant_unique_id=695701003&customData=&productId=O01P6N29ADQ5&first_name=John&last_name=Smith&email=john.smith%40email.com&currency=EUR&pmDisplayName=6****8026&clientUniqueId=695701003&cardType=Debit&isPrepaid=false&cardIssuerCountry=BE&customField1=customField1-valueU&customField2=customField2-valueU&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=221B+Baker+Street&address2=&country=BE&state=&city=Brussels&zip=1000&phone1=32475388403&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=CL-BRW1&cardNumber=6****8026&bin=670375&noCVV=&acquirerId=99&acquirerBank=Nuvei+Acquirer+-+MasterCard&expMonth=12&expYear=25&Token=ZgBlAEcAUAAwAG4AZABkADAAbgBQADAAcABxAG0AMgBJAFQAUABUAEsAMAA4AGsAXgBNAFgAdABpADUAdABZAGIAUgB0ACUAQwA5AE8ATABQACcAeAAvAGIASAB1ADIAVgBYADcAMwA%3D&tokenId=222207473&AuthCode=470110&AvsCode=S&Cvv2Reply=M&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=2024-07-05.12%3A23%3A00&buyButtonProductId=&webMasterId=H3OXP1Q7HZ3H&appliedPromotions=&uniqueCC=tLrP2elAk%2FMe1q8w7n0reTbb9D0%3D&transactionType=Auth&externalEmail=&cardCompany=Maestro&user_token_id=MXKB1IAZ2EGG&userPaymentOptionId=2153280701&TransactionID=2110000000014283503&externalAccountDescription=nameOnCard%3ACL-BRW1&finalFraudDecision=Accept&fraudScore=0&totalAmount=35.0&dynamicDescriptor=Darin+Cashier+API+U&item_name_1=Item+1U&item_number_1=&item_amount_1=35.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=&maskedNetworkTokenNumber=&upoRegistrationDate=20240705&shippingCounty=SCountyU&type=DEPOSIT&autoSettleMode=TIME&clientRequestId=HJL20J87N&relatedTransactionId=&secondaryCardBrand=BancontactCard&selectedCardBrand=BancontactCard&processedCardBrand=BancontactCard&lastFourDigits=8026&responsechecksum=b7032891cea1e079bede5f544afc459b&advanceResponseChecksum=bac3c78b2b0f4663e35b1bcb162cb667',

Additional API Methods

These API methods support paymentOption.card.selectedBrand:

/authorize3d – See 3DS MPI-Only REST implementation.
/refundTransaction – Nuvei supports co-badged cards for Unreferenced Refunds.

Responses to these methods support processedBrand and DMNs for them support secondaryCardBrand, selectedCardBrand, and processedCardBrand.

Web SDK with Nuvei Fields Payments

To perform a payment with a co-badged card using Nuvei Web SDK with Nuvei Fields integration:

After a user selects card payment and enters a card number, send a getCardDetails () Web SDK method request. If the response includes secondaryBrand, allow the user to select the brand with which to process the payment.
If the user selects an existing UPO associated with a co-badged card, allow the user to change the preferred brand.
Send the createPayment() Web SDK method request with selectedBrand.

Example `createPayment ()` Request

sfc.createPayment({
  sessionToken: sessionData.sessionToken,
  selectedBrand: "BancontactAcquirer",
  cardHolderName: document.getElementById('cardHolderName').value,
  "paymentOption": cardNumber,
}, function(res) {
  console.log(res)
})

Simply Connect Payments

If the merchant is using the Simply Connect integration method for payments, use Simply Connect payment customization to enable presenting both brands of co-badged cards on the payment page. When enabled, Nuvei handles the co-brand logic.

For co-badged cards, responses to the checkout.getCardDetails() Simply Connect method include secondaryBrand.

Testing Cards

To test a merchant’s integration for supporting co-badged cards, you can use the following cards in the Nuvei integration environment.

Bancontact Co-badged Test Cards

Issuer Name	Card Number	Expiration Date
Belfius	6703 0510 0219 0500 6	Dec-26
Belfius	6703 0510 0219 0400 9	Dec-26
Beobank	6703 9500 0174 1700 0	Jun-26
Beobank	6703 9500 0174 2200 0	Jun-26
Crelan	6703 1030 3178 7402 1	Jun-27
Bank van Breda	6703 6459 1548 1200 7	Feb-27
Nagelmackers	6703 6369 0000 0000 6	Dec-24
Nagelmackers	6703 6369 0000 0305 9	Dec-24
Аха	6703 7509 3120 2611 1	Dec-26
Аха	6703 7509 4388 4801 8	Dec-26
Аха	6703 7509 4388 4802 6	Dec-26
Deutsche Bank	6703 6118 2742 2001 8	Feb-27

For more information about testing cards, see Testing Cards.

Co-badged Cards

Overview

Card Scheme Transaction Type Support

Implementation

REST API

Payment (Deposit) Flow

1. Generate a sessionToken

2. Render a Payment Form

3. (Optional) Initialize 3D-Secure

Example /initPayment Request – Full Card Details

Example /initPayment Response

4. Send a /payment Request

Example /payment Request – Full Card Details for 3D-Secure v2

Example /payment Response

Example Payment DMN for Co-badged Card

Merchant-Initiated Transactions (MITs)

Payout (Withdrawal) Flow

1. Render a Payout Form

2. Send a /payout Request

Example /payout Request – Full Card Details

Example /payout Response

Example Payout DMN for Co-badged Card

Additional API Methods

Web SDK with Nuvei Fields Payments

Example createPayment () Request

Simply Connect Payments

Testing Cards

Bancontact Co-badged Test Cards

1. Generate a `sessionToken`

Example `/initPayment` Request – Full Card Details

Example `/initPayment` Response

4. Send a `/payment` Request

Example `/payment` Request – Full Card Details for 3D-Secure v2

Example `/payment` Response

2. Send a `/payout` Request

Example `/payout` Request – Full Card Details

Example `/payout` Response

Example `createPayment ()` Request