Como gerar pedido

Este guia mostra como criar pedidos usando nossa API. Você pode facilmente alternar entre diferentes métodos de pagamento (PIX, Cartão ou Boleto) alterando apenas o campo payment_method.

Pré-requisitos

Antes de começar, certifique-se de ter:

✅ Chave de Cash-In configurada
✅ URL base da API: https://api.exemplo.com/v1
✅ Webhook configurado (opcional, mas recomendado)

Passo a Passo

Chamar o Endpoint de Criação de Pedido

Use a Chave de Cash-In para autenticar a requisição e chame o endpoint POST /orders:

curl -X POST https://api.exemplo.com/v1/orders \
  -H "Authorization: Basic SUA_CHAVE_DE_CASH_IN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "payment_method": "pix",
    "customer": {
      "name": "João Silva",
      "email": "joao@exemplo.com",
      "document": "12345678900"
    },
    "description": "Pagamento de serviço"
  }'

Processar a Resposta

A resposta conterá todas as informações necessárias para processar o pagamento:

{
  "id": "ord_123456789",
  "status": "pending",
  "amount": 10000,
  "currency": "BRL",
  "payment_method": "pix",
  "payload": {
    "code": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426655440000520400005303986540510.005802BR5925NOME DO RECEBEDOR6009SAO PAULO62070503***63041D3D"
  },
  "payment_link": "https://pagamento.exemplo.com/pay/ord_123456789",
  "customer": {
    "name": "João Silva",
    "email": "joao@exemplo.com"
  },
  "created_at": "2024-01-15T10:00:00Z",
  "expires_at": "2024-01-15T11:00:00Z"
}

Exibir o PIX ou Link de Pagamento

Você tem duas opções para processar o pagamento:

Opção A: Exibir QR Code PIX

Use o payload.code para gerar um QR Code na tela:

// Exemplo usando qrcode library
import QRCode from 'qrcode';

async function displayPixQRCode(pixCode) {
  try {
    const qrCodeImage = await QRCode.toDataURL(pixCode);
    // Exibir a imagem na tela
    document.getElementById('qrcode').src = qrCodeImage;
  } catch (err) {
    console.error('Erro ao gerar QR Code:', err);
  }
}

// Usar após receber a resposta
displayPixQRCode(response.payload.code);

Opção B: Usar Link de Pagamento

Redirecione o cliente para o payment_link fornecido:

// Redirecionar para o link de pagamento
window.location.href = response.payment_link;

O payment_link funciona para todos os métodos de pagamento (PIX, Cartão e Boleto), oferecendo uma experiência unificada para o cliente.

Alternando entre Métodos de Pagamento

É muito fácil alternar entre PIX, Cartão e Boleto. Basta alterar o campo payment_method na requisição:

PIX

{
  "amount": 10000,
  "payment_method": "pix",
  "customer": {
    "name": "João Silva",
    "email": "joao@exemplo.com"
  }
}

Cartão de Crédito

{
  "amount": 10000,
  "payment_method": "card",
  "customer": {
    "name": "João Silva",
    "email": "joao@exemplo.com"
  },
  "card": {
    "token": "card_token_abc123",
    "installments": 1
  }
}

Para pagamentos com cartão, você precisa primeiro tokenizar o cartão usando o endpoint de tokenização. Veja mais na Referência de API.

Boleto Bancário

{
  "amount": 10000,
  "payment_method": "boleto",
  "customer": {
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "document": "12345678900"
  },
  "boleto": {
    "due_date": "2024-02-15"
  }
}

A resposta para boleto incluirá o código de barras e o link para visualização:

{
  "id": "ord_123456789",
  "status": "pending",
  "payment_method": "boleto",
  "boleto": {
    "barcode": "34191.09008 01234.567890 12345.678901 2 98760000010000",
    "pdf_url": "https://api.exemplo.com/v1/orders/ord_123456789/boleto.pdf"
  },
  "payment_link": "https://pagamento.exemplo.com/pay/ord_123456789"
}

Monitorando o Status do Pedido

Após criar o pedido, você pode monitorar seu status de duas formas:

Consultar o Pedido

Use o endpoint GET /orders/{id} para verificar o status:

curl -X GET https://api.exemplo.com/v1/orders/ord_123456789 \
  -H "Authorization: Basic SUA_CHAVE_DE_CASH_IN"

Receber Notificação via Webhook

Configure um webhook na plataforma para receber notificações automáticas quando o status do pedido mudar:

{
  "event": "order.paid",
  "order_id": "ord_123456789",
  "status": "paid",
  "amount": 10000,
  "paid_at": "2024-01-15T10:30:00Z"
}

Sempre valide os webhooks recebidos verificando o header Authorization ou X-Signature para garantir a segurança.

Exemplos Completos

JavaScript/TypeScript

async function createOrder(amount: number, paymentMethod: string) {
  const response = await fetch('https://api.exemplo.com/v1/orders', {
    method: 'POST',
    headers: {
      Authorization: `Basic ${process.env.CASH_IN_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount,
      payment_method: paymentMethod,
      customer: {
        name: 'João Silva',
        email: 'joao@exemplo.com',
      },
    }),
  });

  const order = await response.json();

  if (paymentMethod === 'pix') {
    // Exibir QR Code
    displayQRCode(order.payload.code);
  } else {
    // Redirecionar para link de pagamento
    window.location.href = order.payment_link;
  }

  return order;
}

Python

import requests

def create_order(amount, payment_method):
    url = "https://api.exemplo.com/v1/orders"
    headers = {
        "Authorization": f"Basic {CASH_IN_KEY}",
        "Content-Type": "application/json"
    }
    data = {
        "amount": amount,
        "payment_method": payment_method,
        "customer": {
            "name": "João Silva",
            "email": "joao@exemplo.com"
        }
    }

    response = requests.post(url, headers=headers, json=data)
    order = response.json()

    return order

Próximos Passos

Aprenda a consultar e listar pedidos
Configure webhooks para receber notificações automáticas
Veja como fazer saques após receber os pagamentos

Como gerar pedido

On this page