api-transfer-pix

```

Production: https://api.kobana.com.br

Sandbox: https://api-sandbox.kobana.com.br

```

```

Authorization: Bearer {your_api_token}

```

Pix Transfers

| Method | Endpoint | Description |

|--------|----------|-------------|

| GET | /v2/transfer/pix | List all Pix transfers |

| POST | /v2/transfer/pix | Create a new Pix transfer |

| GET | /v2/transfer/pix/{uid} | Get a specific Pix transfer |

| PUT | /v2/transfer/pix/{uid}/cancel | Cancel a Pix transfer |

Pix Transfer Batches

| Method | Endpoint | Description |

|--------|----------|-------------|

| GET | /v2/transfer/batches | List all transfer batches |

| POST | /v2/transfer/pix_batches | Create a new Pix transfer batch |

| GET | /v2/transfer/batches/{uid} | Get a specific batch |

| PUT | /v2/transfer/batches/{uid}/approve | Approve a batch |

| PUT | /v2/transfer/batches/{uid}/reprove | Reprove a batch |

Transfer by Pix Key (Minimum Required)

```json

POST /v2/transfer/pix

{

"amount": 100.50,

"financial_account_uid": "018df180-7208-727b-...",

"type": "key",

"key_type": "email",

"key": "recipient@example.com",

"beneficiary": {

"document_number": "12.345.678/0001-90",

"name": "Company LTDA"

}

}

```

Transfer by Bank Account

```json

POST /v2/transfer/pix

{

"amount": 500.00,

"financial_account_uid": "018df180-7208-727b-...",

"type": "bank_account",

"beneficiary": {

"document_number": "12.345.678/0001-90",

"name": "Company LTDA"

},

"bank_account": {

"compe_number": 341,

"agency_number": "1234",

"agency_digit": "5",

"account_number": "12345",

"account_digit": "6",

"document_number": "12.345.678/0001-90"

},

"scheduled_to": "2026-02-01",

"transfer_purpose": "98",

"external_id": "payment_2026_001",

"tags": ["monthly", "supplier"],

"custom_data": {

"invoice": "INV-2026-001"

}

}

```

By Pix Key (`type: "key"`)

• Requires key_type and key fields
• Key types: cpf, cnpj, email, phone, random
• Use for: Quick transfers when recipient's key is known

By Bank Account (`type: "bank_account"`)

• Requires bank_account object with account details
• Use for: Transfers when only bank account data is available

Pix transfers require a two-step process:

1. Create Transfer - POST /v2/transfer/pix creates a pending transfer
2. Create Batch - POST /v2/transfer/pix_batches sends transfers to the bank

Creating a Batch

```json

POST /v2/transfer/pix_batches

{

"financial_account_uid": "018df180-7208-727b-...",

"transfers": [

{ "uid": "019c0cbe-f018-717e-..." }

]

}

```

Or create transfers directly in the batch:

```json

POST /v2/transfer/pix_batches

{

"financial_account_uid": "018df180-7208-727b-...",

"transfers": [

{

"amount": 100.50,

"type": "key",

"key_type": "email",

"key": "recipient@example.com",

"beneficiary": {

"document_number": "12.345.678/0001-90",

"name": "Company LTDA"

}

}

]

}

```

Some financial accounts require manual approval:

1. Batch created - Status: pending or awaiting_approval
2. Approve - PUT /v2/transfer/batches/{uid}/approve
3. Or Reprove - PUT /v2/transfer/batches/{uid}/reprove

List Pix Transfers

```

GET /v2/transfer/pix?status=pending&per_page=50

```

| Parameter | Description |

|-----------|-------------|

| status | Filter by status (pending, confirmed, rejected) |

| registration_status | Filter by registration status |

| financial_account_uid | Filter by financial account |

| page / per_page | Pagination |

List Transfer Batches

```

GET /v2/transfer/batches?per_page=50

```

```

PUT /v2/transfer/pix/{uid}/cancel

```

Only pending transfers can be canceled. This is processed asynchronously.

Transfer Status

• pending - Pending (initial)
• awaiting_approval - Awaiting approval
• approved - Approved
• confirmed - Confirmed by bank
• rejected - Rejected by bank
• reproved - Reproved (canceled before sending)

Registration Status

• pending - Waiting for registration
• requested - Sent to bank
• confirmed - Confirmed at bank
• rejected - Rejected by bank
• failed - Registration failed

Batch Status

• pending - Pending (initial)
• awaiting_approval - Awaiting approval
• approved - Approved
• confirmed - All transfers confirmed
• reproved - Reproved

| Code | Description |

|------|-------------|

| 20 | Supplier Payment |

| 30 | Salary Payment |

| 32 | Fees Payment |

| 90 | Benefits Payment |

| 98 | Miscellaneous Payments (default) |

| Type | Description | Example |

|------|-------------|---------|

| cpf | CPF number | 111.222.333-44 |

| cnpj | CNPJ number | 11.222.333/0001-44 |

| email | Email address | user@example.com |

| phone | Phone number | +5511999999999 |

| random | Random key (EVP) | 123e4567-e89b-12d3-... |

1. Use batches for multiple transfers - More efficient than individual transfers
2. Set external_id - Track transfers in your system
3. Schedule transfers - Use scheduled_to for future-dated transfers
4. Use X-Idempotency-Key header - Prevent duplicates
5. Test in sandbox - Before production
6. Monitor batch status - Poll or use webhooks for status updates

See [references/REFERENCE.md](references/REFERENCE.md) for complete API documentation including all parameters, response formats, and error codes.