Administrar controles de tarjetas en la aplicación

Permitir a los usuarios finales ver y actualizar los controles de dominio desde la aplicación del emisor usando el SDK D1.

Diagrama de secuencia

Use el SDK D1 para recuperar la configuración actual, mostrar su IU y luego enviar las actualizaciones.

Requisitos previos

Consumidor y tarjeta ya creados/registrados en D1.
El SDK está correctamente inicializado.
La aplicación del emisor llamó a la API de inicio de sesión del SDK D1.
Antes de llamar a la API updateCardControlSettings o updateCardLimitSettings, por favor llame primero a la API getCardSettings.

Integración del SDK D1

El SDK D1 utiliza estas API públicas para tarjetas gestionadas en D1:

CardService.getCardSettings(): Para recuperar la configuración de la tarjeta.
CardService.updateCardControlSettings(): Para actualizar la configuración de control de la tarjeta.

Recuperar la configuración actual

CardService.getCardSettings() devuelve dos grupos de configuraciones:

Configuración de control de la tarjeta (controles de dominio)
La configuración de límite de tarjeta (límites de gasto) remítase a la documentación de la API fpara la información detallada a nivel de campo sobre la configuración de control de tarjeta y de límites de tarjeta.

Vea el Referencia de la API del SDK D1 para detalles a nivel de campo.

Si también implementa límites de gasto, vea Implementar límites de gasto.

// obtener configuración de la tarjeta
String cardID = ""; // cardID recibido desde el backend.
final CardSettings[] cardSettingsCached = new CardSettings[0];

CardService cardService = d1Task.getCardService();
D1Task.Callback<CardSettings> callback = new D1Task.Callback<CardSettings>() {
    @Override
    public void onSuccess(CardSettings cardSettings) {
        // almacenar la configuración en caché en la app
        cardSettingsCached[0] = cardSettings;
    }

    @Override
    public void onError(D1Exception exception) {
        // Consulte Integración del SDK D1 – sección de Gestión de errores.
    }
};
cardService.getCardSettings(cardID, callback);

let cardID = "" // obtenido por ejemplo desde el servidor
let cardService = d1Task.cardService()
cardService.cardSettings(cardID) { [weak self] cardSettings, error in
    if let error = error {
       // Manejar el error
    } else if let cardSettings = cardSettings {
        cardSettingsCached = cardSettings
        // Continuar con los flujos subsiguientes, por ejemplo mostrar la IU de controles/límites de la tarjeta
    }
}

Renderizar la configuración de control de la tarjeta en su IU

Lea los controles de la tarjeta desde el objeto CardSettings, luego muestre solo los controles que existan.

Algunos controles son opcionales a nivel de Producto de Tarjeta. D1 los devuelve como null. Oculte esos controles.

// obtener configuración de la tarjeta
String cardID = ""; // cardID recibido desde el backend.
final static CardSettings cardSettingsCached;// Configuración de la tarjeta almacenada en caché o recuperada de la API `Cardservice.getCardSettings()`
CardControlSettings cardControlSettings = cardSettingsCached.getControl();    
        

//
// ==== Sección de estado de pago =====
//
// Habilitar/deshabilitar el estado de pago en línea
Switch onlinePaymentSwitch;
onlinePaymentSwitch.setChecked(cardControlSettings.isOnlinePaymentEnabled());

// Habilitar/deshabilitar el estado de pago en el extranjero
Switch abroadPaymentSwitch;
abroadPaymentSwitch.setChecked(cardControlSettings.isAbroadPaymentEnabled());

// Habilitar/deshabilitar el estado de pago sin contacto.
if(cardControlSettings.isContactlessEnabled() != null) {
    // Nota: Solo muestre esta configuración si el atributo isContactlessEnabled está disponible en la respuesta de la API `CardService.getCardSettings()`.
    Switch contactlessSwitch;
    contactlessSwitch.setChecked(cardControlSettings.isContactlessEnabled());
}

// Habilitar/deshabilitar el pago con banda magnética
if(cardControlSettings.isMagneticStripeEnabled() != null) {
    // Nota: Solo muestre esta configuración si el atributo isMagneticStripeEnabled está disponible en la respuesta de la API `CardService.getCardSettings()`.
    Switch magneticStripeSwitch;
    magneticStripeSwitch.setChecked(cardControlSettings.isMagneticStripeEnabled());
}

