Criar Transacao (PIX)

Cria uma transacao de pagamento via PIX. Valores monetarios sao sempre em centavos (inteiros).

POST/api/v1/transactions/create

Headers Obrigatorios

Headershttp

Content-Type: application/json
Accept: application/json
X-Client-Id: <client_id>
X-API-Key: <api_key>
Idempotency-Key: tx_<unique> (Recomendado)

Importante

Todos os valores monetarios (amount, unitPrice, fee) devem ser informados em centavos. Exemplo: R$ 5,00 = 500

Request Body

Request Bodyjson

{
  "amount": 500,
  "currency": "BRL",
  "paymentMethod": "PIX",
  "installments": 1,
  "customer": {
    "id": "CUST-1729131560000",
    "name": "Joao Teste",
    "email": "[email protected]",
    "document": { "number": "24577481600", "type": "CPF" },
    "phone": "11987654321",
    "externalRef": "LEAD-1234"
  },
  "items": [
    {
      "title": "Produto X",
      "unitPrice": 500,
      "quantity": 1,
      "tangible": true,
      "externalRef": "SKU-001"
    }
  ],
  "pix": { "expiresInDays": 1 },
  "postbackUrl": "https://seu-site.com/webhook",
  "metadata": "{\"origem\":\"n8n\",\"ambiente\":\"producao\"}",
  "traceable": true,
  "ip": "177.123.45.67"
}

Response 200 (PIX)

Response (200 OK)json

{
  "data": {
    "id": "ebe485c6-cdf4-4736-aa3e-464044c4d4eb",
    "externalRef": "686725",
    "amount": 500,
    "refundedAmount": 0,
    "providerCompanyId": "b6877393-8a98-4e4e-8a20-e086aacf3d8c",
    "companyId": 1,
    "installments": 1,
    "paymentMethod": "PIX",
    "status": "WAITING_PAYMENT",
    "postbackUrl": "https://seu-site.com/webhook",
    "metadata": null,
    "traceable": true,
    "createdAt": "2025-10-17T01:38:51.943Z",
    "updatedAt": "2025-10-17T01:38:51.943Z",
    "pix": {
      "qrcode": "00020126580014br.gov.bcb.pix...",
      "url": null,
      "expirationDate": "2025-10-18T01:38:51.943Z"
    }
  },
  "status": 200,
  "message": "Transacao criada com sucesso."
}

Exemplo cURL

cURLbash

curl -X POST https://korvopay.com/api/v1/transactions/create \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -H "Idempotency-Key: tx_$(date +%s)_$RANDOM" \
  -d '{
    "amount": 500,
    "currency": "BRL",
    "paymentMethod": "PIX",
    "customer": {
      "id": "CUST-123",
      "name": "Joao",
      "email": "[email protected]",
      "document": {"number": "24577481600", "type": "CPF"},
      "phone": "11987654321"
    },
    "items": [{
      "title": "Produto X",
      "unitPrice": 500,
      "quantity": 1,
      "tangible": true
    }],
    "pix": { "expiresInDays": 1 }
  }'