Stripe and PayPal

Connect Stripe or PayPal with your own API keys, let Rebutdesk create the dispute webhook, see the buyer's payments and refund them from a case.

You connect payment accounts with your own API keys. Rebutdesk checks the keys, creates a webhook in your account so disputes arrive on their own, and uses the same keys to show a buyer’s payments, refund them, and answer disputes. Keys are stored encrypted with BETTER_AUTH_SECRET and are never shown again.

Connecting accounts needs the “Connect Stripe and PayPal” permission (admins have it). See Sign-in and security.

Connect an account

  1. In the sidebar, open Payment accounts.
  2. Under Connect an account, pick the Stripe or PayPal tab.
  3. Fill in the fields below and click Connect Stripe or Connect PayPal.

Rebutdesk checks the keys with the processor first. If the processor refuses them, the form shows “Stripe refused these credentials: …” (or PayPal) with the processor’s reason, and nothing is saved.

You can connect more than one account of each kind.

Stripe fields

Field What to enter
Secret or restricted key A secret key (sk_live_..., sk_test_...) or a restricted key (rk_...) from the Stripe Dashboard under Developers, API keys.

A key containing _test_ is marked test on the connection.

A restricted key needs these permissions, based on the Stripe API calls Rebutdesk makes:

Permission Used for
Disputes: Write Checking the key, reading disputes, saving and submitting evidence, accepting (closing) disputes
Charges: Read Reading the disputed charge and the buyer’s charges
Customers: Read Finding the buyer’s payments by email, and reading the customer on a disputed charge
Files: Write Uploading the evidence PDF
Webhook Endpoints: Write Creating the webhook on connect and deleting it on removal
Refunds: Write Refunds from a case
Account: Read (optional) Showing your account name; without it the connection is still created

PayPal fields

Field What to enter
Environment live for real disputes, or sandbox for testing.
REST app client ID The client ID of a REST app in the PayPal developer dashboard, under Apps and Credentials.
REST app secret That app’s secret.

Use the credentials from the live tab of the developer dashboard for real disputes. Sandbox connections are marked sandbox.

The webhook

Each connection gets its own webhook URL:

<BETTER_AUTH_URL>/api/webhooks/payments/<connection id>

When you connect, Rebutdesk creates this webhook in your account for you:

  • Stripe: a webhook endpoint described “Rebutdesk disputes” for charge.dispute.created, charge.dispute.updated, charge.dispute.closed, charge.dispute.funds_withdrawn and charge.dispute.funds_reinstated. Its signing secret is stored with the connection.
  • PayPal: a webhook on your REST app for CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.UPDATED and CUSTOMER.DISPUTE.RESOLVED. Its webhook ID is stored with the connection.

If that worked, the page says “Stripe is connected. We created the webhook in your Stripe account.” and the connection shows “Webhook created by Rebutdesk.”

Every delivery is verified before anything is recorded: Stripe signatures are checked against the signing secret (and refused when older than 5 minutes), and PayPal deliveries are verified with PayPal’s verify-webhook-signature API. Rebutdesk then reads the full dispute from the processor instead of trusting the event body, so late or out-of-order events are handled correctly.

If the webhook cannot be created

If the key cannot create webhooks (for example a restricted key without Webhook Endpoints: Write), the connection is still saved and the page shows One more step: add the webhook in Stripe (or PayPal), with the reason after “We could not create it for you:”.

Add it by hand:

  1. Copy the webhook URL shown in the box.
  2. Stripe: in the Stripe Dashboard open Developers, Webhooks, Add endpoint. Paste the URL, pick the five events listed in the box, save, then reveal the signing secret and paste it into Webhook signing secret.
  3. PayPal: in the PayPal developer dashboard open your REST app, Webhooks, Add webhook. Paste the URL, tick the three events listed, save, then copy the webhook ID into Webhook ID.
  4. Click Save.

Until the signing secret or webhook ID is saved, deliveries fail verification and are refused. The connection then shows “Webhook added by hand.”

Managing a connection

Each connection on Payment accounts shows when its last event arrived (“Last event …” or “No events yet”) and has these actions:

  • Webhook URL shows the URL to copy.
  • Pause stops the connection. While paused, webhook deliveries are refused with 404, the connection is not used for payment lookups or refunds, and Resume turns it back on.
  • Remove deletes the connection. If Rebutdesk created the webhook, it is deleted from your Stripe or PayPal account too. If the processor refuses to delete it (for example because the key was revoked), the connection is still removed and a message asks you to delete the webhook in Stripe or PayPal yourself. Webhooks you added by hand must always be deleted by hand.

Disputes already recorded stay on their cases after a connection is removed.

Payments on a case

When you open a case whose buyer is known, the Payments section next to the timeline looks up the buyer’s recent payments in every active connection that supports it, and lists them with amount, processor, date, description, payment ID and how much was refunded. Payments linked to a dispute on the case are listed too. If one account fails, its error is shown and the others still load.

How the lookup works:

  • Stripe finds payments through Stripe customers: it uses the buyer’s Stripe customer ID when Rebutdesk knows it, and searches customers by the buyer’s email (up to 5 customers), then lists their charges, newest first, up to 10. Charges are not searchable by email directly, so a guest checkout that created no Stripe customer does not show up by email. Such a charge still appears when it is the charge of a dispute on the case.
  • PayPal cannot look payments up by buyer through the APIs Rebutdesk uses, so the section only shows PayPal payments that came with a dispute.

Refunds from a case

Members with the “Refund payments” permission (admins by default) see Refund under each payment that can still be refunded: it succeeded or completed, it is not fully refunded, and, on Stripe, it is not disputed.

  1. Click Refund.
  2. Enter the amount (the full remaining amount is filled in) and an optional Note for the timeline (optional).
  3. Click Refund and confirm.

The refund goes through the account the payment was found in, so with two Stripe accounts connected each payment is refunded from its own account. A payment stored before Rebutdesk recorded its account is linked again when the case’s payments refresh; until then, with several accounts of that kind connected, it shows no Refund button rather than guessing.

The refund is sent to the processor with an idempotency key, so a double click or a retry refunds once. On success the timeline gets “Refunded … of payment …”, the payment’s refunded amount goes up, and any pending refund promise on the case is marked kept.

  • Stripe refunds the charge with reason requested_by_customer; the note is stored in the refund’s metadata.
  • PayPal refunds the capture; the note is sent as the note to the payer (up to 255 characters).

If the processor refuses, the error is shown and nothing is recorded.

Things learned from real tests

  • Guest checkouts on Stripe. Payments are found by the buyer’s email through Stripe customers. If your checkout does not create a Stripe customer, the buyer’s charges do not appear by email.
  • PayPal webhooks can be slow. PayPal dispute webhooks can arrive several minutes after the dispute appears in PayPal. Wait before assuming the webhook is broken; the connection’s “Last event” time shows when the last one arrived.

For what happens when a dispute arrives, see Disputes and evidence.

Next: Disputes and evidence