billing help · For merchants
Payment gateway guides
Stripe, PayPal, Square and Authorize.net from account creation to go-live: verification, keys, webhooks, sandbox tests and common errors; paying payees with Stripe Transfers and PayPal Payouts.
- Choosing and connecting a payment provider
- Stripe
- PayPal
- Square
- Authorize.net
- Paying payees with Stripe
- Paying payees with PayPal
Choosing and connecting a payment provider
Every provider is used the same way: buyers pay on the provider's hosted page, and the provider tells your workspace about the result through a signed webhook. You bring your own provider account; the money is paid into it directly.
Which provider?#
| Stripe | PayPal | Square | Authorize.net | |
|---|---|---|---|---|
| Cards | yes | yes | yes | yes |
| Buyer's PayPal balance | — | yes | — | — |
| US bank payments | ACH | (PayPal's own eCheck) | — | eCheck |
| Subscriptions | yes | yes | yes | yes (ARB) |
| Free trials | yes | yes | — | yes ($1 card check, voided) |
| Partial refunds | yes | yes | yes | after settlement |
| Fees shown in reports | yes | yes | yes | no |
| Disputes reported | yes | yes | yes | no (handle them in its Merchant Interface) |
Many stores offer Stripe or Square for cards plus PayPal for buyers who prefer it. Authorize.net suits merchants who already have a merchant account with a bank.
Connecting a provider, in short#
- Create the provider account and finish its verification (business details, bank account).
- In the provider's developer area, copy the API keys for test/sandbox first.
- Settings → Gateways → Add credential set, paste the keys.
- Register the webhook URL shown on the set at the provider, with the listed events, and paste the webhook value back into the set.
- Verify, then Put in service (Test). Bind the set to a product and make a test payment.
- Repeat with live/production keys when the test works.
Text description
The provider posts an event to /webhooks/provider.php with the credential set in the query string (Authorize.net: no query string; the set is found by its signature key). The signature is checked on the raw body before anything is parsed or stored; a bad signature is refused. The event id is recorded once, so duplicates are ignored. The object is fetched again from the provider's API. The state machine applies the change if it is allowed; a stale or out-of-order event is kept but not applied. Then emails, outbound webhooks and analytics follow. If processing fails the endpoint answers 500 and the provider retries.
Test and live sets#
Keep a test set and a live set per provider. Events from the provider are accepted only for payments made with a set of the same provider and the same mode, so the webhook secret of a test set, which developers often see, can never mark a live payment as paid. When you replace a set with a new one for the same provider account, renewals of older subscriptions that arrive at the new set's address still apply.
When payments stay pending#
A buyer paid but the payment stays Pending and the page keeps saying Confirming your payment…: the provider's webhook did not arrive or was refused.
- Open the payment's page. Under History, are there any provider events?
- Open the provider's webhook or event log for the endpoint. It shows each delivery and the answer it got.
- Match the answer:
| Symptom | Cause / fix |
|---|---|
| Set disabled, owners emailed | Three authentication failures: a key was rotated or revoked. Edit the set, paste the new key, verify. |
| Webhook log shows 400 Invalid signature | Wrong secret, key or webhook ID in the set; for Square, the subscription URL differs from the URL shown on the set. |
| Webhook log shows 503 | No webhook value in the set yet, or (PayPal) PayPal's verification API could not be reached. The provider retries. |
| Webhook log shows 409 (Authorize.net) | Two credential sets use the same Signature Key. Keep one set per account. |
| Payment stays Confirming… | No webhook arrived: check the endpoint in the provider dashboard and the events selected. |
| eCheck stays Processing | Normal until settlement (Authorize.net 1–3 business days). Super → Health & jobs shows payments.reconcile. |
Stripe
Create and verify the account#
- Sign up at stripe.com with the email address of the person who will own the account.
- Stripe opens in a sandbox (test mode) straight away, so you can set up and test before verification finishes.
- To take live payments, activate the account: business type and details, the representative's identity, the bank account for payouts, and the statement descriptor (the name on buyers' card statements; use your store's name).
- Stripe may ask for documents later. Answer quickly: unanswered requests can pause payouts.
Enable what you sell#
- Cards are on by default.
- ACH (US bank account): Settings → Payment methods → enable ACH Direct Debit. Then tick US bank account on the product here.
- Subscriptions need nothing extra: prices are created automatically from your plans.
- Disputes: nothing to enable; fraud warnings (Radar early fraud warnings) arrive with the events below.
Copy the API keys#
Developers → API keys (in test mode first):
- Publishable key (
pk_test_…). - Secret key (
sk_test_…), or a restricted key (rk_test_…) with write access to the resources this integration uses (Checkout Sessions, Customers, Prices, Products, Refunds, Subscriptions, Invoices, Disputes) and read access to Events, Charges and Balance transactions. If Verify reports a missing permission, add it to the key.
Paste both into a new Stripe credential set with environment Test.
Register the webhook#
Stripe's Workbench → Webhooks → Create an event destination (older accounts: Developers → Webhooks → Add endpoint):
- Choose events from Your account, destination type Webhook endpoint.
- Endpoint URL — the one shown on your credential set:
- Select these events:
checkout.session.completedcheckout.session.async_payment_succeededcheckout.session.async_payment_failedcheckout.session.expiredinvoice.paidinvoice.payment_failedcustomer.subscription.createdcustomer.subscription.updatedcustomer.subscription.deletedcharge.refundedcharge.refund.updatedcharge.dispute.createdcharge.dispute.updatedcharge.dispute.closedradar.early_fraud_warning.created
- Create the destination, open it and reveal the Signing secret (
whsec_…). Paste it into the set's Webhook signing secret.
Then Verify credentials and Put in service (Test).
Test in the sandbox#
| Card | Result |
|---|---|
4242 4242 4242 4242 | Succeeds |
4000 0000 0000 3220 | Asks for 3-D Secure, then succeeds |
4000 0000 0000 9995 | Declined (insufficient funds) |
Use any future expiry date, any CVC and any postal code. For ACH, choose the test bank on Stripe's page; the payment shows Processing, then Paid. Refund the test payment from its page and check that it reaches Refunded.
Go live#
- [ ] Account activated, payouts enabled.
- [ ] A live credential set with
pk_live_…/sk_live_…, its own live webhook destination and signing secret. - [ ] Products switched to the live set under Pay with.
- [ ] One small real payment and refund.
- [ ] Statement descriptor and support email set at Stripe.
Common errors#
| Message | Fix |
|---|---|
| does not look right on a key | Copy the whole key; publishable keys start pk_, secret keys sk_ or rk_. |
| belongs to the live environment, but this set is TEST | Use test keys in a test set and live keys in a live set. |
| Webhook deliveries answer 400 | The signing secret is from another destination or the other mode. |
| Verify says the key lacks permission | A restricted key misses one of the permissions above. |
| ACH tile missing | Enable ACH in Stripe and tick US bank account on the product. |
PayPal
Create the business account#
- Open a PayPal Business account at paypal.com (or upgrade a personal one).
- Confirm the email address, link and confirm a bank account, and complete the business verification PayPal asks for.
- Sign in to developer.paypal.com with the same login. The developer dashboard has a Sandbox and a Live side; switch with the toggle at the top.
Create the REST app#
- Apps & Credentials → (Sandbox) → Create App. Name it after your store, type Merchant, and choose the sandbox business account PayPal created for you.
- Copy the Client ID and the Secret.
- Under the app's features, make sure Accept payments and Subscriptions are enabled (they usually are by default). For disputes, keep Customer disputes on.
Paste the Client ID and Secret into a new PayPal credential set with environment Test.
Register the webhook#
On the app's page → Sandbox Webhooks → Add Webhook:
- Webhook URL — the one shown on your credential set:
- Select these events:
CHECKOUT.ORDER.APPROVEDPAYMENT.CAPTURE.COMPLETEDPAYMENT.CAPTURE.PENDINGPAYMENT.CAPTURE.DENIEDPAYMENT.CAPTURE.DECLINEDPAYMENT.CAPTURE.REFUNDEDPAYMENT.CAPTURE.REVERSEDPAYMENT.SALE.COMPLETEDPAYMENT.SALE.DENIEDPAYMENT.SALE.REFUNDEDPAYMENT.SALE.REVERSEDBILLING.SUBSCRIPTION.ACTIVATEDBILLING.SUBSCRIPTION.UPDATEDBILLING.SUBSCRIPTION.RE-ACTIVATEDBILLING.SUBSCRIPTION.SUSPENDEDBILLING.SUBSCRIPTION.CANCELLEDBILLING.SUBSCRIPTION.EXPIREDBILLING.SUBSCRIPTION.PAYMENT.FAILEDCUSTOMER.DISPUTE.CREATEDCUSTOMER.DISPUTE.UPDATEDCUSTOMER.DISPUTE.RESOLVED
- Save. PayPal shows the new webhook's Webhook ID. Paste it into the set's Webhook ID.
Verify credentials now also reads the webhook and reports its URL and event count. Then Put in service (Test).
Test in the sandbox#
Developer dashboard → Testing Tools → Sandbox Accounts lists a personal (buyer) account with its email and password. Pay on your product page, sign in to PayPal as that buyer, and approve. The payment becomes Paid a few seconds later. Test a refund too.
Subscriptions: the buyer approves the subscription on PayPal. With a trial, the first charge comes when the trial ends; the subscription shows Trialing until then.
Go live#
- [ ] Business account verified, bank account confirmed.
- [ ] Live side → your app (or a new live app) → live Client ID and Secret in a live credential set.
- [ ] Live Webhooks → the same URL from the live set and the same events → live Webhook ID in the set.
- [ ] Products switched to the live set.
- [ ] One small real payment and refund.
Common errors#
| Message | Fix |
|---|---|
| Verify fails with an authentication error | Client ID and Secret are from the other side (Sandbox/Live) or from different apps. |
| Webhook deliveries answer 400 | The Webhook ID belongs to another webhook or the other side. |
| Webhook deliveries answer 503 | No Webhook ID in the set yet, or PayPal's verification service was unreachable; PayPal retries. |
| Plan change waits | PayPal asks the buyer to approve a new price; the change applies after approval, at renewal. |
| Payment shows Processing | A PayPal eCheck or a held payment; it becomes Paid or Failed when PayPal decides. |
Technical details#
Credentials. Go to developer.paypal.com → Apps & Credentials, choose Sandbox or Live, then open your REST app.
- Client ID → Client ID.
- Secret → Secret, stored sealed.
- After you add the webhook (below), copy the Webhook ID into the set.
Verify obtains an OAuth token (POST /v1/oauth2/token). If a Webhook ID is present, it also reads that webhook (GET /v1/notifications/webhooks/{id}) and reports its URL and event count.
Webhook. In the app, choose Add Webhook and paste the URL shown on the set (https://encrypted.com/webhooks/paypal.php?cs=…). Select these events:
- CHECKOUT.ORDER.APPROVED
- PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.PENDING, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.DECLINED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED
- PAYMENT.SALE.COMPLETED, PAYMENT.SALE.DENIED, PAYMENT.SALE.REFUNDED, PAYMENT.SALE.REVERSED
- BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.UPDATED, BILLING.SUBSCRIPTION.RE-ACTIVATED, BILLING.SUBSCRIPTION.SUSPENDED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.EXPIRED, BILLING.SUBSCRIPTION.PAYMENT.FAILED
- CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.UPDATED, CUSTOMER.DISPUTE.RESOLVED
How a delivery is verified. The five PAYPAL-* transmission headers, the Webhook ID and the event are posted to /v1/notifications/verify-webhook-signature. Only verification_status = SUCCESS passes. Before that call, the endpoint checks:
- all five headers are present;
- the cert URL is
https://…paypal.com; - the transmission is less than 3 days old.
The event is sent back byte-for-byte, spliced into the request rather than re-encoded, because re-encoding can change numbers and escaping and fail the check. If PayPal cannot be reached, or the app's credentials are refused, the endpoint answers 503 and PayPal retries.
One-time flow.
- An order is created (
custom_idandinvoice_idare our checkout id) and the buyer approves it on PayPal. - The order is captured when the buyer comes back. It is captured again on CHECKOUT.ORDER.APPROVED in case the buyer never returns. The capture is idempotent through
PayPal-Request-Id. - PAYMENT.CAPTURE.COMPLETED marks the payment Paid.
A pending capture (for example a PayPal eCheck) shows Processing until COMPLETED or DENIED arrives.
Subscriptions.
- A catalog product and a billing plan are created once per price and cached per credential set.
- Quarterly is MONTH × 3. Annual is YEAR × 1.
- A free trial is a TRIAL cycle with no pricing scheme.
- The subscription starts with
user_action = SUBSCRIBE_NOW. - BILLING.SUBSCRIPTION.ACTIVATED starts access (Trialing during a trial).
- Each charge is a PAYMENT.SALE.COMPLETED. Failed charges arrive as BILLING.SUBSCRIPTION.PAYMENT.FAILED and leave the subscription Past due for 3 days of grace.
- SUSPENDED means Unpaid (access ends). CANCELLED and EXPIRED mean Canceled.
Refunds. One-time payments are refunded on the capture (/v2/payments/captures/{id}/refund). Subscription charges are refunded on the sale (/v1/payments/sale/{id}/refund). Both are confirmed by the refund webhook.
Disputes. CUSTOMER.DISPUTE.CREATED marks the payment Disputed and emails the owners. RESOLVED in the buyer's favour means Chargeback; in the seller's favour, Paid. A reversal without a dispute (PAYMENT.CAPTURE.REVERSED or PAYMENT.SALE.REVERSED) is recorded as a dispute that was opened and lost.
Square
Create the account#
- Sign up at squareup.com and complete the identity and bank verification. Square accounts used here must settle in US dollars.
- Open the Developer Console (developer.squareup.com) with the same login and create an application named after your store.
Copy the credentials#
In your application, switch the toggle to Sandbox first:
- Credentials → Application ID (
sandbox-sq0idb-…) and Access token. - Locations → the Location ID that should receive payments.
Paste them into a new Square credential set with environment Test. Verify reads the location; it fails unless the location settles in USD, and reports whether card processing is enabled.
Register the webhook#
Application → Webhooks → Subscriptions → Add subscription:
- Notification URL — paste it exactly as shown on your set; Square signs the URL together with the body, so one different character breaks every delivery:
- Choose the latest API version and these events:
payment.createdpayment.updatedrefund.createdrefund.updatedsubscription.createdsubscription.updatedinvoice.payment_madeinvoice.scheduled_charge_faileddispute.createddispute.state.updated
- Save, open the subscription, and Show the Signature key. Paste it into the set.
Then Put in service (Test).
Test in the sandbox#
Pay with Square's sandbox card 4111 1111 1111 1111, any future date, CVV 111, any postal code. Square adds its processing fee a moment after the payment; the fee then appears on the payment.
What Square does differently#
- No free trials through Square: a plan with trial days does not show the Square tile.
- Cancel always takes effect at the end of the paid period.
- Square retries failed renewals itself; there is no "retry now".
- Dispute evidence is submitted in Square's dashboard; record it here afterwards.
Go live#
- [ ] Toggle the application to Production: production Application ID (
sq0idp-…), access token and Location ID in a live set. - [ ] A production webhook subscription with the live set's URL, the same events, and its own signature key.
- [ ] Products switched to the live set.
- [ ] One small real payment and refund.
Common errors#
| Message | Fix |
|---|---|
| Verify: location does not settle in USD | Choose a US location, or this account cannot be used. |
| Webhook deliveries answer 400 | The subscription URL differs from the set's URL, or the signature key is from another subscription. Each subscription has its own key. |
| Application ID belongs to the other environment | Sandbox IDs start sandbox-; production IDs do not. |
Technical details#
Credentials. Go to developer.squareup.com → your application → Credentials, using Sandbox or Production.
- Application ID.
- Access token, stored sealed.
- The Location ID from the Locations tab.
Verify reads the location. It fails unless the location settles in USD, and it reports whether card processing is enabled. Requests pin Square-Version: 2025-10-16.
Webhook. Go to Webhooks → Subscriptions → Add subscription. Paste the URL exactly as shown (https://encrypted.com/webhooks/square.php?cs=…), because Square signs the URL together with the body. If the site's base URL changes, update the subscription. Select these events:
- payment.created, payment.updated
- refund.created, refund.updated
- subscription.created, subscription.updated
- invoice.payment_made, invoice.scheduled_charge_failed
- dispute.created, dispute.state.updated
Copy the subscription's Signature key into the set. The check is base64(HMAC-SHA256(key, notification URL + raw body)).
One-time flow. A payment link is created from an order whose reference_id is our checkout id; the link's payment_note carries it as well. payment.updated with status COMPLETED marks the payment Paid. APPROVED or PENDING shows Processing; FAILED or CANCELED marks it Failed. Square usually adds processing_fee a little after completion: the later payment.updated fills in the fee without changing the paid time.
Subscriptions.
- A SUBSCRIPTION_PLAN (per product) and a SUBSCRIPTION_PLAN_VARIATION (per price, STATIC pricing; cadence MONTHLY, QUARTERLY or ANNUAL) are created once and cached.
- The payment link uses
quick_paywith the phase price andcheckout_options.subscription_plan_id= the variation id. Square's documentation names the fieldsubscription_plan_id, but it takes the variation id. - After payment Square creates the customer, the card on file and the subscription. The subscription is found with SearchSubscriptions (same customer and variation).
- If Square has not created it yet, the webhook answers 500 and Square retries.
- Renewals arrive as invoice.payment_made. Each charge is keyed by the Square payment id, so the first invoice and the checkout payment are never counted twice.
- invoice.scheduled_charge_failed means Past due. DEACTIVATED means Unpaid.
Free trials are not offered through Square. Square's hosted checkout supports a free phase, but how quick_pay pricing interacts with a free first phase is not verified. A trial plan with Square is refused before any checkout is created, with a clear message. Use PayPal, Stripe or Authorize.net for trials.
Cancellation. Square cancels at the end of the paid period. The subscription shows cancels at period end until then.
Refunds and disputes. Refunds go through the Refunds API and are confirmed by refund.updated with COMPLETED. REJECTED or FAILED refunds are not counted. Disputes: created means Disputed; LOST or ACCEPTED means Chargeback; WON means Paid again.
Authorize.net
Accounts you need#
- A merchant account and gateway from Authorize.net (directly or through a reseller or bank). Ask for eCheck.Net if you want US bank payments, and Automated Recurring Billing (ARB) for subscriptions.
- A free sandbox account from developer.authorize.net for testing. It has its own login and keys.
Copy the keys#
Merchant Interface → Account → Settings (new interface: Account and API Settings) → Security Settings → API Credentials & Keys:
- API Login ID — shown on the page.
- Transaction Key — choose New Transaction Key. Authorize.net asks for a PIN sent by email. Generating a new key ends the old one, so do it when nothing else uses the account.
- Signature Key — choose New Signature Key, again with the PIN. It is 128 hexadecimal characters.
Paste all three into a new Authorize.net credential set with environment Test. Verify calls the merchant details, checks USD and reports whether eCheck is enabled and whether the account is in test mode.
Register the webhook#
Merchant Interface → Account → Settings → Business Settings → Webhooks → Add Endpoint:
- Endpoint URL — Authorize.net does not allow a query string, so every Authorize.net set uses the same address:
- Status Active, and select these events:
net.authorize.payment.authcapture.creatednet.authorize.payment.authorization.creatednet.authorize.payment.capture.creatednet.authorize.payment.priorAuthCapture.creatednet.authorize.payment.refund.creatednet.authorize.payment.void.creatednet.authorize.payment.fraud.heldnet.authorize.payment.fraud.approvednet.authorize.payment.fraud.declinednet.authorize.customer.subscription.creatednet.authorize.customer.subscription.updatednet.authorize.customer.subscription.suspendednet.authorize.customer.subscription.terminatednet.authorize.customer.subscription.cancellednet.authorize.customer.subscription.expirednet.authorize.customer.subscription.failed
- Save. Deliveries are matched to your set by the Signature Key. Use one credential set per Authorize.net account.
Then Put in service (Test).
Enable what you sell#
- Accept Hosted (the hosted payment form) needs no setting.
- eCheck.Net must be enabled on the account; then tick US bank account on the product.
- ARB must be enabled for subscriptions.
- The Fraud Detection Suite may hold transactions for review. Held payments stay Processing until you approve or decline them in the Merchant Interface.
Test in the sandbox#
Use card 4111 1111 1111 1111, any future date, any CVV. Sandbox accounts can run in test mode, in which case transactions are not stored; turn test mode off in the sandbox's settings so that webhooks and refunds behave as in production.
Free trials sign up with a $1.00 authorization that is voided at once, so the buyer sees no charge. The first real charge comes when the trial ends.
Settlement, refunds and eCheck timing#
- Card payments settle once a day at the batch cut-off time. Before that, a payment can only be voided in full. After settlement, partial and full refunds work.
- eCheck payments stay Processing until settlement (1–3 business days). Authorize.net sends no webhook for settlement, so the hourly job
payments.reconcilechecks their status and marks them Paid or Failed. - Authorize.net does not report processing fees through its API: net equals gross for these payments, and reports mark them.
Go live#
- [ ] Production API Login ID, Transaction Key and Signature Key in a live set.
- [ ] Production webhook endpoint added and Active, with the same events.
- [ ] Account in Live mode (not test mode).
- [ ] Products switched to the live set.
- [ ] One small real payment, voided the same day, and another refunded after settlement if you want to test both.
Common errors#
| Message | Fix |
|---|---|
| Webhook deliveries answer 409 | Two credential sets use the same Signature Key. Keep one set per account. |
| Webhook deliveries answer 400 | The Signature Key in the set is not the current one (a new key ends the old one). |
| Partial refund not possible yet | The payment has not settled; void it in full, or refund after settlement. |
| Hosted page says expired | The buyer took more than 15 minutes; start a new checkout. |
Technical details#
Credentials. Go to Merchant Interface → Account → Security Settings → API Credentials & Keys.
- API Login ID.
- Transaction Key: 16 characters, stored sealed. Generating a new key invalidates the old one.
- Signature Key: 128 hex characters, stored sealed.
Verify calls getMerchantDetails. It checks USD and reports whether eCheck is enabled and whether the account is in test mode.
Webhook. Go to Account → Webhooks → Add Endpoint and paste https://encrypted.com/webhooks/authnet.php. Authorize.net does not allow a query string in webhook URLs, so every Authorize.net set shares this endpoint. Each delivery is matched to its set by the Signature Key, which means you must use one credential set per Authorize.net account; if two sets share a key, deliveries answer 409 and are logged. Select these events:
- net.authorize.payment.authcapture.created, .authorization.created, .capture.created, .priorAuthCapture.created
- net.authorize.payment.refund.created, .void.created
- net.authorize.payment.fraud.held, .fraud.approved, .fraud.declined
- net.authorize.customer.subscription.created, .updated, .suspended, .terminated, .cancelled, .expired, .failed
The check is X-ANET-Signature: sha512=<HEX>, the HMAC-SHA512 of the raw body. Authorize.net's samples key the HMAC with the Signature Key as text; some integrations hex-decode it first. Both forms are accepted, and both need the key.
One-time flow.
getHostedPaymentPagereturns a token.- The buyer's browser lands on our own page,
/pay/go/<checkout>, which posts the token to Accept Hosted. That page is the only one whose Content-Security-Policy allows a form to post there. Tokens expire after 15 minutes; an older checkout shows expired. - The order's
invoiceNumberis the last 20 characters of our checkout id, and the description carries the full id.
Cards are marked Paid on the auth-capture webhook. eCheck payments stay Processing until settlement. Authorize.net sends no webhook for settlement or returns, so the payments.reconcile job (hourly) asks for the transaction status: settledSuccessfully means Paid; returnedItem, voided or declined means Failed, and the buyer is emailed. Transactions held by the fraud filters stay Processing until they are approved or declined.
Subscriptions (ARB).
- The hosted transaction charges the first period and creates a customer payment profile (
profile.createProfile). - On its webhook an ARB subscription is created from that profile. It starts one interval later (quarterly = 3 months, annual = 12 months).
- Creation is idempotent: if the profile already has a subscription, it is reused rather than duplicated.
- ARB renewals arrive as auth-capture webhooks that carry the subscription id.
- A declined renewal, or subscription.suspended, means Past due. Cancelled, terminated or expired means Canceled.
Free trial.
- The sign-up is a $1.00 authorization only, a card check that is voided straight away, so the buyer is never charged.
- ARB starts when the trial ends. ARB's
trialOccurrencescounts whole intervals, so a 14-day trial is a later start date instead. - Trial sign-ups are card-only.
Refunds.
- Before settlement, usually within 24 hours, only a void of the full amount is possible. A partial refund is refused with an explanation.
- After settlement,
refundTransactionis sent with the last four digits of the card or account taken from the transaction details. - Both are confirmed by the void.created or refund.created webhook.
Fees. The API does not expose processing fees. These payments are recorded with fee_known = 0 (net = gross) and flagged as such in insights.
Paying payees with Stripe
To pay payees through Stripe, your own Stripe account becomes a Connect platform for them. Payees get accounts connected to your account, and their shares move from your Stripe balance to theirs as Stripe Transfers. Stripe then pays them to their bank. The billing platform is not involved in the money and charges nothing.
1. Turn on Connect#
- In the Stripe Dashboard of the account your customers pay (the one in your Stripe credential set), open Connect and choose Get started.
- Complete Stripe's platform profile. Choose that you will onboard accounts with Stripe-hosted onboarding and that you pay out (payees receive transfers; they do not take payments).
- Do the same in test mode first if you want to rehearse.
Payees get Express accounts. With Express accounts Stripe holds the platform — you — responsible for a payee account's negative balance; since payees only receive transfers, that happens only if you reverse a transfer that they have already paid out to their bank.
2. Choose the account in Payouts → Settings#
Under Stripe account, choose that Stripe credential set (it must use your own keys). Payouts in Live batches need a Live set; Test batches a Test set.
Add transfer.reversed to the set's webhook (Stripe → Developers → Webhooks → your endpoint → add event), so a transfer you reverse in the Dashboard puts the money back on the payee's balance here.
3. Payees set up their accounts#
Add the payee with Paid by: Stripe transfer and send the invitation. In their earnings page the payee presses Set up payouts with Stripe; Stripe asks for their details and bank account on its own pages and brings them back. When Stripe enables transfers for the account, the payee becomes Active. You can press Check status now on the payee's page; otherwise the system asks Stripe every 15 minutes while the payee is onboarding.
4. Payouts#
Each payout in a batch is one Transfer (POST /v1/transfers) from your balance, with the payout's id as Idempotency-Key, so a retry after a timeout never pays twice. A transfer needs that much available balance in your Stripe account; card payments become available on Stripe's own schedule. If it is not enough, the payout fails and the money returns to the payee's balance for the next batch.
If you reverse a transfer in Stripe (all or part), the reversal comes back through the transfer.reversed webhook: a full reversal makes the payout Returned, a partial one adds one adjustment to the payee's ledger. As a safety net the system also reads each paid transfer (GET /v1/transfers/{id}) once a day for 30 days after it was paid, so a missed webhook still gets booked; each reversal is booked once.
Sandbox test#
- Test-mode Stripe set chosen in Settings; a test product with a revenue share.
- Add a payee (Stripe), invite, complete Stripe's test onboarding with Stripe's test data.
- Pay with a test card that adds to your available balance immediately (Stripe's
4000 0000 0000 0077). - Payouts → Test mode → Build a test batch → Send. The payout shows Paid with a
tr_…reference; the transfer appears in Stripe → Connect → the payee's account.
Common errors#
| Message | Fix |
|---|---|
| Only Stripe Connect platforms can work with other accounts | Connect is not turned on for this Stripe account (step 1). |
| Your destination account needs … transfers | Stripe has not enabled transfers to the payee yet; they must finish onboarding. |
| You have insufficient available funds | Your Stripe balance is not available yet; wait or add funds, then build the next batch. |
| No such destination | The payee's account was rejected or removed in Stripe; ask the payee to set up again. |
Paying payees with PayPal
PayPal Payouts sends money from your PayPal Business account to payees' PayPal addresses, many at once. Each payout batch here becomes one PayPal payout batch.
1. Get Payouts enabled#
Payouts is not on by default for live accounts. In your PayPal Business account, request access to Payouts (PayPal reviews it; have your business details ready). Sandbox business accounts can use Payouts at once.
2. Use your REST app#
Payouts uses the same REST app as your PayPal credential set (developer.paypal.com → Apps & Credentials). Choose that set under Payouts → Settings → PayPal REST app. A Live set pays Live batches; a Sandbox set pays Test batches. A set connected through the platform's partner application cannot be used.
3. Add the payout events to the webhook#
On developer.paypal.com → your app → your webhook, add the events listed on the settings page: PAYMENT.PAYOUTS-ITEM.SUCCEEDED, …FAILED, …RETURNED, …UNCLAIMED, …BLOCKED, …CANCELED, …DENIED, …REFUNDED, PAYMENT.PAYOUTSBATCH.SUCCESS, PAYMENT.PAYOUTSBATCH.DENIED. Without them the system still asks PayPal every 15 minutes.
What payees see#
PayPal e-mails the payee when money arrives. A payee without a PayPal account at that address gets a sign-up invitation; the payout is Unclaimed until they accept it. PayPal returns unclaimed money to you after 30 days: the payout becomes Returned and its amount is back on the payee's balance. Correct the address on the payee's page and the next batch sends it again. You need not wait the 30 days: Cancel unclaimed on the batch page asks PayPal to cancel the item (POST /v1/payments/payouts-item/{id}/cancel); the money returns to your PayPal balance and to the payee's balance here at once. PayPal only cancels items that are still unclaimed.
PayPal may charge a fee per payout item, taken from your PayPal balance; payees receive the full amount.
Sandbox test#
- Sandbox PayPal set chosen in Settings; a test product with a revenue share; a payee (PayPal) with a sandbox personal account address.
- Pay the product with a sandbox buyer.
- Payouts → Test mode → Build a test batch → Send. The payout is Sent, then Paid when the sandbox reports SUCCESS.
Common errors#
| Message | Fix |
|---|---|
| Payouts is not enabled for this account | Step 1. |
| Insufficient funds | Your PayPal balance cannot cover the batch; add funds and build the next batch. |
| Receiver is unregistered / blocked | The address cannot receive; change it on the payee's page. |
| ITEM_CANNOT_BE_CANCELLED | The item is no longer unclaimed (claimed, paid or already returned); nothing changed. |