Pular para o conteúdo principal

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, through base44.payments.

preloadCheckout()

preloadCheckout(provider): Promise<void>
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. 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
obrigatório
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(element, checkout, options?): Promise<CheckoutMount>
Renders an embedded checkout inside an element on the page. Pass the result of a 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 then onComplete.
  • 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.
To make the checkout appear faster, load the library ahead of time with 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

CheckoutElement
obrigatório
Element to render the checkout in. It should be empty.
MountableCheckout
obrigatório
The result of createCheckout().
string
obrigatório
ID of the checkout.
string
obrigatório
Three-letter ISO currency code of the checkout.
EmbeddedCheckout | null
obrigatório
Data for the embedded checkout. Mounting rejects when it’s null.
MountCheckoutOptions
Callbacks for the checkout’s outcome.
(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.
() => void
obrigatório
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(checkoutId): Promise<CompleteCheckoutResult>
Completes a PayPal checkout after the buyer approves it. When you use 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
obrigatório
The checkout_id from createCheckout().

Returns

CompleteCheckoutResult Promise resolving to the checkout’s payment status.
string
obrigatório
ID of the checkout.
"pending" | "paid"
obrigatório
Whether the payment went through or the provider is still processing it.

Example


listPurchases()

listPurchases(params?): Promise<ListPurchasesResult>
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, use 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.
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.

Returns

ListPurchasesResult Promise resolving to a page of purchases.
Purchase[]
obrigatório
Purchases on this page.
string
obrigatório
ID of the checkout the purchase came from.
PurchaseStatus
obrigatório
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[]
obrigatório
Line items of the purchase.
string
obrigatório
Item name.
number | null
Unit price in minor units, when the provider reports it.
number | null
Number of units, when the provider reports it.
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.
string
obrigatório
Recipient’s full name, 1 to 300 characters.
string
obrigatório
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
obrigatório
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
obrigatório
Cursor for the next page, or null on the last page.

Examples

Service role methods

These methods use service role authentication, through base44.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(params): Promise<CreateCheckoutResult>
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 with 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().
A checkout with a recurring item creates a subscription.

Parameters

CreateCheckoutParams
obrigatório
Items, return paths, and options for the checkout.
CheckoutItem[]
obrigatório
Items to sell, 1 to 100 entries.
string
obrigatório
Item name shown to the buyer, 1 to 255 characters.
number
obrigatório
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.
PaymentsRecurringFrequency
obrigatório
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.
PaymentsRecurringFrequency
obrigatório
Unit of the trial length, which is 'day', 'week', 'month', or 'year'. Stripe supports only 'day' and 'week'.It’s 'day', 'week', 'month', or 'year'.
number
obrigatório
Number of frequency units the trial lasts, from 1 to 999.
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
obrigatório
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
Details about the buyer, used to prefill the checkout.
string
Buyer’s email address.
string
Buyer’s first name.
string
Buyer’s last name.
string
Buyer’s phone number.
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 at redirect_url.
  • 'embedded': The checkout renders inside the app with mountCheckout().
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.
ShippingAddress
Address your app collected. Omit it to let the provider ask the buyer.
string
obrigatório
Recipient’s full name, 1 to 300 characters.
string
obrigatório
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
obrigatório
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.
string
obrigatório
ID of the checkout. For Stripe it’s the Checkout Session ID, and for PayPal it’s the PayPal order or subscription ID.
string
obrigatório
Three-letter ISO currency code of the checkout, in lowercase.
number
obrigatório
Amount the buyer pays now, in minor units. It’s 0 for a subscription that starts with a free trial.
string | null
obrigatório
Absolute URL of the provider’s hosted checkout page, for redirect checkouts.
EmbeddedCheckout | null
obrigatório
Data for mountCheckout(), for embedded checkouts.

Examples


completeCheckout()

completeCheckout(checkoutId): Promise<CompleteCheckoutResult>
Completes a PayPal checkout from a backend function, after the buyer approves it. Use it when you render your own PayPal button and its 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
obrigatório
The checkout_id from createCheckout().

Returns

CompleteCheckoutResult Promise resolving to the checkout’s payment status.
string
obrigatório
ID of the checkout.
"pending" | "paid"
obrigatório
Whether the payment went through or the provider is still processing it.

Example


listPurchases()

listPurchases(params?): Promise<ListPurchasesResult>
Lists the app’s purchases. Unlike 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.
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.
Purchase[]
obrigatório
Purchases on this page.
string
obrigatório
ID of the checkout the purchase came from.
PurchaseStatus
obrigatório
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[]
obrigatório
Line items of the purchase.
string
obrigatório
Item name.
number | null
Unit price in minor units, when the provider reports it.
number | null
Number of units, when the provider reports it.
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.
string
obrigatório
Recipient’s full name, 1 to 300 characters.
string
obrigatório
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
obrigatório
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
obrigatório
Cursor for the next page, or null on the last page.

Examples


refund()

refund(params): Promise<RefundResult>
Refunds all or part of a payment. Retrying with the same 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
obrigatório
The payment, amount, and idempotency key.
string
obrigatório
The payment_id of the purchase to refund.
number
obrigatório
Amount to refund as an integer in minor units. Must be greater than 0.
string
obrigatório
Key that makes retries return the original refund instead of refunding twice, 1 to 100 characters.

Returns

RefundResult Promise resolving to the refund.
string
obrigatório
Provider’s ID of the refund.
string
obrigatório
ID of the refunded payment.
number
obrigatório
Refunded amount in minor units.
string
obrigatório
Three-letter ISO currency code, in lowercase.
"pending" | "succeeded"
obrigatório
Whether the refund went through or the provider is still processing it.

Example


cancelSubscription()

cancelSubscription(subscriptionId, options?): Promise<SubscriptionResult>
Cancels a subscription, now or at the end of the current billing period. Not supported for Base44 Payments. PayPal supports canceling now only.

Parameters

string
obrigatório
The subscription_id of the purchase.
CancelSubscriptionOptions
When to cancel.
boolean
Cancel at the end of the current billing period instead of now. Defaults to false. Not supported for PayPal.

Returns

SubscriptionResult Promise resolving to the subscription’s state.
string
obrigatório
ID of the subscription.
"canceled" | "active" | "past_due" | "paused"
obrigatório
Current status of the subscription.
boolean
obrigatório
Whether the subscription is set to cancel at the end of the current billing period.

Example


pauseSubscription()

pauseSubscription(subscriptionId): Promise<SubscriptionResult>
Pauses a subscription’s billing. Not supported for Base44 Payments.

Parameters

string
obrigatório
The subscription_id of the purchase.

Returns

SubscriptionResult Promise resolving to the subscription’s state.
string
obrigatório
ID of the subscription.
"canceled" | "active" | "past_due" | "paused"
obrigatório
Current status of the subscription.
boolean
obrigatório
Whether the subscription is set to cancel at the end of the current billing period.

Example


resumeSubscription()

resumeSubscription(subscriptionId): Promise<SubscriptionResult>
Resumes a paused subscription’s billing. Not supported for Base44 Payments.

Parameters

string
obrigatório
The subscription_id of the purchase.

Returns

SubscriptionResult Promise resolving to the subscription’s state.
string
obrigatório
ID of the subscription.
"canceled" | "active" | "past_due" | "paused"
obrigatório
Current status of the subscription.
boolean
obrigatório
Whether the subscription is set to cancel at the end of the current billing period.

Example

Errors

PaymentsErrorCode

PaymentsErrorCode = "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"
Error codes that payments methods set in the 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 same idempotency_key and amount, which returns the original refund if one was made.
  • refund_in_progress: A refund with the same idempotency_key is still running.
  • refund_amount_mismatch: The idempotency_key was already used for a different amount.
  • rate_limited: Too many requests. Wait for the number of seconds in the Retry-After response header, available at error.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.