# Verified Transfer

Verified Transfers are used to send money to a receiver you have already confirmed through a [Verified Account](https://docs.starkbank.com/api/v2/verified-account.md), without repeating the receiver's data on every payment.

You only inform the Verified Account id and the amount. The receiver name, tax ID, bank code, branch, account number and account type are copied from the Verified Account, so the money can only reach an account that has already been validated.

Creating a Verified Transfer creates a regular [Transfer](https://docs.starkbank.com/api/v2/transfer.md). The object you get back is a Transfer and the id you get back is a Transfer id, so from that point on you list it, cancel it, download its PDF and receive its webhook events through the Transfer routes.

### The Verified Transfer object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the transfer. This is a Transfer id and can be used on every Transfer route. |
| `accountNumber` | STRING | Receiver bank account number, copied from the Verified Account. |
| `accountType` | STRING | Receiver bank account type, copied from the Verified Account. Options: "checking", "savings", "salary", "payment", "other". |
| `amount` | INTEGER | Amount in cents to be transferred. Example: 1000 (R$10.00). |
| `bankCode` | STRING | Receiver bank code or ISPB, copied from the Verified Account. |
| `branchCode` | STRING | Receiver bank account branch, copied from the Verified Account. |
| `created` | STRING | Creation datetime. Example: "2020-02-06T16:22:24.664148+00:00". |
| `description` | STRING | Text displayed in the bank statement. When you do not send one, it defaults to the receiver name and tax ID. Example: "Tony Stark (012.345.678-90)". |
| `displayDescription` | STRING | Description shown in the receiver bank interface. Returns an empty string when none was sent. |
| `externalId` | STRING | Unique external ID to prevent duplicates. When you do not send one, it is generated from the workspace, the amount, the Verified Account data and the scheduled date. |
| `fee` | INTEGER | Fee charged in cents when the transfer is created. Example: 200 (R$2.00). |
| `metadata` | OBJECT | Dictionary object used to store additional information about the transfer. |
| `name` | STRING | Receiver full name, copied from the Verified Account. |
| `rules` | LIST OF OBJECTS | List of rule objects with key and value. |
| `scheduled` | STRING | Scheduled payment datetime. Example: "2020-08-14T10:00:00+00:00". |
| `status` | STRING | Current transfer status. Options: "created", "processing", "success", "failed", "canceled", "unknown". |
| `tags` | LIST OF STRINGS | Tags associated with the transfer. The tag "verified-account/<accountId>" is always added by us. All tags are returned in lowercase. |
| `taxId` | STRING | Receiver CPF or CNPJ, copied from the Verified Account. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the transfer. |
| `updated` | STRING | Last update datetime. Example: "2020-02-06T16:22:24.664148+00:00". |

### Create Verified Transfers

`POST /v2/verified-transfer`

This route is used to send transfers to receivers you have already verified. You can create up to 100 Verified Transfers in a single request.

**NOTE:**The receiver data (name, taxId, bankCode, branchCode, accountNumber and accountType) is always copied from the Verified Account identified by accountId, so it cannot be sent in the request.

**NOTE:**The Verified Account must not be canceled or failed. Accounts in the "creating", "created", "processing" and "active" statuses are accepted.

**NOTE:**The response carries Transfer objects. The accountId you sent is not echoed back as a field, but every created transfer is tagged with "verified-account/<accountId>".

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `accountId` | REQUIRED | Id of the Verified Account that will receive the money. Example: "5155165527080960" |
| `amount` | REQUIRED | A positive integer that represents the amount in cents to be transferred. Must be lower than 10^15. Example: 1000 (R$10.00) |
| `description` | OPTIONAL | Optional description to override the default description shown in the bank statement. Must have between 10 and 300 characters. Example: "Payment for service #1234" |
| `displayDescription` | OPTIONAL | Description to be shown in the receiver bank interface. Max = 300 characters. Example: "Payment for service #1234" |
| `externalId` | OPTIONAL | Unique url-safe ID to prevent duplicate transfers. Max = 170 characters. By default, it blocks transfers of the same amount to the same Verified Account on the same day. Example: "my-external-id" |
| `rules` | OPTIONAL | List of up to 3 rules for modifying transfer behavior. Keys are "resendingLimit" (integer from 0 to 10), "isReversalAllowed" (boolean) and "isPartialReversalAllowed" (boolean). Each key can be used only once. Example: ``` [{"key": "resendingLimit", "value": 5}] ``` |
| `scheduled` | OPTIONAL | Schedule the transfer for a specific date. Today is the default. A date without a time is scheduled for 07:00 (BRT). Example: "2020-08-14T15:23:26+00:00" or "2020-08-14" |
| `tags` | OPTIONAL | Array of up to 100 strings to tag the entity for future queries. Each tag can have up to 100 characters and all tags will be converted to lowercase. Example: ["iron", "suit"] |

**Request**

```python
import starkbank

transfers = starkbank.verifiedtransfer.create([
    starkbank.VerifiedTransfer(
        account_id="5155165527080960",
        amount=1000,
        external_id="my-external-id",
        scheduled="2020-08-14",
        description="Payment for service #1234",
        display_description="Payment for service #1234",
        tags=["iron", "suit"],
        rules=[
            starkbank.transfer.Rule(
                key="resendingLimit",
                value=5
            )
        ]
    )
])

for transfer in transfers:
    print(transfer)
```

**Response**

```python
VerifiedTransfer(
    id=5412038532661248,
    amount=1000,
    account_id=None,
    account_type=checking,
    external_id=my-external-id,
    scheduled=2020-08-14 10:00:00,
    description=Payment for service #1234,
    display_description=Payment for service #1234,
    tags=['iron', 'suit', 'verified-account/5155165527080960'],
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    fee=200,
    status=created,
    transaction_ids=[],
    metadata={},
    created=2020-02-06 16:22:24.664148,
    updated=2020-02-06 16:22:24.664148
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkbank.com/api/v2/verified-transfer-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/verified-transfer-node.md)
- [PHP](https://docs.starkbank.com/api/v2/verified-transfer-php.md)
- [Java](https://docs.starkbank.com/api/v2/verified-transfer-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/verified-transfer-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/verified-transfer-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/verified-transfer-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/verified-transfer-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/verified-transfer-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/verified-transfer-curl.md)