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

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

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

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

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

Code	Description
20	Supplier Payment
30	Salary Payment
32	Fees Payment
90	Benefits Payment
98	Miscellaneous Payments (default)

Key Types

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-...

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.