Skip to main content
This guide walks through connecting PayPal Payouts to the TeraWallet Pro Wallet Withdrawal module, so approved requests are sent straight to the customer’s PayPal account and final status is reported back automatically.
Requires TeraWallet Pro with the Withdrawal module active, and a PayPal Business account with Payouts enabled. PayPal’s API calls are made server-side, so your site needs working outbound HTTPS.

​
How it works

  1. The customer requests a withdrawal; the wallet is debited the requested amount.
  2. When the request is approved (automatically, or by you), TeraWallet calls the PayPal Payouts API with the amount minus your processing fee.
  3. If PayPal accepts the batch (status PENDING, PROCESSING, SUCCESS or NEW), the request moves to Approved.
  4. PayPal later sends a webhook with the final result. On failure, TeraWallet cancels the request and restores the customer’s balance.

​
Step 1 — Create a PayPal REST app

  1. Sign in to the PayPal Developer Dashboard.
  2. Switch the toggle to Sandbox (for testing) or Live (for real payouts).
  3. Go to Apps & Credentials → Create App, choose type Merchant, and name it (e.g. “TeraWallet Payouts”).
  4. Open the app and copy the Client ID and Secret key.
  5. Under Features, tick Payouts and save.
Without the Payouts feature on the app (and Payouts approved on the Business account for live mode), PayPal rejects every payout request. Sandbox and Live use separate credentials — never mix them.

​
Step 2 — Fund the PayPal account

Payouts are drawn from the PayPal balance of the account that owns the app. Keep enough balance to cover pending withdrawals. In sandbox, add funds to your sandbox Business account from the dashboard under Testing Tools → Sandbox Accounts.

​
Step 3 — Configure TeraWallet

Go to TeraWallet → Settings → Withdrawal. General options PayPal gateway options Save your changes.

​
Step 4 — Register the webhook

Webhooks tell TeraWallet whether a payout actually succeeded or later failed.
  1. In the PayPal app, scroll to Webhooks → Add Webhook.
  2. Set the Webhook URL to:
    The URL must be public HTTPS. Use the same Sandbox/Live mode as your credentials.
  3. Subscribe to these events: Other event types are acknowledged and ignored.
  4. Save, then copy the generated Webhook ID into PayPal Webhook ID in TeraWallet and save.
Every webhook is verified against PayPal’s signature-verification API using your Webhook ID and credentials. If the Webhook ID is empty, or the signature is invalid, the request is rejected and no withdrawal changes. Cancelled requests have their wallet debit reversed, so the customer is made whole.

​
Step 5 — What customers need to do

Customers add their PayPal email once, under My Account → Wallet → Withdrawal → Payment Settings (field: PayPal email). If it is missing, the withdrawal form tells them to set it up before they can submit. The payout goes to this email address, so make sure customers use the one tied to their PayPal account.

​
Step 6 — Test in sandbox

  1. Set Mode to Sandbox / Test and use sandbox credentials and a sandbox webhook.
  2. In the dashboard, create a sandbox Personal account; use its email as the test customer’s PayPal email.
  3. As that customer, with a wallet balance, submit a withdrawal.
  4. In wp-admin, open the withdrawal list and Approve the request (or let Automatic mode do it).
  5. Check the request: it should be Approved, with log entries showing the PayPal response.
  6. Use Webhooks → Simulate event in the PayPal dashboard (e.g. PAYMENT.PAYOUTS-ITEM.SUCCEEDED, then a failure event on a second request) to confirm status changes and notes.
  7. Log in to the sandbox personal account at sandbox.paypal.com to see the received funds.

​
Go live checklist

  • Payouts approved on the live PayPal Business account and enabled on the live app
  • Mode switched to Live / Production
  • Live Client ID and Secret Key pasted
  • A new live webhook created, with its Webhook ID pasted (sandbox IDs do not work live)
  • PayPal balance funded
  • Enable logging turned off
  • One small real withdrawal tested end to end

​
Duplicate-payment protection

Each withdrawal is sent with a stored unique batch ID (also used as PayPal’s PayPal-Request-Id), so a retry after a timeout is treated by PayPal as the same request and cannot pay twice.

​
Troubleshooting

Enable Enable logging, then open the request in the withdrawal list to see its gateway log. Failure reasons are also saved as notes on the request.
Hosts that block unauthenticated REST requests (security plugins, WAFs, “REST API disabled” settings) can stop PayPal from reaching the webhook URL. Allow POST /wp-json/terawallet/v1/paypal/webhook.

​
Developer notes

  • The payout uses PayPal Payouts v1, with the recipient type EMAIL and the withdrawal ID as the sender_item_id.
  • Filter woo_wallet_paypal_payouts_sync_mode (default false) switches Payouts to synchronous mode.
  • Filter woo_wallet_withdrawal_payout_batch_status changes which batch statuses count as accepted (default PENDING, PROCESSING, SUCCESS, NEW).
See Pro Hooks & REST API for the full reference.