api-payment-pix

```

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

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

```

```

Authorization: Bearer {your_api_token}

```

Pix Payments

| Method | Endpoint | Description |

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

| GET | /v2/payment/pix | List all Pix payments |

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

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

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

Pix Decoding

| Method | Endpoint | Description |

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

| POST | /v2/payment/pix/decode | Decode a Pix EMV (QR code/copy-paste) |

Payment Batches

| Method | Endpoint | Description |

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

| GET | /v2/payment/batches | List all payment batches |

| POST | /v2/payment/pix_batches | Create a Pix payment batch |

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

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

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

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

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

```json

POST /v2/payment/pix/decode

{

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

}

```

Response:

```json

{

"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):

```json

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):

```json

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"

}

```

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

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

```json

POST /v2/payment/pix_batches

{

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

"payments": [

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

]

}

```

Or create payments directly in the batch:

```json

POST /v2/payment/pix_batches

{

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

"payments": [

{

"emv": "00020126580014br.gov.bcb.pix...",

"amount": 150.00

}

]

}

```

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

List Pix Payments

```

GET /v2/payment/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 |

| created_from / created_to | Filter by creation date |

| page / per_page | Pagination |

List Payment Batches

```

GET /v2/payment/batches?per_page=50

```

```

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

```

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

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

| Type | Description |

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

| static | Static Pix - Fixed key, variable amount |

| dynamic | Dynamic Pix - Generated for specific charge with fixed amount |

| dynamic_due_date | Dynamic Pix with due date (Pix Cobrança) |

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

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