Skip to main content
POST
/
api
/
v1
/
payments
curl -X POST 'https://app.plowf.com/api/v1/payments' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 250.00,
    "type": "pix",
    "external_ref": "PED-001",
    "final_beneficiary": {
      "name": "Maria Santos",
      "document": "98765432100"
    },
    "splits": [
      {
        "type": "percentage",
        "value": 10,
        "recipient_account_uuid": "550e8400-e29b-41d4-a716-446655440000"
      },
      {
        "type": "fixed",
        "value": 5.00,
        "recipient_account_uuid": "660e8400-e29b-41d4-a716-446655440001"
      }
    ]
  }'

{
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440000",
    "value": 250,
    "total_value": 255,
    "fees": 5,
    "currency": "BRL",
    "status": "PENDING",
    "type": "PIX",
    "payment": {
      "uuid": "880e8400-e29b-41d4-a716-446655440001",
      "value": 250,
      "type": "PIX",
      "status": "PENDING",
      "payload": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913FULANO DE TAL6008BRASILIA62070503***63041D3D",
      "pix": {
        "sender": null,
        "receiver": {
          "name": "Empresa Demo LTDA",
          "document": "12345678000190",
          "account_number": "9876543",
          "account_agency": "0001",
          "bank": {
            "code": "",
            "name": "PLOWF IP LTDA.",
            "ispb": "00000000"
          },
          "account_type": "CHECKING"
        },
        "txid": "770e8400e29b41d4a716446655440000",
        "value": 250,
        "type": "QR_DYNAMIC",
        "pix_key": "1234567890",
        "additional_info": [
          {
            "name": "ID da cobrança",
            "value": "770e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "transaction": null,
        "status": "PENDING",
        "expires_at": "2024-01-01T23:59:59Z",
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-01T10:00:00Z"
      },
      "expires_at": "2024-01-01T23:59:59Z",
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:00:00Z"
    },
    "external_ref": "PED-001",
    "final_beneficiary": {
      "name": "Maria Santos",
      "document": "98765432100"
    },
    "splits": [
      {
        "uuid": "990e8400-e29b-41d4-a716-446655440002",
        "type": "PERCENTAGE",
        "value": 10,
        "status": "PENDING",
        "recipient_account": {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Empresa Parceira LTDA"
        }
      },
      {
        "uuid": "aa0e8400-e29b-41d4-a716-446655440003",
        "type": "FIXED",
        "value": 5,
        "status": "PENDING",
        "recipient_account": {
          "uuid": "660e8400-e29b-41d4-a716-446655440001",
          "name": "Taxa Plataforma"
        }
      }
    ],
    "history": [
      {
        "status": "PENDING",
        "created_at": "2024-01-01T10:00:00Z"
      }
    ],
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  }
}
Cria um nova cobrança PIX In (gera QR Code/Copia e Cola para recebimento). 
curl -X POST 'https://app.plowf.com/api/v1/payments' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 250.00,
    "type": "pix",
    "external_ref": "PED-001",
    "final_beneficiary": {
      "name": "Maria Santos",
      "document": "98765432100"
    },
    "splits": [
      {
        "type": "percentage",
        "value": 10,
        "recipient_account_uuid": "550e8400-e29b-41d4-a716-446655440000"
      },
      {
        "type": "fixed",
        "value": 5.00,
        "recipient_account_uuid": "660e8400-e29b-41d4-a716-446655440001"
      }
    ]
  }'

​
Body Parameters

​
value
number
required
Valor da cobrança. Mínimo: 0
​
type
string
required
Tipo da cobrança. Deve ser exatamente "PIX"
​
final_beneficiary
object
required
Dados do beneficiário final (seller)
​
external_ref
string
Referência externa para identificação da cobrança
​
provider_uuid
string
UUID do provedor que receberá a cobrança. Quando omitido, a Plowf escolhe o provedor padrão da conta para PIX (configurável em PUT /providers/defaults). Liste os UUIDs disponíveis em GET /providers.Ignorado quando o token está vinculado a um provedor — neste caso, o provedor do token sempre prevalece.
​
splits
object[]
Lista de regras de split para distribuição do valor recebido entre outras contas

​
Validações

  • type deve ser exatamente “pix”
  • value deve ser maior ou igual a 0
  • Se final_beneficiary for enviado, ambos name e document são obrigatórios
  • document deve ser um CPF ou CNPJ válido se informado
  • Para splits do tipo percentage, o valor não pode exceder 100%
  • A soma de todos os splits percentuais não pode exceder 100%
  • A soma de todos os splits (percentual + fixo) não pode ser maior que o valor total da cobrança
  • A combinação de recipient_account_uuid e type deve ser única por cobrança (não é possível ter dois splits do mesmo tipo para a mesma conta)
  • provider_uuid, se informado, deve referenciar um provedor existente na conta. Se omitido, o provedor padrão de PIX da conta é usado.

​
Resposta de Sucesso

A resposta retorna o objeto da cobrança criado com o QR Code/Copia e Cola no campo payment.payload. 
{
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440000",
    "value": 250,
    "total_value": 255,
    "fees": 5,
    "currency": "BRL",
    "status": "PENDING",
    "type": "PIX",
    "payment": {
      "uuid": "880e8400-e29b-41d4-a716-446655440001",
      "value": 250,
      "type": "PIX",
      "status": "PENDING",
      "payload": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913FULANO DE TAL6008BRASILIA62070503***63041D3D",
      "pix": {
        "sender": null,
        "receiver": {
          "name": "Empresa Demo LTDA",
          "document": "12345678000190",
          "account_number": "9876543",
          "account_agency": "0001",
          "bank": {
            "code": "",
            "name": "PLOWF IP LTDA.",
            "ispb": "00000000"
          },
          "account_type": "CHECKING"
        },
        "txid": "770e8400e29b41d4a716446655440000",
        "value": 250,
        "type": "QR_DYNAMIC",
        "pix_key": "1234567890",
        "additional_info": [
          {
            "name": "ID da cobrança",
            "value": "770e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "transaction": null,
        "status": "PENDING",
        "expires_at": "2024-01-01T23:59:59Z",
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-01T10:00:00Z"
      },
      "expires_at": "2024-01-01T23:59:59Z",
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:00:00Z"
    },
    "external_ref": "PED-001",
    "final_beneficiary": {
      "name": "Maria Santos",
      "document": "98765432100"
    },
    "splits": [
      {
        "uuid": "990e8400-e29b-41d4-a716-446655440002",
        "type": "PERCENTAGE",
        "value": 10,
        "status": "PENDING",
        "recipient_account": {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Empresa Parceira LTDA"
        }
      },
      {
        "uuid": "aa0e8400-e29b-41d4-a716-446655440003",
        "type": "FIXED",
        "value": 5,
        "status": "PENDING",
        "recipient_account": {
          "uuid": "660e8400-e29b-41d4-a716-446655440001",
          "name": "Taxa Plataforma"
        }
      }
    ],
    "history": [
      {
        "status": "PENDING",
        "created_at": "2024-01-01T10:00:00Z"
      }
    ],
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  }
}
​
data
object
Dados da cobrança criado
O campo payment.payload contém o código Copia e Cola do PIX. Você pode usar este código para gerar um QR Code usando bibliotecas como qrcode (Node.js) ou qrcode (Python). O QR Code expira na data indicada em payment.expires_at.

​
Erros Comuns