API

Para utilizar a API da Bitpayway, você precisará da API KEY gerada no painel de controle do seu negócio. Você deverá passar na requisição HTTP o token da seguinte forma:

Header

• Authorization: "ApiKey <SECRET_KEY>"

Routes

POST/api/orderCria ordem de pagamento

Query parameters

POST /api/order?isTestnet=true

isTestnet (boolean): Trava de segurança para ambientes que não podem criar ordens na mainnet. Defina como true para garantir que a operação seja realizada somente em uma testnet; se a rede selecionada for uma mainnet, a operação será bloqueada. Isso é especialmente útil em ambientes de staging.

Request body

{
    "description": "Compra #1",
    "requestId": "2f3c9d2c-1b75-4e9d-9b2f-67d0a9c3c7d1",
    "amount": "10.50",
    "network": "ethereum",
    "token": "USDT"
}

description: É a descrição da ordem de pagamento criada

requestId: É um id unico gerado pela sua aplicação para você poder identificar facilmente a ordem gerada

amount: É o valor da ordem de pagamento. Este campo é uma string do valor.

network: É a rede da moeda (token) da ordem de pagamento.

token: É a moeda que você deseja que a ordem de pagamento seja pago. É o simbolo do token, não o nome.

paymentModel (opcional): standard ou split, em que split cria uma ordem multidestino. Omita o campo para manter o comportamento e o formato de resposta tradicionais.

split (obrigatório quando paymentModel é split): a divisão destinada a um parceiro, no formato { "partnerId": "<UUID do vínculo>", "partnerAmount": "<parcela bruta>" }. O partnerAmount é uma string decimal na unidade de exibição do token, entre zero e amount, limitado aos decimais do token. Veja Pagamentos multidestino.

Responses

• 201

  Ordem criada (ou existente retornada por duplicidades).

  • gatewayUrl: É a URL da página de pagamento da Bitpayway para a qual o pagador deverá ser redirecionado.

  • paymentModel e split: retornados somente nas ordens multidestino, com o parceiro e a divisão bruta fixados na ordem.

  {
    "order": {
      "id": "7f7f5a2a-5c4f-4c6b-9cbb-1f0f4b4e42f2",
      "date": "2026-02-12T18:12:43.384Z",
      "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "clientId": "12345",
      "orderId": "42",
      "description": "string",
      "amount": "10.50",
      "status": "pending",
      "gatewayUrl": "https://example.com/"
    }
  }

• 400Falha ao criar ordem

  {
    "message": "Failed to create orders",
    "details": "requestId must be a valid uuid"
  }

• 401Falha ao criar ordem

  {
    "message": "Failed to create order",
    "details": "Unauthorized"
  }

GET/api/orderListar ordens

Query parameters

Todos os filtros são opcionais e podem ser combinados. Quando mais de um filtro é informado, são retornadas apenas as ordens que correspondem a todos eles.

GET /api/order?dateStart=2026-01-10&dateEnd=2026-01-15&status=paid&amount=200

Parâmetro	Tipo	Descrição
date	date ou date-time	Filtra pela data de criação da ordem. YYYY-MM-DD considera o dia inteiro; uma data e hora ISO 8601 busca o instante exato.
dateStart	date ou date-time	Limite inicial inclusivo da data de criação da ordem.
dateEnd	date ou date-time	Limite final inclusivo da data de criação da ordem. YYYY-MM-DD considera o dia inteiro. Deve ser maior ou igual a dateStart.
requestId	UUID v4	Filtra pelo identificador da requisição informado na criação da ordem.
status	string	Filtra pelo status. Valores aceitos: pending, partial paid, expired partial paid, paid waiting confirmations, paid, expired e canceled.
amount	string numérica	Filtra pelo valor exato da ordem, por exemplo 200 ou 200.50.

Responses

