canonical: https://jentic.com/apis/hyperwallet.com/hyperwallet

# Hyperwallet Payout API

Jentic publishes the only available OpenAPI specification for Hyperwallet Payout API, keeping it validated and agent-ready. Hyperwallet is a PayPal-owned payout platform; the API exposes 13 endpoints for managing payee users, issuing payments, configuring bank accounts and transfer methods, and subscribing to webhook notifications. Calls run against the v4 sandbox at https://api.sandbox.hyperwallet.com/rest/v4 and authenticate with HTTP basic credentials issued from the Hyperwallet program portal. The API is designed for marketplaces, gig platforms, and creator economies that need to send money to many recipients.

## For AI agents

Onboard payees, send payouts, configure bank accounts and transfer methods, and subscribe to webhooks through Hyperwallet from an AI agent or backend service.

## Scope

Does not handle buyer-side payment acceptance, accounting, or tax filing - use for payee onboarding, payouts, transfer methods, and payout webhooks only.

## Capabilities

- Create and update payee user records inside a Hyperwallet program
- Issue a payment to a payee with currency, amount, and purpose fields
- Add and update bank account transfer methods for a payee
- List and configure transfer methods available to a payee
- Subscribe to webhook notifications for payment lifecycle events
- Retrieve a payment by token to read its current status

## Use cases

### Marketplace Seller Payouts

Run weekly payouts to marketplace sellers or freelancers by creating a user via /users, attaching a bank account via `/users/{userToken}/bank-accounts`, and issuing a payment via /payments. The webhook-notifications resource lets the marketplace track payout status without polling. This automates a flow that would otherwise require manual ACH or wire transfers.

Example prompt: POST /users to create the payee, POST `/users/{userToken}/bank-accounts` to attach a bank account, then POST /payments for $200 USD.

### Bank Account Onboarding

Build a payee onboarding flow that captures bank routing details and stores them on Hyperwallet through `/users/{userToken}/bank-accounts.` The API validates bank routing numbers and returns a transfer method token that future payouts reference, so the marketplace never stores raw bank credentials directly.

Example prompt: POST `/users/{userToken}/bank-accounts` with the routing number, account number, and currency.

### Payout Status Webhooks

Wire Hyperwallet webhook-notifications into an internal status dashboard or finance pipeline so finished payouts close out invoices automatically. The webhook payload includes the payment token, status, and timestamp, which downstream systems can match against a payout register. Saves polling `/payments/{paymentToken}` on a timer.

Example prompt: POST /webhook-notifications with the program webhook URL and an event filter for payment status changes.

### AI Agent Payout Operations

Give a finance ops AI assistant a scoped 'send_payout' tool that calls Hyperwallet via Jentic. The agent searches for 'send a payout to a creator', loads the schema, and executes the POST /payments call - the basic-auth credentials never enter the agent context, which matters for sensitive money-movement operations.

Example prompt: Search Jentic for 'send a payout', load the Hyperwallet POST /payments schema, and execute with currency=USD and amount=200.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/users` | Create a payee user |
| GET | `/users/{userToken}` | Retrieve a payee user record |
| POST | `/payments` | Issue a payment to a payee |
| GET | `/payments/{paymentToken}` | Retrieve a payment by token |
| POST | `/users/{userToken}/bank-accounts` | Add a bank account to a payee |
| GET | `/users/{userToken}/transfer-methods` | List transfer methods for a payee |
| POST | `/webhook-notifications` | Subscribe to webhook notifications |

## Key resources

- **Users** — Create and manage payee user records within a Hyperwallet program
- **Payments** — Issue and read payment records by token
- **Bank Accounts** — Configure bank account transfer methods on payees
- **Transfer Methods** — List and configure transfer methods available to a payee
- **Webhook Notifications** — Subscribe to lifecycle event notifications

## Why Jentic

- **Setup:** Wiring the Hyperwallet Payout API by hand means holding HTTP basic credentials, targeting the sandbox host under `/rest/v4` before your live host, and threading user tokens across payout and transfer-method calls yourself. Through Jentic you install once, import the Hyperwallet Payout API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** This API puts the user token in the URL path (`/users/{userToken}/bank-accounts`, `/users/{userToken}/transfer-methods`), so a rule can pin your agent to one payee: it can read that user's transfer methods and add a bank account and nothing else. You choose the operations it may call, so creating a payment is not included unless you add it.
- **Credential handling:** Your Hyperwallet basic credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. The raw username and password never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a payout to a creator' or 'add a payee bank account', and Jentic returns the matching Hyperwallet operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **PayPal Payouts API** — PayPal Payouts is the parent-platform alternative with similar bulk-payout endpoints
- **Payoneer API** — Payoneer is a marketplace payout alternative with similar bulk-payout endpoints
- **Stripe API** — Stripe collects payments from buyers while Hyperwallet sends payouts to sellers - they pair in marketplaces

## FAQ

### Why is there no official OpenAPI spec for Hyperwallet Payout API?

Hyperwallet publishes developer documentation but not a canonical OpenAPI specification in the catalogue. Jentic generates and maintains this spec so AI agents and developers can call Hyperwallet via structured tooling. It is validated against the documented API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Hyperwallet Payout API use?

The Hyperwallet API uses HTTP basic authentication with credentials issued from the Hyperwallet program portal. Through Jentic the basic credentials are stored in the credential vault and Jentic injects the Authorization header at execution time, so the raw credentials never enter the agent's context.

### Can I send a payout through the Hyperwallet API?

Yes. POST /payments with the destination user token, currency, amount, and purpose to issue a payout, then poll `/payments/{paymentToken}` or subscribe to /webhook-notifications to track status. Bank account transfer methods must be configured on the payee user before payouts can settle.

### What are the rate limits for the Hyperwallet Payout API?

The OpenAPI spec does not declare numeric rate limits. Hyperwallet sets program-specific limits in the merchant portal, so check your program configuration and watch for HTTP 429 responses to back off automatically before scaling traffic.

### How do I onboard a new payee through Jentic?

Search Jentic for 'create a Hyperwallet payee', load the schema for POST /users, and execute with the payee profile fields. Install with pip install jentic and use the async search, load, and execute pattern, then attach a bank account via POST `/users/{userToken}/bank-accounts.`

### Does the Hyperwallet API support webhook notifications?

Yes. POST /webhook-notifications subscribes the program to lifecycle events, and incoming payloads include the payment token and status. This avoids polling `/payments/{paymentToken}` on a timer to track payout completion.

### Can I limit what my agent is allowed to do with the Hyperwallet Payout API?

Yes. Because you run Jentic One yourself, your own rules decide which Hyperwallet operations and credentials the agent may use. Since the user token sits in the URL path on routes like `/users/{userToken}/transfer-methods` and `/users/{userToken}/bank-accounts`, you can pin the agent to a single payee and allow only reading that payee's transfer methods and adding a bank account. Issuing money via POST /payments stays off limits until you explicitly grant it.