Checkout (nube.api.getCheckout())

The Checkout adapter lets your app invoke checkout host operations from inside the Web Worker — hiding payment options, changing the benefit label under a gateway, adding descriptive content, or hiding specific installment counts. Each method mirrors the host's public surface 1:1.

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  const checkout = nube.api.getCheckout();
}

getCheckout() returns a cached CheckoutCommands instance — repeated calls return the same object. See the API overview for how the namespace is materialized and how errors are surfaced.

Availability

These operations act on the checkout's payment step, so they only take effect on the checkout page. Some methods are honored only for specific gateway types (noted per method below).

Methods

Method	Description
getPaymentIds()	Log the IDs of every enabled payment gateway to the host console.
hidePaymentOptions(gatewayIds)	Hide one or more payment options.
changePaymentBenefit(benefit)	Change the benefit label rendered under a gateway.
addPaymentContentText(content)	Add descriptive content under a payment option.
hideInstallments(installments)	Hide specific installment counts for a gateway.

All methods are asynchronous and return Promise<void>. In the per-method snippets below, checkout is the instance returned by nube.api.getCheckout() (see the setup above); handle the returned promise as shown in the full example .

getPaymentIds

Logs the IDs of every payment gateway currently enabled in the checkout to the host console. It does not return the list — the host method is fire-and-forget and intended for debugging (e.g. to discover the gateway IDs you'll pass to the other methods).

getPaymentIds(): Promise<void>;

await checkout.getPaymentIds(); // gateway IDs are printed to the console

hidePaymentOptions

Hides one or more payment options.

hidePaymentOptions(gatewayIds: string[]): Promise<void>;

Parameter	Type	Description
gatewayIds	string[]	Array of gateway IDs to hide.

await checkout.hidePaymentOptions(["boleto", "pix"]);

changePaymentBenefit

Changes the benefit — the label rendered under the option — for a payment gateway.

changePaymentBenefit(benefit: PaymentBenefit): Promise<void>;

type PaymentBenefit = {
  id: string;    // gateway ID
  value: string; // benefit label, e.g. "12x sem juros"
};

await checkout.changePaymentBenefit({ id: "credit-card", value: "12x sem juros" });

addPaymentContentText

Adds descriptive content under a payment option.

addPaymentContentText(content: PaymentContent): Promise<void>;

type PaymentContent = {
  id: string;    // gateway ID
  value: string; // plain-text content to render under the gateway
};

note

The host only honors this for external gateways.

await checkout.addPaymentContentText({
  id: "my-external-gateway",
  value: "Pay in up to 12 installments with no interest.",
});

hideInstallments

Hides specific installment counts for a payment gateway, keeping the gateway itself (and other installment counts) visible.

hideInstallments(installments: InstallmentsToHide): Promise<void>;

type InstallmentsToHide = {
  id: string;      // gateway ID
  value: number[]; // installment counts to hide, e.g. [3, 6] hides 3x and 6x
};

note

The host only honors this for transparent credit/debit card gateways.

// Hide the 3x and 6x options, keeping the rest visible
await checkout.hideInstallments({ id: "credit-card", value: [3, 6] });

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  const checkout = nube.api.getCheckout();

  // These are fire-and-forget: attach a rejection handler so a failed
  // command doesn't surface as an unhandled promise rejection.
  checkout.getPaymentIds().catch(console.error); // gateway IDs printed to console

  checkout.hidePaymentOptions(["boleto"]).catch(console.error);
  checkout
    .changePaymentBenefit({ id: "credit-card", value: "12x sem juros" })
    .catch(console.error);
}

Notes

• Every method is asynchronous and resolves once the host has applied the change. On failure the promise rejects with an Error in the form "<code>: <message>" — see Return values and errors .
• Gateway IDs are the values reported by getPaymentIds() .
• addPaymentContentText is honored only for external gateways; hideInstallments only for transparent credit/debit card gateways.