• 200

  Lista de ordens. Cada ordem inclui os campos de valores abaixo como strings decimais no token da ordem:

  • paidAmount: Valor total pago na blockchain antes das taxas.
  • netAmount: Valor enviado para a carteira do cliente após as taxas de pagamento.
  • fee: Spread da plataforma.

  Uma ordem multidestino traz também paymentModel, split, settlementStatus, settlementVersion e os valores de cada parcela (partnerNetAmount, partnerGrossAmount, clientCommission, partnerCommission, commissionReceived). Em uma ordem multidestino, o netAmount é o valor que você recebeu e o paidAmount é o valor bruto confirmado da ordem. Veja Pagamentos multidestino.

  {
    "data": [
      {
        "id": "7f7f5a2a-5c4f-4c6b-9cbb-1f0f4b4e42f2",
        "date": "2026-02-12T18:12:43.384Z",
        "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "clientId": "12345",
        "orderId": "42",
        "description": "string",
        "amount": "10.50",
        "status": "pending",
        "gatewayUrl": "https://example.com/",
        "paidAmount": "0",
        "netAmount": "0",
        "fee": "0"
      }
    ]
  }

• 400Falha ao listar ordem

  {
    "message": "Failed to list orders",
    "details": "requestId must be a valid uuid"
  }

• 401Falha ao listar ordem

  {
    "message": "Failed to list order",
    "details": "Unauthorized"
  }

GET/api/order/request/{requestId}Buscar ordem de pagamento pelo ID da requisição

Path parameters

GET /api/order/request/3fa85f64-5717-4562-b3fc-2c963f66afa6

Parâmetro	Tipo	Obrigatório	Descrição
requestId	UUID	Sim	Identificador da requisição informado na criação da ordem de pagamento.

Responses

• 200

  Ordem de pagamento encontrada pelo ID da requisição. A resposta inclui os campos de valores abaixo como strings decimais no token da ordem:

  • paidAmount: Valor total pago na blockchain antes das taxas.
  • netAmount: Valor enviado para a carteira do cliente após as taxas de pagamento.
  • fee: Spread da plataforma.

  {
    "order": {
      "id": "7f7f5a2a-5c4f-4c6b-9cbb-1f0f4b4e42f2",
      "date": "2026-02-12T18:12:43.384Z",
      "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "clientId": "12345",
      "orderId": "42",
      "description": "Pedido #1234",
      "amount": "1000.52",
      "status": "paid",
      "gatewayUrl": "https://example.com/",
      "paidAmount": "1000.52",
      "netAmount": "950.494",
      "fee": "50.026"
    }
  }

• 400ID da requisição inválido.
• 401API Key inválida.
• 404Ordem de pagamento não encontrada.
• 503Não foi possível conciliar o status da ordem de pagamento com a blockchain.

GET/api/currency-tokenLista moedas (tokens) disponíveis

Responses

• 200Lista de tokens. Ele mostra todas os tokens de cada rede disponíveis na plataforma.

  {
    "data": [
      {
        "contractId": "28a555aa-d6bb-4a0b-9266-0b6668f824b5",
        "name": "Tether USD",
        "symbol": "USDT",
        "network": "Ethereum",
        "chainId": "1",
        "isTestnet": false,
        "splitEnabled": true
      }
    ]
  }

• 400Falha ao listar tokens

  {
    "message": "Failed to list orders",
    "details": "requestId must be a valid uuid"
  }

• 401Falha ao listar tokens

  {
    "message": "Failed to list orders",
    "details": "requestId must be a valid uuid"
  }

Configuração de pagamentos multidestino

Para consultar o ciclo completo — responsabilidades das carteiras, configuração no painel, ordens, liquidação e conciliação — use o guia único de Pagamentos multidestino. Os componentes abaixo são a referência da API para integrações de servidor. A carteira do cliente também pode ser gerenciada pelo painel; vínculos e carteiras de parceiros estão disponíveis somente pela API.

GET/api/split/partnersLista os vínculos de parceiros do negócio associado à chave de API.

Query parameters

Os dois filtros são opcionais e usam correspondência exata. Quando ambos são informados, somente o parceiro que corresponde aos dois valores é retornado. Os resultados sempre permanecem restritos ao negócio associado à chave de API.

