GlobalE.UpdatePaymentMethod

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.

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

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.

​Summary

​Signature

​Parameters

​Callbacks

​Callback responses

​Return from redirect

​Clearing the flow

​Common errors

Summary

Signature

Parameters

Callbacks

Callback responses

Return from redirect

Clearing the flow

Common errors