> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portalhq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Payins

> Assign virtual bank account details and process fiat-to-stablecoin settlement with Noah payins through Portal.

## Overview

Noah payins let your client receive virtual bank account details, send fiat funds, and settle into stablecoins.

## 1. Prerequisite: approved KYC

Ensure the client completed Noah onboarding and has `APPROVED` status.

See [Noah KYC onboarding](/integrations/On-Off-Ramp/noah-kyc).

## 2. Initiate payin

Call `POST /payins` to create a bank-deposit-to-onchain workflow.

```bash theme={null}
curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/noah/payins \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "fiatCurrency": "USD",
    "cryptoCurrency": "USDC_TEST",
    "network": "eip155:11155111",
    "destinationAddress": "0xc118ad00663be7d0360b56a4e9fbb20530bf4693"
  }'
```

<Note>
  In Noah's sandbox, cryptocurrency tickers must be suffixed with `_TEST` (e.g. `USDC_TEST`). Drop the suffix in production. See [Noah's sandbox naming convention](https://docs.noah.com/products/global-payouts-api/#sandbox-cryptocurrency-naming-convention).
</Note>

### Optional: per-method business fees

Pass `businessFees` to apply a per-`PaymentMethodType` business fee on top of
the customer's transaction. Each entry is keyed by a Noah `PaymentMethodType`
(e.g. `BankAch`, `BankFedwire`, `BankSepa`) and configures a fixed
(`FeeBase`) and/or percentage (`FeePct`) fee in the given `FiatCurrency`.

```bash theme={null}
curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/noah/payins \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "fiatCurrency": "USD",
    "cryptoCurrency": "USDC_TEST",
    "network": "eip155:11155111",
    "destinationAddress": "0xc118ad00663be7d0360b56a4e9fbb20530bf4693",
    "businessFees": {
      "BankAch": { "FeeBase": "1", "FeePct": "0.5", "FiatCurrency": "USD" }
    }
  }'
```

Example response (truncated to key fields):

```json theme={null}
{
  "data": {
    "payinId": "cmmw70gq500053saq9urbu8ag",
    "bankDetails": {
      "accountHolderName": "John Mock-Doe",
      "accountNumber": "900366164700",
      "bankAddress": {
        "city": "Kansas City",
        "country": "US",
        "postCode": "64108",
        "state": "MO",
        "street": "1801 Main St"
      },
      "bankCode": "101019644",
      "bankName": "LEAD BANK",
      "network": "EthereumTestSepolia",
      "paymentMethodId": "Bank/Ach/USD/101019644/900366164700/cmmw6tzqc00003saqzbgwueb5",
      "paymentMethodType": "BankAch",
      "relatedPaymentMethods": [
        {
          "details": {
            "accountNumber": "900366164700",
            "bankCode": "101019644"
          },
          "paymentMethodId": "Bank/Fedwire/USD/101019644/900366164700/cmmw6tzqc00003saqzbgwueb5",
          "paymentMethodType": "BankFedwire"
        }
      ]
    }
  }
}
```

## 3. Display bank instructions

Show `bankDetails` to your user in your UI so they can submit their fiat transfer.

## 4. (Optional, sandbox) Simulate fiat deposit

To test payin flows in sandbox, call `POST /payins/simulate` with the
`paymentMethodId` returned in `bankDetails`.

```bash theme={null}
curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/noah/payins/simulate \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethodId": "Bank/Fedwire/USD/101019644/900366164700/cmmw6tzqc00003saqzbgwueb5",
    "fiatAmount": "100.00",
    "fiatCurrency": "USD"
  }'
```

Example response:

```json theme={null}
{
	"data": {
		"fiatDepositId": "accdeef0-c364-5b67-976c-f90a50aa957c"
	}
}
```

## 5. Configure Noah webhooks for payin updates

Set up Noah webhooks in Noah Dashboard to receive payin lifecycle updates directly from Noah.

* Subscribe to `FiatDeposit` and `Transaction` events for payin status and settlement updates.
* [Noah Webhooks](/integrations/On-Off-Ramp/noah-webhooks)

## 6. Monitor payin progress

Use `FiatDeposit` and `Transaction` webhook events plus Noah Dashboard delivery logs for payin reconciliation and status tracking.

<Tip>
  Acknowledge webhook deliveries quickly with `2XX`, then process events asynchronously.
</Tip>