Nome	Tipo	Obrigatório	Descrição
id	UUID	Não	ID público do vínculo retornado por POST /api/split/partners.
external_id	string	Não	ID do parceiro definido pelo cliente, de 1 a 255 caracteres.

Responses

• 200Vínculos de parceiros.

  {
    "data": [
      {
        "id": "9f1c2d64-5717-4562-b3fc-2c963f66afa6",
        "name": "Parceiro do marketplace",
        "external_id": "vendedor-marketplace-42"
      }
    ]
  }

• 400O filtro id ou external_id é inválido.
• 401Chave de API ausente ou inválida.

POST/api/split/partnersCria um vínculo de parceiro para pagamentos multidestino.

Request body

{
  "name": "Parceiro do marketplace",
  "external_id": "vendedor-marketplace-42"
}

Cria um vínculo de parceiro pertencente ao negócio associado à chave de API. Use o id retornado como split.partnerId ao criar ordens e como parâmetro partnerId ao configurar a carteira desse parceiro.

external_id é uma string opcional definida pelo cliente, de 1 a 255 caracteres. Quando informado, deve ser único entre os parceiros deste negócio. Outro negócio pode usar o mesmo valor. Uma duplicidade no mesmo negócio retorna 409. Quando omitido, a resposta contém "external_id": null.

Responses

• 201Vínculo de parceiro criado.

  {
    "partner": {
      "id": "9f1c2d64-5717-4562-b3fc-2c963f66afa6",
      "name": "Parceiro do marketplace",
      "external_id": "vendedor-marketplace-42"
    }
  }

• 400Nome ou external_id do parceiro inválido.
• 401Chave de API ausente ou inválida.
• 409O external_id já está em uso por este negócio.

PATCH/api/split/walletSalva a carteira multidestino desejada para o negócio.

Request body

{
  "tokenContractId": "28a555aa-d6bb-4a0b-9266-0b6668f824b5",
  "wallet": "0x1111111111111111111111111111111111111111",
  "active": true
}

Use um contractId retornado por GET /api/currency-token com splitEnabled: true. O campo active assume true; somente vínculos de parceiros podem ser desativados. Salvar não altera a blockchain até que a autorização retornada seja enviada on-chain.

Responses

• 200Configuração salva com a autorização assinada para o registro.

  {
    "walletRegisterAddress": "0x2222222222222222222222222222222222222222",
    "abi": [],
    "network": { "name": "Ethereum", "chainId": "1", "isTestnet": false },
    "functionName": "setSplitWalletWithAuth",
    "args": [
      "12345",
      "7",
      "0x3333333333333333333333333333333333333333",
      "0x1111111111111111111111111111111111111111",
      true,
      "0",
      "1789834200",
      27,
      "0x...",
      "0x..."
    ],
    "expiresAt": "2026-09-20T12:10:00.000Z",
    "signatureParams": {
      "clientId": "12345",
      "splitId": "7",
      "token": "0x3333333333333333333333333333333333333333",
      "wallet": "0x1111111111111111111111111111111111111111",
      "active": true,
      "nonce": "0",
      "deadline": "1789834200",
      "v": 27,
      "r": "0x...",
      "s": "0x..."
    }
  }

  functionName é o método do contrato de registro (presente na abi) a ser chamado no walletRegisterAddress, na rede indicada em network.chainId, passando os args. O valor é setSplitWalletWithAuth para a carteira de um parceiro e setClientWalletWithAuth para a carteira do próprio negócio; splitId aparece em signatureParams apenas no caso do parceiro.

• 400Corpo ou parâmetros inválidos.
• 401Chave de API ausente ou inválida.
• 404Parceiro ou contrato do token não encontrado para este cliente.
• 422Pagamentos multidestino indisponíveis ou configuração inválida.

POST/api/split/wallet/authorizationRetorna uma autorização EIP-712 de curta duração para a configuração salva.

Request body

{
  "tokenContractId": "28a555aa-d6bb-4a0b-9266-0b6668f824b5"
}

Assina a configuração salva mais recente. A autorização expira após dez minutos e só pode ser consumida uma vez. Sua integração ou relayer deve enviá-la para walletRegisterAddress usando a ABI retornada, na rede indicada em network.chainId.

