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

# Payment Details

> Add a payment details to facilitate transfers to a counterparty.

## Add payment details

`POST /payment-details`

Attach bank account, mobile money, stablecoin, or book transfer routing information to a counterparty. The returned payment detail ID is used when initiating transfers.

### Request parameters

<ParamField body="payment_method" type="string" required>
  The payment rail. One of: `bank-transfer`, `momo-transfer`, `stablecoin-transfer`, `book-transfer`.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code (e.g. `USD`, `GBP`, `KES`). Use `USC` for USDC and `UST` for USDT.
</ParamField>

<ParamField body="account_holder_name" type="string" required>
  Full name of the payment recipient, as it appears on the receiving account.
</ParamField>

<ParamField body="entity_id" type="string" required>
  The entity initiating the payout.
</ParamField>

<ParamField body="counterpaty_id" type="string" required>
  The ID of the recipient counterparty
</ParamField>

<ParamField body="country" type="string">
  ISO alpha-2 destination country code. Required for bank transfers.
</ParamField>

<ParamField body="scheme" type="string">
  Payment scheme. Required when the currency supports multiple rails. For USD, specify `ach` or `wire`. For GBP, `fps` or `chaps`.
</ParamField>

### Request

<CodeGroup>
  ```bash FPS / GBP theme={null}
  curl -X POST https://api.nuvion.dev/payment-details \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method": "bank-transfer",
      "currency": "GBP",
      "country": "GB",
      "account_holder_name": "Jane Smith",
      "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
      "counterparty_id": "01KQESEEKSRKEKMACFX5H",
      "sort_code": "040004",
      "account_number": "12345678"
    }'
  ```

  ```bash ACH / USD theme={null}
  curl -X POST https://api.nuvion.dev/payment-details \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method": "bank-transfer",
      "currency": "USD",
      "country": "US",
      "scheme": "ach",
      "account_holder_name": "Danielle Brooks",
      "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
      "counterparty_id": "01KQESEEKSRKEKMACFX5H",
      "routing_number": "026009593",
      "account_number": "987654321012",
      "account_type": "checking",
      "bank_name": "Bank of America"
    }'
  ```

  ```bash Mobile Money theme={null}
  curl -X POST https://api.nuvion.dev/payment-details \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method": "momo-transfer",
      "currency": "KES",
      "account_holder_name": "John Smith",
      "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
      "counterparty_id": "01KQESEEKSRKEKMACFX5H",
      "scheme": "mpesa",
      "phone_number": "+254712345678"
    }'
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "01KM37FAABC123DEF456GHI789",
  "payment_method": "bank-transfer",
  "currency": "GBP",
  "country": "GB",
  "scheme": "fps",
  "account_holder_name": "Jane Smith",
  "sort_code": "040004",
  "account_number": "12345678",
  "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
  "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS"
}
```

***

### Retrieve Payment Details

To retrieve a payment detail, use the `GET /payment-details/{id}` endpoint with the payment detail ID returned from the `POST /payment-details` request.

<CodeGroup>
  ```bash Req theme={null}
  curl -X GET https://api.nuvion.dev/payment-details/"01KM37FAABC123DEF456GHI789" \
    -H "Authorization: Bearer $NUVION_API_KEY"
  ```

  ```bash 200 OK theme={null}
  {
      "status": "success",
      "message": "Payment detail retrieved successfully",
      "data": {
          "id": "01KM37FAABC123DEF456GHI789",
          "payment_method": "stablecoin-transfer",
          "currency": "USC",
          "account_holder_name": "Jane Smith",
          "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
          "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
          "scheme": "stablecoin",
          "wallet_address": "0x9829203632188bAAe5C0BFDd362Fd6FDdD943B61",
          "country": "US",
          "blockchain_network": "ETH_MAINNET"
      }
  }
  ```
</CodeGroup>

***

### Update Payment Details

To update a payment detail, use the `PATCH /payment-details/{id}` endpoint with the payment detail ID returned from the `POST /payment-details` request.

<CodeGroup>
  ```bash Req theme={null}
  curl -X PATCH https://api.nuvion.dev/payment-details/01KM37FAABC123DEF456GHI789 \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
      "bank_address": {
        "line1": "885 Teaneck Road",
        "city": "Teaneck",
        "state": "NJ",
        "country": "US",
        "postal_code": "07666"
      }
  }'
  ```
</CodeGroup>

<Tip>
  See [Send a Payout](/guides/send-a-payout) for the complete list of rail-specific required fields across all 24 corridors.
</Tip>