Skip to main content
POST
/
payments
/
orders
import cobo_waas2
from cobo_waas2.models.create_payment_order_request import CreatePaymentOrderRequest
from cobo_waas2.models.order import Order
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_payment_order_request = cobo_waas2.CreatePaymentOrderRequest(
        merchant_id="M1001", 
        merchant_order_code="M20240201001",
        psp_order_code="P20240201001", 
        pricing_currency="USD",
        pricing_amount="100.00",
        fee_amount="2.00",
        payable_currency="ETH_USDT"
    )

    try:
        # Create pay-in order
        api_response = api_instance.create_payment_order(
            create_payment_order_request=create_payment_order_request
        )
        print("The response of PaymentApi->create_payment_order:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling PaymentApi->create_payment_order: %s\n" % e)


{
  "order_id": "5001",
  "psp_order_code": "P20240201001",
  "fee_amount": "2.00",
  "chain_id": "ETH",
  "payable_amount": "103.03",
  "exchange_rate": "0.99",
  "receive_address": "0x1234567890abcdef1234567890abcdef12345678",
  "status": "Pending",
  "received_token_amount": "103.0305",
  "merchant_id": "1001",
  "merchant_order_code": "M20240201001",
  "pricing_currency": "USD",
  "pricing_amount": "100.00",
  "payable_currency": "ETH_USDT",
  "amount_tolerance": "0.5",
  "expired_at": 1711324800,
  "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"
      }
    }
  ],
  "currency": "<string>",
  "order_amount": "<string>",
  "token_id": "<string>",
  "settlement_status": "Pending"
}
import cobo_waas2
from cobo_waas2.models.create_payment_order_request import CreatePaymentOrderRequest
from cobo_waas2.models.order import Order
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_payment_order_request = cobo_waas2.CreatePaymentOrderRequest(
        merchant_id="M1001", 
        merchant_order_code="M20240201001",
        psp_order_code="P20240201001", 
        pricing_currency="USD",
        pricing_amount="100.00",
        fee_amount="2.00",
        payable_currency="ETH_USDT"
    )

    try:
        # Create pay-in order
        api_response = api_instance.create_payment_order(
            create_payment_order_request=create_payment_order_request
        )
        print("The response of PaymentApi->create_payment_order:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling PaymentApi->create_payment_order: %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 pay-in order.

​
merchant_id
string
required

The merchant ID.

Example:

"1001"

​
psp_order_code
string
required

A unique reference code assigned by the developer to identify this order in their system.

Example:

"P20240201001"

​
fee_amount
string
required

The developer fee for the order. It is added to the base amount (pricing_amount) to determine the final charge. For example, if pricing_amount is "100.00" and fee_amount is "2.00", the payer will be charged "102.00" in total, with "100.00" being settled to the merchant account and "2.00" settled to the developer account. Values must be greater than 0 and contain two decimal places.

Example:

"2.00"

​
payable_currency
string
required

The ID of the cryptocurrency used for payment. Supported values:

  • USDC: ETH_USDC, ARBITRUM_USDC, SOL_USDC, BASE_USDC, MATIC_USDC, BSC_USDC
  • USDT: TRON_USDT, ETH_USDT, ARBITRUM_USDT, SOL_USDT, BASE_USDT, MATIC_USDT, BSC_USDT
Example:

"ETH_USDT"

​
merchant_order_code
string

A unique reference code assigned by the merchant to identify this order in their system.

Example:

"M20240201001"

​
pricing_currency
string

The pricing currency that denominates pricing_amount and fee_amount. If left empty, both values will be denominated in payable_currency. Currently, For a complete list of supported currencies, see Supported chains and tokens.

Example:

"USD"

​
pricing_amount
string

The base amount of the order, excluding the developer fee (specified in fee_amount). Values must be greater than 0 and contain two decimal places.

Example:

"100.00"

​
payable_amount
string

The total amount the payer needs to pay, denominated in the specified payable_currency. If this field is left blank, the system will automatically calculate the amount at order creation using the following formula: (pricing_amount + fee_amount) / current exchange rate.

Values must be greater than 0 and contain two decimal places.

Example:

"103.03"

​
expired_in
integer
default:1800

The number of seconds until the pay-in order expires, counted from when the request is sent. For example, if set to 1800, the order will expire in 30 minutes. Must be greater than zero and cannot exceed 3 hours (10800 seconds). After expiration:

  • The order status becomes final and cannot be changed
  • The received_token_amount field will no longer be updated
  • Funds received after expiration will be categorized as late payments and can only be settled from the developer balance.
  • A late payment will trigger a transactionLate webhook event.
Example:

1800

​
amount_tolerance
string

The allowed amount deviation, with precision up to 1 decimal place.

For example, if payable_amount is 100.00 and amount_tolerance is 0.50:

  • Payer pays 99.55 → Success (difference of 0.45 ≤ 0.5)
  • Payer pays 99.40 → Underpaid (difference of 0.60 > 0.5)
Example:

"0.5"

​
currency
string
default:""

This field has been deprecated. Please use pricing_currency instead.

Example:

"USD"

​
order_amount
string

This field has been deprecated. Please use pricing_amount instead.

Example:

"100.00"

​
token_id
string

This field has been deprecated. Please use payable_currency instead.

Example:

"ETH_USDT"

​
use_dedicated_address
boolean

This field has been deprecated.

Example:

false

​
custom_exchange_rate
string

This field has been deprecated.

Example:

"1.00"

Response

The request was successful.

​
order_id
string
required

The order ID.

Example:

"5001"

​
psp_order_code
string
required

A unique reference code assigned by the developer to identify this order in their system.

Example:

"P20240201001"

​
fee_amount
string
required

The developer fee for the order. It is added to the base amount to determine the final charge.

Example:

"2.00"

​
chain_id
string
required

The ID of the blockchain network where the payment transaction should be made.

Example:

"ETH"

​
payable_amount
string
required

The cryptocurrency amount to be paid for this order.

Example:

"103.03"

​
exchange_rate
string
required

The exchange rate between payable_currency and pricing_currency, calculated as (pricing_amount + fee_amount) / payable_amount.

This field is only returned when payable_amount was not provided in the order creation request.

Example:

"0.99"

​
receive_address
string
required

The recipient wallet address to be used for the payment transaction.

Example:

"0x1234567890abcdef1234567890abcdef12345678"

​
status
enum<string>
required

The current status of the pay-in order:

  • Pending: The order has been created and is awaiting payment. No incoming transaction has been detected.
  • Processing: An incoming transaction has been detected at the recipient address.
  • Completed: The payment has been fully received and is now complete.
  • Expired: The order has reached its expiration time without receiving any payment, or the order has been cancelled by the Update pay-in order operation.
  • Underpaid: The order has reached its expiration time. A payment was received but the amount is less than the order's required amount.
Available options:
Pending,
Processing,
Completed,
Expired,
Underpaid
Example:

"Pending"

​
received_token_amount
string
required

The total cryptocurrency amount received for this order. Updates until the expiration time. Precision matches the token standard (e.g., 6 decimals for USDT).

Example:

"103.0305"

​
merchant_id
string

The merchant ID.

Example:

"1001"

​
merchant_order_code
string

A unique reference code assigned by the merchant to identify this order in their system.

Example:

"M20240201001"

​
pricing_currency
string

The pricing currency of the order.

Example:

"USD"

​
pricing_amount
string

The base amount of the order, excluding the developer fee (specified in fee_amount).

Example:

"100.00"

​
payable_currency
string

The ID of the cryptocurrency used for payment.

Example:

"ETH_USDT"

​
amount_tolerance
string

The allowed amount deviation, with precision up to 1 decimal place.

For example, if payable_amount is 100.00 and amount_tolerance is 0.50:

  • Payer pays 99.55 → Success (difference of 0.45 ≤ 0.5)
  • Payer pays 99.40 → Underpaid (difference of 0.60 > 0.5)
Example:

"0.5"

​
expired_at
integer

The expiration time of the pay-in order, represented as a UNIX timestamp in seconds.

Example:

1711324800

​
created_timestamp
integer

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

Example:

1744689600

​
updated_timestamp
integer

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

Example:

1744689600

​
transactions
object[]

An array of transactions associated with this pay-in order. Each transaction represents a separate blockchain operation related to the settlement process.

​
currency
string

This field has been deprecated. Please use pricing_currency instead.

​
order_amount
string

This field has been deprecated. Please use pricing_amount instead.

​
token_id
string

This field has been deprecated. Please use payable_currency instead.

​
settlement_status
enum<string>

The current status of a settlement.

  • Pending: The settlement has been created and is awaiting processing.
  • Processing: The settlement is being processed.
  • Completed: The funds have been successfully deposited into the bank account or the withdrawal crypto address.
  • PartiallyCompleted: Some settlement transactions have been completed successfully, while others have failed.
  • Failed: The settlement could not be completed due to an error.
Available options:
Pending,
Processing,
Completed,
PartiallyCompleted,
Failed
Example:

"Pending"