# Saved Payout Beneficiaries

The bank accounts and other payment methods the user can be paid out to, read live from the bank ramp.

## Overview

The bank ramp keeps the payment methods a user was paid out to. Show them so the user can pay out to the same account again without typing it, and pass `paymentMethodId` to [Search Channels](https://docs.aureahub.com/docs/payout-channels.md) or [Channel Form](https://docs.aureahub.com/docs/payout-channel-form.md).

- `paymentMethodId` is the bank ramp's id of the payment method. It contains the account number: send it only in a request body — the payout endpoints never take it in a URL, which servers write to their logs.
- `details.type` says which fields apply: `bank` (`accountNumber`, `bankCode`, `routingNumber`, `swiftCode`, `bankName`, `bankingSystems`, `bankAddress`), `card` (`last4`, `scheme`), `identifier` (`identifierType` and `identifier`, for example a tax id), or `unknown` for a display type the bank ramp doesn't document, shown without fields.
- `accountHolder` is the name on the account; `capabilities.payoutTo` tells whether a payout can go to it.
- One page at a time: send `nextPageToken` back as `pageToken` until it is `null`. `pageSize` is 1 to 100.
- **Payouts must be switched on** for your tenant in that environment ([Tenant Settings](https://docs.aureahub.com/docs/bank-settings.md)): otherwise `403` `NOAH_FUNCTION_OFF`. A tenant that does not use the bank ramp, or a token without a tenant, gets `403`.
- The user needs a bank ramp profile in that environment ([Onboarding Session](https://docs.aureahub.com/docs/payin-session.md)): otherwise `404` with `details.code` `NOAH_CUSTOMER_NOT_FOUND`. The bank ramp's own refusals pass through with their status and `details`.
- `isTestnet=true` reads the bank ramp's sandbox with the user's sandbox profile; `false` or omitted reads production. Nothing is stored and nothing moves.

## Endpoint

### `GET /v1/ramp/bank/payout/beneficiaries`

Authentication: bearer token required.

Returns one page of the payment methods the user's bank ramp customer can be paid out to.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `pageSize` | integer | no | 1 to 100; the bank ramp's default is 20 |
| `pageToken` | string | no | nextPageToken of the previous page |
| `isTestnet` | boolean | no | `true` for the bank ramp's sandbox; `false` or omitted for production |

**Responses**

`200` OK

```json
{
  "environment": "sandbox",
  "beneficiaries": [
    {
      "paymentMethodId": "<bank payment method ID>",
      "paymentMethodType": null,
      "country": "DE",
      "paymentMethodCategory": "Bank",
      "details": {
        "type": "bank",
        "accountNumber": "<IBAN>",
        "bankCode": "<BIC>",
        "routingNumber": null,
        "swiftCode": null,
        "bankName": "<bank name>",
        "bankingSystems": [],
        "bankAddress": null,
        "last4": null,
        "scheme": null,
        "identifierType": null,
        "identifier": null
      },
      "accountHolder": {
        "type": "Individual",
        "firstName": "<first name>",
        "middleName": null,
        "lastName": "<last name>",
        "nameLocal": null,
        "businessName": null
      },
      "issuerName": "<bank name>",
      "capabilities": { "payoutTo": true, "payoutFrom": false, "payinTo": false }
    }
  ],
  "nextPageToken": null
}
```

---

Web version: https://docs.aureahub.com/#payout-beneficiaries