Owynd API v1.0

Cria uma cobrança PIX. Retorna o QR Code para o cliente pagar.

Headers

Body (JSON)

Exemplo

curl -X POST https://api.owynd.com/api/v1/api-gateway/v1/transactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_sua_chave_secreta" \
  -d '{
  "paymentMethod": "pix",
  "amount": 10000,
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "phone": "11999999999",
    "document": { "type": "cpf", "number": "12345678900" }
  },
  "items": [
    { "title": "Assinatura Premium", "unitPrice": 10000, "quantity": 1 }
  ],
  "postbackUrl": "https://meusite.com/webhook/owynd",
  "externalId": "pedido-123",
  "tracking": {
    "utm_source": "facebook",
    "utm_campaign": "campanha-verao",
    "utm_medium": "cpc",
    "utm_content": "criativo-a"
  }
}'

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid-da-transacao",
    "status": "pending",
    "amount": 10000,
    "paymentMethod": "pix",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com"
    },
    "pixQrCode": "00020126580014br.gov.bcb.pix...",
    "pixQrCodeImage": "https://api.owynd.com/qrcode/xxx.png",
    "expiresAt": "2026-01-15T11:00:00.000Z",
    "createdAt": "2026-01-15T10:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1"
  }
}

Consulta status e dados de uma transação. Aceita Secret Key ou Public Key.

curl https://api.owynd.com/api/v1/api-gateway/v1/transactions/uuid \
  -H "x-api-key: sk_live_sua_chave_secreta"

Resposta

{
  "success": true,
  "data": {
    "id": "uuid-da-transacao",
    "externalId": "pedido-123",
    "status": "paid",
    "amount": 10000,
    "paymentMethod": "pix",
    "customerName": "João Silva",
    "customerEmail": "joao@email.com",
    "expiresAt": "2026-01-15T11:00:00.000Z",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

Lista suas transações com paginação. Aceita Secret Key ou Public Key.

Solicita um saque. O valor de amount (bruto, com a taxa dentro) é debitado imediatamente do saldo disponível. O saque fica como PENDING até aprovação manual pelo admin (ou é processado na hora, com a auto-aprovação descrita acima).

Headers

Body (JSON)

Validação de pixKey por tipo

Exemplo 1 — Saque para conta bancária cadastrada

curl -X POST https://api.owynd.com/api/v1/api-gateway/v1/withdrawals \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_sua_chave_secreta" \
  -d '{ "amount": 5000 }'

Exemplo 2 — Saque para chave PIX externa

curl -X POST https://api.owynd.com/api/v1/api-gateway/v1/withdrawals \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_sua_chave_secreta" \
  -d '{
    "amount": 5000,
    "pixKey": "joao@email.com",
    "pixKeyType": "EMAIL",
    "holderName": "João da Silva",
    "holderDocument": "12345678909"
  }'

Resposta (200) — Modo padrão (conta bancária)

{
  "success": true,
  "data": {
    "id": "uuid-do-saque",
    "amount": 50.00,
    "fee": 2.00,
    "netAmount": 48.00,
    "status": "PENDING",
    "destination": "BANK_ACCOUNT",
    "pixKey": null,
    "pixKeyType": null,
    "holderName": null,
    "holderDocument": null,
    "createdAt": "2026-05-04T12:00:00.000Z",
    "updatedAt": "2026-05-04T12:00:00.000Z",
    "paidAt": null,
    "rejectionReason": null,
    "autoApproved": false
  }
}
/* amount      = total debitado do saldo (bruto solicitado)
   fee         = taxa de saque cobrada (sai de dentro de amount)
   netAmount   = valor líquido que será creditado no PIX (amount − fee)
   autoApproved = true quando a auto-aprovação processou o saque na hora (status vem "PAID"/"PROCESSING") */

Resposta (200) — Modo PIX externo

{
  "success": true,
  "data": {
    "id": "uuid-do-saque",
    "amount": 50.00,
    "fee": 2.00,
    "netAmount": 48.00,
    "status": "PENDING",
    "destination": "EXTERNAL_PIX",
    "pixKey": "joao@email.com",
    "pixKeyType": "EMAIL",
    "holderName": "João da Silva",
    "holderDocument": "12345678909",
    "createdAt": "2026-05-04T12:00:00.000Z",
    "updatedAt": "2026-05-04T12:00:00.000Z",
    "paidAt": null,
    "rejectionReason": null,
    "autoApproved": false
  }
}

Erros comuns

Lista todos os saques da conta com paginação. Aceita Secret Key ou Public Key.

curl "https://api.owynd.com/api/v1/api-gateway/v1/withdrawals?page=1&limit=20" \
  -H "x-api-key: sk_live_sua_chave_secreta"

Resposta (200)

{
  "success": true,
  "data": [
    {
      "id": "uuid-do-saque",
      "amount": 52.00,
      "fee": 2.00,
      "netAmount": 50.00,
      "status": "PENDING",
      "createdAt": "2026-04-13T12:00:00.000Z",
      "paidAt": null,
      "rejectionReason": null
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 20
  }
}

Consulta detalhes de um saque específico. Aceita Secret Key ou Public Key.

curl "https://api.owynd.com/api/v1/api-gateway/v1/withdrawals/uuid-do-saque" \
  -H "x-api-key: sk_live_sua_chave_secreta"

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid-do-saque",
    "amount": 52.00,
    "fee": 2.00,
    "netAmount": 50.00,
    "status": "PAID",
    "createdAt": "2026-04-13T12:00:00.000Z",
    "updatedAt": "2026-04-13T14:30:00.000Z",
    "paidAt": "2026-04-13T14:30:00.000Z",
    "rejectionReason": null
  }
}

