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

# Internal transfers (P2P)

> Move funds between accounts within your institution instantly, 24/7, with no BACEN routing. The plugin detects internal transfers automatically.

P2P transfers move funds between accounts within your institution instantly, at no cost by default, 24 hours a day. You can configure fees per organization — see [Fee configuration](#fee-configuration) below. The transfer never leaves your system, so it settles synchronously and needs no BACEN network.

## When to use P2P

***

P2P is the right transfer type whenever both the sender and recipient hold accounts at your institution. Common scenarios include:

* **Moving money between a customer's own accounts** — a customer transferring from their checking account to their savings account, or between two accounts they manage.
* **Paying another customer at the same institution** — a customer sending money to a friend, family member, or business that also banks with you.
* **Internal treasury movements** — splitting balances between corporate accounts held within the same organization.
* **Payment splitting** — distributing amounts across multiple accounts for payroll, expense sharing, or cashback.

The plugin detects P2P automatically. When the recipient's ISPB matches your institution's ISPB, the plugin routes the transfer internally. Your API integration is identical to TED OUT, so you need no separate endpoint or logic.

## Key advantages

***

| Aspect               | P2P                                   | TED OUT                        |
| -------------------- | ------------------------------------- | ------------------------------ |
| **Settlement time**  | Real time (synchronous)               | Via JD SPB                     |
| **Operating hours**  | 24/7, including weekends and holidays | Mon–Fri, 06:30–17:00 (default) |
| **Fee (default)**    | None                                  | Configurable                   |
| **BACEN dependency** | None                                  | Required (JD SPB)              |

## How it works

***

P2P reuses the same API as TED OUT, so your integration stays consistent across transfer types. The process is two steps from the customer's perspective:

<img src="https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/ted-how-it-works-p2p.svg?fit=max&auto=format&n=SEOef3JqTInYAAau&q=85&s=5b2f5c4c8b5d0aee382a1ba5d6d73f28" alt="P2P flow diagram" width="1401" height="284" data-path="images/en/d2/ted-how-it-works-p2p.svg" />

1. **Initiate** — The customer submits the transfer details. The plugin validates the recipient, checks the sender balance, and confirms the fee (typically R\$ 0.00). The customer sees the transfer summary before committing.
2. **Confirm** — The customer confirms. The plugin creates an atomic debit + credit in Midaz. The transfer completes immediately.

The two-step flow gives you a natural moment to show the customer a confirmation screen with the full transfer summary before any funds move.

## Transfer states

***

<img src="https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/ted-state-machine-ted-p2p.svg?fit=max&auto=format&n=SEOef3JqTInYAAau&q=85&s=9129b5880915cbe6e6e8b8be0eaa7765" alt="P2P state machine diagram" width="784" height="461" data-path="images/en/d2/ted-state-machine-ted-p2p.svg" />

| State        | What it means                                      |
| ------------ | -------------------------------------------------- |
| `CREATED`    | Transfer initiated, awaiting customer confirmation |
| `PROCESSING` | Midaz atomic transaction underway                  |
| `COMPLETED`  | Transfer settled — funds have moved                |
| `FAILED`     | Internal error; no funds were moved                |
| `CANCELLED`  | Cancelled by the customer before confirmation      |

<Note>
  The `PENDING` state does not apply to P2P transfers. TED OUT uses `PENDING` to mark funds it reserves while it awaits SPB submission. P2P settles entirely within Midaz, so the transfer moves directly from `PROCESSING` to `COMPLETED`.
</Note>

## Fee configuration

***

<Note>
  The plugin disables fees by default. Most institutions offer internal transfers at no charge. The fee configuration is available if your pricing model needs it. To enable P2P fees, see [TED configuration](/en/rails/ted/jd/ted-configuration).
</Note>

## Recipient validation

***

The recipient must have an account at the same institution. When you submit a transfer, the plugin looks up the recipient in CRM. It matches the bank details you provide: ISPB, branch, account, and holder document.

If the plugin does not find the recipient, it rejects the transfer and moves no funds. The customer must check the account details and try again.

## Technical integration

***

P2P uses the same endpoints as TED OUT. You need no extra integration work beyond the outbound transfer flow you already built.

* [Initiate Transfer](/en/reference/midaz/plugins/ted/initiate-transfer) — POST /v1/transfers/initiate
* [Process Transfer](/en/reference/midaz/plugins/ted/process-transfer) — POST /v1/transfers/process
* [Get Transfer](/en/reference/midaz/plugins/ted/retrieve-transfer) — GET /v1/transfers/{transferId}

<Note>
  The `type` field in the transfer response is `P2P`. P2P transfers have no `controlNumber`, because they do not go through JD SPB.
</Note>

## Error handling

***

P2P transfers are atomic. The plugin creates the debit and credit as a single Midaz transaction. If any part fails, Midaz applies neither leg. No intermediate state moves funds partially or leaves an account short.

If a transfer fails, the customer keeps the same balance and can retry. See the [full error list](/en/reference/midaz/plugins/ted/ted-error-list) for error codes and recovery guidance.