API

To use the Bitpayway API, you will need the API Key generated in your business control panel. You must include the token in your HTTP request as follows:

Header

• Authorization: "ApiKey <SECRET_KEY>"

Routes

POST/api/orderCria ordem de pagamento

Query parameters

POST /api/order?isTestnet=true

isTestnet (boolean): A safety guard for environments that must not create orders on mainnet. Set it to true to ensure that the operation is performed only on a testnet; if the selected network is a mainnet, the operation is blocked. This is especially useful in staging environments.

Request body

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

description: The description of the created payment order.

requestId: A unique ID generated by your application so you can easily identify the created order.

amount: The value of the payment order. This field must be a string representing the amount.

network: The network of the currency (token) used for the payment order. This field is case insensitive, so ethereum, Ethereum and ETHEREUM are equivalent. Available networks:

• Mainnet: Ethereum, Arbitrum
• Testnet: Sepolia, Arbitrum Sepolia

The token must be available on the selected network; GET /api/currency-token lists each token with its network.

token: The currency you want the payment order to be paid with. It is the token's symbol, not its name.

paymentModel (optional): standard or split, where split creates a multi-destination order. Omit it to keep the standard behaviour and the standard response shape.

split (required when paymentModel is split): the allocation for one partner, as { "partnerId": "<partner link UUID>", "partnerAmount": "<gross share>" }. partnerAmount is a decimal string in the display unit of the token, between zero and amount, limited to the token's decimals. See Multi-destination payments.

Responses

• 201

  Payment order created (or an existing one returned due to duplication).

  • gatewayUrl: The URL of the Bitpayway payment page to which the payer must be redirected.

  • paymentModel and split: returned only for multi-destination orders, with the partner and the gross allocation fixed on the order.

  {
    "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

All filters are optional and can be combined. When more than one filter is provided, only orders matching all of them are returned.

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

Parameter	Type	Description
date	date or date-time	Filters by the order creation date. YYYY-MM-DD includes the entire day; an ISO 8601 date-time matches the exact instant.
dateStart	date or date-time	Inclusive lower boundary for the order creation date.
dateEnd	date or date-time	Inclusive upper boundary for the order creation date. YYYY-MM-DD includes the entire day. It must be greater than or equal to dateStart.
requestId	UUID v4	Filters by the request identifier supplied when the order was created.
status	string	Filters by status. Accepted values: pending, partial paid, expired partial paid, paid waiting confirmations, paid, expired, and canceled.
amount	numeric string	Filters by the exact order amount, for example 200 or 200.50.

Responses

• 200

  List of orders. Each order includes the payment amount fields below as decimal strings in the order token:

  • paidAmount: Total amount paid on-chain before fees.
  • netAmount: Amount sent to the client wallet after payment fees.
  • fee: Platform spread.

  A multi-destination order also carries paymentModel, split, settlementStatus, settlementVersion and the amounts of each side (partnerNetAmount, partnerGrossAmount, clientCommission, partnerCommission, commissionReceived). On a multi-destination order, netAmount is the amount you received and paidAmount is the confirmed gross amount of the order. See Multi-destination payments.

  {
    "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}Get payment order by request ID

Path parameters

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

Parameter	Type	Required	Description
requestId	UUID	Yes	Request identifier supplied when the payment order was created.

Responses

• 200

  Payment order found by its request ID. The response includes the payment amount fields below as decimal strings in the order token:

  • paidAmount: Total amount paid on-chain before fees.
  • netAmount: Amount sent to the client wallet after payment fees.
  • fee: Platform spread.

  {
    "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": "Order #1234",
      "amount": "1000.52",
      "status": "paid",
      "gatewayUrl": "https://example.com/",
      "paidAmount": "1000.52",
      "netAmount": "950.494",
      "fee": "50.026"
    }
  }

• 400Invalid request ID.
• 401Invalid API key.
• 404Payment order not found.
• 503The payment order status could not be reconciled with the 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"
  }

Multi-destination payment configuration

For the complete lifecycle—from wallet responsibilities and dashboard setup to orders, settlement and reconciliation—use the single Multi-destination payments guide. The components below are the API reference for server integrations. The client wallet may also be managed in the dashboard; partner links and wallets are API-only.

GET/api/split/partnersLists the partner links owned by the business associated with the API key.

Query parameters

Both filters are optional and use exact matching. When both are provided, only the partner that matches both values is returned. Results always remain scoped to the business associated with the API key.

Name	Type	Required	Description
id	UUID	No	Public partner-link ID returned by POST /api/split/partners.
external_id	string	No	Client-defined partner ID, from 1 to 255 characters.

Responses

• 200Partner links.

  {
    "data": [
      {
        "id": "9f1c2d64-5717-4562-b3fc-2c963f66afa6",
        "name": "Marketplace partner",
        "external_id": "marketplace-seller-42"
      }
    ]
  }

• 400The id or external_id filter is invalid.
• 401Invalid or missing API key.

POST/api/split/partnersCreates a partner link for multi-destination payments.

Request body

{
  "name": "Marketplace partner",
  "external_id": "marketplace-seller-42"
}

Creates a partner link owned by the business associated with the API key. Use the returned id as split.partnerId when creating orders and as the partnerId path parameter when configuring that partner's wallet.

