> ## Documentation Index
> Fetch the complete documentation index at: https://docs.econpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /payments/order

> Criar um novo pagamento (PIX ou Boleto)

## Descrição

Endpoint unificado para processar pagamentos. Suporta os seguintes métodos de pagamento:

* **PIX** - Pagamento instantâneo com QR Code
* **Boleto** - Boleto bancário registrado

<Warning>
  **Valor Mínimo:** R\$ 5,00 (500 centavos). Valores menores serão rejeitados.
</Warning>

<Note>
  **Valores em Centavos:** Todos os valores monetários devem ser enviados em centavos. R\$ 100,00 = 10000 centavos.
</Note>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token JWT obtido no login
</ParamField>

## Request Body

<ParamField body="access_token" type="string" required>
  Token de acesso do estabelecimento (obtido no dashboard)
</ParamField>

<ParamField body="payment_link_id" type="string">
  ID do link de pagamento (opcional)
</ParamField>

<ParamField body="customer" type="object" required>
  Dados do cliente

  <Expandable title="properties">
    <ParamField body="customer.name" type="string" required>
      Nome completo do cliente
    </ParamField>

    <ParamField body="customer.email" type="string" required>
      Email do cliente
    </ParamField>

    <ParamField body="customer.document" type="string" required>
      CPF ou CNPJ (apenas números)
    </ParamField>

    <ParamField body="customer.ip" type="string">
      Endereço IP do cliente (recomendado para antifraude)
    </ParamField>

    <ParamField body="customer.phone" type="object" required>
      <Expandable title="properties">
        <ParamField body="customer.phone.country_code" type="string" required>
          Código do país (ex: "55" para Brasil)
        </ParamField>

        <ParamField body="customer.phone.area_code" type="string" required>
          DDD (ex: "11")
        </ParamField>

        <ParamField body="customer.phone.number" type="string" required>
          Número do telefone (ex: "999999999")
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="customer.address" type="object">
      <Expandable title="properties">
        <ParamField body="customer.address.line_1" type="string">
          Endereço (rua, número)
        </ParamField>

        <ParamField body="customer.address.line_2" type="string">
          Complemento
        </ParamField>

        <ParamField body="customer.address.zip_code" type="string">
          CEP (apenas números)
        </ParamField>

        <ParamField body="customer.address.city" type="string">
          Cidade
        </ParamField>

        <ParamField body="customer.address.state" type="string">
          Estado (UF)
        </ParamField>

        <ParamField body="customer.address.country" type="string">
          País (código ISO, ex: "BR")
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="items" type="array" required>
  Lista de itens do pedido

  <Expandable title="properties">
    <ParamField body="items[].name" type="string" required>
      Nome do produto/serviço
    </ParamField>

    <ParamField body="items[].quantity" type="number" required>
      Quantidade
    </ParamField>

    <ParamField body="items[].price" type="number" required>
      Preço unitário em centavos
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="payment" type="object" required>
  Dados do pagamento

  <Expandable title="properties">
    <ParamField body="payment.type" type="string" required>
      Tipo de pagamento: `pix` ou `invoice`
    </ParamField>

    <ParamField body="payment.installments" type="number" required>
      Número de parcelas (sempre 1 para PIX e Boleto)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="shipping" type="object" required>
  Dados de envio

  <Expandable title="properties">
    <ParamField body="shipping.name" type="string" required>
      Nome do método de envio (ex: "Sedex", "Digital")
    </ParamField>

    <ParamField body="shipping.price" type="number" required>
      Valor do frete em centavos (0 para digital)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="subtotal" type="number" required>
  Subtotal em centavos (soma dos itens)
</ParamField>

<ParamField body="total" type="number" required>
  Total em centavos (subtotal + frete)
</ParamField>

