Secure Limit Management: disable/enable spend/ATM limits.

Update Card Security settings

Card transaction capabilities can be enabled or disabled for an individual card for security reasons or according to the cardholder’s preferences.

Card security controls are managed using the Update Card Security Settings API.

This functionality is separate from the Update Card Limits API:

Update Card Security Settings API — enables or disables specific transaction categories.
Update Card Limits API — defines the monetary limits applicable to those transaction categories.

Available Security Settings

The following card security settings can be managed:

contactlessPayments — enables or disables contactless payments.
withdrawals — enables or disables cash withdrawals.
internetPurchases — enables or disables internet purchases.
overallPurchases — enables or disables application of the card’s overall purchase limits.

When a transaction category is disabled, transactions belonging to that category cannot be performed regardless of the monetary limits configured for the card.

Supported Card Statuses

Standard flow only allowed in statuses:

???????

Standard Configuration

In the standard White Label card program configuration, Overall Purchases are disabled at program level. Therefore, overallPurchases does not normally need to be included in the request.

ChipAndPin Card

For a ChipAndPin card, the following security settings can be updated:

{
  "contactlessPayments": {
    "enable": true
  },
  "withdrawals": {
    "enable": true
  },
  "internetPurchases": {
    "enable": true
  }
}

Set enable to:

true — enable the transaction category.
false — disable the transaction category.

Virtual Card

For a Virtual card, the standard request contains:

{
  "contactlessPayments": {
    "enable": true
  },
  "internetPurchases": {
    "enable": true
  }
}

The withdrawals setting is not applicable to the standard Virtual card configuration.

Overall Purchases

Some card programs may have Overall Purchases enabled.

In this configuration, the overallPurchases object must also be included when updating card security settings:

{
  "overallPurchases": {
    "enable": true
  }
}

When overallPurchases is enabled, the values configured under overallLimits using the Update Card Limits API become applicable.

Overall Purchase limits act as the overarching purchase restriction for the card and take precedence over the individual purchase-limit categories.

For example, a transaction may still be restricted by the Overall Purchase limit even when the applicable category-specific limit has not been reached.

Note: The availability of overallPurchases depends on the configuration of the card program. In the standard White Label setup, Overall Purchases are disabled.

Internet Purchases and 3DS Dependency

Enabling internetPurchases has an additional security dependency.

Before internet purchases can be enabled, the cardholder must configure the card’s 3D Secure settings using the Update Card 3DS Security Settings API.

This includes setting the 3DS password that may later be used as part of the cardholder authentication flow for internet purchases.

The required sequence is:

Card activated → Configure 3DS security settings → Enable internetPurchases

If the required 3DS password has not been configured, an attempt to enable internetPurchases using the Update Card Security Settings API will return an error.

Default Internet Purchase Setting

internetPurchases are disabled when the card is created.

Therefore, applications should not attempt to enable internet purchases immediately after card creation.

The recommended flow is:

Create the card.
Wait until the card reaches the required active status.
Configure the card’s 3DS security settings.
Enable internetPurchases.
Configure the required Internet Purchase limits using the Update Card Limits API, if applicable.

Developer tip: Enabling a transaction category and configuring its monetary limits are separate operations. A category may have limits configured but still be unavailable if the corresponding security setting is disabled.

3DS Security Settings: How to manage 3D Secure configurations.

Update Card 3DS security settings

Card 3D Secure (3DS) security settings can be configured using the Update Card 3DS Security Settings API.

The API can be used both to set the 3DS security settings initially and to update existing settings.

Important: 3DS security settings must be configured for cards that are intended to be used for internet purchases.

3DS Password Requirements

When a 3DS password is configured, it must meet the following requirements:

Length: 8–36 characters
Uppercase letters: A–Z
Lowercase letters: a–z
Digits: 0–9
Supported special characters:
! " # : ; ? * ( ) + = / \ , . [ ] { }
Spaces are not allowed

The existing 3DS password cannot be retrieved. The API supports setting or replacing the password, but there is no Get Password operation.

Identity Verification

No additional Identity Verification (IDV) is required when the 3DS settings are managed from an authenticated mobile application flow where the cardholder has already completed the required identity verification during login.

The Partner is responsible for ensuring that access to this functionality is available only to an appropriately authenticated cardholder.