Responses

• 201Autorização assinada para o registro.

  {
    "walletRegisterAddress": "0x2222222222222222222222222222222222222222",
    "abi": [],
    "network": { "name": "Ethereum", "chainId": "1", "isTestnet": false },
    "functionName": "setSplitWalletWithAuth",
    "args": [
      "12345",
      "7",
      "0x3333333333333333333333333333333333333333",
      "0x1111111111111111111111111111111111111111",
      true,
      "0",
      "1789834200",
      27,
      "0x...",
      "0x..."
    ],
    "expiresAt": "2026-09-20T12:10:00.000Z",
    "signatureParams": {
      "clientId": "12345",
      "splitId": "7",
      "token": "0x3333333333333333333333333333333333333333",
      "wallet": "0x1111111111111111111111111111111111111111",
      "active": true,
      "nonce": "0",
      "deadline": "1789834200",
      "v": 27,
      "r": "0x...",
      "s": "0x..."
    }
  }

  functionName é o método do contrato de registro (presente na abi) a ser chamado no walletRegisterAddress, na rede indicada em network.chainId, passando os args. O valor é setSplitWalletWithAuth para a carteira de um parceiro e setClientWalletWithAuth para a carteira do próprio negócio; splitId aparece em signatureParams apenas no caso do parceiro.

• 400Corpo ou parâmetros inválidos.
• 401Chave de API ausente ou inválida.
• 404Parceiro ou contrato do token não encontrado para este cliente.
• 422Pagamentos multidestino indisponíveis ou configuração inválida.

GET/api/split/wallet/statusCompara a configuração salva com o estado atual do registro on-chain.

Query parameters

Nome	Tipo	Obrigatório	Descrição
tokenContractId	UUID	Sim	UUID do contrato retornado como contractId por GET /api/currency-token.

Responses

• 200Estado salvo e estado on-chain da carteira.

  {
    "wallet": "0x1111111111111111111111111111111111111111",
    "active": true,
    "isEnabled": true,
    "configured": {
      "wallet": "0x1111111111111111111111111111111111111111",
      "active": true
    }
  }

  wallet e active são o estado atual on-chain. configured é o estado desejado que foi salvo. isEnabled é true quando os dois coincidem; em uma desativação confirmada do parceiro, ele pode ser true enquanto active é false.

• 400Corpo ou parâmetros inválidos.
• 401Chave de API ausente ou inválida.
• 404Parceiro ou contrato do token não encontrado para este cliente.
• 422Pagamentos multidestino indisponíveis ou configuração inválida.

PATCH/api/split/partners/{partnerId}/walletSalva a carteira desejada e o estado do vínculo de parceiro.

Path parameters

Nome	Tipo	Obrigatório	Descrição
partnerId	UUID	Sim	Vínculo retornado por POST /api/split/partners.

Request body

{
  "tokenContractId": "28a555aa-d6bb-4a0b-9266-0b6668f824b5",
  "wallet": "0x1111111111111111111111111111111111111111",
  "active": true
}

Use um contractId retornado por GET /api/currency-token com splitEnabled: true. O campo active assume true; somente vínculos de parceiros podem ser desativados. Salvar não altera a blockchain até que a autorização retornada seja enviada on-chain.

Responses

• 200Configuração salva com a autorização assinada para o registro.

  {
    "walletRegisterAddress": "0x2222222222222222222222222222222222222222",
    "abi": [],
    "network": { "name": "Ethereum", "chainId": "1", "isTestnet": false },
    "functionName": "setSplitWalletWithAuth",
    "args": [
      "12345",
      "7",
      "0x3333333333333333333333333333333333333333",
      "0x1111111111111111111111111111111111111111",
      true,
      "0",
      "1789834200",
      27,
      "0x...",
      "0x..."
    ],
    "expiresAt": "2026-09-20T12:10:00.000Z",
    "signatureParams": {
      "clientId": "12345",
      "splitId": "7",
      "token": "0x3333333333333333333333333333333333333333",
      "wallet": "0x1111111111111111111111111111111111111111",
      "active": true,
      "nonce": "0",
      "deadline": "1789834200",
      "v": 27,
      "r": "0x...",
      "s": "0x..."
    }
  }

  functionName é o método do contrato de registro (presente na abi) a ser chamado no walletRegisterAddress, na rede indicada em network.chainId, passando os args. O valor é setSplitWalletWithAuth para a carteira de um parceiro e setClientWalletWithAuth para a carteira do próprio negócio; splitId aparece em signatureParams apenas no caso do parceiro.

