Skip to main content
POST
/
payments
/
settlement_requests
import cobo_waas2
from cobo_waas2.models.create_settlement_request_request import (
    CreateSettlementRequestRequest,
)
from cobo_waas2.models.settlement import Settlement
from cobo_waas2.rest import ApiException
from pprint import pprint

# See configuration.py for a list of all supported configurations.
configuration = cobo_waas2.Configuration(
    # Replace `<YOUR_PRIVATE_KEY>` with your private key
    api_private_key="<YOUR_PRIVATE_KEY>",
    # Select the development environment. To use the production environment, change the URL to https://api.cobo.com/v2.
    host="https://api.dev.cobo.com/v2",
)
# Enter a context with an instance of the API client
with cobo_waas2.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = cobo_waas2.PaymentApi(api_client)
    create_settlement_request_request = cobo_waas2.CreateSettlementRequestRequest(
        request_id="SETTLEMENT123", 
        settlement_type="Merchant",
        payout_channel="Crypto",
        settlements=[
            cobo_waas2.CreateSettlement(
                    merchant_id="M1001",
                    token_id="ETH_USDT", 
                    amount="500.00",
                    crypto_address="0xabc123456789def0000000000000000000000000"
                )
            ]
    )

    try:
        # Create settlement request
        api_response = api_instance.create_settlement_request(
            create_settlement_request_request=create_settlement_request_request
        )
        print("The response of PaymentApi->create_settlement_request:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling PaymentApi->create_settlement_request: %s\n" % e)


{
  "settlement_request_id": "S20250304-1001",
  "request_id": "SETTLEMENT123",
  "status": "Pending",
  "settlements": [
    {
      "currency": "USD",
      "token_id": "ETH_USDT",
      "chain_id": "ETH",
      "merchant_id": "M1001",
      "amount": "500.00",
      "settled_amount": "500.00",
      "status": "Pending",
      "bank_account": {
        "bank_account_id": "123e4567-e89b-12d3-a456-426614174003",
        "info": {
          "beneficiary_name": "John Doe",
          "beneficiary_address": "123 Main St, Anytown, USA",
          "account_number": "4111111111111111",
          "bank_name": "ABC Bank",
          "bank_country": "USA",
          "bank_address": "456 Bank Ave, Cityville, USA",
          "swift_or_bic": "ABCDEFGH"
        },
        "created_timestamp": 1744689600,
        "updated_timestamp": 1744689600
      },
      "transactions": [
        {
          "tx_id": "tx_123e4567-e89b-12d3-a456-426614174003",
          "from_address": "0xF8e4bfc10A2821DF52D3322cB5170E5E9276b537",
          "to_address": "0x15B95A2D8af95D9F48148667B6b8B3CdF89e4F15",
          "amount": "0.15",
          "status": "Submitted",
          "created_timestamp": 1610445878970,
          "updated_timestamp": 1610445878970,
          "tx_hash": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
          "token_id": "ETH_USDT",
          "counterparty": {
            "counterparty_type": "Individual",
            "counterparty_name": "Counterparty A",
            "created_timestamp": 1744689600,
            "updated_timestamp": 1744689600,
            "counterparty_id": "123e4567-e89b-12d3-a456-426614174003",
            "country": "USA",
            "email": "[email protected]",
            "contact_address": "123 Main St, Anytown, USA"
          },
          "destination": {
            "destination_type": "Individual",
            "destination_name": "Destination A",
            "created_timestamp": 1744689600,
            "updated_timestamp": 1744689600,
            "destination_id": "123e4567-e89b-12d3-a456-426614174003",
            "country": "USA",
            "email": "[email protected]",
            "contact_address": "123 Main St, Anytown, USA",
            "merchant_id": "M1001"
          }
        }
      ],
      "created_timestamp": 1744689600,
      "updated_timestamp": 1744689600,
      "crypto_address_id": "addr_ethusdt_20250429T134512_a8c31f",
      "crypto_address": "0xabc123456789def0000000000000000000000000",
      "payout_channel": "Crypto",
      "acquiring_type": "Order",
      "settlement_request_id": "S20250304-1001",
      "order_ids": [
        "O20250304-M1001-1001"
      ],
      "commission_fee": {
        "fee_amount": "<string>"
      },
      "bridging_fee": {
        "fee_amount": "<string>",
        "received_token_id": "<string>",
        "received_amount": "<string>",
        "bridge_status": "Completed"
      }
    }
  ],
  "created_timestamp": 1744689600,
  "updated_timestamp": 1744689600,
  "initiator": "api_key_b2ae1b5aaade686c968ef2bbd31cc75ba94e5a85fd9cb0b35b81dcc15f520e9d",
  "acquiring_type": "Order",
  "payout_channel": "Crypto",
  "settlement_type": "Merchant",
  "currency": "USD",
  "received_amount_fiat": "500.00",
  "bank_account": {
    "bank_account_id": "123e4567-e89b-12d3-a456-426614174003",
    "info": {
      "beneficiary_name": "John Doe",
      "beneficiary_address": "123 Main St, Anytown, USA",
      "account_number": "4111111111111111",
      "bank_name": "ABC Bank",
      "bank_country": "USA",
      "bank_address": "456 Bank Ave, Cityville, USA",
      "swift_or_bic": "ABCDEFGH"
    },
    "created_timestamp": 1744689600,
    "updated_timestamp": 1744689600
  }
}
import cobo_waas2
from cobo_waas2.models.create_settlement_request_request import (
    CreateSettlementRequestRequest,
)
from cobo_waas2.models.settlement import Settlement
from cobo_waas2.rest import ApiException
from pprint import pprint