Exemplo com Split Inline

curl -X POST https://api.owynd.com/api/v1/api-gateway/v1/transactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_sua_chave_secreta" \
  -d '{
  "paymentMethod": "pix",
  "amount": 10000,
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "split": [
    { "email": "parceiro@email.com", "percentage": "10" },
    { "email": "afiliado@email.com", "percentage": "5" }
  ],
  "postbackUrl": "https://meusite.com/webhook",
  "externalId": "pedido-456"
}'

Campos do Split

Exemplo de divisão:

Venda: R$ 100,00
Taxa plataforma (6%): - R$ 6,00
Valor líquido: R$ 94,00

Split parceiro (10%): R$ 9,40 → creditado para parceiro@email.com
Split afiliado (5%):  R$ 4,70 → creditado para afiliado@email.com
Você recebe (85%):    R$ 79,90

Cria um link de checkout para o cliente assinar. Envie o checkoutUrl ao cliente.

Body (JSON)

Exemplo

curl -X POST https://api.owynd.com/api/v1/api-gateway/v1/subscriptions \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_sua_chave_secreta" \
  -d '{
    "amount": 4990,
    "period": "monthly",
    "name": "Clube VIP",
    "paymentMethod": "pix_automatico",
    "externalId": "cliente-123",
    "postbackUrl": "https://seu-site.com/webhooks/owynd",
    "returnUrl": "https://seu-site.com/obrigado",
    "customer": { "name": "João da Silva", "email": "joao@email.com" }
  }'

Resposta (200)

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "open",
    "checkoutUrl": "https://checkout.owynd.com/pay/ass-3f9a1c2b7d4e?assinatura=7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Clube VIP",
    "amount": 4990,
    "period": "monthly",
    "paymentMethod": "pix_automatico",
    "externalId": "cliente-123",
    "expiresAt": "2026-09-30T18:00:00.000Z",
    "createdAt": "2026-09-27T18:00:00.000Z",
    "subscription": null
  }
}

Erros

Modo direto (Pix Automático): com mode: "direct" a assinatura nasce na hora e a resposta traz o QR Code, sem link de checkout. Você mostra o QR ao seu cliente no seu app, site ou bot.

Campos do modo direto

Exemplo

curl -X POST https://api.owynd.com/api/v1/api-gateway/v1/subscriptions \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_sua_chave_secreta" \
  -d '{
    "mode": "direct",
    "paymentMethod": "pix_automatico",
    "amount": 4990,
    "period": "monthly",
    "name": "Clube VIP",
    "externalId": "pedido-123",
    "customer": {
      "name": "João da Silva",
      "document": "12345678909",
      "email": "joao@email.com",
      "address": {
        "zipCode": "01310100", "street": "Avenida Paulista", "number": "1000",
        "district": "Bela Vista", "city": "São Paulo", "state": "SP"
      }
    }
  }'

Resposta: campos a mais

O que você precisa fazer

• Aviso ao cliente (obrigatório): exiba, junto do QR, algo como "Ao pagar, você autoriza a cobrança automática de R$ X/<período>; pode cancelar no app do seu banco."
• Exiba só o QR mais recente. Um QR antigo pode continuar pagável depois que você gerou outro. Se ele for pago, o dinheiro entra e você recebe subscription.paid, com o status da assinatura no corpo, que pode vir canceled. Concilie pelo seu externalId.
• externalId: repetir a chamada com os mesmos dados devolve o mesmo QR enquanto ele vale. Se o QR venceu sem pagamento ou a tentativa falhou, o mesmo externalId gera uma tentativa nova. Com outro valor, período ou documento, responde 409. Duas chamadas ao mesmo tempo resultam numa só assinatura, e a segunda responde 409 "em processamento".
• Acompanhe o resultado pelo webhook ou consultando a assinatura, respeitando o limite de 10 consultas por segundo.