Supported Card Statuses

The Update Card 3DS Security Settings API can only be used when the card is in a supported status.

Supported statuses: To be updated.

If the card is in a status that does not support updating 3DS settings, the request will not be processed.

Testing

3DS functionality cannot be fully tested in the Sandbox environment.

End-to-end 3DS authentication and related cardholder verification flows must be tested in Production using an agreed production testing approach.

3DS SMS Template

When SMS-based 3DS verification is used, the following template can be used for the One-Time Password (OTP) notification:

Verification code: {{otp}}. Use it to authorize payment to {{merchant_name}} for {{amount}} {{currency}} on {{purchase_date}} with card ending in {{last_four_digits}}.

For White Label programs, the SMS template may be localized into the language used for the cardholder experience. But only one language per One white label program. One program does not support 2 or more languages for SMS messaging.

Supported 3DS Languages for White Label Programs

The following languages are supported:

Czech
Danish
Dutch
English
Estonian
Finnish
French
German
Italian
Latvian
Lithuanian
Polish
Portuguese
Russian
Spanish
Swedish

Language Selection

The 3DS language should be selected according to the cardholder’s configured language, device settings, and regional preferences.

If the exact requested language is not available, an appropriate supported language for the cardholder’s region should be selected.

A specific language may also be configured where required by the White Label program.

PIN Management: Secure PIN retrieval or resets.

GET PIN (Only ChipAndPin)

The card PIN can be retrieved using the Get Card PIN API. The same RSA encryption mechanism is also used to protect sensitive card data returned by the following APIs:

Get Card PIN — Chip & PIN cards
Get CVV — Virtual and Chip & PIN cards
Get Card Number — Virtual and Chip & PIN cards

The API encrypts sensitive card data using an RSA public key supplied by the customer.

To use these APIs:

Generate an RSA public/private key pair.
Provide the Base64-encoded public key in the API request.
Keep the private key securely on your side.
Use the private key to decrypt the encrypted value returned by the API.

Important: Never send or expose the private key. It must remain securely stored by the customer.

Request Sample

{
  "publicKey": "xxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxxxxxxxx*Public_*Key_xxxx"
}

Generate the RSA Key Pair

The following Java example generates a 2048-bit RSA key pair.

The generated public key is encoded in Base64 and wrapped in PEM format:

-----BEGIN PUBLIC KEY-----
<Base64-encoded public key>
-----END PUBLIC KEY-----

The complete PEM-formatted public key is then Base64-encoded for use with the API.

The private key is generated in PKCS#8 format and Base64-encoded. Store it securely because it is required to decrypt the API response.

Sample Java Program

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.SecureRandom;
import java.util.Base64;

public class RSAKeyPairExample {

    public static void main(String[] args) throws Exception {

        // Generate a new 2048-bit RSA key pair
        KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
        keyPairGenerator.initialize(2048, new SecureRandom());

        KeyPair keyPair = keyPairGenerator.generateKeyPair();
        PublicKey publicKey = keyPair.getPublic();
        PrivateKey privateKey = keyPair.getPrivate();

        // Convert the public key to PEM format
        String publicKeyPEM =
                "-----BEGIN PUBLIC KEY-----\n"
                + Base64.getEncoder().encodeToString(publicKey.getEncoded())
                + "\n-----END PUBLIC KEY-----";

        System.out.println("Public key:");
        System.out.println(publicKeyPEM);

        // Base64-encode the complete PEM-formatted public key for the API
        System.out.println("Base64-encoded public key:");
        System.out.println(
                Base64.getEncoder().encodeToString(publicKeyPEM.getBytes())
        );

        // Encode the PKCS#8 private key
        String privateKeyPEM =
                Base64.getEncoder().encodeToString(privateKey.getEncoded());

        System.out.println("Private key:");
        System.out.println("-----BEGIN PRIVATE KEY-----");
        System.out.println(privateKeyPEM);
        System.out.println("-----END PRIVATE KEY-----");
    }
}

Decrypt the Encrypted Response

Sensitive card data returned by the API is encrypted using RSA OAEP with SHA-256.

To decrypt the response:

Base64-decode your PKCS#8 private key.
Create an RSA private key using PKCS8EncodedKeySpec.
Base64-decode the encrypted value returned by the API.
Configure RSA OAEP decryption with SHA-256.
Use the appropriate OAEP label for the value being decrypted.
Decrypt the value using your private key.