• 400Corpo ou parâmetros inválidos.
• 401Chave de API ausente ou inválida.
• 404Parceiro ou contrato do token não encontrado para este cliente.
• 422Pagamentos multidestino indisponíveis ou configuração inválida.

POST/api/split/partners/{partnerId}/wallet/authorizationRetorna uma autorização EIP-712 de curta duração para a configuração salva.

Path parameters

Nome	Tipo	Obrigatório	Descrição
partnerId	UUID	Sim	Vínculo retornado por POST /api/split/partners.

Request body

{
  "tokenContractId": "28a555aa-d6bb-4a0b-9266-0b6668f824b5"
}

Assina a configuração salva mais recente. A autorização expira após dez minutos e só pode ser consumida uma vez. Sua integração ou relayer deve enviá-la para walletRegisterAddress usando a ABI retornada, na rede indicada em network.chainId.

Responses

• 201Autorização assinada para o registro.

  {
    "walletRegisterAddress": "0x2222222222222222222222222222222222222222",
    "abi": [],
    "network": { "name": "Ethereum", "chainId": "1", "isTestnet": false },
    "functionName": "setSplitWalletWithAuth",
    "args": [
      "12345",
      "7",
      "0x3333333333333333333333333333333333333333",
      "0x1111111111111111111111111111111111111111",
      true,
      "0",
      "1789834200",
      27,
      "0x...",
      "0x..."
    ],
    "expiresAt": "2026-09-20T12:10:00.000Z",
    "signatureParams": {
      "clientId": "12345",
      "splitId": "7",
      "token": "0x3333333333333333333333333333333333333333",
      "wallet": "0x1111111111111111111111111111111111111111",
      "active": true,
      "nonce": "0",
      "deadline": "1789834200",
      "v": 27,
      "r": "0x...",
      "s": "0x..."
    }
  }

  functionName é o método do contrato de registro (presente na abi) a ser chamado no walletRegisterAddress, na rede indicada em network.chainId, passando os args. O valor é setSplitWalletWithAuth para a carteira de um parceiro e setClientWalletWithAuth para a carteira do próprio negócio; splitId aparece em signatureParams apenas no caso do parceiro.

• 400Corpo ou parâmetros inválidos.
• 401Chave de API ausente ou inválida.
• 404Parceiro ou contrato do token não encontrado para este cliente.
• 422Pagamentos multidestino indisponíveis ou configuração inválida.

GET/api/split/partners/{partnerId}/wallet/statusCompara a configuração salva com o estado atual do registro on-chain.

Path parameters

Nome	Tipo	Obrigatório	Descrição
partnerId	UUID	Sim	Vínculo retornado por POST /api/split/partners.

Query parameters

Nome	Tipo	Obrigatório	Descrição
tokenContractId	UUID	Sim	UUID do contrato retornado como contractId por GET /api/currency-token.

Responses

• 200Estado salvo e estado on-chain da carteira.

  {
    "wallet": "0x1111111111111111111111111111111111111111",
    "active": true,
    "isEnabled": true,
    "configured": {
      "wallet": "0x1111111111111111111111111111111111111111",
      "active": true
    }
  }

  wallet e active são o estado atual on-chain. configured é o estado desejado que foi salvo. isEnabled é true quando os dois coincidem; em uma desativação confirmada do parceiro, ele pode ser true enquanto active é false.

• 400Corpo ou parâmetros inválidos.
• 401Chave de API ausente ou inválida.
• 404Parceiro ou contrato do token não encontrado para este cliente.
• 422Pagamentos multidestino indisponíveis ou configuração inválida.