Erros do modo direto

Consulta uma assinatura. Aceita o id do link, recebido na criação, ou o id da assinatura, recebido no webhook.

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "active",
    "amount": 4990,
    "period": "monthly",
    "externalId": "cliente-123",
    "subscription": {
      "id": "b1f0c2d3-0000-4000-8000-000000000001",
      "status": "active",
      "amount": 4990,
      "period": "monthly",
      "paidCycles": 3,
      "currentPeriodEnd": "2026-10-27T23:59:59.000Z",
      "paymentMethod": "pix_automatico",
      "card": null,
      "customer": { "name": "João da Silva", "email": "joao@email.com" }
    }
  }
}

Lista os links criados pela API, do mais recente para o mais antigo. Parâmetros: page (padrão 1), limit (padrão 20, máximo 100) e externalId.

Assinatura ativa: para as próximas cobranças, sem estornar o que já foi pago, e dispara subscription.canceled. Link ainda aberto: invalida o link. Se a operadora recusar o cancelamento, a resposta é erro e a assinatura continua ativa; tente de novo.

No Pix Automático, um QR já emitido pode continuar pagável por um curto período, então esconda-o do seu cliente. Se ele for pago, o dinheiro entra e você recebe subscription.paid com o status canceled no corpo.

Lista as infrações da sua conta, da contestação mais recente para a mais antiga. Só Secret Key.

Um parâmetro inválido responde 400 com a explicação (ele nunca é ignorado em silêncio).

curl "https://api.owynd.com/api/v1/api-gateway/v1/infracoes?status=em_analise&desde=2026-11-01" \
  -H "x-api-key: sk_live_sua_chave_secreta"

Resposta (200)

{
  "success": true,
  "data": [
    {
      "id": "b3f1c2a4-7d1e-4c55-9a3b-1f2e3d4c5b6a",
      "status": "em_analise",
      "statusTexto": "Em análise",
      "valor": 49.90,
      "valorBloqueado": 49.90,
      "motivo": "Contestação do pagador (MED)",
      "detalheMotivo": null,
      "e2eId": "E1234567820261108123456789012345",
      "venda": {
        "id": "uuid-da-transacao",
        "origem": "api",
        "criadaEm": "2026-11-05T14:02:11.000Z",
        "pagaEm": "2026-11-05T14:03:40.000Z"
      },
      "pagador": { "nome": "João Silva", "email": "joao@email.com", "documento": "123.456.789-00" },
      "contestadaEm": "2026-11-07T09:15:00.000Z",
      "defesa": { "texto": "Produto entregue conforme combinado.", "enviadaEm": "2026-11-07T09:16:02.000Z" },
      "decisao": null,
      "taxaDefesa": null,
      "criadaEm": "2026-11-07T09:15:30.000Z",
      "atualizadaEm": "2026-11-07T09:16:02.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Uma infração da sua conta. Só Secret Key. Id que não existe (ou de outra conta) responde 404.

curl "https://api.owynd.com/api/v1/api-gateway/v1/infracoes/b3f1c2a4-7d1e-4c55-9a3b-1f2e3d4c5b6a" \
  -H "x-api-key: sk_live_sua_chave_secreta"

Resposta (200) — infração defendida

{
  "success": true,
  "data": {
    "id": "b3f1c2a4-7d1e-4c55-9a3b-1f2e3d4c5b6a",
    "status": "defendida",
    "statusTexto": "Defendida",
    "valor": 49.90,
    "valorBloqueado": 0,
    "motivo": "Contestação do pagador (MED)",
    "detalheMotivo": null,
    "e2eId": "E1234567820261108123456789012345",
    "venda": { "id": "uuid-da-transacao", "origem": "api", "criadaEm": "2026-11-05T14:02:11.000Z", "pagaEm": "2026-11-05T14:03:40.000Z" },
    "pagador": { "nome": "João Silva", "email": "joao@email.com", "documento": "123.456.789-00" },
    "contestadaEm": "2026-11-07T09:15:00.000Z",
    "defesa": { "texto": "Produto entregue conforme combinado.", "enviadaEm": "2026-11-07T09:16:02.000Z" },
    "decisao": { "observacao": null, "decididaEm": "2026-11-09T18:00:00.000Z" },
    "taxaDefesa": { "valor": 2.00, "pagaEm": "2026-11-09T18:00:00.000Z" },
    "criadaEm": "2026-11-07T09:15:30.000Z",
    "atualizadaEm": "2026-11-09T18:00:00.000Z"
  }
}