<ParamField body="splitParticipants" type="array">
  Participantes do split (opcional, para divisão de valores)

  <Expandable title="properties">
    <ParamField body="splitParticipants[].accessToken" type="string" required>
      Access token do participante
    </ParamField>

    <ParamField body="splitParticipants[].merchantType" type="string" required>
      Tipo: `PRIMARY` ou `SECONDARY`
    </ParamField>

    <ParamField body="splitParticipants[].type" type="string" required>
      Tipo de divisão: `PERCENTAGE` ou `FIXED`
    </ParamField>

    <ParamField body="splitParticipants[].chargeFee" type="boolean" required>
      Se este participante paga as taxas
    </ParamField>

    <ParamField body="splitParticipants[].discountGrossAmount" type="boolean" required>
      Se desconta do valor bruto
    </ParamField>

    <ParamField body="splitParticipants[].amountSplit" type="number" required>
      Valor em centavos (FIXED) ou porcentagem em centavos (PERCENTAGE)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indica se a operação foi bem-sucedida
</ResponseField>

<ResponseField name="transaction" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="number">
      ID da transação
    </ResponseField>

    <ResponseField name="order_number" type="string">
      Número do pedido (único)
    </ResponseField>

    <ResponseField name="status" type="string">
      Status da transação: `PENDING`, `APPROVED`, `FAILED`
    </ResponseField>

    <ResponseField name="amount" type="number">
      Valor em centavos
    </ResponseField>

    <ResponseField name="payment_type" type="string">
      Tipo de pagamento usado
    </ResponseField>

    <ResponseField name="pix_qr_code" type="string">
      String do QR Code PIX (apenas para PIX)
    </ResponseField>

    <ResponseField name="pix_qr_code_url" type="string">
      URL da imagem do QR Code (apenas para PIX)
    </ResponseField>

    <ResponseField name="boleto_url" type="string">
      URL do boleto (apenas para boleto)
    </ResponseField>

    <ResponseField name="boleto_barcode" type="string">
      Código de barras do boleto (apenas para boleto)
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Data de criação (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash PIX theme={null}
  curl --request POST \
    --url https://api.econpay.com.br/payments/order \
    --header 'Authorization: Bearer SEU_TOKEN_JWT' \
    --header 'Content-Type: application/json' \
    --data '{
      "access_token": "SEU_ACCESS_TOKEN",
      "customer": {
        "name": "João da Silva",
        "email": "joao@exemplo.com",
        "document": "12345678900",
        "phone": {
          "country_code": "55",
          "area_code": "11",
          "number": "999999999"
        }
      },
      "items": [{
        "name": "Produto Teste",
        "quantity": 1,
        "price": 10000
      }],
      "payment": {
        "type": "pix",
        "installments": 1
      },
      "shipping": {
        "name": "Digital",
        "price": 0
      },
      "subtotal": 10000,
      "total": 10000
    }'
  ```

  ```bash Boleto theme={null}
  curl --request POST \
    --url https://api.econpay.com.br/payments/order \
    --header 'Authorization: Bearer SEU_TOKEN_JWT' \
    --header 'Content-Type: application/json' \
    --data '{
      "access_token": "SEU_ACCESS_TOKEN",
      "customer": {
        "name": "Maria Santos",
        "email": "maria@exemplo.com",
        "document": "98765432100",
        "phone": {
          "country_code": "55",
          "area_code": "11",
          "number": "988888888"
        }
      },
      "items": [{
        "name": "Produto Premium",
        "quantity": 1,
        "price": 30000
      }],
      "payment": {
        "type": "invoice",
        "installments": 1
      },
      "shipping": {
        "name": "Sedex",
        "price": 1500
      },
      "subtotal": 30000,
      "total": 31500
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.econpay.com.br/payments/order', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      access_token: 'SEU_ACCESS_TOKEN',
      customer: {
        name: 'João da Silva',
        email: 'joao@exemplo.com',
        document: '12345678900',
        phone: {
          country_code: '55',
          area_code: '11',
          number: '999999999'
        }
      },
      items: [{
        name: 'Produto Teste',
        quantity: 1,
        price: 10000 // R$ 100,00
      }],
      payment: {
        type: 'pix',
        installments: 1
      },
      shipping: {
        name: 'Digital',
        price: 0
      },
      subtotal: 10000,
      total: 10000
    })
  });

  const payment = await response.json();

  if (payment.success) {
    console.log('Pagamento criado:', payment.transaction.order_number);
    
    if (payment.transaction.payment_type === 'pix') {
      console.log('QR Code:', payment.transaction.pix_qr_code);
      // Exibir QR Code para o cliente
    }
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.econpay.com.br/payments/order',
      headers={
          'Authorization': f'Bearer {token}',
          'Content-Type': 'application/json'
      },
      json={
          'access_token': 'SEU_ACCESS_TOKEN',
          'customer': {
              'name': 'João da Silva',
              'email': 'joao@exemplo.com',
              'document': '12345678900',
              'phone': {
                  'country_code': '55',
                  'area_code': '11',
                  'number': '999999999'
              }
          },
          'items': [{
              'name': 'Produto Teste',
              'quantity': 1,
              'price': 10000  # R$ 100,00
          }],
          'payment': {
              'type': 'pix',
              'installments': 1
          },
          'shipping': {
              'name': 'Digital',
              'price': 0
          },
          'subtotal': 10000,
          'total': 10000
      }
  )

  payment = response.json()

  if payment['success']:
      print(f"Pagamento criado: {payment['transaction']['order_number']}")
      
      if payment['transaction']['payment_type'] == 'pix':
          print(f"QR Code: {payment['transaction']['pix_qr_code']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - PIX Success theme={null}
  {
    "success": true,
    "transaction": {
      "id": 123,
      "order_number": "ORD-20240122-123456",
      "status": "PENDING",
      "amount": 10000,
      "payment_type": "pix",
      "pix_qr_code": "00020126580014br.gov.bcb.pix...",
      "pix_qr_code_url": "https://api.econpay.com.br/qrcode/123.png",
      "created_at": "2024-01-22T10:30:00Z"
    }
  }
  ```

  ```json 200 - Boleto Success theme={null}
  {
    "success": true,
    "transaction": {
      "id": 124,
      "order_number": "ORD-20240122-123457",
      "status": "PENDING",
      "amount": 31500,
      "payment_type": "invoice",
      "boleto_url": "https://api.econpay.com.br/boleto/124.pdf",
      "boleto_barcode": "34191.79001 01043.510047 91020.150008 1 82880000030000",
      "created_at": "2024-01-22T10:35:00Z"
    }
  }
  ```

  ```json 400 - Valor Mínimo theme={null}
  {
    "success": false,
    "message": "Valor mínimo não atingido",
    "error": "O valor mínimo para transações é R$ 5,00. Valor enviado: R$ 2,00"
  }
  ```

  ```json 400 - Dados Inválidos theme={null}
  {
    "success": false,
    "message": "Dados de pagamento inválidos",
    "error": "Campo 'customer.email' é obrigatório"
  }
  ```

  ```json 403 - Access Token Inválido theme={null}
  {
    "success": false,
    "message": "Access token inválido",
    "error": "Token não encontrado ou inativo"
  }
  ```
</ResponseExample>

## Métodos de Pagamento

<Tabs>
  <Tab title="PIX">
    ### Pagamento PIX

    * Aprovação instantânea (geralmente em segundos)
    * QR Code válido por 30 minutos
    * Disponível 24/7
    * Sem taxas para o cliente final

    **Resposta inclui:**

    * `pix_qr_code`: String EMV do QR Code
    * `pix_qr_code_url`: URL da imagem do QR Code

    **Status:**

    * `PENDING`: Aguardando pagamento
    * `APPROVED`: Pago (webhook enviado)
  </Tab>

  <Tab title="Boleto">
    ### Boleto Bancário

    * Vencimento configurável
    * Registro automático
    * Código de barras e linha digitável

    **Resposta inclui:**

    * `boleto_url`: URL do PDF do boleto
    * `boleto_barcode`: Código de barras
    * `boleto_digitable_line`: Linha digitável

    **Status:**

    * `PENDING`: Aguardando pagamento
    * `APPROVED`: Pago (webhook enviado)
  </Tab>
</Tabs>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Reembolso" icon="rotate-left" href="/api-reference/payments/refund">
    Processar estornos
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Receber notificações
  </Card>

  <Card title="Listar Transações" icon="list" href="/api-reference/transactions/list">
    Consultar pagamentos
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/guides/errors">
    Códigos de erro
  </Card>
</CardGroup>