external_id is an optional client-defined string from 1 to 255 characters. When set, it must be unique among the partners of this business. Another business may use the same value. A duplicate within the same business returns 409. When omitted, the response contains "external_id": null.

Responses

• 201Partner link created.

  {
    "partner": {
      "id": "9f1c2d64-5717-4562-b3fc-2c963f66afa6",
      "name": "Marketplace partner",
      "external_id": "marketplace-seller-42"
    }
  }

• 400The partner name or external_id is invalid.
• 401Invalid or missing API key.
• 409The external_id is already in use by this business.

PATCH/api/split/walletSaves the desired multi-destination wallet for the business.

Request body

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

Use a contractId returned by GET /api/currency-token with splitEnabled: true. The active field defaults to true; only partner links can be deactivated. Saving does not change the blockchain until the returned authorization is submitted on-chain.

Responses

• 200Configuration saved with the signed registry authorization.

  {
    "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 is the registry contract method (part of the abi) to call on walletRegisterAddress, on the network in network.chainId, passing args. The value is setSplitWalletWithAuth for a partner wallet and setClientWalletWithAuth for the business's own wallet; splitId is present in signatureParams only in the partner case.

• 400Invalid request body or parameters.
• 401Invalid or missing API key.
• 404Partner or token contract not found for this client.
• 422Multi-destination payments are unavailable or the configuration is invalid.

POST/api/split/wallet/authorizationReturns a short-lived EIP-712 authorization for the saved configuration.

Request body

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

Signs the latest saved configuration. The authorization expires after ten minutes and can be consumed only once. Your integration or relayer must submit it to walletRegisterAddress using the returned ABI, on the network in network.chainId.

Responses

• 201Signed registry authorization.

  {
    "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 is the registry contract method (part of the abi) to call on walletRegisterAddress, on the network in network.chainId, passing args. The value is setSplitWalletWithAuth for a partner wallet and setClientWalletWithAuth for the business's own wallet; splitId is present in signatureParams only in the partner case.

• 400Invalid request body or parameters.
• 401Invalid or missing API key.
• 404Partner or token contract not found for this client.
• 422Multi-destination payments are unavailable or the configuration is invalid.

GET/api/split/wallet/statusCompares the saved configuration with the current on-chain registry state.

Query parameters

Name	Type	Required	Description
tokenContractId	UUID	Yes	Token contract UUID returned as contractId by GET /api/currency-token.

Responses

• 200Saved and on-chain wallet state.

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

  wallet and active are the current on-chain state. configured is the saved desired state. isEnabled is true when both states match; for a confirmed partner deactivation it can be true while active is false.

• 400Invalid request body or parameters.
• 401Invalid or missing API key.
• 404Partner or token contract not found for this client.
• 422Multi-destination payments are unavailable or the configuration is invalid.

PATCH/api/split/partners/{partnerId}/walletSaves the desired wallet and active state for a partner link.

Path parameters

Name	Type	Required	Description
partnerId	UUID	Yes	Partner link returned by POST /api/split/partners.

Request body

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

Use a contractId returned by GET /api/currency-token with splitEnabled: true. The active field defaults to true; only partner links can be deactivated. Saving does not change the blockchain until the returned authorization is submitted on-chain.

Responses

• 200Configuration saved with the signed registry authorization.

  {
    "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 is the registry contract method (part of the abi) to call on walletRegisterAddress, on the network in network.chainId, passing args. The value is setSplitWalletWithAuth for a partner wallet and setClientWalletWithAuth for the business's own wallet; splitId is present in signatureParams only in the partner case.

• 400Invalid request body or parameters.
• 401Invalid or missing API key.
• 404Partner or token contract not found for this client.
• 422Multi-destination payments are unavailable or the configuration is invalid.

POST/api/split/partners/{partnerId}/wallet/authorizationReturns a short-lived EIP-712 authorization for the saved configuration.

Path parameters

Name	Type	Required	Description
partnerId	UUID	Yes	Partner link returned by POST /api/split/partners.

Request body

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

Signs the latest saved configuration. The authorization expires after ten minutes and can be consumed only once. Your integration or relayer must submit it to walletRegisterAddress using the returned ABI, on the network in network.chainId.

Responses

• 201Signed registry authorization.

  {
    "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 is the registry contract method (part of the abi) to call on walletRegisterAddress, on the network in network.chainId, passing args. The value is setSplitWalletWithAuth for a partner wallet and setClientWalletWithAuth for the business's own wallet; splitId is present in signatureParams only in the partner case.

• 400Invalid request body or parameters.
• 401Invalid or missing API key.
• 404Partner or token contract not found for this client.
• 422Multi-destination payments are unavailable or the configuration is invalid.

GET/api/split/partners/{partnerId}/wallet/statusCompares the saved configuration with the current on-chain registry state.

Path parameters

Name	Type	Required	Description
partnerId	UUID	Yes	Partner link returned by POST /api/split/partners.

Query parameters

Name	Type	Required	Description
tokenContractId	UUID	Yes	Token contract UUID returned as contractId by GET /api/currency-token.

Responses

• 200Saved and on-chain wallet state.

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

  wallet and active are the current on-chain state. configured is the saved desired state. isEnabled is true when both states match; for a confirmed partner deactivation it can be true while active is false.

• 400Invalid request body or parameters.
• 401Invalid or missing API key.
• 404Partner or token contract not found for this client.
• 422Multi-destination payments are unavailable or the configuration is invalid.