Skip to main content
POST
/
v1
/
transfers
Create Pix Transfer
curl --request POST \
  --url https://conta-public-api.kiwify.com/v1/transfers \
  --header 'Content-Type: application/json' \
  --header 'X-PoP-Challenge: <api-key>' \
  --header 'X-PoP-Format: <api-key>' \
  --header 'X-PoP-Signature: <api-key>' \
  --header 'x-access-id: <api-key>' \
  --data '
{
  "allowed_tax_ids": [
    "12345678909"
  ],
  "transfers": [
    {
      "amount_in_cents": 15000,
      "display_description": "Pagamento fornecedor",
      "external_reference_id": "payroll-2026-05-001",
      "pix_key": "12345678901",
      "pix_key_type": "cpf",
      "type": "pix_key"
    },
    {
      "account_number": "123456",
      "account_type": "payment_account",
      "amount_in_cents": 25000,
      "branch_code": "0001",
      "external_reference_id": "supplier-001",
      "ispb": "00000000",
      "name": "João Silva",
      "tax_id": "12345678909",
      "type": "bank_account"
    }
  ]
}
'
{
  "batch": {
    "created_at": "2026-05-28T14:30:00Z",
    "id": 123,
    "origin_bank_account_id": 123,
    "total_amount_in_cents": 123,
    "total_items": 123,
    "allowed_tax_ids": [
      "<string>"
    ],
    "idempotency_key": "<string>"
  },
  "transfers": [
    {
      "amount_in_cents": 123,
      "beneficiary": {
        "pix_key": "<string>",
        "resolved_account_number": "<string>",
        "resolved_branch": "<string>",
        "resolved_ispb": "<string>",
        "name": "<string>",
        "tax_id": "<string>"
      },
      "created_at": "2026-05-28T14:30:00Z",
      "id": 123,
      "display_description": "<string>",
      "end_to_end_id": "<string>",
      "external_reference_id": "<string>",
      "failed_message": "<string>",
      "scheduled_date": "2026-06-01",
      "transaction_id": 123
    }
  ]
}

Authorizations

​
x-access-id
string
header
required

UUID of the service account (e.g., 550e8400-e29b-41d4-a716-446655440000)

​
X-PoP-Challenge
string
header
required

Unix timestamp in milliseconds (e.g., 1704636800000). Must be within 5 minutes of server time.

​
X-PoP-Format
string
header
required

Must be 'service-account' for service account authentication

​
X-PoP-Signature
string
header
required

EdDSA signature of the request in base64 format. Signs: uri:method:body:timestamp

Headers

​
X-Idempotency-Key
string | null

Optional idempotency key for safe retries. When provided, requests with the same key return the same result. Without this header, duplicate external_reference_id values will fail with 400 Bad Request.

Body

application/json
​
transfers
(Chave Pix · object | Transferência manual · object)[]
required

Transfers to create in this batch (1–100 items).

Transfer to a PIX key (email, phone, CPF/CNPJ, or random key).

​
allowed_tax_ids
string[]

Optional list of CPF/CNPJ that restricts the allowed beneficiary documents for this batch. For pix_key transfers: the document resolved from the PIX key must match one of the listed values. For bank_account transfers: the tax_id provided in the transfer must be present in the list. When empty, transfers to any document are accepted.

Response

Transfers batch created successfully

​
batch
object
required

Batch metadata for the created transfers.

​
transfers
object[]
required

Individual transfer items in the batch.