// Habilitar/deshabilitar el retiro en cajero automático
if(cardControlSettings.isATMWithdrawalEnabled() != null) {
    // Nota: Solo muestre esta configuración si el atributo isATMWithdrawalEnabled está disponible en la respuesta de la API `CardService.getCardSettings()`.
    Switch atmWithdrawalSwitch;
    atmWithdrawalSwitch.setChecked(cardControlSettings.isATMWithdrawalEnabled());
}

//
// ==== Sección de lista de monedas denegadas =====
//
// Mostrar la sección de lista de monedas denegadas
List<String> deniedCurrencies = cardControlSettings.getDeniedCurrencyList();
RecyclerView deniedCurrencyListRecyclerview;
DeniedCurrencyListAdapter deniedCurrencyAdapter = new DeniedCurrencyListAdapter(deniedCurrencies);
deniedCurrencyListRecyclerview.setAdapter(deniedCurrencyAdapter);


//
// ==== Sección de geografía =====
//
// Mostrar la sección de configuración de geografía
CardControlSettings.Geography geography = cardControlSettings.getGeography();
List<CardControlSettings.Region> regionList = geography.getRegionList();
RecyclerView regionListRecyclerview;
RegionListAdapter regionAdapter = new RegionListAdapter(regionList);
regionListRecyclerview.setAdapter(regionAdapter);


List<String> countryList = geography.getCountryList();
RecyclerView countryListRecyclerview;
CountryListAdapter countryAdapter = new CountryListAdapter(countryList);
countryListRecyclerview.setAdapter(countryAdapter);

//
// ==== Sección de comerciantes =====
//
// Mostrar la sección de comerciantes
CardControlSettings.Merchant merchant = cardControlSettings.getMerchant();
// Habilitar/deshabilitar el pago en comerciantes de juegos de azar
Switch gamblingMerchantSwitch;
gamblingMerchantSwitch.setChecked(merchant.isGamblingMerchantEnabled());

// Habilitar/deshabilitar el pago en comerciantes para adultos
Switch adultMerchantSwitch;
adultMerchantSwitch.setChecked(merchant.isAdultMerchantEnabled());

// Habilitar/deshabilitar el pago en comerciantes de riesgo
Switch riskyMerchantSwitch;
riskyMerchantSwitch.setChecked(merchant.isRiskyMerchantEnabled());

// Ejemplos de visualización de IU
let onlinePaymentSwitch = UISwitch()
let contactlessSwitch = UISwitch()
let magneticStripeSwitch = UISwitch()
let atmWithdrawalSwitch = UISwitch()
let abroadPaymenSwitch = UISwitch()
let deniedCurrencyListTextView = UITextView()
let countryListTextView = UITextView()
let regionListTextView = UITextView()
let gamblingMerchantSwitch = UISwitch()
let adultMerchantSwitch = UISwitch()
let riskyMerchantSwitch = UISwitch()

let cardControlSettings = cardSettingsCached.control

//
// ===== Sección de estado de pago =====
//

// Habilitar/deshabilitar el pago en línea
onlinePaymentSwitch.isOn = cardControlSettings.isOnlinePaymentEnabled

// Habilitar/deshabilitar el pago sin contacto
if let isContactlessEnabled = cardControlSettings.isContactlessEnabled {
    contactlessSwitch.isOn = isContactlessEnabled
} else {
    // Nota: Solo mostrar la configuración si el valor no es nil
    contactlessSwitch.isHidden = true
}

// Habilitar/deshabilitar banda magnética
if let isMagneticStripeEnabled = cardControlSettings.isMagneticStripeEnabled {
    magneticStripeSwitch.isOn = isMagneticStripeEnabled
} else {
    // Nota: Solo mostrar la configuración si el valor no es nil
    magneticStripeSwitch.isHidden = true
}

// Habilitar/deshabilitar retiro en cajero automático
if let isATMWithdrawalEnabled = cardControlSettings.isATMWithdrawalEnabled {
    atmWithdrawalSwitch.isOn = isATMWithdrawalEnabled
} else {
    // Nota: Solo mostrar la configuración si el valor no es nil
    atmWithdrawalSwitch.isHidden = true
}

// Habilitar/deshabilitar el estado de pago en el extranjero
abroadPaymenSwitch.isOn = cardControlSettings.isAbroadPaymentEnabled

//
// ===== Sección de lista de monedas denegadas =====
//

// Mostrar la sección de lista de monedas denegadas, por ejemplo en UITextView o UITableView
for currency in cardControlSettings.deniedCurrencyList {
    deniedCurrencyListTextView.text = "\(deniedCurrencyListTextView.text)\n\(currency)"
}

