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
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. For PayPal, you can instead pass a PayPalCheckoutOnClick to show the button before any checkout exists. The SDK creates the checkout only when the buyer clicks the button, so visitors who don’t buy don’t leave unused checkouts behind.
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 an on-click PayPal checkout is mounted before the app’s PayPal can take payments, 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
The result of
createCheckout(), or for PayPal a PayPalCheckoutOnClick that creates it when the buyer clicks.MountableCheckout properties
MountableCheckout properties
PayPalCheckoutOnClick properties
PayPalCheckoutOnClick properties
Creates the checkout when the buyer clicks, usually by calling the backend function that calls
createCheckout(). Resolve with its result. It must be an embedded PayPal checkout with the same currency and intent you set here, or onError receives an error. Reject to stop, for example when a required form field is empty. PayPal’s window then closes and onError receives the error.Properties
Properties
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().Called when the buyer closes the PayPal window without paying. The button stays mounted so the buyer can try again.
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
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
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
Properties
Properties
Returns
ListPurchasesResult
Promise resolving to a page of purchases.
Properties
Properties
Purchases on this page.
Properties
Properties
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.
The metadata passed to
createCheckout(). Always null unless you call with the service role.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
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.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
Properties
Properties
Items to sell, 1 to 100 entries.
Properties
Properties
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.Whether the item ships. For a shippable item, the provider collects a shipping address unless you pass one in
shipping.address.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
Unit of the billing period.It’s
'day', 'week', 'month', or 'year'.Whether the subscription renews automatically at the end of its billing cycles. Stripe doesn’t support
false.Number of billing cycles before the subscription ends, at least 1. Omit for no limit. Not supported for Stripe.
Free trial before the first charge. Stripe applies one trial to the whole checkout, so every recurring item must request the same trial.
Three-letter ISO currency code, such as
'usd'. Defaults to the payment account’s currency. Required for PayPal.App-relative path the buyer returns to after paying, such as
'/thank-you'. Must start with /.App-relative path the buyer returns to after canceling. Must start with
/. Not supported for Stripe embedded checkout.Your own key-value pairs, up to 50 keys. Returned in each purchase’s
metadata to service role callers only. Not supported for PayPal.Key that makes retries return the same checkout instead of creating another, 1 to 200 characters. Not supported for Base44 Payments or PayPal subscriptions.
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().
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
Address your app collected. Omit it to let the provider ask the buyer.
Properties
Properties
Returns
CreateCheckoutResult
Promise resolving to the checkout. Exactly one of redirect_url and embedded is set, depending on the checkout’s presentation.
Properties
Properties
ID of the checkout. For Stripe it’s the Checkout Session ID, and for PayPal it’s the PayPal order or subscription ID.
Amount the buyer pays now, in minor units. It’s
0 for a subscription that starts with a free trial.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
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
Properties
Properties
Returns
ListPurchasesResult
Promise resolving to a page of purchases.
Properties
Properties
Purchases on this page.
Properties
Properties
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.
The metadata passed to
createCheckout(). Always null unless you call with the service role.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
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.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
Properties
Properties
Returns
RefundResult
Promise resolving to the refund.
Properties
Properties
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
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
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.