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

Kobana Payment API Skill

Pay Pix charges, decode QR codes, and manage Pix payments 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 Payments

Pix Decoding

Payment Batches

Paying a Pix Charge

Step 1: Decode the Pix EMV (Optional but Recommended)

Before paying, decode the QR code to validate the charge data:

POST /v2/payment/pix/decode

{
  "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000..."
}

Response:

{
  "status": 200,
  "data": {
    "type": "static",
    "key": "recipient@example.com",
    "key_type": "email",
    "merchant_name": "Company LTDA",
    "merchant_city": "São Paulo",
    "amount": 150.00,
    "txid": "PAYMENT123456",
    "description": "Invoice January 2026"
  }
}

Step 2: Create the Payment

By EMV (QR Code/Copy-Paste):

POST /v2/payment/pix

{
  "financial_account_uid": "018df180-7208-727b-...",
  "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000...",
  "amount": 150.00,
  "scheduled_to": "2026-01-31",
  "external_id": "payment_001"
}

By Pix Key (Static Pix):

POST /v2/payment/pix

{
  "financial_account_uid": "018df180-7208-727b-...",
  "type": "key",
  "key_type": "email",
  "key": "recipient@example.com",
  "amount": 150.00,
  "beneficiary": {
    "document_number": "12.345.678/0001-90",
    "name": "Company LTDA"
  },
  "external_id": "payment_001"
}

Payment Types

By EMV (Dynamic Pix)

• Use when you have a QR code or copy-paste string
• Amount may be fixed by the charge
• Most common for invoices and bills

By Pix Key (Static Pix)

• Use when paying directly to a Pix key
• You define the amount
• Use for donations, tips, or manual payments

Important: Two-Step Flow

Pix payments require a two-step process:

1. Create Payment - POST /v2/payment/pix creates a pending payment
2. Create Batch - POST /v2/payment/pix_batches sends payments to the bank

Creating a Batch

POST /v2/payment/pix_batches

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

Or create payments directly in the batch:

POST /v2/payment/pix_batches

{
  "financial_account_uid": "018df180-7208-727b-...",
  "payments": [
    {
      "emv": "00020126580014br.gov.bcb.pix...",
      "amount": 150.00
    }
  ]
}

Batch Approval Workflow

Some financial accounts require manual approval:

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

Listing and Filtering

List Pix Payments

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

List Payment Batches

GET /v2/payment/batches?per_page=50

Canceling a Payment

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

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

Status Reference

Payment 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 payments confirmed
• reproved - Reproved

Pix Types

Key Types

Best Practices

1. Decode before paying - Validate the charge data before creating payment
2. Use batches for multiple payments - More efficient than individual payments
3. Set external_id - Track payments in your system
4. Schedule payments - Use scheduled_to for future-dated payments
5. Use X-Idempotency-Key header - Prevent duplicates
6. Test in sandbox - Before production
7. 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.