//
// ===== Sección de geografía =====
//

// Mostrar la sección de configuración de geografía, por ejemplo en UITextView o UITableView
for country in cardControlSettings.geography.countryList {
    countryListTextView.text = "\(countryListTextView.text)\n\(country)"
}
for region in cardControlSettings.geography.regionList {
    regionListTextView.text = "\(countryListTextView.text)\n\(region)"
}

//
// ===== Sección de comerciantes =====
//

// Mostrar la sección de comerciantes
// Habilitar/deshabilitar el pago en comerciantes de juegos de azar
gamblingMerchantSwitch.isOn = cardControlSettings.merchant.isGamblingMerchantEnabled
// Habilitar/deshabilitar el pago en comerciantes para adultos
adultMerchantSwitch.isOn = cardControlSettings.merchant.isAdultMerchantEnabled
// Habilitar/deshabilitar el pago en comerciantes de riesgo
riskyMerchantSwitch.isOn = cardControlSettings.merchant.isRiskyMerchantEnabled

Actualizar la configuración de control de la tarjeta

Trate las actualizaciones de control de la tarjeta como una operación sensible.

Realice autenticación adicional antes de modificar la configuración de la tarjeta.
Siempre comience desde un objeto CardSettings, objeto devuelto por CardService.getCardSettings().
Nunca cree un objeto CardSettings, objeto usted mismo.

Si envía un objeto auto-inicializado a CardService.updateCardControlSettings(), puede sobrescribir valores existentes en el backend de D1. También puede provocar errores como ERROR_CARD_SETTINGS_OPERATION_NOT_ALLOWED, ERROR_CARD_SETTINGS_INVALID_FORMAT, o ERROR_CARD_SETTINGS_INVALID_VALUE.

Requisitos previos y actualizaciones permitidas

Antes de actualizar un control, verifique que D1 devolvió el atributo correspondiente en getCardSettings().

El SDK D1 devuelve ERROR_CARD_SETTINGS_OPERATION_NOT_ALLOWED cuando el usuario final actualiza un control que no está disponible.

La siguiente tabla muestra el requisito previo para las respectivas configuraciones de control:

Configuración de control de tarjeta

Requisito previo

CardControlSettings.setOnlinePaymentEnabled(true)

N/A

CardControlSettings.setAbroadPaymentEnabled(true)

N/A

CardControlSettings.setDeniedCurrencyList()

N/A

CardControlSettings.Merchant.setGamblingMerchantEnabled(true)

N/A

CardControlSettings.Merchant.setAdultMerchantEnabled(true)

N/A

CardControlSettings.Merchant.setRiskyMerchantEnabled(true)

N/A

CardControlSettings.setContactlessEnabled(true)

Si el atributo isContactlessEnabled se recupera de la CardService.getCardSettings() API, entonces se permite una operación de actualización.

CardControlSettings.setMagneticStripeEnabled(true)

Si el isMagneticStripeEnabled se recupera de la CardService.getCardSettings() API, entonces se permite una operación de actualización.

CardControlSettings.setATMWithdrawalEnabled(true)

Si el isATMWithdrawalEnabled se recupera de la CardService.getCardSettings() API, entonces se permite una operación de actualización.

Validación de entrada y errores

El SDK D1 puede devolver:

El ERROR_CARD_SETTINGS_INVALID_FORMAT código de error a la aplicación del emisor cuando el usuario final intenta actualizar la configuración de control de la tarjeta con una entrada con formato inválido.
El ERROR_CARD_SETTINGS_INVALID_VALUE código de error cuando el usuario final intenta actualizar configuraciones de control de tarjeta donde el formato es correcto pero el valor de entrada es incorrecto.

Use los siguientes formatos para controles basados en listas:

Configuración de control de tarjeta

Formato

CardControlSettings.getGeography().setCountryList()

Consulte formato ISO 3166-1 alpha-2 para los formatos de código de país permitidos. Si el formato es inválido, el SDK D1 propagará el error a la aplicación del emisor. Consulte la API de países de Android para evitar que ocurra dicho error.

CardControlSettings.setDeniedCurrencyList()

Consulte Formato de código alfa ISO 4217 para los formatos de código de las monedas permitidas. Si el formato es inválido, el SDK D1 propagará el error a la aplicación del emisor. Consulte API de moneda de Android para evitar que ocurra dicho error.

Use los siguientes ejemplos para enviar actualizaciones:

