Overview
Payments module for accepting one-time payments and subscriptions in your app through its connected payment provider. This module provides:- Checkouts for one-time payments and subscriptions, on the provider’s hosted page or embedded in your app
- Purchase lookup
- Refunds
- Subscription management, including canceling, pausing, and resuming
Providers
Each app connects one provider, which is Stripe, PayPal, or Base44 Payments powered by Wix.Authentication modes
- Anonymous or user authentication (
base44.payments): Preloads and mounts embedded checkouts, completes PayPal checkouts, and lists the current user’s own purchases. - Service role authentication (
base44.asServiceRole.payments): Creates checkouts, lists any purchase, refunds payments, and changes subscriptions. Use the service role methods in backend functions.
Methods
These methods use anonymous or user authentication, throughbase44.payments.
preloadCheckout()
preloadCheckout(Starts downloading the provider’s JavaScript library, Stripe.js or the PayPal JavaScript SDK, before you mount a checkout, so the checkout appears faster. Call it when the checkout page or form opens, while the buyer is still filling it in.provider):Promise<void>
mountCheckout() needs the library to render the checkout, and downloads it itself if you didn’t preload it.
It never rejects, so you don’t need to await it or catch errors. If the library can’t load, mountCheckout() tries again and rejects with the error. Loading the library requires a browser environment and is skipped in the backend.
Parameters
any
obbligatorio
The provider the app is connected to.
"stripe" | "paypal"Returns
Promise<void>
Promise resolving once the library has loaded or failed to load.
Example
mountCheckout()
mountCheckout(Renders an embedded checkout inside an element on the page. Pass the result of aelement,checkout,options?):Promise<CheckoutMount>
createCheckout() call made with presentation: 'embedded'. Because only the service role can create checkouts, create it in a backend function and return the result to the page.
The SDK loads the provider’s library and renders the checkout for you:
- PayPal: Renders a PayPal button. When the buyer approves the payment, the SDK calls
completeCheckout()and thenonComplete. - Stripe: Mounts Stripe Embedded Checkout. After paying, the buyer returns to the checkout’s
success_path. Stripe allows one embedded checkout per page, so mounting another Stripe checkout destroys the previous one.
preloadCheckout() when the page opens.
Requires a browser environment and can’t be used in the backend. Rejects when the checkout isn’t embedded, when the payments config can’t be fetched or has no valid script URL for the provider, when the provider’s library fails to load, or when PayPal isn’t available for the checkout’s currency.
The checkout’s callbacks run in the buyer’s browser, where they can be faked. Grant access to what the buyer paid for only after your backend confirms the purchase, for example with listPurchases() in a backend function.
Parameters
Properties
Properties
CheckoutElement
obbligatorio
Element to render the checkout in. It should be empty.
MountableCheckout
obbligatorio
The result of
createCheckout().Properties
Properties
MountCheckoutOptions
Callbacks for the checkout’s outcome.
Properties
Properties
(result: CompleteCheckoutResult) => void
Called after the buyer approves a PayPal payment and the SDK completes the checkout. Use it to update the page, not to grant access.Stripe doesn’t call this. After a Stripe payment, the buyer returns to the checkout’s
success_path with a session_id query parameter. That parameter is the checkout_id. Show the result there with listPurchases().() => void
Called when the buyer closes the PayPal window without paying. The button stays mounted so the buyer can try again.
(error: unknown) => void
Called when a PayPal checkout fails after it’s mounted, including a declined payment with the
payment_declined code. The button stays mounted so the buyer can try again. If it keeps failing with payment_declined, create a new checkout and mount it. Stripe shows its own errors inside the checkout.The error is a Base44Error when completing the checkout fails, or PayPal’s own error object when the PayPal window fails.Returns
CheckoutMount
Promise resolving to the mounted checkout once it renders.
Properties
Properties
() => void
obbligatorio
Removes the checkout from the page. Call it when the component that holds it unmounts. For Stripe, mounting another checkout destroys this one for you.
Examples
completeCheckout()
completeCheckout(Completes a PayPal checkout after the buyer approves it. When you usecheckoutId):Promise<CompleteCheckoutResult>
mountCheckout(), it calls this for you. Call it directly only if you render your own PayPal button. Calling it again for the same checkout returns the same result.
Only PayPal checkouts need completing. Other providers reject with complete_not_supported.
To complete the checkout from a backend function instead, use completeCheckout() with the service role.
Parameters
string
obbligatorio
The
checkout_id from createCheckout().Returns
CompleteCheckoutResult
Promise resolving to the checkout’s payment status.
Properties
Properties
Example
listPurchases()
listPurchases(Lists the current user’s purchases. A purchase belongs to the user when it was made with the user’s email address. To confirm a purchase in a backend function before you grant access, or to look up any buyer’s purchases, useparams?):Promise<ListPurchasesResult>
listPurchases() with the service role.
PayPal can’t list purchases, so for PayPal apps, pass checkout_id or subscription_id. The call looks up that one purchase and rejects with invalid_request without either.
Rejects with forbidden when the client uses anonymous authentication.
Parameters
ListPurchasesParams
Optional filters and pagination.
Properties
Properties
Returns
ListPurchasesResult
Promise resolving to a page of purchases.
Properties
Properties
Purchase[]
obbligatorio
Purchases on this page.
Properties
Properties
string
obbligatorio
ID of the checkout the purchase came from.
PurchaseStatus
obbligatorio
Status of the purchase.
'pending': The buyer hasn’t finished paying, or the provider is still processing the payment.'paid': The payment went through.'refunded': The payment was refunded.'canceled': The checkout or subscription was canceled.'failed': The payment failed.'unknown': The provider reported a state that doesn’t map to the others.
PurchaseItem[]
obbligatorio
number | null
Total amount in minor units.
string | null
Three-letter ISO currency code, in lowercase.
string | null
Buyer’s email address.
Record<string, string> | null
The metadata passed to
createCheckout(). Always null unless you call with the service role.string | null
ID of the subscription, for recurring purchases.
ShippingAddress | null
Where the order ships, whether your app or the provider collected the address. Always
null unless you call with the service role. Save it on your order record.Properties
Properties
string
obbligatorio
Recipient’s full name, 1 to 300 characters.
string
obbligatorio
Street address, 1 to 300 characters.
string | null
Apartment, suite, or building, up to 300 characters.
string | null
City, up to 120 characters. Some countries address by region and postal code alone.
string | null
State, province, or region, up to 300 characters.
string | null
Postal or ZIP code, up to 60 characters.
string
obbligatorio
Two-letter ISO 3166-1 country code, such as
'US'.number | null
Shipping fee in minor units, when the checkout charged one.
string | null
ID of the payment to pass to
refund(). For a PayPal subscription it’s the latest charge, returned only with the service role. Read it when you start a refund and reuse it on retries. It’s null when the provider doesn’t name a payment, such as a PayPal subscription whose latest charge is already refunded.string | null
obbligatorio
Cursor for the next page, or
null on the last page.Examples
Service role methods
These methods use service role authentication, throughbase44.asServiceRole.payments. Call them from backend functions.
Not every provider supports every operation. See Providers for which ones do.
Refunds take a required idempotency_key and checkouts take an optional one, so retrying them doesn’t charge or refund twice. Repeating a subscription change returns the subscription’s current state.
createCheckout()
createCheckout(Creates a checkout. A checkout is either a redirect checkout, where the buyer leaves your app for the provider’s hosted checkout page, or an embedded checkout, which renders inside your app. Choose one withparams):Promise<CreateCheckoutResult>
presentation. It defaults to 'redirect'.
After you create the checkout, use the result:
- Redirect checkout: Send the buyer to the returned
redirect_url. - Embedded checkout: Return the result to the page and pass it to
mountCheckout().
recurring item creates a subscription.
Parameters
CreateCheckoutParams
obbligatorio
Items, return paths, and options for the checkout.
Properties
Properties
CheckoutItem[]
obbligatorio
Items to sell, 1 to 100 entries.
Properties
Properties
string
obbligatorio
Item name shown to the buyer, 1 to 255 characters.
number
obbligatorio
Unit price as an integer in the currency’s minor units, such as cents. Must be greater than
0. Providers may also reject a total below their minimum charge.number
Number of units, from 1 to 1,000,000. Defaults to
1.boolean
Whether the item ships. For a shippable item, the provider collects a shipping address unless you pass one in
shipping.address.CheckoutItemRecurring
Billing terms. Set this to sell the item as a subscription. PayPal and Base44 Payments allow one recurring item per checkout, and PayPal allows no other items with it.
Properties
Properties
PaymentsRecurringFrequency
obbligatorio
Unit of the billing period.It’s
'day', 'week', 'month', or 'year'.number
Number of
frequency units between charges, from 1 to 3650. Defaults to 1.boolean
Whether the subscription renews automatically at the end of its billing cycles. Stripe doesn’t support
false.number
Number of billing cycles before the subscription ends, at least 1. Omit for no limit. Not supported for Stripe.
CheckoutFreeTrial
Free trial before the first charge. Stripe applies one trial to the whole checkout, so every recurring item must request the same trial.
string
Subscription title shown to the buyer, up to 150 characters.
string
Subscription description shown to the buyer, up to 500 characters.
string
Three-letter ISO currency code, such as
'usd'. Defaults to the payment account’s currency. Required for PayPal.string
obbligatorio
App-relative path the buyer returns to after paying, such as
'/thank-you'. Must start with /.string
App-relative path the buyer returns to after canceling. Must start with
/. Not supported for Stripe embedded checkout.CheckoutBuyer
Record<string, string>
Your own key-value pairs, up to 50 keys. Returned in each purchase’s
metadata to service role callers only. Not supported for PayPal.string
Key that makes retries return the same checkout instead of creating another, 1 to 200 characters. Not supported for Base44 Payments or PayPal subscriptions.
CheckoutPresentation
How the buyer pays. Defaults to
'redirect'. PayPal apps must pass 'embedded', and Base44 Payments supports only 'redirect'.'redirect': The buyer leaves the app for the provider’s hosted checkout page atredirect_url.'embedded': The checkout renders inside the app withmountCheckout().
CheckoutShipping
Shipping address and fee. Allowed only when at least one item is
shippable. Supported for PayPal one-time checkouts only. Other providers and subscriptions reject it with invalid_request.Compute the fee in a backend function, never in the browser. When the fee depends on the address, such as by distance or zone, collect the address in your app and pass it in address. PayPal shows the address to the buyer locked, so the order ships to the address you computed the fee for. When the fee doesn’t depend on the address, pass only amount and PayPal asks the buyer for the address.Properties
Properties
ShippingAddress
Address your app collected. Omit it to let the provider ask the buyer.
Properties
Properties
string
obbligatorio
Recipient’s full name, 1 to 300 characters.
string
obbligatorio
Street address, 1 to 300 characters.
string | null
Apartment, suite, or building, up to 300 characters.
string | null
City, up to 120 characters. Some countries address by region and postal code alone.
string | null
State, province, or region, up to 300 characters.
string | null
Postal or ZIP code, up to 60 characters.
string
obbligatorio
Two-letter ISO 3166-1 country code, such as
'US'.number
Shipping fee as an integer in minor units, shown to the buyer as its own shipping line. Omit it for free shipping.
Returns
CreateCheckoutResult
Promise resolving to the checkout. Exactly one of redirect_url and embedded is set, depending on the checkout’s presentation.
Properties
Properties
string
obbligatorio
ID of the checkout. For Stripe it’s the Checkout Session ID, and for PayPal it’s the PayPal order or subscription ID.
string
obbligatorio
Three-letter ISO currency code of the checkout, in lowercase.
number
obbligatorio
Amount the buyer pays now, in minor units. It’s
0 for a subscription that starts with a free trial.string | null
obbligatorio
Absolute URL of the provider’s hosted checkout page, for redirect checkouts.
EmbeddedCheckout | null
obbligatorio
Data for
mountCheckout(), for embedded checkouts.Examples
completeCheckout()
completeCheckout(Completes a PayPal checkout from a backend function, after the buyer approves it. Use it when you render your own PayPal button and itscheckoutId):Promise<CompleteCheckoutResult>
onApprove handler sends the checkout ID to your backend. Calling it again for the same checkout returns the same result.
Only PayPal checkouts need completing. Other providers reject with complete_not_supported.
Parameters
string
obbligatorio
The
checkout_id from createCheckout().Returns
CompleteCheckoutResult
Promise resolving to the checkout’s payment status.
Properties
Properties
Example
listPurchases()
listPurchases(Lists the app’s purchases. Unlikeparams?):Promise<ListPurchasesResult>
base44.payments.listPurchases(), it returns any buyer’s purchases and includes their metadata.
PayPal can’t list purchases, so for PayPal apps, pass checkout_id or subscription_id. The call looks up that one purchase and rejects with invalid_request without either.
Parameters
ServiceRoleListPurchasesParams
Optional filters and pagination.
Properties
Properties
string
Only return the purchase from this checkout.
string
Only return purchases of this subscription.
number
Maximum number of purchases to return, from 1 to 100. Defaults to
20.string
The
next_cursor from the previous page. Send the same filters and limit as that call.string
Only return purchases made with this email address.
Returns
ListPurchasesResult
Promise resolving to a page of purchases.
Properties
Properties
Purchase[]
obbligatorio
Purchases on this page.
Properties
Properties
string
obbligatorio
ID of the checkout the purchase came from.
PurchaseStatus
obbligatorio
Status of the purchase.
'pending': The buyer hasn’t finished paying, or the provider is still processing the payment.'paid': The payment went through.'refunded': The payment was refunded.'canceled': The checkout or subscription was canceled.'failed': The payment failed.'unknown': The provider reported a state that doesn’t map to the others.
PurchaseItem[]
obbligatorio
number | null
Total amount in minor units.
string | null
Three-letter ISO currency code, in lowercase.
string | null
Buyer’s email address.
Record<string, string> | null
The metadata passed to
createCheckout(). Always null unless you call with the service role.string | null
ID of the subscription, for recurring purchases.
ShippingAddress | null
Where the order ships, whether your app or the provider collected the address. Always
null unless you call with the service role. Save it on your order record.Properties
Properties
string
obbligatorio
Recipient’s full name, 1 to 300 characters.
string
obbligatorio
Street address, 1 to 300 characters.
string | null
Apartment, suite, or building, up to 300 characters.
string | null
City, up to 120 characters. Some countries address by region and postal code alone.
string | null
State, province, or region, up to 300 characters.
string | null
Postal or ZIP code, up to 60 characters.
string
obbligatorio
Two-letter ISO 3166-1 country code, such as
'US'.number | null
Shipping fee in minor units, when the checkout charged one.
string | null
ID of the payment to pass to
refund(). For a PayPal subscription it’s the latest charge, returned only with the service role. Read it when you start a refund and reuse it on retries. It’s null when the provider doesn’t name a payment, such as a PayPal subscription whose latest charge is already refunded.string | null
obbligatorio
Cursor for the next page, or
null on the last page.Examples
refund()
refund(Refunds all or part of a payment. Retrying with the sameparams):Promise<RefundResult>
idempotency_key and amount returns the original refund instead of refunding twice. When the call rejects with refund_failed, the outcome is unknown, so retry it with the same values.
Not supported for Base44 Payments.
Parameters
RefundParams
obbligatorio
The payment, amount, and idempotency key.
Properties
Properties
Returns
RefundResult
Promise resolving to the refund.
Properties
Properties
string
obbligatorio
Provider’s ID of the refund.
string
obbligatorio
ID of the refunded payment.
number
obbligatorio
Refunded amount in minor units.
string
obbligatorio
Three-letter ISO currency code, in lowercase.
"pending" | "succeeded"
obbligatorio
Whether the refund went through or the provider is still processing it.
Example
cancelSubscription()
cancelSubscription(Cancels a subscription, now or at the end of the current billing period. Not supported for Base44 Payments. PayPal supports canceling now only.subscriptionId,options?):Promise<SubscriptionResult>
Parameters
Properties
Properties
Returns
SubscriptionResult
Promise resolving to the subscription’s state.
Properties
Properties
Example
pauseSubscription()
pauseSubscription(Pauses a subscription’s billing. Not supported for Base44 Payments.subscriptionId):Promise<SubscriptionResult>
Parameters
string
obbligatorio
The
subscription_id of the purchase.Returns
SubscriptionResult
Promise resolving to the subscription’s state.
Properties
Properties
Example
resumeSubscription()
resumeSubscription(Resumes a paused subscription’s billing. Not supported for Base44 Payments.subscriptionId):Promise<SubscriptionResult>
Parameters
string
obbligatorio
The
subscription_id of the purchase.Returns
SubscriptionResult
Promise resolving to the subscription’s state.
Properties
Properties
Example
Errors
PaymentsErrorCode
PaymentsErrorCode =Error codes that payments methods set in the"forbidden"|"unauthenticated"|"not_found"|"conflict"|"rate_limited"|"payments_not_connected"|"invalid_request"|"invalid_items"|"amount_below_minimum"|"currency_mismatch"|"currency_required"|"invalid_metadata"|"idempotency_not_supported"|"idempotency_key_reused"|"multiple_subscription_items"|"recurring_option_not_supported"|"invalid_cursor"|"presentation_not_supported"|"embedded_checkout_unavailable"|"checkout_not_found"|"checkout_not_approved"|"checkout_closed"|"payment_declined"|"complete_not_supported"|"provider_unavailable"|"payment_not_found"|"refund_rejected"|"refund_in_progress"|"refund_amount_mismatch"|"refund_temporarily_unavailable"|"refund_failed"|"refund_not_supported"|"subscription_not_found"|"subscription_not_active"|"subscription_action_not_supported"
code of a Base44Error when they reject. Invalid arguments and mountCheckout() failures reject with a plain Error instead.
Notable codes include:
payment_declined: The buyer’s payment method was declined when completing the checkout. The buyer can try again with another method.refund_failed: The refund’s outcome is unknown. Retry with the sameidempotency_keyandamount, which returns the original refund if one was made.refund_in_progress: A refund with the sameidempotency_keyis still running.refund_amount_mismatch: Theidempotency_keywas already used for a different amount.rate_limited: Too many requests. Wait for the number of seconds in theRetry-Afterresponse header, available aterror.originalError.response.headers['retry-after'].refund_not_supported,subscription_action_not_supported,complete_not_supported,presentation_not_supported: The app’s payment provider doesn’t support the operation.