# Payout Channel Form

The beneficiary details a channel needs, as a JSON Schema to render or fill in.

## Overview

Use it when you already have a channel and need its form again, or only the part a saved payment method still misses.

- `channelId` is a channel id from [Search Channels](https://docs.aureahub.com/docs/payout-channels.md), a UUID: anything else answers `400`.
- With `paymentMethodId` the schema asks only for what the bank ramp doesn't have yet; `formSchema` is `null` when the bank ramp needs nothing more. It's a `POST` because the id contains the account number. Send a body, even an empty `{}` for production.
- **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`. KYC approval is not needed to read; the bank ramp's own refusals pass through with their status and `details`. **A user who has not started their onboarding is a different case**: Aurea lets the read through and the bank ramp answers `404`, which arrives as `404` `NOAH_RESOURCE_NOT_FOUND`. The reason is worth knowing — **The bank ramp does not create the customer when the session is created, but when the user actually begins the hosted flow**, so until then the bank ramp has nobody by that id (measured against the bank ramp's sandbox on 21 September 2026: [Sync KYC Status](https://docs.aureahub.com/docs/payin-sync-status.md) answers `synced: false` and says the customer is not in the bank ramp yet). These reads become useful once the user has started onboarding.
- `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

### `POST /v1/ramp/bank/payout/channels/{channelId}/form`

Authentication: bearer token required.

Returns the JSON Schema of the details a payout channel needs.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channelId` | string | yes | the bank ramp's channel id (UUID) |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `paymentMethodId` | string | no | A saved payment method (1 to 150 characters) |
| `isTestnet` | boolean | no | `true` for the bank ramp's sandbox; `false` or omitted for production |

**Responses**

`200` OK

```json
{
  "environment": "sandbox",
  "channelId": "ebb9736b-08b3-599d-886b-10ee8aea82b5",
  "formSchema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "PaymentPurpose": { "type": "string", "title": "Payment Purpose" }
    },
    "required": ["PaymentPurpose"]
  },
  "formContentHash": "a1b2c3"
}
```

`200` Nothing more needed

```json
{
  "environment": "sandbox",
  "channelId": "ebb9736b-08b3-599d-886b-10ee8aea82b5",
  "formSchema": null,
  "formContentHash": null
}
```

---

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