# See configuration.py for a list of all supported configurations.
configuration = cobo_waas2.Configuration(
    # Replace `<YOUR_PRIVATE_KEY>` with your private key
    api_private_key="<YOUR_PRIVATE_KEY>",
    # Select the development environment. To use the production environment, change the URL to https://api.cobo.com/v2.
    host="https://api.dev.cobo.com/v2",
)
# Enter a context with an instance of the API client
with cobo_waas2.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = cobo_waas2.PaymentApi(api_client)
    create_settlement_request_request = cobo_waas2.CreateSettlementRequestRequest(
        request_id="SETTLEMENT123", 
        settlement_type="Merchant",
        payout_channel="Crypto",
        settlements=[
            cobo_waas2.CreateSettlement(
                    merchant_id="M1001",
                    token_id="ETH_USDT", 
                    amount="500.00",
                    crypto_address="0xabc123456789def0000000000000000000000000"
                )
            ]
    )

    try:
        # Create settlement request
        api_response = api_instance.create_settlement_request(
            create_settlement_request_request=create_settlement_request_request
        )
        print("The response of PaymentApi->create_settlement_request:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling PaymentApi->create_settlement_request: %s\n" % e)

Authorizations

​
BIZ-API-KEY
string
header
required

The API key. For more details, refer to API key.

In the API playground, enter your API secret, and your API key will be accordingly calculated.

Body

application/json

The request body to create a settlement request.

​
request_id
string
required

The request ID that is used to track a settlement request. The request ID is provided by you and must be unique.

Example:

"SETTLEMENT123"

​
settlements
object[]
required
​
acquiring_type
enum<string>

The payment acquisition type.

  • Order: Payers pay by fixed-amount orders. Ideal for specific purchases and one-time transactions.
  • TopUp: Account recharge flow where payers deposit funds to their dedicated top-up addresses. Ideal for flexible or usage-based payment models.
Available options:
Order,
TopUp
Example:

"Order"

​
payout_channel
enum<string>

The channel through which the payout will be processed. Possible values include:

  • Crypto: The payout will be processed as a cryptocurrency transfer to a crypto address.
  • OffRamp: The payout will be processed as a fiat currency transfer to a registered bank account.
Available options:
Crypto,
OffRamp
Example:

"Crypto"

​
settlement_type
enum<string>

Specifies the source of funds for the settlement:

  • Merchant: The settlement amount will be deducted from the merchant balance.
  • Psp: The settlement amount will be deducted from the developer balance.
Available options:
Merchant,
Psp
Example:

"Merchant"

​
bank_account_id
string<uuid>

The ID of the bank account where the funds will be deposited. You can call List all bank accounts to retrieve the IDs of registered bank accounts.

This field is only applicable for off-ramp.

Example:

"123e457-e89b-12d3-a456-426614174004"

​
currency
string

The fiat currency to receive after off-ramping. Currently, only USD is supported. Specify this field when payout_channel is set to OffRamp.

Example:

"USD"

​
remark
string

The remark for the payout request.

Example:

"Request for customer 123"

Response

The settlement request was successfully created.

​
settlement_request_id
string
required

The settlement request ID generated by Cobo.

Example:

"S20250304-1001"

​
request_id
string
required

The request ID provided by you when creating the settlement request.

Example:

"SETTLEMENT123"

​
status
enum<string>
required

The current status of a settlement request:

  • Pending: The settlement request has been created and is awaiting processing.
  • Processing: The settlement request is currently being processed, with at least one settlement in progress.
  • Completed: All requested settlements have been completed.
  • PartiallyCompleted: Some requested settlements have been completed successfully, while others have failed.
  • Failed: All requested settlements have failed.
  • Canceled: The settlement request has been canceled due to bank transfer failure. Contact Cobo's support team through [email protected] for assistance.
Available options:
Pending,
Processing,
Completed,
PartiallyCompleted,
Failed,
Canceled
Example:

"Pending"

​
settlements
object[]
required
​
created_timestamp
integer

The created time of the settlement request, represented as a UNIX timestamp in seconds.

Example:

1744689600

​
updated_timestamp
integer

The updated time of the settlement request, represented as a UNIX timestamp in seconds.

Example:

1744689600

​
initiator
string

The initiator of this settlement request. Can return either an API key or the Payments App's ID.

  • Format api_key_<API_KEY>: Indicates the settlement request was initiated via the Payments API using the API key.
  • Format app_<APP_ID>: Indicates the settlement request was initiated through the Payments App using the App ID.
Example:

"api_key_b2ae1b5aaade686c968ef2bbd31cc75ba94e5a85fd9cb0b35b81dcc15f520e9d"

​
acquiring_type
enum<string>

The payment acquisition type.

  • Order: Payers pay by fixed-amount orders. Ideal for specific purchases and one-time transactions.
  • TopUp: Account recharge flow where payers deposit funds to their dedicated top-up addresses. Ideal for flexible or usage-based payment models.
Available options:
Order,
TopUp
Example:

"Order"

​
payout_channel
enum<string>

The channel through which the payout will be processed. Possible values include:

  • Crypto: The payout will be processed as a cryptocurrency transfer to a crypto address.
  • OffRamp: The payout will be processed as a fiat currency transfer to a registered bank account.
Available options:
Crypto,
OffRamp
Example:

"Crypto"

​
settlement_type
enum<string>

Specifies the source of funds for the settlement:

  • Merchant: The settlement amount will be deducted from the merchant balance.
  • Psp: The settlement amount will be deducted from the developer balance.
Available options:
Merchant,
Psp
Example:

"Merchant"

​
currency
string

The fiat currency for the off-ramp.

Example:

"USD"

​
received_amount_fiat
string

The estimated amount of the fiat currency to receive after off-ramping. This amount is subject to change due to bank transfer fees.

Example:

"500.00"

​
bank_account
object