> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/transaction-control/es/implement-transaction-control/implement-domain-controls/manage-in-app-card-controls.md). # 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](https://thalesgroup.github.io/d1sdk-docs/d1-sdk/latest/android/index.html) 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](https://thalesgroup.github.io/d1sdk-docs/d1-sdk/latest/android/index.html) para detalles a nivel de campo. Si también implementa límites de gasto, vea [Implementar límites de gasto](/transaction-control/es/implement-transaction-control/implement-spending-limits-controls.md). {% tabs %} {% tab title="Android" %} ```java // 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 callback = new D1Task.Callback() { @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); ``` {% endtab %} {% tab title="iOS" %} ```swift 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 } } ``` {% endtab %} {% endtabs %} ### 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. {% tabs %} {% tab title="Android" %} ```java // 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 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 regionList = geography.getRegionList(); RecyclerView regionListRecyclerview; RegionListAdapter regionAdapter = new RegionListAdapter(regionList); regionListRecyclerview.setAdapter(regionAdapter); List 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()); ``` {% endtab %} {% tab title="iOS" %} ```swift // 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 ``` {% endtab %} {% endtabs %} ### Actualizar la configuración de control de la tarjeta {% hint style="warning" %} 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`. {% endhint %} #### 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](https://www.iban.com/country-codes) 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](https://developer.android.com/reference/java/util/Locale#getCountry\(\)) para evitar que ocurra dicho error. | | `CardControlSettings.setDeniedCurrencyList()` | Consulte [Formato de código alfa ISO 4217](https://www.iban.com/currency-codes) 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](https://developer.android.com/reference/android/icu/util/Currency) para evitar que ocurra dicho error. | Use los siguientes ejemplos para enviar actualizaciones: {% tabs %} {% tab title="Android" %} ```java 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 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 regionList = new ArrayList<>(); regionList.add(CardControlSettings.Region.ASIA); regionList.add(CardControlSettings.Region.SCHENGEN_AREA); geography.setRegionList(regionList); // Actualizar la lista de países ArrayList 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() { @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. } }); ``` {% endtab %} {% tab title="iOS" %} ```swift // 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 } } ``` {% endtab %} {% endtabs %} ### Próximos pasos * Si usa geografía por región, vea [Regiones compatibles](/transaction-control/es/implement-transaction-control/implement-domain-controls/supported-regions.md). * Si necesita los grupos MCC predeterminados, vea [Tipo de comerciante predeterminado](/transaction-control/es/implement-transaction-control/implement-domain-controls/default-merchant-types.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.payments.thalescloud.io/transaction-control/es/implement-transaction-control/implement-domain-controls/manage-in-app-card-controls.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.