# PayPal: payment requests, status and refunds

> Connect PayPal to Avox with your own REST app, send PayPal payment requests in WhatsApp chats, check and refund payments, turn on instant updates and see what happens if PayPal fails.

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

Connect PayPal and an Avox automation can make a PayPal payment request 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 request. Money goes straight to your own PayPal account; Avox never holds it.

## What Avox can and cannot do

**Can:** create a PayPal payment request (a PayPal invoice) for one item; check whether it was paid,
cancelled or refunded; refund all or part of a paid request; cancel an unpaid one; and hear from PayPal
the moment a request is paid or cancelled.

**Cannot:**

- Show every PayPal payment. The **In PayPal** list shows invoices only.
- Set how long a request stays open. **Link works for** has no effect on PayPal: a request stays open
  until it is paid or cancelled.
- Refund a request you marked as paid by hand in PayPal, because no PayPal payment sits behind it.

## What you need before you start

- A PayPal Business account and a REST app in the PayPal Developer Dashboard that can use invoicing.
- The app's **Client ID** and **Secret**, for **Live** or for **Sandbox** if you want to test first.
- 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.

## Connect PayPal

**1. Get the credentials**

In the PayPal Developer Dashboard open **Apps & Credentials**, choose **Live** (or **Sandbox**), open or
create your app and copy its **Client ID** and **Secret**.

**2. Open PayPal in Avox**

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

**3. Paste the details**

Paste the **Client ID** and **Secret** and pick the matching **Environment**: **Live** or **Sandbox
(testing)**. Leave **Webhook ID** empty for now and click **Connect**. Avox signs in to PayPal with them,
stores them encrypted and never shows the secret again, not even to you.

**4. Check the result**

A green message says PayPal is connected.

PayPal uses your own credentials, so it never shows **Coming soon**. To move from sandbox to live, use
**Reconnect** with the live details.

## What you see in Avox afterwards

Open **Apps**, then **PayPal**. The menu 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 PayPal accepted the app and invoicing works.
- **Payments**: **Sent by Avox** is every request Avox made; **In PayPal** is your invoices, 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 PayPal's **Overview**, under **Instant updates**, copy Avox's address for PayPal. Keep it private.

**2. Add the webhook in PayPal**

In your PayPal app add a webhook with that address, in the same environment. Tick
`INVOICING.INVOICE.PAID`, `INVOICING.INVOICE.CANCELLED` and `PAYMENT.CAPTURE.REFUNDED`. PayPal then shows a
**Webhook ID**.

**3. Paste the Webhook ID**

In Avox, next to **Webhook ID**, click **Add**, paste it and click **Save**.

Avox checks every update with PayPal using that ID. Without it Avox shows a reminder
([AVX-3709](https://docs.theavoxai.com/error-codes/avx-3709)) and refuses every update. Paid and cancelled updates change the status
at once; a refund update is noted on the payment, and **Check status now** shows its new status.

## Using PayPal in Avox

**Create a payment request.** In the automation builder add **Use a connected app**, set **What to do** to
**Create a payment link** and **With** to PayPal. Fill in **Amount** (normal units, like `49.50`),
**Currency** (like `USD`), **What it's for** (up to 200 characters, used as the invoice note and item
name), and optionally **Your reference** (up to 40 letters, numbers, `-` and `_`), **Customer name** and
**Customer email**. With an email, PayPal also emails the request; without one, Avox only gives you the
link.

The step gives `{{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 PayPal, 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 request"
followed by `{{payment.url}}`.

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

- **Refund** appears for a paid or partly refunded request, for at most what is left, which is filled in
  for you. Add a reason if you like (PayPal sends it to the payer as a note), type the amount again to
  confirm ([AVX-3723](https://docs.theavoxai.com/error-codes/avx-3723) if it differs) and click **Refund**. PayPal 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 request [AVX-3720](https://docs.theavoxai.com/error-codes/avx-3720).
- **Cancel link** appears while the request is unpaid. It cancels the request in PayPal without emailing
  the customer. A paid or cancelled request gives [AVX-3721](https://docs.theavoxai.com/error-codes/avx-3721).

**Nothing is taken twice.** Every try at making a request carries the same repeat key, so PayPal does not
make a second request for one failed try. Avox never repeats a refund or cancel on its own, and reads the
request from PayPal first, so only what is really left can be refunded. Running an automation twice still
makes two requests.

## Limits

- **120 calls a minute** to PayPal 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 PayPal.
- Each try waits up to 10 seconds; an answer over 1 MB is refused.
- Descriptions stop at 200 characters, references at 40.

## When PayPal fails or says no

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

- **Retries.** Reads, signing in to PayPal and making the request are tried up to 2 more times (after about
  0.4 and 1.2 seconds) when PayPal is busy or unreachable; if PayPal says how long to wait, Avox waits up
  to 5 seconds. Sending the request after it is made, a refund and a cancel are never repeated.
- **Status.** If PayPal stops accepting the Client ID and Secret (deleted, rotated or the wrong
  environment), 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 does not count against it.
- **Log.** Every call is written to **Activity** with its result, tries and PayPal's own reason. Personal
  details are hidden and credentials 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 PayPal is
  [AVX-3605](https://docs.theavoxai.com/error-codes/avx-3605).
- **Pages.** If PayPal 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).

**Before you try again,** click **Open in PayPal** and look at the invoice. For a refund, if it is already
listed, do not repeat it; then click **Check status now** in Avox. A refund that timed out may still have
gone through. If a step failed while sending, look in the **In PayPal** list: Avox makes the request first
and sends it second, so a draft invoice can be left. Delete or send it in PayPal.

## Disconnecting

On the **Overview** click **Disconnect**. Avox first shows what uses PayPal: those steps stop until you
connect again ([AVX-3708](https://docs.theavoxai.com/error-codes/avx-3708)). Avox deletes the credentials it saved and keeps the log.
In PayPal you can also delete the app or Avox's webhook. Avox does not cancel requests it already sent, so
cancel any you want closed first.

## Common questions

**Can I test with the PayPal sandbox?**

Yes. Use the **Sandbox** Client ID and Secret, pick **Sandbox (testing)**, and add the webhook in the
sandbox app. When you are ready, click **Reconnect** with your live details.

**Avox says the details were refused**

[AVX-3686](https://docs.theavoxai.com/error-codes/avx-3686): copy the Client ID and Secret again, whole and without spaces, and check
the **Environment** matches where you copied them.

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

Check the webhook in your PayPal app uses the exact address on the Overview, has the three events ticked,
and that the Webhook ID in Avox matches. Click **Check status now** to ask PayPal directly.

## Related