The OAEP label depends on the type of sensitive data:

PIN: PIN
CVV2: use the CVV2-specific label expected by the API
Card number: use the CardNumber-specific label expected by the API

The label used during decryption must match the label used during encryption.

Sample Java Program — PIN Decryption

The example below decrypts an encrypted PIN using RSA OAEP with SHA-256 and the PIN OAEP label.

import java.nio.charset.StandardCharsets;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.KeyFactory;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.MGF1ParameterSpec;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;

import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.OAEPParameterSpec;
import javax.crypto.spec.PSource;

public class CARDPinDecryption {

    // Private key generated by the customer.
    // Store the key securely and never expose it publicly.
    private static final String PRIVATE_KEY =
            "<BASE64_ENCODED_PRIVATE_KEY>";

    // Encrypted PIN received from the API response.
    // Remove any message headers, footers, or line breaks if applicable.
    private static final String ENCRYPTED_PIN =
            "<BASE64_ENCODED_ENCRYPTED_PIN>";

    public static void main(String[] args)
            throws NoSuchAlgorithmException,
                   InvalidKeySpecException,
                   NoSuchPaddingException,
                   InvalidKeyException,
                   IllegalBlockSizeException,
                   BadPaddingException,
                   InvalidAlgorithmParameterException {

        // Decode the PKCS#8 private key
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");

        byte[] encodedPrivateKey =
                Base64.getDecoder().decode(
                        PRIVATE_KEY.getBytes(StandardCharsets.US_ASCII)
                );

        PKCS8EncodedKeySpec privateKeySpec =
                new PKCS8EncodedKeySpec(encodedPrivateKey);

        PrivateKey privateKey =
                keyFactory.generatePrivate(privateKeySpec);

        // Decode the encrypted PIN
        byte[] encryptedValue =
                Base64.getDecoder().decode(ENCRYPTED_PIN);

        // Configure RSA OAEP with SHA-256
        Cipher cipher =
                Cipher.getInstance("RSA/ECB/OAEPPadding");

        OAEPParameterSpec oaepParams =
                new OAEPParameterSpec(
                        "SHA-256",
                        "MGF1",
                        new MGF1ParameterSpec("SHA-256"),
                        new PSource.PSpecified(
                                "PIN".getBytes(StandardCharsets.US_ASCII)
                        )
                );

        cipher.init(
                Cipher.DECRYPT_MODE,
                privateKey,
                oaepParams
        );

        // Decrypt the PIN
        byte[] decryptedValue =
                cipher.doFinal(encryptedValue);

        System.out.println(
                "PIN Number: "
                + new String(decryptedValue, StandardCharsets.UTF_8)
        );
    }
}

Security Considerations

The RSA private key provides access to highly sensitive cardholder data and must therefore be protected appropriately.

Generate and store the private key in a secure environment.
Never include the private key in API requests.
Never expose the private key in application logs or source-code repositories.
Restrict access to the private key to services that require decryption.
Treat decrypted PIN, CVV2, and card-number values as sensitive cardholder data and avoid logging or persisting them unnecessarily.

Standard flow only allowed in statuses:

???????

Change Pin (Only ChipAndPin)

Availability: The Change Card PIN API is supported only for Chip & PIN cards.

The card PIN can be changed using the Change Card PIN API.

Before sending the request, the new PIN must be encrypted using the permanent RSA public key provided by ConnectPay. Contact your ConnectPay representative to obtain the appropriate public key.

Important: Different public keys are used for PROD and NONPROD environments. Make sure you use the public key corresponding to the environment where the API request is being made.

Sandbox Public Key

MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAz93xoSnH4RoPYFL5uW9TJmgPfittxEAJZmevBqs3yw0gYlldRgQ6L15ssIsNXcE4J6DPLk5l5Xth17a2E00soRZ5S+lMZ04YCtM0lGA+tc7MTXK8OW+85HNoGH7g7hjbrU+BeMyolTocU7wm1Qkl1GIbrKgP5TYA3YT0XCraMvuPhklXwjaCmPXRUWuPDBExrjUSV27rpUk3vacYnyZJMc1SkW6BxQq/+ChhqugmZVPm+9kBo9VGgJnNXJ8KwyCfZ3QJxzxI05KgiWy4lWUKKi7VZegFiBoorXJ4qAgmt0dHMejBumWQXfFuuqbMYmxr/ysSziSBLP6bmF0fJM591NkasBHPUxQoVfXGX2Ddhee7xhqjYamhn5Jwmi2knMCW6q8Fb9u8iuzX/O0DwDCvwQ6Xq+DpRIKgXIKHpqxj8OvSq9/ylTLOQBgO9PoC+WXNO5p58rUMoTpNvMFMOw/BACEXkuX6KuS/7vAxAZfW/gxPrhwx3l16rLwSwEbTWuYQc0f0LW43m2KtNQmV8LocA8Q365yQCEM9nNJdK8nUHI6nVdsa/np3sBNz2rBUtZaLRs7cGVYyciqEBCGe/C777tB2sP8/8KMsijDwwm2WTqmpIC8LeIplVXobglyVRXAAkPGhdYdxl4fQqja/gcnX8fsel7iMLwOXz0HCHyMxpA0CAwEAAQ1==

Production Public Key

MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA5EJa1N976S1k9oPtOK0btc/iVjutjjcRVpCFMjFrHWBu2lR51BJCQ0+IQOm2BhfgN/4mozWM0LqpMLM6St009EZbt13rw9Rkp2zOu8ch289VjzMNrAaC58OhrMj6F/wT8X95gxQ8wXVYk0vzLmo7cG7P8fqsat7VbNO+wTglPrKkp/V/tRXFBThnPo3Co8sVMJ5VYAX+b3W5E54DL7MEPSj4ja5QHoRSMBKPQ3Q5E7TPLu9PgE0EpAx1ECs82GpRd/PNPrwiknjriukVH6/h+m1EyDETi0XETZQo50dtK+ZShpnJw3Si9o0ozfPH1S/r7pR707Od9HC3PeRUJxDnTLApwFp/xKXyk+g+jtoKVGGlb1Y5aCotcvn7ebUORgFfyAPsujrsn3fbAiUH2+2ax3wXJStyl3wX/SH6LXu4T51FsLJ/3ST6mu4b5ltcLaywPTfXapNk69tOd5iyExMTJmugiO2kAdMVE3yXRCug9/JUTTiqC8xWGdzUN6djebYTUZe7IbRAkx1feUyy05EbVpNjisWsxHWfBWxqhJdwLFB37nOqVe0rmTQfZZvbBOslI/gEqp9e11pJCMbZlK2CDenh/jjGG3b3/R7MlDgNwofgo83W8NfEtKQB0mWITIcPr0nK3xJeBx4urwo2+vwA5EFn9+JNimATyl41yZVeTikCAwEAAQ1==

Change pin Sample Body