String cardID = ""; // cardID recibido desde el backend.

CardService cardService = d1Task.getCardService();
CardSettings cardSettings = null; // Obtener la configuración de la tarjeta desde la API o usar desde la caché

CardControlSettings cardControlSettings = cardSettings.getControl();

// Habilitar/deshabilitar el estado de pago en línea
cardControlSettings.setOnlinePaymentEnabled(true); // o false

// Habilitar/deshabilitar el pago sin contacto
// si el atributo isContactlessEnabled se recuperó de la API `CardService.getCardSettings()` entonces la siguiente operación está permitida       
if (cardControlSettings.isContactlessEnabled() != null) {
    cardControlSettings.setContactlessEnabled(true); // o false
}

// Habilitar/deshabilitar el pago con banda magnética
// si el atributo isMagneticStripeEnabled se recuperó de la API `CardService.getCardSettings()` entonces la siguiente operación está permitida        
if (cardControlSettings.isMagneticStripeEnabled() != null) {
    cardControlSettings.setMagneticStripeEnabled(true); // o false
}

// Habilitar/deshabilitar el estado de retiro en cajero
// si el atributo isATMWithdrawalEnabled se recuperó de la API `CardService.getCardSettings()` entonces la siguiente operación está permitida        
if (cardControlSettings.isATMWithdrawalEnabled() != null) {
    cardControlSettings.setATMWithdrawalEnabled(true); // o false
}

// Habilitar/deshabilitar el estado de pago en el extranjero
cardControlSettings.setAbroadPaymentEnabled(true);     // o false

// Actualizar la lista de monedas denegadas
ArrayList<String> deniedCurrencies = new ArrayList<>();

// Por favor consulte Android Currency API [Android Currency API](https://developer.android.com/reference/android/icu/util/Currency)
// por ejemplo:         
// Currency currency = Currency.getInstance(Locale.CANADA);
// String currencyCode = currency. getCurrencyCode(); 
        
deniedCurrencies.add("USD");
deniedCurrencies.add("GBP");
cardControlSettings.setDeniedCurrencyList(deniedCurrencies);

// Configuración de geografía
CardControlSettings.Geography geography = cardControlSettings.getGeography();
// Actualizar la lista de regiones
ArrayList<CardControlSettings.Region> regionList = new ArrayList<>();
regionList.add(CardControlSettings.Region.ASIA);
regionList.add(CardControlSettings.Region.SCHENGEN_AREA);
geography.setRegionList(regionList);

// Actualizar la lista de países
ArrayList<String> countryList = new ArrayList<>();
// Por favor consulte Android Country API [Android Country API](https://developer.android.com/reference/java/util/Locale#getCountry())
// También puede consultar el siguiente ejemplo:
// String[] countries = Locale.getISOCountries();        
countryList.add("SG");
countryList.add("FR");
geography.setCountryList(countryList);

// Configuración de comerciantes
CardControlSettings.Merchant merchant = cardControlSettings.getMerchant();
// Habilitar/deshabilitar el pago en comerciantes de juegos de azar
merchant.setGamblingMerchantEnabled(true);          // o false
// Habilitar/deshabilitar el pago en comerciantes para adultos
merchant.setAdultMerchantEnabled(true);             // o false
// Habilitar/deshabilitar el pago en comerciantes de riesgo
merchant.setRiskyMerchantEnabled(true);             // o false

cardService.updateCardControlSettings(cardID, cardControlSettings, new D1Task.Callback<Void>() {
    @Override
    public void onSuccess(Void data) {
            // Continuar con los flujos subsiguientes, por ejemplo, actualizar la IU.
    }
    @Override
    public void onError(@NonNull D1Exception exception) {
            // Consulte Integración del SDK D1 – sección de Gestión de errores.
    }
});

// p. ej. se encontró un error al actualizar
let cardService = d1Task.cardService()
let cardID = "" // obtenido por ejemplo desde el servidor
cardService.updateCardControlSettings(cardID, settings: cardControlSettings) { error in
    if let error = error {
        // Restaurar la configuración al estado inicial antes de la actualización
        cardControlSettings.restore()
    } else {
        // Continuar con los flujos subsiguientes, p. ej. actualizar la IU
    }
}

Próximos pasos

Si usa geografía por región, vea Regiones compatibles.
Si necesita los grupos MCC predeterminados, vea Tipo de comerciante predeterminado.

AnteriorImplementar controles de dominio SiguienteRegiones compatibles

Última actualización hace 3 meses

¿Te fue útil?