> ## Documentation Index
> Fetch the complete documentation index at: https://docs.global-e.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GlobalE.UpdatePaymentMethod

<Info>
  This is a **client-side JavaScript SDK method**, not a REST endpoint. It has no OpenAPI spec and no request playground; the contract is documented here.
</Info>

## Summary

GlobalE.UpdatePaymentMethod starts the update-payment-method flow for a subscription. It loads a dynamic script, injects an iframe into a DOM container that you provide, and runs callbacks when the flow succeeds, is cancelled by the user, or fails.

API source: `globale.merchant.client.js` (GEClient instance exposed as `GlobalE`).

## Signature

```js theme={null}
GlobalE.UpdatePaymentMethod(subscriptionId, cultureCode, currencyCode, container, onSuccess, onCancelation, onFailure, merchantReturnUrl)
```

## Parameters

| Parameter | Location | Type | Required | Description |
| - | - | - | - | - |
| `subscriptionId` | Argument | string | Yes | Subscription ID to update the payment method for. |
| `cultureCode` | Argument | string | No | Culture code (e.g., en-US). Default is base culture. |
| `currencyCode` | Argument | string | No | Currency code (e.g., USD). Default is base currency. |
| `container` | Argument | string | Yes | DOM element ID or selector where iframe will be injected. |
| `onSuccess` | Argument | function | Yes | Callback when payment method updated successfully. |
| `onCancelation` | Argument | function | Yes | Callback when user cancels the flow. |
| `onFailure` | Argument | function | Yes | Callback when an error occurs. |
| `merchantReturnUrl` | Argument | String | No | Absolute HTTPS URL where the customer should land after 3DS or payment-gateway redirect. If provided, Global‑e stores it for this subscription update and uses it for the post-redirect return (before the app-setting fallback). Must be a valid absolute URL. |

## Callbacks

* `onSuccess(data)` – After the customer returns from redirect, when the flow completes successfully:
* `data` is usually an object: `{ statusCode, subscriptionId }` — e.g. `{ statusCode: "Settled", subscriptionId: "your-subscription-id" }`.
* In some cases `data` may still be a status string only (e.g. `"Settled"`). Integrators should support both: if `typeof data === "object" && data !== null && data.statusCode`, use `data.statusCode` and `data.subscriptionId`; otherwise treat `data` as the status string.
* `onCancelation(info)` – `info` may be a status string (e.g. `'UserCanceled'`).
* `onFailure(error)` – `error` usually contains `error.error` or `error.message` and possibly `error.details`.

## Callback responses

| Result Code | Callback Invoked | Argument Passed | Description |
| - | - | - | - |
| Settled | onSuccess | Subscription id | The payment method was updated successfully and the transaction settled. |
| PaymentDeclined | onFailure | `{ error: "PaymentDeclined" }` | The payment was declined by the provider (includes a failed fraud check / not-approved result). |
| GeneralException | onFailure | `{ error: "GeneralException" }` | An unexpected error occurred while processing the update (catch-all server error). |
| BillingCountryValidationFailed | onFailure | `{ error: "BillingCountryValidationFailed" }` | The billing country provided failed validation, so the payment method could not be updated. |
| UserCanceled | onCancelation | `"UserCanceled"` | The shopper canceled the update flow before completing it. |

## Return from redirect

* On a final status, the matching callback runs (onSuccess, onCancelation, or onFailure)
* Global‑e then redirects the customer to your return URL (`merchantReturnUrl` if you supplied one, otherwise `ChangePaymentMethodFormReturnUrl`)

## Clearing the flow

`GlobalE.ClearUpdatePaymentMethod()` – removes the iframe and resets the state. Use when closing the flow or switching containers.

## Common errors

* `'subscriptionId is required'` – subscriptionId was not provided.
* Invalid `cultureCode` or `currencyCode` – must be non‑empty strings if provided.
* Failed to initialize/execute UpdatePaymentMethod – script load or runtime error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.