# Transfer (Pix or TED)

Transfers are used to send money to any bank account in Brazil using the Ted or Pix systems.

Here we will show you how to create and manage them.

If you send money repeatedly to the same receiver, you can confirm the account once with a [Verified Account](https://docs.starkbank.com/api/v2/verified-account.md) and then pay it with a [Verified Transfer](https://docs.starkbank.com/api/v2/verified-transfer.md), which creates a regular Transfer tagged with "verified-account/<accountId>".

### The Transfer object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the transfer. |
| `accountNumber` | STRING | Receiver bank account number. |
| `accountType` | STRING | Receiver bank account type. Options: "checking", "savings", "salary", "payment". |
| `amount` | INTEGER | Amount in cents to be transferred. Example: 100 (R$1.00). |
| `bankCode` | STRING | Receiver bank code or ISPB. |
| `branchCode` | STRING | Receiver bank account branch. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `description` | STRING | Text displayed in the bank statement. |
| `displayDescription` | STRING | Description shown in the receiver bank interface. |
| `externalId` | STRING | Unique external ID to prevent duplicates. |
| `fee` | INTEGER | Fee charged in cents. |
| `name` | STRING | Receiver full name. |
| `rules` | LIST OF OBJECTS | List of rule objects with key and value. |
| `scheduled` | STRING | Scheduled payment datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `status` | STRING | Current transfer status. Options: "created", "processing", "confirmed", "success", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the transfer. |
| `taxId` | STRING | Receiver CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the transfer. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Transfers

`POST /v2/transfer`

This route is used to send your transfers to their receivers.

You can create up to 100 transfers in a single request.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `accountNumber` | REQUIRED | Receiver bank account number. Use "-" before the validation digit. Example: 876543-2. |
| `amount` | REQUIRED | A positive integer that represents the amount in cents to be transferred. Example: 100 (R$1.00) |
| `bankCode` | REQUIRED | Besides informing the receiver bank, this parameter specifies whether this will be a Pix or a Ted transfer. If you wish to send a Pix, pass the bank ISPB (8 digits). Example: 20018183 = StarkBank. If you wish to send a Ted, pass the usual bank code (1 to 3 digits). Example: 665 = Stark |
| `branchCode` | REQUIRED | Receiver bank account branch. Use "-" in case there is a validation digit. Example: 1234-5 |
| `name` | REQUIRED | Receiver full name. Example: "Joana da Silva" |
| `taxId` | REQUIRED | Receiver CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90 |
| `accountType` | OPTIONAL | Receiver bank account type. Options are "checking", "payment", "savings" and "salary". "checking" is the default. This parameter only has effect on Pix Transfers. |
| `description` | OPTIONAL | Optional description to override default description to be shown in the bank statement. Example: "Payment for service #1234" |
| `displayDescription` | OPTIONAL | Description to be shown in the receiver bank interface. ex: "Payment for service #1234" |
| `externalId` | OPTIONAL | Unique ID to prevent duplicate transfers. Repeated externalIds should cause failures by duplication. By default, it blocks transfers to the same bank account with the same amount on the same day. Example: "my-internal-id-123456" |
| `rules` | OPTIONAL | List of rules for modifying transfer behavior. Example: ``` [{"key": "resendingLimit", "value": 5}] ``` |
| `scheduled` | OPTIONAL | Schedule the transfer for a specific date. Today is the default. Ted Transfer's schedules for today will be accepted until 16:00 (BRT) and will be pushed to the next business day afterwards. Pix Transfers are available 24/7 and can be scheduled for any date and time. Example: "2020-08-14T15:23:26+00:00" or "2020-08-14" |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

transfers = starkbank.transfer.create([
    starkbank.Transfer(
        amount=1000000,
        tax_id="123.456.789-10",
        name="Daenerys Targaryen Stormborn",
        bank_code="20018183",
        branch_code="2201",
        account_number="76543-8",
        external_id="my-external-id",
        scheduled="2020-08-14",
        tags=["daenerys", "invoice/1234"],
        rules=[
            starkbank.transfer.Rule(
                key="resendingLimit",
                value=5
            )
        ]
    )
])

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

**Response**

```python
Transfer(
    account_number=76543-8,
    account_type=checking,
    amount=1000000,
    bank_code=20018183,
    branch_code=2201,
    created=2020-02-06 16:22:24.664134,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    external_id=my-external-id,
    fee=0,
    id=5412038532661248,
    name=Daenerys Targaryen Stormborn,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    scheduled=2020-08-14 10:00:00,
    status=created,
    tags=['daenerys', 'invoice/1234'],
    tax_id=123.456.789-10,
    transaction_ids=[],
    updated=2020-02-06 16:22:24.664148
)
```

### List Transfers

`GET /v2/transfer`

Here you can list and filter all transfers you have made. We return it paged.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `sort` | OPTIONAL | Sort order considered in the response. Options are: "created", "-created", "updated" and "-updated". "-" means descending order. Default is "-created". |
| `status` | OPTIONAL | Filter transfers by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `taxId` | OPTIONAL | Filter transfers sent to the specified tax ID. |
| `transactionIds` | OPTIONAL | List of transaction IDs linked to the desired transfers. |

**Request**

```python
import starkbank

transfers = starkbank.transfer.query(
    after="2020-04-01",
    before="2020-04-30",
)

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

**Response**

```python
Transfer(
    account_number=76543-8,
    account_type=checking,
    amount=1000000,
    bank_code=665,
    branch_code=2201,
    created=2020-04-24 17:49:10.225810,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    external_id=my-external-id,
    fee=200,
    id=5950134772826112,
    name=Daenerys Targaryen Stormborn,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    status=processing,
    scheduled=2020-08-14 11:00:00,
    tags=['daenerys', 'invoice/1234'],
    tax_id=594.739.480-42,
    transaction_ids=['5991715760504832'],
    updated=2020-04-24 17:49:10.225810
)
```

### Get a Transfer

`GET /v2/transfer/:id`

Get a single transfer by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the transfer entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

transfer = starkbank.transfer.get("5950134772826112")

print(transfer)
```

**Response**

```python
Transfer(
    account_number=76543-8,
    account_type=checking,
    amount=1000000,
    bank_code=665,
    branch_code=2201,
    created=2020-04-24 17:49:10.225810,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    external_id=my-external-id,
    fee=200,
    id=5950134772826112,
    name=Daenerys Targaryen Stormborn,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    status=processing,
    scheduled=2020-08-14 11:00:00,
    tags=['daenerys', 'invoice/1234'],
    tax_id=594.739.480-42,
    transaction_ids=['5991715760504832'],
    updated=2020-04-24 17:49:10.225810
)
```

### Cancel a scheduled Transfer

`DELETE /v2/transfer/:id`

Cancel a scheduled transfer. You can only cancel transfers before they start being processed.

**NOTE:**Canceled transfers will still appear in your queries.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the transfer entity. |

**Request**

```python
import starkbank

transfer = starkbank.transfer.delete("6693962735681536")

print(transfer)
```

**Response**

```python
Transfer(
    account_number=76543-8,
    account_type=checking,
    amount=100000000,
    bank_code=665,
    branch_code=2201,
    created=2020-04-24 17:49:10.225810,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    external_id=my-external-id,
    fee=200,
    id=6693962735681536,
    name=Daenerys Targaryen Stormborn,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    status=canceled,
    scheduled=2020-08-14 11:00:00,
    tags=['daenerys', 'invoice/1234'],
    tax_id=594.739.480-42,
    transaction_ids=['5991715760504832'],
    updated=2020-04-24 17:49:10.225810
)
```

### Get a Transfer PDF

`GET /v2/transfer/:id/pdf`

Get a PDF from a single transfer by its id. A receipt only exists while the transfer status is "processing" or "success".

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the transfer entity. |

**Request**

```python
import starkbank

pdf = starkbank.transfer.pdf("5646210941583360")

with open("transfer.pdf", "wb") as file:
    file.write(pdf)
```

### List Transfer Logs

`GET /v2/transfer/log`

Get a paged list of all transfer logs. A log tracks a change in the transfer entity according to its life cycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `transferIds` | OPTIONAL | Array of transfer ids that are linked to the logs you desire. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.transfer.log.query(
    after="2020-04-01",
    before="2020-04-30"
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id=5662318377566208,
    created=2020-04-24 17:49:09.348444,
    errors=[],
    type=sending,
    transfer=Transfer(
        id=5950134772826112,
        account_number=76543-8,
        account_type=checking,
        amount=100000000,
        bank_code=665,
        branch_code=2201,
        created=2020-04-24 17:49:08.748893,
        description=Daenerys Targaryen Stormborn (594.739.480-42),
        external_id=my-external-id,
        fee=200,
        name=Daenerys Targaryen Stormborn,
        rules=[
            Rule(
                key=resendingLimit,
                value=5
            )
        ],
        status=processing,
        scheduled=2020-08-14 11:00:00,
        tags=['daenerys', 'invoice/1234'],
        tax_id=594.739.480-42,
        transaction_ids=['5991715760504832'],
        updated=2020-04-24 17:49:10.259578
    )
)
```

### Get a Transfer Log

`GET /v2/transfer/log/:id`

Get a single transfer log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the transfer entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

log = starkbank.transfer.log.get("5662318377566208")

print(log)
```

**Response**

```python
Log(
    id=5662318377566208,
    created=2020-04-24 17:49:09.348444,
    errors=[],
    type=sending,
    transfer=Transfer(
        id=5950134772826112,
        account_number=76543-8,
        account_type=checking,
        amount=100000000,
        bank_code=665,
        branch_code=2201,
        created=2020-04-24 17:49:08.748893,
        description=Daenerys Targaryen Stormborn (594.739.480-42),
        external_id=my-external-id,
        fee=200,
        name=Daenerys Targaryen Stormborn,
        rules=[
            Rule(
                key=resendingLimit,
                value=5
            )
        ],
        status=processing,
        scheduled=2020-08-14 11:00:00,
        tags=['daenerys', 'invoice/1234'],
        tax_id=594.739.480-42,
        transaction_ids=['5991715760504832'],
        updated=2020-04-24 17:49:10.259578
    )
)
```

## 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/transfer-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/transfer-node.md)
- [PHP](https://docs.starkbank.com/api/v2/transfer-php.md)
- [Java](https://docs.starkbank.com/api/v2/transfer-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/transfer-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/transfer-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/transfer-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/transfer-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/transfer-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/transfer-curl.md)