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

# Initiate an Internal Transfer Between Accounts

> POST /v1/payments/internal — Transfers funds between two accounts at the same bank partner. Requires com.diameterpay.api/payments.write scope.

Transfer funds between two Diameter virtual accounts that are held at the same bank partner. Internal transfers settle immediately within the bank partner's ledger and do not require external wire routing. Both accounts must belong to the same bank partner — attempting to transfer between accounts held at different bank partners will result in a validation error. Every request must include a unique `x-idempotency-key` to prevent duplicates on retry.

## Endpoint

```
POST /v1/payments/internal
```

**Required scope:** `com.diameterpay.api/payments.write`

## Headers

**Authorization** `string` *required*

`Bearer {access_token}`

**x-idempotency-key** `string` *required*

A unique UUID v4 for this request. Re-submitting the same key returns the original response without creating a duplicate transfer. Generate a new UUID for each distinct transfer.

## Request Body

**endToEndId** `string` *required*

Your unique reference for this transfer. Maximum 36 characters.

**debtorAccountId** `string` *required*

UUID of the Diameter virtual account to debit (the sending account).

**creditorAccountId** `string` *required*

UUID of the Diameter virtual account to credit (the receiving account). Must be at the same bank partner as `debtorAccountId`.

**amount** `string` *required*

The transfer amount as a decimal string, e.g. `"250.00"`. Must be a positive value with up to two decimal places.

**currency** `string` *required*

The transfer currency. Currently must be `USD`.

**description** `string` *required*

A description for the transfer, visible in transaction records. In the sandbox environment, prefix this value with `AUTO_APPROVE` to bypass the manual approval step (e.g., `"AUTO_APPROVE Sweep to reserve account"`).

**additionalInfo** `string`

Optional free-text field for supplementary transfer notes. Maximum 255 characters.

## Response Fields (201 Created)

**id** `string`

The Diameter-issued UUID for the created internal transfer. Use this to track status via [Get Payment](https://diameterpay.mintlify.site/api-reference/payments/get-payment.md).

## Notes

* Both `debtorAccountId` and `creditorAccountId` must belong to the same bank partner (`PORTAGE` or `SLOVAK_SAVINGS_BANK`). Cross-bank-partner transfers are not supported via this endpoint — use a wire payment instead.
* **Sandbox only:** Prefix the `description` field with `AUTO_APPROVE` to have the transfer automatically approved without manual review. This flag has no effect in production.

## Example Request

```bash theme={null}
curl --request POST \
  --url "https://api.diameterpay.com/v1/payments/internal" \
  --header "Authorization: Bearer {access_token}" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: 883b1733-15ce-74a7-d049-779988773333" \
  --data '{
    "endToEndId": "INT-SWEEP-2024-001",
    "debtorAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "creditorAccountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "amount": "5000.00",
    "currency": "USD",
    "description": "AUTO_APPROVE Daily sweep to reserve account",
    "additionalInfo": "Automated treasury sweep"
  }'
```

## Example Response

```json theme={null}
{
  "id": "f6a7b8c9-d0e1-2345-fabc-de3456789012"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.