# Stripe: payment links, status and refunds

> Connect Stripe to Avox with a restricted key, send payment links in WhatsApp chats, check payments, refund them, turn on instant updates and see what happens if Stripe fails.

Source: https://docs.theavoxai.com/connections/apps/stripe

Connect Stripe and an Avox automation can make a Stripe payment page for an amount and hand its link to the
next step, so it goes in the chat. From the payment's page you can check its status, refund it or cancel
the link. Money goes straight to your own Stripe account; Avox never holds it.

## What Avox can and cannot do

**Can:** create a payment page (a Stripe Checkout page) for one item; check whether it was paid, expired or
refunded; refund all or part of a paid payment; cancel an unpaid link; and hear from Stripe the moment a
page changes.

**Cannot:**

- Show every payment on your Stripe account. The **In Stripe** list shows payment pages only.
- Pass the customer's name or phone number to Stripe. Only the email is sent.

## What you need before you start

- A Stripe account and a **restricted key** with **Checkout Sessions: Write** and **Refunds: Write**. A
  secret key also works, but a restricted key can do less if it is ever leaked.
- A plan with room for another app ([AVX-3683](https://docs.theavoxai.com/error-codes/avx-3683), or
  [AVX-3706](https://docs.theavoxai.com/error-codes/avx-3706) without a plan).
- The **Manage connected apps** permission in your Switchboard to connect, test or disconnect. **See
  connected apps** lets people look at the rest.

A key starting with `rk_test_` or `sk_test_` connects in **Test mode**; `rk_live_` or `sk_live_` is live.
A Switchboard has one Stripe connection, so to move from test to live, use **Reconnect** with the live key.

## Connect Stripe

**1. Create the key in Stripe**

In the Stripe Dashboard open **Developers**, then **API keys**, and click **Create restricted key**. Give
it **Checkout Sessions: Write** and **Refunds: Write**, and copy the key.

**2. Open Stripe in Avox**

Open **Apps** in the sidebar, then **Stripe**, and click **Connect**. Read what Avox will be allowed to do
and click **Continue**.

**3. Paste the key**

Paste it into **Restricted key**, leave **Webhook signing secret** empty for now and click **Connect**. Avox
tries the key with Stripe, stores it encrypted and never shows it again, not even to you.

**4. Check the result**

A green message says Stripe is connected, with your Stripe account's name (or **Live mode** or **Test
mode**). Click **Open Stripe in Avox**.

Stripe uses your own key, so it never shows **Coming soon**.

## What you see in Avox afterwards

Open **Apps**, then **Stripe**. The menu (tabs on a phone) has **Overview**, **Payments** and **Activity**.

- **Overview**: the status badge (**Connected**, **Needs reconnecting** or **Having trouble**), who
  connected it, when it last worked, the last problem with its code, and **Test connection**,
  **Reconnect** and **Disconnect**. A good test says Stripe accepted the key and shows the mode.
- **Payments**: **Sent by Avox** is every link Avox made; **In Stripe** is Stripe's payment pages, 20 at a
  time with **Load more**.
- **Activity**: usage by day and the log, with a **Calls** tab and a **Webhooks** tab.

### Instant updates (webhooks)

**1. Copy Avox's address**

On Stripe's **Overview**, under **Instant updates**, copy Avox's address for Stripe. Keep it private.

**2. Add the endpoint in Stripe**

In Stripe open **Developers**, then **Webhooks**, and add an endpoint with that address. Tick
`checkout.session.completed`, `checkout.session.expired` and `charge.refunded`.

**3. Paste the signing secret**

Copy the endpoint's **Signing secret** (it starts with `whsec_`). In Avox, next to **Webhook signing
secret**, click **Add**, paste it and click **Save**.

Avox accepts an update only with a valid signature from the last 5 minutes. Without the secret it shows a
reminder ([AVX-3709](https://docs.theavoxai.com/error-codes/avx-3709)) and refuses every update. Each good update appears once under
**Webhooks**, even if Stripe sends it twice.

## Using Stripe in Avox

**Create a payment link.** In the automation builder add **Use a connected app**, set **What to do** to
**Create a payment link** and **With** to Stripe. Fill in **Amount** (normal units, like `49.50`),
**Currency** (like `USD`), **What it's for** (up to 200 characters, the customer sees it), and optionally
**Your reference** (up to 40 letters, numbers, `-` and `_`), **Customer email** and **Link works for
(minutes)**. A Stripe page stays open from 30 minutes to 24 hours; a longer time is cut to 24 hours, and
no time means 24 hours.

The step gives later steps `{{payment.url}}`, `{{payment.id}}` and `{{payment.status}}`. Under **If it
can't be done**, choose **Stop the run** or **Carry on with the next step**. App steps cost no credits.
Answers from a submitted Flow reach the step as `{{flow.<field>}}` when the automation starts with **Flow
submitted** (see [Automations with Tables and Flows](https://docs.theavoxai.com/automation/tables)).

**Example only, made up for illustration:** an automation starts when a customer submits a Flow about a
booking. Step 1 creates a payment link with Stripe, using the price and currency you chose and
`{{flow.email}}` as the customer email. Step 2 is a **Text reply** saying "Here is your payment link"
followed by `{{payment.url}}`.

**Check, refund and cancel.** Open **Payments**, then a payment. Buttons: **Copy payment link**, **Open
payment link**, **Open in Stripe**, **Check status now**, **Refund** and **Cancel link** (the last three
need **Manage connected apps**). Statuses are **Pending**, **Paid**, **Partly refunded**, **Refunded**,
**Expired** and **Cancelled**.

- **Refund** appears for a paid or partly refunded payment, for at most what is left, which is filled in
  for you. Add a reason if you like (Stripe keeps it as a note on the refund), type the amount again to
  confirm ([AVX-3723](https://docs.theavoxai.com/error-codes/avx-3723) if it differs) and click **Refund**. Stripe may take a few
  days to return the money. A refund above what is left gives [AVX-3719](https://docs.theavoxai.com/error-codes/avx-3719), and an
  unpaid payment [AVX-3720](https://docs.theavoxai.com/error-codes/avx-3720).
- **Cancel link** appears while the page is unpaid. The page stops working, and Stripe treats it as
  expired, so it may later show **Expired**. A paid or expired page gives
  [AVX-3721](https://docs.theavoxai.com/error-codes/avx-3721).

**Nothing is taken twice.** Give each link its own reference: Stripe then never makes two pages for the
same reference, even if the step runs again. Without a reference, Avox does not repeat a failed create by
itself, but running the automation twice makes two pages. Avox never repeats a refund or cancel on its own, and reads the payment from Stripe first, so only what is really left can be refunded.

## Limits

- **120 calls a minute** to Stripe from one Switchboard. Over that, calls are refused for the rest of the
  minute ([AVX-3695](https://docs.theavoxai.com/error-codes/avx-3695)) and nothing is sent to Stripe.
- Each try waits up to 10 seconds; an answer over 1 MB is refused.
- Descriptions stop at 200 characters and references at 40. Lists show 20 at a time.

## When Stripe fails or says no

Stripe can be slow, busy or refuse a request. The rest of your account keeps working.

- **Retries.** Reads, and creating a page **with a reference**, are tried up to 2 more times (after about
  0.4 and 1.2 seconds) when Stripe is busy or unreachable; if Stripe says how long to wait, Avox waits up
  to 5 seconds. Creating a page without a reference, a refund and a cancel are never repeated.
- **Status.** If Stripe stops accepting the key (deleted, rolled or wrong), the status becomes **Needs
  reconnecting** at once: the first refused call is logged as [AVX-3686](https://docs.theavoxai.com/error-codes/avx-3686), then
  calls are refused with [AVX-3692](https://docs.theavoxai.com/error-codes/avx-3692). Five failed calls in a row make it **Having
  trouble**; one good call puts it back to **Connected** by itself. A bad detail Avox catches first, like a
  missing field, does not count against it.
- **Log.** Every call is written to **Activity** with its result, number of tries and Stripe's own reason.
  Personal details are hidden and keys are never kept.
- **Automations.** The step stops the run or carries on, as you chose. While the app **Needs
  reconnecting** or your Switchboard is paused ([AVX-3711](https://docs.theavoxai.com/error-codes/avx-3711)), the step does not run
  ([AVX-3596](https://docs.theavoxai.com/error-codes/avx-3596) in the run). A refusal from Stripe is
  [AVX-3605](https://docs.theavoxai.com/error-codes/avx-3605).
- **Pages.** If Stripe cannot be read, **Payments** shows what Avox saved, with
  [AVX-3717](https://docs.theavoxai.com/error-codes/avx-3717) and a second code that says why, such as
  [AVX-3694](https://docs.theavoxai.com/error-codes/avx-3694) (not answering) or [AVX-3713](https://docs.theavoxai.com/error-codes/avx-3713) (refused). Click
  **Refresh** when it is back.

**Before you try a refund or cancel again,** click **Open in Stripe** and look at the payment's refunds. If
the refund is already listed, do not repeat it; then click **Check status now** in Avox. A refund that
timed out may still have gone through at Stripe.

## Disconnecting

On the **Overview** click **Disconnect**. Avox first shows what uses Stripe: those steps stop until you
connect again ([AVX-3708](https://docs.theavoxai.com/error-codes/avx-3708)). Avox deletes the key it saved and keeps the log for
your retention period. In Stripe, also delete the restricted key and Avox's webhook endpoint. Payments
already made are not affected.

## Common questions

**Avox says the key was refused**

[AVX-3686](https://docs.theavoxai.com/error-codes/avx-3686): copy the key again, whole and without spaces, and check it has
**Checkout Sessions: Write** and **Refunds: Write**. If the log entry names a missing permission, add it to
the key in Stripe.

**A payment was paid but Avox still says Pending**

Check the endpoint in Stripe uses the exact address on the Overview, has the three events ticked, and that
the signing secret in Avox matches. Click **Check status now** to ask Stripe directly.

**Can I try it with a test key first?**

Yes. A test key connects in **Test mode**. When you are ready, click **Reconnect** and paste the live key.

## Related