api-transfer-pix（API transfer PIX 文档）

Kobana Transfer API Skill

Manage Pix transfers, batches, and financial accounts via Kobana API.

Base URLs

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

Authentication

Authorization: Bearer {your_api_token}

API Endpoints Overview

Pix Transfers

Pix Transfer Batches

Creating a Pix Transfer

Transfer by Pix Key (Minimum Required)

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

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"
  }
}

Transfer Types

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

Important: Two-Step Flow

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

POST /v2/transfer/pix_batches

{
  "financial_account_uid": "018df180-7208-727b-...",
  "transfers": [
    { "uid": "019c0cbe-f018-717e-..." }
  ]
}

Or create transfers directly in the batch:

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"
      }
    }
  ]
}

Batch Approval Workflow

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

Listing and Filtering

List Pix Transfers

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

List Transfer Batches

GET /v2/transfer/batches?per_page=50

Canceling a Transfer

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

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

Status Reference

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

Transfer Purpose Codes

Key Types

Best Practices

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

Reference Documentation

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