{
  "encryptedPin": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*EncryptedPin*xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Acceptable PIN change Validation

Two Pin validation rules exist for Change pin:

PIN can’t have same digits
PIN can’t have sequential digits

PIN Change Process

To change a card PIN:

Obtain the appropriate RSA public key from your ConnectPay representative.
Encrypt the new PIN using the provided public key.
Use RSA OAEP with SHA-256 and the PIN OAEP label.
Base64-encode the encrypted value and include it in the Change Card PIN API request.
After the PIN has been changed through the API, perform one successful card operation at a POS terminal or ATM for the change to take effect.

We recommend using an ATM after changing the PIN, as not all POS terminals support PIN change functionality.

Encrypt the New PIN

The following Java example demonstrates how to encrypt a new PIN using the RSA public key provided by ConnectPay.

The encryption uses:

RSA encryption
OAEP padding
SHA-256
MGF1 with SHA-256
OAEP label: PIN

Sample Java Program

package com.connectpay.card.crypto.utils;

import java.nio.charset.StandardCharsets;
import java.security.KeyFactory;
import java.security.PublicKey;
import java.security.spec.MGF1ParameterSpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

import javax.crypto.Cipher;
import javax.crypto.spec.OAEPParameterSpec;
import javax.crypto.spec.PSource;

public class EncryptionProcess {

    public static void main(String[] args) throws Exception {

        // Create an RSA KeyFactory
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");

        /*
         * RSA public key provided by ConnectPay.
         *
         * Different public keys are used for PROD and NONPROD environments.
         * Make sure the correct key is used for the target environment.
         */
        String publicKeyString =
                "<BASE64_ENCODED_PUBLIC_KEY_PROVIDED_BY_CONNECTPAY>";

        // Decode the Base64-encoded public key
        byte[] encodedPublicKey =
                Base64.getDecoder().decode(
                        publicKeyString.getBytes(StandardCharsets.US_ASCII)
                );

        // Create an X.509 public key specification
        X509EncodedKeySpec keySpec =
                new X509EncodedKeySpec(encodedPublicKey);

        // Generate the RSA PublicKey
        PublicKey publicKey =
                keyFactory.generatePublic(keySpec);

        // New PIN to encrypt
        String pinToEncrypt = "9825";

        // Configure RSA OAEP encryption
        Cipher encryptCipher =
                Cipher.getInstance("RSA/ECB/OAEPPadding");

        OAEPParameterSpec oaepParams =
                new OAEPParameterSpec(
                        "SHA-256",
                        "MGF1",
                        new MGF1ParameterSpec("SHA-256"),
                        new PSource.PSpecified(
                                "PIN".getBytes(StandardCharsets.US_ASCII)
                        )
                );

        // Initialize the cipher for encryption
        encryptCipher.init(
                Cipher.ENCRYPT_MODE,
                publicKey,
                oaepParams
        );

        // Encrypt the new PIN
        byte[] encryptedPin =
                encryptCipher.doFinal(
                        pinToEncrypt.getBytes(StandardCharsets.UTF_8)
                );

        // Base64-encode the encrypted PIN
        String encodedPin =
                Base64.getEncoder().encodeToString(encryptedPin);

        System.out.println("Encrypted PIN:");
        System.out.println(encodedPin);

        // Wrap the encrypted value in the PIN message format
        String encryptedPinMessage =
                "-----BEGIN PIN MESSAGE-----\n"
                + encodedPin
                + "\n-----END PIN MESSAGE-----";

        // Base64-encode the complete PIN message for the API request
        String encryptedPinBase64 =
                Base64.getEncoder().encodeToString(
                        encryptedPinMessage.getBytes(StandardCharsets.UTF_8)
                );

        System.out.println("Base64-encoded PIN message:");
        System.out.println(encryptedPinBase64);
    }
}

Encryption Flow

The sample performs the following operations:

Base64-decodes the RSA public key supplied by ConnectPay.
Creates an RSA public key using X509EncodedKeySpec.
Configures RSA encryption with OAEP-SHA256.
Sets the OAEP label to PIN.
Encrypts the new PIN.
Base64-encodes the encrypted value.
Wraps it in the following format:

-----BEGIN PIN MESSAGE-----
<Base64-encoded encrypted PIN>
-----END PIN MESSAGE-----

Base64-encodes the complete PIN message for use in the API request.

PIN Change Latency

PIN changes are processed on different timelines in the Sandbox and Production environments.

In Production, a PIN change may take up to 10 minutes to propagate, although it typically becomes effective within approximately 1 minute. During this propagation period, the Get Card PIN API may continue to return the previous PIN. This latency occurs because the updated PIN information must be propagated across the Visa network and the relevant financial infrastructure.

In Sandbox, propagation takes longer. It may take up to 1 hour before the Get Card PIN API returns the newly updated PIN. Therefore, immediately retrieving the PIN after a successful PIN change may still return the previous value until the update has been fully processed.

After Changing the PIN

A successful Change Card PIN API request alone does not complete the PIN change process.

For the new PIN to take effect, the cardholder must perform one successful operation using the physical card at a:

ATM — recommended: Must Login to the ATM machine with new Pin Code, and execute Balance Check.
POS terminal

Using an ATM is recommended because PIN change functionality is not supported by all POS terminals. This Action is Vital in order to record New Pin to Physical card. After this action car be used in any POS payment station, with new PIN number.

If Pin is changed, but not Confirmed with ATM balance check, Card Will not work for Any transaction where PIN is needed (neither old nor new pin will be working)

Security Considerations

PIN values are sensitive authentication data and should be handled securely throughout the encryption process.

Obtain the RSA public key only through the appropriate ConnectPay channel.
Use the correct public key for the PROD or NONPROD environment.
Never log or persist the PIN in plaintext.
Encrypt the PIN immediately before submitting the API request.
Avoid hardcoding real PIN values in application source code.
Restrict access to components responsible for processing PIN data.
Do not reuse encrypted PIN values, as RSA OAEP encryption is randomized.

Standard flow only allowed in statuses:

???????

Merchant Category Code (MCC) Restrictions

Merchant Category Code (MCC) restrictions allow individual cards to be limited to specific types of merchants.

MCC restrictions are applied on two levels:

Card program level — defines the MCC categories available to cards issued under the card program.
Card level — additional Merchant Rules can be applied to further restrict an individual card.

Card-level Merchant Rules do not extend the MCC categories available at the card program level.

MCC Management APIs

The following APIs are available for managing card-specific Merchant Rules:

Get Card Merchant Rules

Use Get Card Merchant Rules to retrieve Merchant Rules currently configured for a card.

The API returns the card-specific rules that have been created for the card.

It does not return the complete card program MCC configuration or the card’s full effective MCC list.

Developer tip: Use Get Card Merchant Rules before and after making changes to verify the current card-specific configuration.

Add Card Merchant Rule

Use Add Card Merchant Rule to add an MCC restriction to a card.

Each Merchant Rule applies to one MCC. If multiple MCCs must be restricted, a separate API request must be made for each MCC.

For example, restricting five MCCs requires five Add Card Merchant Rule requests.

Merchant Rules should be added only after the card has been successfully created. The recommended readiness confirmation is receiving the first Card Status Changed webhook for the card.

Delete Card Merchant Rule

Use Delete Card Merchant Rule to remove an existing card-specific Merchant Rule.

After changing the configuration, call Get Card Merchant Rules again to verify the resulting rules.

Standard flow only allowed in statuses:

???????

Recommended Integration Flow

The recommended flow for configuring MCC restrictions is:

Card created → Card Status Changed webhook received → Get existing rules → Add/Delete required rules → Get rules again → Verify configuration

When configuring or repairing a card configuration, first retrieve the existing Merchant Rules and apply only the required changes.

Card Program MCC Configuration

The card program contains a predefined global MCC configuration. Every card issued under that program is subject to this configuration.

Card-specific Merchant Rules are used to further narrow the available MCC categories for a particular card.

Changing the global program MCC configuration is not a card-level API operation. If an MCC outside the configured program list needs to become available, the change must be coordinated with ConnectPay and the Card Issuer.

The Card Issuer does not provide an API for retrieving the complete global list of available MCC categories. Changes to this configuration must therefore be coordinated between ConnectPay and the BaaS Partner.

Renewed and Replacement Cards

Card-specific MCC rules are not inherited when a new card is created.

This applies when a new cardId is generated, including card renewal or card replacement.

Merchant Rules required for the new card must therefore be configured again.

Recommended flow:

New card created → Card Status Changed webhook received → Apply required MCC rules → Verify with Get Card Merchant Rules

Declined Transactions

MCC validation is performed in the Card Issuer system before a successful authorization reservation is created.

If a transaction is rejected because of an MCC restriction:

the authorization is stopped by the Card Issuer;
no reservation is created;
the rejected authorization is not forwarded through the standard ConnectPay authorization flow.

The cardholder may receive a generic failed or restricted transaction response at the terminal rather than a detailed MCC-specific explanation.

Applications should therefore communicate applicable card usage restrictions to the cardholder proactively rather than relying on a declined-transaction webhook.

MCC Sandbox Testing

The ConnectPay Sandbox authorization simulation does not pass transactions through the Card Issuer’s processing system.

Therefore, Sandbox authorization requests do not validate:

MCC restrictions;
card Merchant Rules;
Card Issuer limits.

An authorization generated through the Sandbox API cannot be used as an end-to-end test proving that a blocked MCC will be rejected by the Card Issuer.

To test MCC setup on Sandbox system, please address these requests to tech support of Connectpay.

Production Setup

The required global MCC restrictions must be configured for the Production card program before cards are issued for go-live.

Once configured, cards within the program are subject to the applicable program-level MCC list. Card-specific Merchant Rules can then be used to further narrow individual cards according to the required card profile.

Any future changes to the global MCC configuration must be coordinated with ConnectPay.