Basic API Structure Overview

For production-ready sample code, refer to the official SDKs:

• Go SDK: https://github.com/MartianPay/martianpay-go-sample
• Java SDK: https://github.com/MartianPay/martianpay-java-sample

Making API Requests with Your Secret Key

Assets APIs

1. List Assets (Merchant Enabled)

Returns the assets enabled for your merchant account. Only assets that have been activated for your account will be returned. Use this API to check which coins and networks you can use for payments, payroll, and payouts.

For detailed API reference, see: List Assets API

Field	Value
API Name	List Assets
API Endpoint	/v1/assets
HTTP Method	GET
Data Format	Query Parameters
Authentication	Basic Auth (Username is API Key, Password is empty)

Request URL: GET https://api.martianpay.com/v1/assets

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Example Request:

curl --location --request GET 'https://api.martianpay.com/v1/assets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response will be a JSON object containing the list of assets enabled for the merchant.

{
    "error_code": "success",
    "msg": "success",
    "data": {
        "assets": [
            {
                "id": "USDT-Tron",
                "display_name": "Tether USD (Tron)",
                "coin": "USDT",
                "is_fiat": false,
                "decimals": 6,
                "payable": true,
                "network": "Tron",
                "is_mainnet": true,
                "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
                "address_url_template": "https://tronscan.on.btfs.io/#/address/%s",
                "tx_url_template": "https://tronscan.on.btfs.io/#/transaction/%s",
                "token": "USDT",
                "chain_id": 728126428
            },
            {
                "id": "USDC-Solana",
                "display_name": "USD Coin (Solana)",
                "coin": "USDC",
                "is_fiat": false,
                "decimals": 6,
                "payable": true,
                "network": "Solana",
                "is_mainnet": true,
                "contract_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "address_url_template": "https://solscan.io/account/%s",
                "tx_url_template": "https://solscan.io/tx/%s",
                "token": "USDC",
                "chain_id": 0
            },
            {
                "id": "USD",
                "display_name": "US Dollar",
                "coin": "USD",
                "is_fiat": true,
                "decimals": 2,
                "payable": false,
                "symbol": "$"
            }
        ]
    }
}

For the full list of all supported assets, see Supported Assets.

Response Parameter Description:

Parameter	Description
id	Unique identifier for the asset (e.g., "USDT-Tron")
display_name	Human-readable name of the asset
coin	Cryptocurrency code (e.g., "USDT", "USDC")
is_fiat	true for fiat currency, false for crypto
decimals	Number of decimal places for the asset
payable	Whether the asset can be used for payments
network	The blockchain network (e.g., "Tron", "Ethereum")
is_mainnet	true for production network, false for testnet
contract_address	The smart contract address for the token
address_url_template	URL template for viewing addresses on block explorer
tx_url_template	URL template for viewing transactions on block explorer
token	Token symbol
chain_id	EVM chain ID (0 for non-EVM chains)

2. List All Assets (System-wide)

Returns all assets supported by the system, regardless of whether they are enabled for your merchant account. Use this API to discover all available coins and networks, including those you have not yet activated.

Difference from List Assets:

• /v1/assets — Only returns assets enabled for your account (use for business operations)
• /v1/assets/all — Returns all assets supported by the system (use for discovery)

For detailed API reference, see: List All Assets API

Field	Value
API Name	List All Assets
API Endpoint	/v1/assets/all
HTTP Method	GET
Data Format	JSON
Authentication	None
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/assets/all

Example:

curl --location --request GET 'https://api.martianpay.com/v1/assets/all' \
--header 'Content-Type: application/json'

The response format is the same as List Assets, but includes all system-supported assets.

3. Get Asset Fees

For detailed API reference, see: Get Asset Fees API

Field	Value
API Name	Get Asset Fees
API Endpoint	/v1/assets/fees
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/assets/fees

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Example:

curl --location --request GET 'https://api.martianpay.com/v1/assets/fees' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

Customer APIs

4. Create Customer

For detailed API reference, see: Create Customer API

Request Method: POST

Request Path: https://api.martianpay.com/v1/customers

Request Parameters (JSON body):

Parameter	Type	Required	Description	Example
name	string	No	Customer's name	John Doe
email	string	No	Customer's email address	john@example.com
description	string	No	Additional customer information	VIP customer
metadata	object	No	Custom key-value pairs

Request Example (cURL)

curl --location --request POST 'https://api.martianpay.com/v1/customers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
  "name": "John Doe",
  "email": "john@example.com",
  "description": "VIP customer",
  "metadata": {
    "order_id": "12345"
  }
}'

Response Structure (JSON):

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "cus_123456",
    "object": "customer",
    "name": "John Doe",
    "email": "john@example.com",
    "description": "VIP customer",
    "metadata": {
      "order_id": "12345"
    },
    "created": 1631234567
  }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the customer
object	string	Object type, always "customer"
name	string	Customer's name
email	string	Customer's email address
description	string	Additional customer information
metadata	object	Custom key-value pairs
created	int64	Timestamp of customer creation (Unix time)

5. List Customers

For detailed API reference, see: List Customers API

Request Method: GET

Request Path: https://api.martianpay.com/v1/customers

Request Parameters (Query String):

Parameter	Type	Required	Description	Example
page	int32	Yes	Page number, starting from 0	0
page_size	int32	Yes	Number of records per page, at least 1	10
email	string	No	Filter customers by email	user@example.com

Response Structure (JSON):

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "customers": [ Array of Customer objects ],
    "total": Total record count,
    "page": Current page number,
    "page_size": Number of records per page
  }
}

✅ Request Example (cURL)

curl --location --request GET 'https://api.martianpay.com/v1/customers?page=0&page_size=10&email=user@example.com' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

📌 Response Example (JSON)

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "customers": [ ... ],
    "total": 1,
    "page": 0,
    "page_size": 10
  }
}

Response Parameter Description:

Top-level Response Structure (CustomerListResp)

Parameter	Type	Description
customers	Customer[]	Customer list
total	int32	Total number of customers matching the query
page	int32	Current page number (starting from 0)
page_size	int32	Number of customer records per page

6. Retrieve a Single Customer

For detailed API reference, see: Get Customer API

Request Method: GET

Request Path: https://api.martianpay.com/v1/customers/{id}

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Unique customer ID	cus_12345

Response Structure (JSON):

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "cus_12345",
    "object": "customer",
    "total_expense": 500,
    "total_payment": 550,
    "total_refund": 50,
    "currency": "USD",
    "created": 1740731398,
    "name": "John Doe",
    "email": "user@example.com",
    "description": "Test customer",
    "metadata": {
      "source": "api",
      "vip": "yes"
    },
    "phone": "+1234567890"
  }
}

✅ Request Example (cURL)

curl --location --request GET 'https://api.martianpay.com/v1/customers/cus_12345' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

📌 Response Example (JSON)

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "cus_12345",
    "object": "customer",
    "total_expense": 500,
    "total_payment": 550,
    "total_refund": 50,
    "currency": "USD",
    "created": 1740731398,
    "name": "John Doe",
    "email": "user@example.com",
    "description": "Test customer",
    "metadata": {
      "source": "api",
      "vip": "yes"
    },
    "phone": "+1234567890"
  }
}

7. Update Customer

For detailed API reference, see: Update Customer API

Request Method: POST

Request Path: https://api.martianpay.com/v1/customers/cus_7p51tXM7GBi7sz5J

Request Parameters (JSON body):

Parameter	Type	Required	Description	Example
name	string	No	Customer's new name	Jane Doe
email	string	No	Customer's new email address	jane@example.com
description	string	No	Updated customer information	Platinum customer
metadata	object	No	Updated custom key-value pairs

Response Structure (JSON):

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "cus_7p51tXM7GBi7sz5J",
    "object": "customer",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "description": "Platinum customer",
    "metadata": {
      "status": "active"
    },
    "updated": 1631234567
  }
}

Request Example (cURL)

curl --location --request POST 'https://api.martianpay.com/v1/customers/cus_7p51tXM7GBi7sz5J' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "description": "Platinum customer",
  "metadata": {
    "status": "active"
  }
}'

Response Structure (JSON):

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "cus_123456",
    "object": "customer",
    "name": "John Doe",
    "email": "john@example.com",
    "description": "VIP customer",
    "metadata": {
      "order_id": "12345"
    },
    "created": 1631234567
  }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the customer
object	string	Object type, always "customer"
name	string	Customer's name
email	string	Customer's email address
description	string	Additional customer information
metadata	object	Custom key-value pairs
created	int64	Timestamp of customer creation (Unix time)

8. Delete Customer

For detailed API reference, see: Delete Customer API

Field	Value
API Name	Delete Customer
API Endpoint	/v1/customers/{id}
HTTP Method	DELETE
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: DELETE https://api.martianpay.com/v1/customers/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Unique customer identifier to delete

Example:

curl --location --request DELETE 'https://api.martianpay.com/v1/customers/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

9. Create Ephemeral Token for Customer

For detailed API reference, see: Create Ephemeral Token API

Field	Value
API Name	Create Ephemeral Token for Customer
API Endpoint	/v1/customers/ephemeral_tokens
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/customers/ephemeral_tokens

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Body:

{
  "idp_key": "email",
  "idp_subject": "user@example.com",
  "provider": "instagram",
  "allow_create": true,
  "issued_by": "instagram_commerce_bot",
  "channel_metadata": {
    "instagram_user_id": "12345",
    "dm_thread_id": "67890"
  }
}

Request Parameter Description:

Parameter	Type	Required	Description	Example
idp_key	string	No	Identity provider type - determines how to identify the customer. Valid values: "email", "phone", "uuid". Optional: If not provided, creates an anonymous ephemeral token (only order_id based)	email
idp_subject	string	No	Unique identifier under the specified IDP. When idp_key="email", this should be the email address. When idp_key="phone", this should be the phone number. When idp_key="uuid", this should be a UUID. Optional: If not provided along with idp_key, creates an anonymous ephemeral token	user@example.com
provider	string	No	Channel or platform initiating the request. Examples: "instagram", "whatsapp", "wechat", "telegram". Used for tracking and channel-specific business logic. Optional: If not provided, creates an anonymous ephemeral token	instagram
order_id	string	No	Order identifier to associate with this ephemeral token. When provided, this order_id will be returned when the token is resolved. Useful for tracking which order the customer authentication is for	ord_abc123
return_url	string	No	URL to redirect the customer after authentication/payment. Used in social media integrations where the flow needs to return to a specific page. This URL will be returned when the ephemeral token is resolved	https://example.com/payment/success
allow_create	boolean	No	Determines whether to create a new customer if not found (default: true). Set to false to return an error if customer doesn't exist	true
issued_by	string	No	Identifies the system or service issuing this token request. Used for audit logging and tracking token origin	instagram_commerce_bot
channel_metadata	object	No	Stores arbitrary channel-specific data. Examples: {"instagram_user_id": "12345", "dm_thread_id": "67890"}	{"instagram_user_id": "12345"}

Example:

curl --location --request POST 'https://api.martianpay.com/v1/customers/ephemeral_tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
  "idp_key": "email",
  "idp_subject": "user@example.com",
  "provider": "instagram",
  "order_id": "ord_abc123",
  "allow_create": true,
  "issued_by": "instagram_commerce_bot",
  "channel_metadata": {
    "instagram_user_id": "12345",
    "dm_thread_id": "67890"
  }
}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "token": "eph_abc123xyz789",
    "expires_at": 1735689600
  }
}

Response Parameter Description:

Parameter	Type	Description
token	string	Ephemeral token string (short-lived, typically 5-15 minutes). Use this token with payment link URLs
expires_at	integer	Unix timestamp when the ephemeral token expires

Important Note:

The ephemeral token is used to authenticate customers when accessing payment links. Include the token as a query parameter in the payment link URL:

https://buy.martianpay.com/{payment_link_id}?ephemeral_token={token}

Example:

https://buy.martianpay.com/plink_abc123?ephemeral_token=eph_abc123xyz789

This allows customers to access pre-authenticated payment experiences through various channels (Instagram, WhatsApp, etc.) without requiring them to log in separately.

10. Resolve Customer Identity

For detailed API reference, see: Resolve Customer Identity API

Field	Value
API Name	Resolve Customer Identity
API Endpoint	/v1/customers/identities/resolve
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/customers/identities/resolve

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
request	string	Yes	Identity resolution parameters - must specify one authentication method

Example:

curl --location --request POST 'https://api.martianpay.com/v1/customers/identities/resolve' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "customer_id": "cus_abc123",
    "stripe_customer_id": "cus_stripe_xyz",
    "email": "user@example.com",
    "phone": "+1234567890",
    "uuid": "2b3deaec-bfe4-4519-9fcf-6248215f158e",
    "addresses": [],
    "tax_regions": [],
    "auth_token": "auth_token_abc123",
    "issued_by": "instagram_bot",
    "provider": "instagram",
    "order_id": "ord_abc123",
    "is_saved_customer": true,
    "payermax_customer_id": "pm_cust_123"
  }
}

Response Parameter Description:

Parameter	Type	Description
customer_id	string	MartianPay customer identifier
stripe_customer_id	string	Associated Stripe customer ID if applicable
email	string	Customer's email address
phone	string	Customer's phone number
uuid	string	Merchant-assigned unique identifier for the customer
addresses	array	Customer's saved addresses (always returns array, empty if none)
tax_regions	array	Customer's tax regions (always returns array, empty if none)
auth_token	string	Authentication token for session (returned when refresh_token=true)
issued_by	string	System or service that issued the authentication
provider	string	Channel or platform identifier
order_id	string	Merchant order ID associated with this authentication
is_saved_customer	boolean	Indicates if customer has been saved (has stripe_customer_id)
payermax_customer_id	string	Associated PayerMax customer ID if applicable

[Refer to the API documentation for complete response schema]

Payment Intent APIs

11. Create Payment Intent

For detailed API reference, see: Create Payment Intent API

Field	Value
API Name	Create Payment Intent
API Endpoint	/v1/payment_intents
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payment_intents

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Body (JSON):

{
    "amount": "100.00",
    "currency": "USD",
    "customer": "cus_7p51tXM7GBi7sz5J",
    "description": "Payment for Order #123",
    "metadata": {
        "order_id": "order_123",
        "customer_name": "John Doe"
    },
    "merchant_order_id": "order_1234",
    "payment_method_type": "crypto"
}

Request Parameter Description:

Parameter	Type	Description
amount	string	Transaction amount (in the specified currency)
currency	string	Currency code (e.g., USD, EUR)
customer	string	Customer ID (optional)
description	string	Description of the payment (optional)
metadata	object	Additional metadata for the payment intent (optional)
merchant_order_id	string	Merchant's order ID (optional)
payment_method_type	string	Payment method type (e.g., crypto)

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payment_intents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "amount": "100.00",
    "currency": "USD",
    "customer": "cus_7p51tXM7GBi7sz5J",
    "description": "Payment for Order #123",
    "metadata": {
        "order_id": "order_123",
        "customer_name": "John Doe"
    },
    "merchant_order_id": "order_1234",
    "payment_method_type": "crypto"
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "pi_NKYVrCoNF340AnUAam7tghbz",
        "object": "payment_intent",
        "amount": {
            "asset_id": "USD",
            "amount": "100"
        },
        "payment_details": {
            "amount_captured": {
                "asset_id": "USD",
                "amount": "0"
            },
            "amount_refunded": {
                "asset_id": "USD",
                "amount": "0"
            },
            "tx_fee": {
                "asset_id": "USD",
                "amount": "0"
            },
            "tax_fee": {
                "asset_id": "USD",
                "amount": "0"
            },
            "frozen_amount": {
                "asset_id": "USD",
                "amount": "0"
            },
            "net_amount": {
                "asset_id": "USD",
                "amount": "0"
            },
            "gas_fee": {},
            "network_fee": {
                "asset_id": "USD",
                "amount": "0"
            }
        },
        "canceled_at": 0,
        "cancellation_reason": "",
        "client_secret": "pi_NKYVrCoNF340AnUAam7tghbz_secret_SvEYW0QGbP60JWp1IJRxwSPkv",
        "created": 1748440360,
        "updated": 1748440360,
        "currency": "USD",
        "customer": {
            "id": "cus_7p51tXM7GBi7sz5J",
            "object": "customer",
            "total_expense": 490,
            "total_payment": 580,
            "total_refund": 90,
            "currency": "USD",
            "created": 1737964162,
            "name": "John Doe",
            "email": "john@example.com",
            "description": "VIP customer",
            "metadata": {
                "source": "web",
                "user_id": "123"
            },
            "phone": "+1234567890"
        },
        "description": "Payment for order #123",
        "livemode": false,
        "metadata": {
            "customer_name": "John Doe",
            "order_id": "order_123"
        },
        "payment_link_details": null,
        "merchant_order_id": "order_123",
        "payment_method_type": "",
        "charges": [],
        "receipt_email": "",
        "status": "RequiresPaymentMethod",
        "payment_intent_status": "Created",
        "complete_on_first_payment": false,
        "permanent_deposit": false,
        "permanent_deposit_asset_id": "",
        "expired_at": 0
    }
}

Response Parameter Description:

PaymentIntent Structure Description

Parameter	Type	Description
id	string	Unique identifier for the payment intent
object	string	Object type, fixed value: payment_intent
amount	AssetAmount	Payment amount details
payment_details	PaymentDetails	Payment details (including fees, taxes, net amount, etc.)
canceled_at	int64	Cancellation timestamp (0 if not canceled)
cancellation_reason	string	Cancellation reason
client_secret	string	Client secret
created	int64	Creation timestamp
updated	int64	Update timestamp
currency	string	Currency code (e.g., USD)
customer	Customer	Customer information
description	string	Payment intent description
livemode	bool	Whether it's in production mode (true: production, false: test)
metadata	map[string]interface	Additional metadata
payment_link_details	PaymentLinkDetails	Payment link details
merchant_order_id	string	Merchant order ID
payment_method_type	PaymentMethodType	Payment method type (crypto, visa, mastercard, etc.)
charges	Charge[]	List of charge details related to the payment intent
receipt_email	string	Receipt email
status	string	Status description
payment_intent_status	PaymentIntentStatus	Current status enum value for the payment intent
complete_on_first_payment	bool	Complete payment immediately when first transaction arrives, regardless of amount
permanent_deposit	bool	Indicates if this payment is a permanent deposit
permanent_deposit_asset_id	string	Asset ID for the permanent deposit
expired_at	uint64	Expiration timestamp for the payment intent
unfreeze_withdraws	[]UnfreezeWithdraw	Array of unfreeze withdrawal records for previously frozen funds
invoice	string	Invoice ID if this payment intent is associated with an invoice
invoice_details	Invoice	Expanded invoice details (when using expand parameter)
subscription	string	Subscription ID resolved through the associated invoice
subscription_details	Subscription	Expanded subscription details (when using expand parameter)

Important Nested Structure Descriptions:

AssetAmount (Amount Details Structure)

Parameter	Type	Description
asset_id	string	Asset ID (e.g., "USD", "USDC-Ethereum-TEST")
amount	string	Amount value

PaymentDetails (Payment Details Structure)

Parameter	Type	Description
amount_captured	AssetAmount	Actual captured amount
amount_refunded	AssetAmount	Refunded amount
tx_fee	AssetAmount	Transaction fee
tax_fee	AssetAmount	Tax fee
frozen_amount	AssetAmount	Frozen amount
net_amount	AssetAmount	Net amount
gas_fee	map[string]AssetAmount	Miner fee details (for each token)
network_fee	AssetAmount	Network fee

Charge (Charge Details Structure)

Parameter	Type	Description
id	string	Charge ID
amount	AssetAmount	Charge amount details
transactions	TransactionDetails[]	List of blockchain transaction details
refunded	bool	Whether refunded
refunds	Refund[]	List of refund details
created	int64	Creation timestamp
payer_max_payload	PayerMaxPayload	PayerMax payment provider specific data
stripe_payload	StripePayload	Stripe payment provider specific data
payment_provider	string	Payment provider identifier (stripe, payer_max, or empty for crypto)
payment_method_type	PaymentMethodType	Payment method type
payment_method_options	PaymentMethodOptions	Payment method specific options

TransactionDetails (Blockchain Transaction Details)

Parameter	Type	Description
tx_id	string	Transaction ID
source_address	string	Source address
destination_address	string	Destination address
tx_hash	string	Transaction hash
amount	string	Transaction amount
token	string	Token name (e.g., BTC, ETH, USDT)
network	string	Network type (e.g., ERC20, TRC20)
created_at	int64	Transaction creation timestamp
status	string	Transaction status

Refund (Refund Details)

Parameter	Type	Description
id	string	Refund ID
amount	AssetAmount	Refund amount details
transactions	TransactionDetails[]	List of blockchain transactions for the refund
status	string	Refund status

12. List Payment Intents in Bulk

For detailed API reference, see: List Payment Intents API

Field	Value
API Name	Payment Intent List
API Endpoint	/v1/payment_intents
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/payment_intents

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters (Query String):

page=0&page_size=10&customer=cus_123456&customer_email=user@example.com&merchant_order_id=order_123

Request Parameter Description:

Parameter	Type	Required	Description	Example
page	int32	Yes	Page number, starting from 0	0
page_size	int32	Yes	Number of items per page, at least 1	10
customer	string	No	Filter by customer ID. If provided, customer_email is ignored	cus_123456
customer_email	string	No	Filter by customer email	user@example.com
merchant_order_id	string	No	Filter by merchant order ID	order_123

Example:

curl --location --request GET 'https://api.martianpay.com/v1/payment_intents?page=0&page_size=10&customer=cus_123456&customer_email=user@example.com' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "payment_intents": [ ... ],
    "total": 1,
    "page": 0,
    "page_size": 20
  }
}

Response Parameter Description:

Top-level structure (PaymentIntentListResp)

Parameter	Type	Description
payment_intents	PaymentIntent[]	List of payment intents
total	int64	Total number of records matching the criteria
page	int32	Current page number (starting from 0)
page_size	int32	Number of records per page

PaymentIntent Structure Description

Parameter	Type	Description
id	string	Unique identifier for the payment intent
object	string	Object type, fixed value: "payment_intent"
amount	AssetAmount	Payment amount details
payment_details	PaymentDetails	Payment details (including fees, taxes, net amount, etc.)
canceled_at	int64	Cancellation timestamp (0 if not canceled)
cancellation_reason	string	Cancellation reason
client_secret	string	Client secret
created	int64	Creation timestamp
updated	int64	Update timestamp
currency	string	Currency code (e.g., USD)
customer	Customer	Customer information
description	string	Payment intent description
livemode	bool	Whether it's in production mode (true: production, false: test)
metadata	map[string]interface	Additional metadata
payment_link_details	PaymentLinkDetails	Payment link details
merchant_order_id	string	Merchant order ID
payment_method_type	PaymentMethodType	Payment method type (crypto, visa, mastercard, etc.)
charges	Charge[]	List of charge details related to the payment intent
receipt_email	string	Receipt email
status	string	Status description
payment_intent_status	PaymentIntentStatus	Current status enum value for the payment intent
complete_on_first_payment	bool	Complete payment immediately when first transaction arrives, regardless of amount
permanent_deposit	bool	Indicates if this payment is a permanent deposit
permanent_deposit_asset_id	string	Asset ID for the permanent deposit
expired_at	uint64	Expiration timestamp for the payment intent
unfreeze_withdraws	[]UnfreezeWithdraw	Array of unfreeze withdrawal records for previously frozen funds
invoice	string	Invoice ID if this payment intent is associated with an invoice
invoice_details	Invoice	Expanded invoice details (when using expand parameter)
subscription	string	Subscription ID resolved through the associated invoice
subscription_details	Subscription	Expanded subscription details (when using expand parameter)

Important Nested Structure Descriptions:

AssetAmount (Amount Details Structure)

Parameter	Type	Description
asset_id	string	Asset ID (e.g., "USD", "USDC-Ethereum-TEST")
amount	string	Amount value

PaymentDetails (Payment Details Structure)

Parameter	Type	Description
amount_captured	AssetAmount	Actual captured amount
amount_refunded	AssetAmount	Refunded amount
tx_fee	AssetAmount	Transaction fee
tax_fee	AssetAmount	Tax fee
frozen_amount	AssetAmount	Frozen amount
net_amount	AssetAmount	Net amount
gas_fee	map[string]AssetAmount	Miner fee details (for each token)
network_fee	AssetAmount	Network fee

Charge (Charge Details Structure)

Parameter	Type	Description
id	string	Charge ID
amount	AssetAmount	Charge amount details
transactions	TransactionDetails[]	List of blockchain transaction details
refunded	bool	Whether refunded
refunds	Refund[]	List of refund details
created	int64	Creation timestamp
payer_max_payload	PayerMaxPayload	PayerMax payment provider specific data
stripe_payload	StripePayload	Stripe payment provider specific data
payment_provider	string	Payment provider identifier (stripe, payer_max, or empty for crypto)
payment_method_type	PaymentMethodType	Payment method type
payment_method_options	PaymentMethodOptions	Payment method specific options

TransactionDetails (Blockchain Transaction Details)

Parameter	Type	Description
tx_id	string	Transaction ID
source_address	string	Source address
destination_address	string	Destination address
tx_hash	string	Transaction hash
amount	string	Transaction amount
token	string	Token name (e.g., BTC, ETH, USDT)
network	string	Network type (e.g., ERC20, TRC20)
created_at	int64	Transaction creation timestamp
status	string	Transaction status

Refund (Refund Details)

Parameter	Type	Description
id	string	Refund ID
amount	AssetAmount	Refund amount details
transactions	TransactionDetails[]	List of blockchain transactions for the refund
status	string	Refund status

13. Retrieve a Single Payment Intent

For detailed API reference, see: Get Payment Intent API

Field	Value
API Name	Get Single Payment Intent
API Endpoint	/v1/payment_intents/{id}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/payment_intents/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Example Request (with Payment Intent ID pi_0WE7asHes1AjF5rnIybjlcgL):

curl --location --request GET 'https://api.martianpay.com/v1/payment_intents/pi_0WE7asHes1AjF5rnIybjlcgL' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "pi_0WE7asHes1AjF5rnIybjlcgL",
    "object": "payment_intent",
    "amount": {
      "asset_id": "USD",
      "amount": "10"
    },
    "currency": "USD",
    "status": "Completed",
    "client_secret": "pi_0WE7asHes1AjF5rnIybjlcgL_secret_abc123",
    "created": 1735689600,
    "customer": "cus_abc123",
    "description": "Payment for order #123",
    "metadata": {
      "order_id": "order_123"
    }
  }
}

14. Update Payment Intent

For detailed API reference, see: Update Payment Intent API

Field	Value
API Name	Update Payment Intent
API Endpoint	/v1/payment_intents/{id}
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payment_intents/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Body (JSON):

{
    "payment_method_type": "crypto",
    "payment_method_options": {
        "crypto": {
            "asset_id": "USDC-Ethereum-TEST"
        }
    }
}

Note: Replace \{id\} in the URL with the actual Payment Intent ID.

Request Parameter Description:

Parameter	Type	Description
payment_method_type	string	Payment method type (e.g., crypto)
payment_method_options	object	Options specific to the payment method
- crypto	object	Options for crypto payments
-- asset_id	string	ID of the asset to be used for payment (e.g., USDC-Ethereum-TEST)

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payment_intents/pi_Mv1w0RwHEnloacfnivvsktAG' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "payment_method_type": "crypto",
    "payment_method_options": {
        "crypto": {
            "asset_id": "USDC-Ethereum-TEST"
        }
    }
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "payment_intents": [
            {
                "id": "pi_Mv1w0RwHEnloacfnivvsktAG",
                "object": "payment_intent",
                "amount": 100,
                "amount_received": 0,
                "canceled_at": -62135596800,
                "cancellation_reason": "",
                "client_secret": "pi_Mv1w0RwHEnloacfnivvsktAG_secret_5FB3MwZd3ki3U7fsfjw9SWwGh",
                "created": 1739088184,
                "currency": "USD",
                "customer": "cus_7p51tXM7GBi7sz5J",
                "description": "Payment for order #123",
                "transactions": [],
                "livemode": false,
                "metadata": {
                    "customer_name": "John Doe",
                    "order_id": "order_123"
                },
                "payment_method_type": "crypto",
                "payment_method_options": {
                    "crypto": {
                        "amount": "1000000",
                        "token": "USDC",
                        "network": "Ethereum Sepolia",
                        "decimals": 6,
                        "exchange_rate": 1,
                        "deposit_address": "0xA0677D28c18BaB87cDcD0cBa29DB8232E1cec854",
                        "expired_at": 1739090058
                    }
                },
                "charges": [
                    {
                        "id": "ch_rmwSC1uJ0NJsezyj9VsNcJla",
                        "object": "charge",
                        "amount": 100,
                        "amount_captured": 0,
                        "amount_refunded": 0,
                        "calculated_statement_descriptor": "",
                        "captured": false,
                        "created": 0,
                        "currency": "USD",
                        "customer": "",
                        "description": "",
                        "disputed": false,
                        "failure_code": "",
                        "failure_message": "",
                        "fraud_details": null,
                        "livemode": false,
                        "metadata": null,
                        "transactions": null,
                        "paid": false,
                        "payment_intent": "pi_Mv1w0RwHEnloacfnivvsktAG",
                        "payment_method_type": "crypto",
                        "payment_method_options": {
                            "crypto": {
                                "amount": "1000000",
                                "token": "USDC",
                                "network": "Ethereum Sepolia",
                                "decimals": 6,
                                "exchange_rate": 1,
                                "deposit_address": "0xA0677D28c18BaB87cDcD0cBa29DB8232E1cec854",
                                "expired_at": 1739090058
                            }
                        },
                        "receipt_email": "",
                        "receipt_url": "",
                        "refunded": false,
                        "refunds": null,
                        "review": null,
                        "status": ""
                    }
                ],
                "receipt_email": "",
                "status": "Processing"
            }
        ],
        "total": 1,
        "page": 0,
        "page_size": 10
    }
}

Response Parameter Description:

PaymentIntent Structure Description

Parameter	Type	Description
id	string	Unique identifier for the payment intent
object	string	Object type, fixed value: "payment_intent"
amount	AssetAmount	Payment amount details
payment_details	PaymentDetails	Payment details (including fees, taxes, net amount, etc.)
canceled_at	int64	Cancellation timestamp (0 if not canceled)
cancellation_reason	string	Cancellation reason
client_secret	string	Client secret
created	int64	Creation timestamp
updated	int64	Update timestamp
currency	string	Currency code (e.g., USD)
customer	Customer	Customer information
description	string	Payment intent description
livemode	bool	Whether it's in production mode (true: production, false: test)
metadata	map[string]interface	Additional metadata
payment_link_details	PaymentLinkDetails	Payment link details
merchant_order_id	string	Merchant order ID
payment_method_type	PaymentMethodType	Payment method type (crypto, visa, mastercard, etc.)
charges	Charge[]	List of charge details related to the payment intent
receipt_email	string	Receipt email
status	string	Status description
payment_intent_status	PaymentIntentStatus	Current status enum value for the payment intent
complete_on_first_payment	bool	Complete payment immediately when first transaction arrives, regardless of amount
permanent_deposit	bool	Indicates if this payment is a permanent deposit
permanent_deposit_asset_id	string	Asset ID for the permanent deposit
expired_at	uint64	Expiration timestamp for the payment intent
unfreeze_withdraws	[]UnfreezeWithdraw	Array of unfreeze withdrawal records for previously frozen funds
invoice	string	Invoice ID if this payment intent is associated with an invoice
invoice_details	Invoice	Expanded invoice details (when using expand parameter)
subscription	string	Subscription ID resolved through the associated invoice
subscription_details	Subscription	Expanded subscription details (when using expand parameter)

Important Nested Structure Descriptions:

AssetAmount (Amount Details Structure)

Parameter	Type	Description
asset_id	string	Asset ID (e.g., "USD", "USDC-Ethereum-TEST")
amount	string	Amount value

PaymentDetails (Payment Details Structure)

Parameter	Type	Description
amount_captured	AssetAmount	Actual captured amount
amount_refunded	AssetAmount	Refunded amount
tx_fee	AssetAmount	Transaction fee
tax_fee	AssetAmount	Tax fee
frozen_amount	AssetAmount	Frozen amount
net_amount	AssetAmount	Net amount
gas_fee	map[string]AssetAmount	Miner fee details (for each token)
network_fee	AssetAmount	Network fee

Charge (Charge Details Structure)

Parameter	Type	Description
id	string	Charge ID
amount	AssetAmount	Charge amount details
transactions	TransactionDetails[]	List of blockchain transaction details
refunded	bool	Whether refunded
refunds	Refund[]	List of refund details
created	int64	Creation timestamp
payer_max_payload	PayerMaxPayload	PayerMax payment provider specific data
stripe_payload	StripePayload	Stripe payment provider specific data
payment_provider	string	Payment provider identifier (stripe, payer_max, or empty for crypto)
payment_method_type	PaymentMethodType	Payment method type
payment_method_options	PaymentMethodOptions	Payment method specific options

TransactionDetails (Blockchain Transaction Details)

Parameter	Type	Description
tx_id	string	Transaction ID
source_address	string	Source address
destination_address	string	Destination address
tx_hash	string	Transaction hash
amount	string	Transaction amount
token	string	Token name (e.g., BTC, ETH, USDT)
network	string	Network type (e.g., ERC20, TRC20)
created_at	int64	Transaction creation timestamp
status	string	Transaction status

Refund (Refund Details)

Parameter	Type	Description
id	string	Refund ID
amount	AssetAmount	Refund amount details
transactions	TransactionDetails[]	List of blockchain transactions for the refund
status	string	Refund status

15. Cancel Payment Intent

For detailed API reference, see: Cancel Payment Intent API

Field	Value
API Name	Cancel Payment Intent
API Endpoint	/v1/payment_intents/{id}/cancel
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payment_intents/{id}/cancel

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Payment intent ID to cancel

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payment_intents/example_id/cancel' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

16. Get Payment Intent Link

For detailed API reference, see: Get Payment Intent Link API

Field	Value
API Name	Get Payment Intent Link
API Endpoint	/v1/payment_intents/link/{id}
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payment_intents/link/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Payment intent ID
request	string	Yes	Payment intent retrieval parameters

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payment_intents/link/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

17. Update Payment Intent Link

For detailed API reference, see: Update Payment Intent Link API

Field	Value
API Name	Update Payment Intent Link
API Endpoint	/v1/payment_intents/link/{id}/update
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payment_intents/link/{id}/update

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Payment intent ID
request	string	Yes	Payment method details with client secret or API key

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payment_intents/link/example_id/update' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

18. List Customer Payment Methods

For detailed API reference, see: List Customer Payment Methods API

Field	Value
API Name	List Customer Payment Methods
API Endpoint	/v1/customers/payment_methods
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/customers/payment_methods

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
customer_id	string	Yes	Customer ID to list payment methods for

Example:

curl --location --request GET 'https://api.martianpay.com/v1/customers/payment_methods?customer_id=cus_abc123' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "payment_methods": [
      {
        "id": "pm_1234567890",
        "provider": "stripe",
        "type": "card",
        "last4": "4242",
        "brand": "visa",
        "exp_month": 12,
        "exp_year": 2025,
        "funding": "credit",
        "country": "US",
        "fingerprint": "abc123def456"
      },
      {
        "id": "pm_0987654321",
        "provider": "stripe",
        "type": "card",
        "last4": "1234",
        "brand": "mastercard",
        "exp_month": 6,
        "exp_year": 2026,
        "funding": "debit",
        "country": "CA",
        "fingerprint": "xyz789uvw012"
      }
    ]
  }
}

Response Parameters:

Parameter	Type	Description
payment_methods	array	List of saved payment methods for the customer
payment_methods[].id	string	Payment method ID (e.g., pm_1234567890)
payment_methods[].provider	string	Payment provider (stripe, paypal, etc.)
payment_methods[].type	string	Payment method type (card, wallet, bank_account, etc.)
payment_methods[].last4	string	Last 4 digits of the card number
payment_methods[].brand	string	Card brand (visa, mastercard, amex, etc.)
payment_methods[].exp_month	integer	Expiration month
payment_methods[].exp_year	integer	Expiration year
payment_methods[].funding	string	Card funding type (credit, debit, etc.)
payment_methods[].country	string	Card issuing country (ISO 2-letter code)
payment_methods[].fingerprint	string	Card fingerprint for deduplication

Payment Link APIs

19. Create Payment Link

For detailed API reference, see: Create Payment Link API

Field	Value
API Name	Create Payment Link
API Endpoint	/v1/payment_links
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payment_links

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Body (JSON):

{
    "product_id": "prod_abc123",
    "default_variant_id": "var_xyz789",
    "primary_variant_ids": ["var_xyz789", "var_def456"],
    "addon_variants": [
        {
            "variant_id": "var_addon123",
            "min_quantity": 0,
            "max_quantity": 5
        }
    ],
    "variant_config": {
        "default_selection": "var_xyz789"
    }
}

Request Parameter Description:

Parameter	Type	Required	Description
product_id	string	Yes	Product ID to create payment link for
default_variant_id	string	Yes	Default variant ID to display
primary_variant_ids	array	Yes	Array of primary variant IDs selectable by buyer
addon_variants	array	No	Optional add-on variants with quantity constraints
variant_config	object	No	UI and default selection metadata

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payment_links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "product_id": "prod_abc123",
    "default_variant_id": "var_xyz789",
    "primary_variant_ids": ["var_xyz789", "var_def456"],
    "addon_variants": [
        {
            "variant_id": "var_addon123",
            "min_quantity": 0,
            "max_quantity": 5
        }
    ]
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "pl_abc123xyz",
        "active": true,
        "url": "https://pay.martianpay.com/pl_abc123xyz",
        "product": {
            "id": "prod_abc123",
            "name": "Sample Product",
            "description": "Product description"
        },
        "primary_variants": [
            {
                "variant_id": "var_xyz789",
                "is_primary": true,
                "quantity": 1,
                "variant": {
                    "id": "var_xyz789",
                    "price": {
                        "amount": "29.99",
                        "currency": "USD"
                    }
                }
            }
        ],
        "addon_variants": [
            {
                "variant_id": "var_addon123",
                "min_quantity": 0,
                "max_quantity": 5,
                "variant": {
                    "id": "var_addon123",
                    "price": {
                        "amount": "5.00",
                        "currency": "USD"
                    }
                }
            }
        ],
        "created_at": 1739088184,
        "updated_at": 1739088184
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the payment link
active	boolean	Indicates if the payment link is currently active
url	string	URL to access the payment link
product	object	Product associated with the payment link
primary_variants	array	Primary variants selectable by the buyer
addon_variants	array	Optional add-on variants
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

20. List Payment Links

For detailed API reference, see: List Payment Links API

Field	Value
API Name	List Payment Links
API Endpoint	/v1/payment_links
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/payment_links

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters (Query String):

page=0&page_size=10&active=true&product=prod_abc123

Request Parameter Description:

Parameter	Type	Required	Description	Example
page	integer	No	Page number, starting from 0	0
page_size	integer	Yes	Number of items per page	10
active	boolean	No	Filter by active status	true
product	string	No	Filter by product ID	prod_abc123

Example:

curl --location --request GET 'https://api.martianpay.com/v1/payment_links?page=0&page_size=10&active=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "payment_links": [
            {
                "id": "pl_abc123xyz",
                "active": true,
                "url": "https://pay.martianpay.com/pl_abc123xyz",
                "product": {
                    "id": "prod_abc123",
                    "name": "Sample Product"
                },
                "primary_variants": [],
                "addon_variants": [],
                "created_at": 1739088184,
                "updated_at": 1739088184
            }
        ],
        "total": 1,
        "page": 0,
        "page_size": 10
    }
}

Response Parameter Description:

Parameter	Type	Description
payment_links	array	List of payment link objects
total	integer	Total number of records
page	integer	Current page number (starting from 0)
page_size	integer	Number of records per page

21. Get Payment Link

For detailed API reference, see: Get Payment Link API

Field	Value
API Name	Get Payment Link
API Endpoint	/v1/payment_links/{id}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)

Request URL: GET https://api.martianpay.com/v1/payment_links/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Unique payment link ID	pl_abc123xyz

Example:

curl --location --request GET 'https://api.martianpay.com/v1/payment_links/pl_abc123xyz' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "pl_abc123xyz",
        "active": true,
        "url": "https://pay.martianpay.com/pl_abc123xyz",
        "product": {
            "id": "prod_abc123",
            "name": "Sample Product",
            "description": "Product description",
            "active": true
        },
        "primary_variants": [
            {
                "variant_id": "var_xyz789",
                "is_primary": true,
                "quantity": 1
            }
        ],
        "addon_variants": [],
        "price_range": {
            "min": "29.99",
            "max": "99.99",
            "currency": "USD"
        },
        "created_at": 1739088184,
        "updated_at": 1739088184
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the payment link
active	boolean	Indicates if the payment link is currently active
url	string	URL to access the payment link
product	object	Product associated with the payment link
primary_variants	array	Primary variants selectable by the buyer
addon_variants	array	Optional add-on variants
price_range	object	Price range across primary variants
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

22. Update Payment Link

For detailed API reference, see: Update Payment Link API

Field	Value
API Name	Update Payment Link
API Endpoint	/v1/payment_links/{id}
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payment_links/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Request Body (JSON):

{
    "active": false
}

Note: Payment link variant configuration cannot be modified after creation. Only the active status can be updated.

Request Parameter Description:

Parameter	Type	Required	Description
active	boolean	Yes	Set payment link active (true) or inactive (false)

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payment_links/pl_abc123xyz' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "active": false
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "pl_abc123xyz",
        "active": false,
        "url": "https://pay.martianpay.com/pl_abc123xyz",
        "product": {
            "id": "prod_abc123",
            "name": "Sample Product"
        },
        "updated_at": 1739090000
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the payment link
active	boolean	Updated active status
updated_at	integer	Last update timestamp in Unix format

23. Delete Payment Link

For detailed API reference, see: Delete Payment Link API

Field	Value
API Name	Delete Payment Link
API Endpoint	/v1/payment_links/{id}
HTTP Method	DELETE
Authentication	Basic Auth (Username is API Key, Password is empty)

Request URL: DELETE https://api.martianpay.com/v1/payment_links/{id}

Request Header Example:

Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Unique payment link ID	pl_abc123xyz

Note: Only inactive payment links can be deleted. This operation cannot be undone.

Example:

curl --location --request DELETE 'https://api.martianpay.com/v1/payment_links/pl_abc123xyz' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "Payment link deleted successfully"
}

Response Parameter Description:

Parameter	Type	Description
code	int	Response code (0 for success)
error_code	string	Error code identifier
msg	string	Response message

Product APIs

24. Create Product

For detailed API reference, see: Create Product API

Field	Value
API Name	Create Product
API Endpoint	/v1/products
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/products

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Body (JSON):

{
    "name": "Premium T-Shirt",
    "description": "High-quality cotton t-shirt",
    "active": true,
    "default_currency": "USD",
    "fixed_price": {
        "amount": "29.99",
        "currency": "USD"
    },
    "options": [
        {
            "name": "Size",
            "values": [
                {"value": "Small"},
                {"value": "Medium"},
                {"value": "Large"}
            ]
        },
        {
            "name": "Color",
            "values": [
                {"value": "Red"},
                {"value": "Blue"},
                {"value": "Green"}
            ]
        }
    ],
    "variants": [
        {
            "option_values": {
                "Size": "Medium",
                "Color": "Blue"
            },
            "price": {
                "amount": "29.99",
                "currency": "USD"
            },
            "active": true,
            "inventory_quantity": 100
        }
    ],
    "metadata": {
        "category": "apparel",
        "sku": "TSHIRT-001"
    }
}

Request Parameter Description:

Parameter	Type	Required	Description
name	string	Yes	Name of the product
description	string	No	Detailed description of the product
active	boolean	No	Product availability (default: true)
default_currency	string	Yes	Base currency for the product/variants
fixed_price	object	No	Explicit price for simple products
options	array	No	Variant option definitions (e.g., Size, Color)
variants	array	No	Variant combinations with pricing
metadata	object	No	Additional custom data for the product
collect_shipping_address	boolean	No	Collect shipping address during checkout
collect_tax_address	boolean	No	Collect billing/tax address during checkout

Example:

curl --location --request POST 'https://api.martianpay.com/v1/products' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "name": "Premium T-Shirt",
    "description": "High-quality cotton t-shirt",
    "active": true,
    "default_currency": "USD",
    "fixed_price": {
        "amount": "29.99",
        "currency": "USD"
    },
    "metadata": {
        "category": "apparel"
    }
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "prod_abc123",
        "name": "Premium T-Shirt",
        "description": "High-quality cotton t-shirt",
        "active": true,
        "default_currency": "USD",
        "fixed_price": {
            "amount": "29.99",
            "currency": "USD"
        },
        "options": [],
        "variants": [],
        "metadata": {
            "category": "apparel"
        },
        "version": 1,
        "created_at": 1739088184,
        "updated_at": 1739088184
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the product
name	string	Name of the product
description	string	Detailed description of the product
active	boolean	Indicates if the product is currently available
default_currency	string	Base currency for the product/variants
fixed_price	object	Explicit price for simple products
options	array	Variant option definitions
variants	array	Variant combinations
metadata	object	Additional custom data for the product
version	integer	Catalog version associated with this product
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

25. List Products

For detailed API reference, see: List Products API

Field	Value
API Name	List Products
API Endpoint	/v1/products
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/products

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters (Query String):

page=0&page_size=10&active=true

Request Parameter Description:

Parameter	Type	Required	Description	Example
page	integer	No	Page number, starting from 0 (default: 0)	0
page_size	integer	No	Number of items per page (1-50, default: 10)	10
active	boolean	No	Filter by active status	true

Example:

curl --location --request GET 'https://api.martianpay.com/v1/products?page=0&page_size=10&active=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "products": [
            {
                "id": "prod_abc123",
                "name": "Premium T-Shirt",
                "description": "High-quality cotton t-shirt",
                "active": true,
                "default_currency": "USD",
                "fixed_price": {
                    "amount": "29.99",
                    "currency": "USD"
                },
                "options": [],
                "variants": [],
                "metadata": {
                    "category": "apparel"
                },
                "version": 1,
                "created_at": 1739088184,
                "updated_at": 1739088184
            }
        ],
        "total": 1,
        "page": 0,
        "page_size": 10
    }
}

Response Parameter Description:

Parameter	Type	Description
products	array	List of product objects
total	integer	Total number of records
page	integer	Current page number (starting from 0)
page_size	integer	Number of records per page

26. Get Product

For detailed API reference, see: Get Product API

Field	Value
API Name	Get Product
API Endpoint	/v1/products/{id}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)

Request URL: GET https://api.martianpay.com/v1/products/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Unique product ID	prod_abc123

Query Parameter:

Parameter	Type	Required	Description	Example
version	integer	No	Optional version number for historical data	1

Example:

curl --location --request GET 'https://api.martianpay.com/v1/products/prod_abc123' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "prod_abc123",
        "name": "Premium T-Shirt",
        "description": "High-quality cotton t-shirt",
        "active": true,
        "default_currency": "USD",
        "fixed_price": {
            "amount": "29.99",
            "currency": "USD"
        },
        "options": [
            {
                "name": "Size",
                "values": [
                    {"value": "Small"},
                    {"value": "Medium"},
                    {"value": "Large"}
                ]
            }
        ],
        "variants": [
            {
                "id": "var_xyz789",
                "option_values": {
                    "Size": "Medium"
                },
                "price": {
                    "amount": "29.99",
                    "currency": "USD"
                },
                "active": true,
                "inventory_quantity": 100
            }
        ],
        "metadata": {
            "category": "apparel"
        },
        "version": 1,
        "created_at": 1739088184,
        "updated_at": 1739088184
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the product
name	string	Name of the product
description	string	Detailed description of the product
active	boolean	Indicates if the product is currently available
default_currency	string	Base currency for the product/variants
fixed_price	object	Explicit price for simple products
options	array	Variant option definitions
variants	array	Variant combinations with full details
metadata	object	Additional custom data for the product
version	integer	Catalog version associated with this product
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

27. Update Product

For detailed API reference, see: Update Product API

Field	Value
API Name	Update Product
API Endpoint	/v1/products/{id}
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/products/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Request Body (JSON):

{
    "name": "Premium T-Shirt Updated",
    "description": "Updated description",
    "active": true,
    "fixed_price": {
        "amount": "34.99",
        "currency": "USD"
    },
    "version": 1
}

Note: Replace \{id\} in the URL with the actual Product ID. The version field is required for optimistic locking.

Request Parameter Description:

Parameter	Type	Required	Description
name	string	No	Updated product name
description	string	No	Updated product description
active	boolean	No	Updated product availability
fixed_price	object	No	Updated price for simple products
options	array	No	Updated variant option definitions
variants	array	No	Updated variant combinations
metadata	object	No	Updated custom data
version	integer	Yes	Current version for optimistic locking

Example:

curl --location --request POST 'https://api.martianpay.com/v1/products/prod_abc123' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "name": "Premium T-Shirt Updated",
    "description": "Updated description",
    "active": true,
    "version": 1
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "prod_abc123",
        "name": "Premium T-Shirt Updated",
        "description": "Updated description",
        "active": true,
        "default_currency": "USD",
        "fixed_price": {
            "amount": "34.99",
            "currency": "USD"
        },
        "options": [],
        "variants": [],
        "metadata": {},
        "version": 2,
        "created_at": 1739088184,
        "updated_at": 1739090000
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the product
version	integer	Incremented version number after update
updated_at	integer	Last update timestamp in Unix format

28. Delete Product

For detailed API reference, see: Delete Product API

Field	Value
API Name	Delete Product
API Endpoint	/v1/products/{id}
HTTP Method	DELETE
Authentication	Basic Auth (Username is API Key, Password is empty)

Request URL: DELETE https://api.martianpay.com/v1/products/{id}

Request Header Example:

Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Unique product ID	prod_abc123

Note: Only inactive products that are not used in any payment links can be deleted. This operation cannot be undone.

Example:

curl --location --request DELETE 'https://api.martianpay.com/v1/products/prod_abc123' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "Product deleted successfully"
}

Response Parameter Description:

Parameter	Type	Description
code	int	Response code (0 for success)
error_code	string	Error code identifier
msg	string	Response message

29. Create Selling Plan Group

For detailed API reference, see: Create Selling Plan Group API

Field	Value
API Name	Create Selling Plan Group
API Endpoint	/v1/selling_plan_groups
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/selling_plan_groups

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
request	string	Yes	Selling plan group parameters

Example:

curl --location --request POST 'https://api.martianpay.com/v1/selling_plan_groups' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

30. List Selling Plan Groups

For detailed API reference, see: List Selling Plan Groups API

Field	Value
API Name	List Selling Plan Groups
API Endpoint	/v1/selling_plan_groups
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/selling_plan_groups

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
status	string	No	Filter by status (active, disabled)
offset	integer	No	Pagination offset (default: 0)
limit	integer	No	Pagination limit (default: 50, max: 100)

Example:

curl --location --request GET 'https://api.martianpay.com/v1/selling_plan_groups' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

31. Get Selling Plan Group

For detailed API reference, see: Get Selling Plan Group API

Field	Value
API Name	Get Selling Plan Group
API Endpoint	/v1/selling_plan_groups/{id}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/selling_plan_groups/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Selling plan group ID
include_plans	boolean	No	Include associated selling plans in response

Example:

curl --location --request GET 'https://api.martianpay.com/v1/selling_plan_groups/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

32. Update Selling Plan Group

For detailed API reference, see: Update Selling Plan Group API

Field	Value
API Name	Update Selling Plan Group
API Endpoint	/v1/selling_plan_groups/{id}
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/selling_plan_groups/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Selling plan group ID
request	string	Yes	Updated selling plan group parameters

Example:

curl --location --request POST 'https://api.martianpay.com/v1/selling_plan_groups/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

33. Delete Selling Plan Group

For detailed API reference, see: Delete Selling Plan Group API

Field	Value
API Name	Delete Selling Plan Group
API Endpoint	/v1/selling_plan_groups/{id}
HTTP Method	DELETE
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: DELETE https://api.martianpay.com/v1/selling_plan_groups/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Selling plan group ID

Example:

curl --location --request DELETE 'https://api.martianpay.com/v1/selling_plan_groups/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

34. Create Selling Plan

For detailed API reference, see: Create Selling Plan API

Field	Value
API Name	Create Selling Plan
API Endpoint	/v1/selling_plans
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/selling_plans

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
request	string	Yes	Selling plan parameters including billing policy and optional pricing policy

Example:

curl --location --request POST 'https://api.martianpay.com/v1/selling_plans' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

35. List Selling Plans

For detailed API reference, see: List Selling Plans API

Field	Value
API Name	List Selling Plans
API Endpoint	/v1/selling_plans
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/selling_plans

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
group_id	string	No	Filter by selling plan group ID
status	string	No	Filter by status (active, disabled)
offset	integer	No	Pagination offset (default: 0)
limit	integer	No	Pagination limit (default: 50, max: 100)

Example:

curl --location --request GET 'https://api.martianpay.com/v1/selling_plans' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

36. Get Selling Plan

For detailed API reference, see: Get Selling Plan API

Field	Value
API Name	Get Selling Plan
API Endpoint	/v1/selling_plans/{id}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/selling_plans/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Selling plan ID

Example:

curl --location --request GET 'https://api.martianpay.com/v1/selling_plans/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

37. Update Selling Plan

For detailed API reference, see: Update Selling Plan API

Field	Value
API Name	Update Selling Plan
API Endpoint	/v1/selling_plans/{id}
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/selling_plans/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Selling plan ID
request	string	Yes	Updated selling plan parameters

Example:

curl --location --request POST 'https://api.martianpay.com/v1/selling_plans/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

38. Delete Selling Plan

For detailed API reference, see: Delete Selling Plan API

Field	Value
API Name	Delete Selling Plan
API Endpoint	/v1/selling_plans/{id}
HTTP Method	DELETE
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: DELETE https://api.martianpay.com/v1/selling_plans/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Selling plan ID

Example:

curl --location --request DELETE 'https://api.martianpay.com/v1/selling_plans/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

39. Calculate Selling Plan Price

For detailed API reference, see: Calculate Selling Plan Price API

Field	Value
API Name	Calculate Selling Plan Price
API Endpoint	/v1/selling_plans/calculate_price
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/selling_plans/calculate_price

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
request	string	Yes	Price calculation parameters (either variant_id or base_price+currency)

Example:

curl --location --request POST 'https://api.martianpay.com/v1/selling_plans/calculate_price' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

Subscription APIs

40. List Subscriptions

For detailed API reference, see: List Subscriptions API

Field	Value
API Name	List Subscriptions
API Endpoint	/v1/subscriptions
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/subscriptions

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters (Query String):

offset=0&limit=20&customer_id=cus_123456&status=active&external_id=ext_123

Request Parameter Description:

Parameter	Type	Required	Description	Example
offset	integer	No	Pagination offset (default: 0)	0
limit	integer	No	Pagination limit (default: 20, max: 100)	20
customer_id	string	No	Filter by customer ID	cus_123456
status	string	No	Filter by status (incomplete, active, paused, past_due, canceled)	active
external_id	string	No	Filter by external ID for linking to your system	ext_123

Example:

curl --location --request GET 'https://api.martianpay.com/v1/subscriptions?offset=0&limit=20&status=active' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "data": [
            {
                "id": "sub_abc123",
                "customer_id": "cus_123456",
                "customer_name": "John Doe",
                "customer_email": "john@example.com",
                "product_id": "prod_xyz789",
                "product_name": "Monthly Subscription",
                "variant_id": "var_def456",
                "selling_plan_id": "sp_ghi789",
                "status": "active",
                "current_period_start": 1739088184,
                "current_period_end": 1741766584,
                "next_charge_amount": "29.99",
                "created_at": 1739088184,
                "updated_at": 1739088184
            }
        ],
        "total": 1,
        "offset": 0,
        "limit": 20
    }
}

Response Parameter Description:

Parameter	Type	Description
data	array	List of subscription objects
total	integer	Total number of subscriptions
offset	integer	Current pagination offset
limit	integer	Number of records per page

Subscription Object Parameters:

Parameter	Type	Description
id	string	Unique identifier for the subscription
customer_id	string	Customer ID
customer_name	string	Customer name for display
customer_email	string	Customer email for display
product_id	string	Product ID
product_name	string	Product name for display
variant_id	string	Variant ID
selling_plan_id	string	Selling plan ID
status	string	Subscription status
current_period_start	integer	Unix timestamp for current period start
current_period_end	integer	Unix timestamp for current period end
next_charge_amount	string	Amount for next payment
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

41. Get Subscription

For detailed API reference, see: Get Subscription API

Field	Value
API Name	Get Subscription
API Endpoint	/v1/subscriptions/{id}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)

Request URL: GET https://api.martianpay.com/v1/subscriptions/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Unique subscription ID	sub_abc123

Example:

curl --location --request GET 'https://api.martianpay.com/v1/subscriptions/sub_abc123' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "sub_abc123",
        "customer_id": "cus_123456",
        "customer_name": "John Doe",
        "customer_email": "john@example.com",
        "product_id": "prod_xyz789",
        "product_name": "Monthly Subscription",
        "product_description": "Premium monthly plan",
        "variant_id": "var_def456",
        "variant_title": "Standard Plan",
        "selling_plan_id": "sp_ghi789",
        "selling_plan_name": "Monthly Billing",
        "status": "active",
        "current_period_start": 1739088184,
        "current_period_end": 1741766584,
        "billing_cycle_anchor": 1739088184,
        "next_charge_amount": "29.99",
        "cancel_at_period_end": false,
        "created_at": 1739088184,
        "updated_at": 1739088184
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the subscription
customer_id	string	Customer ID
customer_name	string	Customer name for display
customer_email	string	Customer email for display
product_id	string	Product ID
product_name	string	Product name for display
product_description	string	Product description for display
variant_id	string	Variant ID
variant_title	string	Variant title
selling_plan_id	string	Selling plan ID
selling_plan_name	string	Selling plan name for display
status	string	Subscription status
current_period_start	integer	Unix timestamp for current period start
current_period_end	integer	Unix timestamp for current period end
billing_cycle_anchor	integer	Unix timestamp for billing cycle anchor
next_charge_amount	string	Amount for next payment
cancel_at_period_end	boolean	Whether subscription will be canceled at period end
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

42. Cancel Subscription

For detailed API reference, see: Cancel Subscription API

Field	Value
API Name	Cancel Subscription
API Endpoint	/v1/subscriptions/{id}/cancel
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/subscriptions/{id}/cancel

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Request Body (JSON):

{
    "cancel_at_period_end": true,
    "cancel_reason": "Customer requested cancellation"
}

Request Parameter Description:

Parameter	Type	Required	Description
cancel_at_period_end	boolean	No	true=cancel at period end, false=cancel immediately (default: true)
cancel_reason	string	No	Cancellation reason

Example:

curl --location --request POST 'https://api.martianpay.com/v1/subscriptions/sub_abc123/cancel' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "cancel_at_period_end": true,
    "cancel_reason": "Customer requested cancellation"
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "sub_abc123",
        "status": "active",
        "cancel_at_period_end": true,
        "cancel_reason": "Customer requested cancellation",
        "canceled_at": 1739090000,
        "current_period_end": 1741766584,
        "updated_at": 1739090000
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the subscription
status	string	Subscription status
cancel_at_period_end	boolean	Whether subscription will be canceled at period end
cancel_reason	string	Cancellation reason
canceled_at	integer	Cancellation timestamp in Unix format
current_period_end	integer	Unix timestamp for current period end
updated_at	integer	Last update timestamp in Unix format

43. Pause Subscription

For detailed API reference, see: Pause Subscription API

Field	Value
API Name	Pause Subscription
API Endpoint	/v1/subscriptions/{id}/pause
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/subscriptions/{id}/pause

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Request Body (JSON):

{
    "behavior": "void",
    "resumes_at": 1744274184
}

Request Parameter Description:

Parameter	Type	Required	Description
behavior	string	Yes	"void" or "keep_as_draft" (default: "void")
resumes_at	integer	No	Unix timestamp for automatic resumption

Example:

curl --location --request POST 'https://api.martianpay.com/v1/subscriptions/sub_abc123/pause' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "behavior": "void",
    "resumes_at": 1744274184
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "sub_abc123",
        "status": "paused",
        "pause_collection_behavior": "void",
        "paused_at": 1739090000,
        "resumes_at": 1744274184,
        "updated_at": 1739090000
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the subscription
status	string	Subscription status (should be "paused")
pause_collection_behavior	string	Pause behavior setting
paused_at	integer	Pause timestamp in Unix format
resumes_at	integer	Unix timestamp for automatic resumption
updated_at	integer	Last update timestamp in Unix format

44. Resume Subscription

For detailed API reference, see: Resume Subscription API

Field	Value
API Name	Resume Subscription
API Endpoint	/v1/subscriptions/{id}/resume
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)

Request URL: POST https://api.martianpay.com/v1/subscriptions/{id}/resume

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Example:

curl --location --request POST 'https://api.martianpay.com/v1/subscriptions/sub_abc123/resume' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "sub_abc123",
        "status": "active",
        "pause_collection_behavior": "",
        "paused_at": 0,
        "resumes_at": 0,
        "updated_at": 1739092000
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the subscription
status	string	Subscription status (should be "active")
pause_collection_behavior	string	Cleared pause behavior setting
paused_at	integer	Cleared pause timestamp
resumes_at	integer	Cleared resume timestamp
updated_at	integer	Last update timestamp in Unix format

45. Revoke Subscription Cancellation

For detailed API reference, see: Revoke Subscription Cancellation API

Field	Value
API Name	Revoke Subscription Cancellation
API Endpoint	/v1/subscriptions/{id}/revoke-cancel
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)

Request URL: POST https://api.martianpay.com/v1/subscriptions/{id}/revoke-cancel

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Understanding

This API revokes a scheduled cancellation for a subscription that has cancel_at_period_end=true. When a subscription is set to cancel at the end of the billing period, calling this endpoint will keep the subscription active and continue billing normally.

Use Case: A customer changes their mind after requesting cancellation and wants to continue their subscription.

Example:

curl --location --request POST 'https://api.martianpay.com/v1/subscriptions/sub_abc123/revoke-cancel' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "sub_abc123",
        "status": "active",
        "cancel_at_period_end": false,
        "canceled_at": 0,
        "cancel_reason": "",
        "customer_id": "cus_xyz789",
        "product_id": "prod_abc123",
        "selling_plan_id": "sp_monthly",
        "current_period_start": 1739000000,
        "current_period_end": 1741678400,
        "updated_at": 1739095000
    }
}

Response Parameter Description (primary fields shown, see API Reference for complete schema):

Parameter	Type	Description
id	string	Unique identifier for the subscription
status	string	Subscription status (should remain "active")
cancel_at_period_end	boolean	Now set to false, subscription will continue
canceled_at	integer	Cleared cancellation timestamp
cancel_reason	string	Cleared cancellation reason
customer_id	string	ID of the customer who owns this subscription
product_id	string	ID of the subscribed product
selling_plan_id	string	ID of the selling plan
current_period_start	integer	Start of current billing period in Unix timestamp
current_period_end	integer	End of current billing period in Unix timestamp
next_charge_date	integer	Unix timestamp of the next billing date
next_charge_amount	string	Amount that will be charged in the next billing cycle
updated_at	integer	Last update timestamp in Unix format

Error Response Example:

{
    "code": 400,
    "error_code": "subscription_not_scheduled_for_cancellation",
    "msg": "Subscription is not scheduled for cancellation"
}

Common Error Codes:

Error Code	Description
subscription_not_found	The specified subscription ID does not exist
subscription_not_scheduled_for_cancellation	Subscription does not have cancel_at_period_end=true
subscription_already_canceled	Subscription has already been canceled

46. Update Subscription (Plan Change)

For detailed API reference, see: Update Subscription API

Field	Value
API Name	Update Subscription
API Endpoint	/v1/subscriptions/{id}
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/subscriptions/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Request Body (JSON):

{
    "primary_variant": {
        "selling_plan_id": "sp_newplan456"
    },
    "proration_behavior": "always_invoice",
    "billing_cycle_anchor": "now"
}

Request Parameter Description:

Parameter	Type	Required	Description
primary_variant	object	Yes	The primary variant selection to update
primary_variant.selling_plan_id	string	Yes	The new selling plan ID to switch to
primary_variant.variant_id	string	No	The new variant ID (optional)
primary_variant.quantity	integer	No	Quantity (default: 1)
proration_behavior	string	No	How proration is handled (see details below)
proration_date	integer	No	Unix timestamp for custom proration calculation (see details below)
billing_cycle_anchor	string	No	Controls billing cycle timing (see details below)
metadata	object	No	Key-value pairs for additional information

Parameter Details:

proration_behavior - Controls how proration charges are handled during plan changes.

Values:

• "always_invoice": Create an invoice immediately for the prorated amount. Customer is charged right away.
• "create_prorations": Defer the plan change to next billing cycle (used for deferred upgrades).
• "none": No proration calculation. Only valid for downgrades.

Default behavior (when not specified):

• Upgrades: "always_invoice" (immediate charge with credit for unused time on old plan)
• Downgrades: "none" (no charge, change takes effect at period end)

VALID COMBINATIONS (other combinations return error invalid_proration_config):

For UPGRADES (3 valid combinations):

proration_behavior	billing_cycle_anchor	Result
always_invoice	now	Immediate upgrade, charge now, reset cycle
always_invoice	unchanged	Immediate upgrade, charge now, keep cycle
create_prorations	unchanged	Deferred upgrade, change at period end

For DOWNGRADES (1 valid combination):

proration_behavior	billing_cycle_anchor	Result
none	unchanged	Deferred downgrade, change at period end

INVALID COMBINATIONS (return error):

• create_prorations + now: Would reset cycle without settling, customer credit lost
• none + now/unchanged (upgrade): Would give customer free upgrade
• any + now (downgrade): Downgrade cannot take effect immediately

billing_cycle_anchor - Controls when the new billing cycle starts after a plan change.

Values:

• "now": Reset billing cycle immediately. New period starts from the change time.
• "unchanged": Keep current billing cycle anchor.

Default behavior (when not specified):

• Upgrades: "now" (billing cycle resets to start fresh)
• Downgrades: Must be "unchanged" (downgrades always take effect at period end)

NOTE: For downgrades, only "unchanged" is valid. Using "now" will return an error. See proration_behavior documentation for valid combinations.

proration_date - A Unix timestamp (seconds) for custom proration calculation (backdating).

When provided, proration credits are calculated as if the plan change happened at this time instead of now.

How it works:

• The remaining time on the old plan is calculated from proration_date to current_period_end
• Credit = (old_plan_price) × (remaining_time / total_period_time)
• This allows backdating: if a customer requested a change yesterday, you can use yesterday's timestamp

Constraints:

• Must be within the current billing period (between current_period_start and current_period_end)
• If not specified, current time (now) is used for calculation

Example: If period is Dec 1-31 and proration_date is Dec 15, customer gets credit for 16 remaining days.

Example:

curl --location --request POST 'https://api.martianpay.com/v1/subscriptions/sub_abc123' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "primary_variant": {
        "selling_plan_id": "sp_newplan456"
    },
    "proration_behavior": "always_invoice",
    "billing_cycle_anchor": "now"
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "sub_abc123",
        "status": "active",
        "selling_plan_id": "sp_newplan456",
        "selling_plan_name": "Premium Monthly",
        "applied": true,
        "is_upgrade": true,
        "effective_date": 1739090000,
        "charge_today": "66.66",
        "proration_behavior": "always_invoice",
        "proration_date": 1739090000,
        "proration_credit": "33.33",
        "proration_details": {
            "current_price": "4999",
            "target_price": "9999",
            "days_remaining": 20,
            "total_days": 30,
            "credited_amount": "3333",
            "charged_amount": "6666",
            "net_amount": "3333"
        },
        "pending_update": null,
        "next_charge_amount": "99.99",
        "next_charge_date": 1741766584,
        "updated_at": 1739090000
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the subscription
status	string	Subscription status
selling_plan_id	string	New selling plan ID
selling_plan_name	string	New selling plan name
applied	boolean	true=change applied, false=preview only
is_upgrade	boolean	true=upgrade, false=downgrade
effective_date	integer	Unix timestamp when change takes effect
charge_today	string	Net amount charged today
proration_behavior	string	How proration was handled
proration_date	integer	Timestamp used for proration calculation
proration_credit	string	Credit for unused time on old plan
proration_details	object	Detailed proration breakdown
pending_update	object	Scheduled changes for downgrades (null for immediate)
next_charge_amount	string	Amount for next payment
next_charge_date	integer	Unix timestamp for next billing
updated_at	integer	Last update timestamp

Proration Details Object:

Parameter	Type	Description
current_price	string	Current plan price in cents
target_price	string	Target plan price in cents
days_remaining	integer	Days remaining in current period
total_days	integer	Total days in billing period
credited_amount	string	Credit for unused time (cents)
charged_amount	string	Charge for new plan's time (cents)
net_amount	string	Net amount: charged - credited (cents)

Pending Update Object (for downgrades):

Parameter	Type	Description
target_selling_plan_id	string	Selling plan to change to
target_selling_plan_name	string	Name of target selling plan
target_variant_id	string	Variant to change to (if specified)
target_variant_title	string	Display title of target variant
target_variant_price	string	Base price of target variant
change_type	string	"upgrade" or "downgrade"
effective_date	integer	Unix timestamp when change takes effect
scheduled_at	integer	Unix timestamp when update was scheduled
proration_behavior	string	How proration will be handled
next_charge_amount	string	Amount after change takes effect
billing_cycle_anchor	string	Billing cycle timing setting

47. Preview Subscription Update

For detailed API reference, see: Preview Subscription Update API

Field	Value
API Name	Preview Subscription Update
API Endpoint	/v1/subscriptions/{id}/preview
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/subscriptions/{id}/preview

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

Request Body (JSON):

{
    "primary_variant": {
        "selling_plan_id": "sp_newplan456"
    },
    "proration_behavior": "always_invoice",
    "billing_cycle_anchor": "now"
}

Request Parameter Description:

Same as Update Subscription API.

Example:

curl --location --request POST 'https://api.martianpay.com/v1/subscriptions/sub_abc123/preview' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "primary_variant": {
        "selling_plan_id": "sp_newplan456"
    },
    "proration_behavior": "always_invoice",
    "billing_cycle_anchor": "now"
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "sub_abc123",
        "status": "active",
        "applied": false,
        "is_upgrade": true,
        "effective_date": 1739090000,
        "charge_today": "66.66",
        "proration_behavior": "always_invoice",
        "proration_date": 1739090000,
        "proration_credit": "33.33",
        "proration_details": {
            "current_price": "4999",
            "target_price": "9999",
            "days_remaining": 20,
            "total_days": 30,
            "credited_amount": "3333",
            "charged_amount": "6666",
            "net_amount": "3333"
        },
        "next_charge_amount": "99.99",
        "next_charge_date": 1741766584
    }
}

Response Parameter Description:

Same as Update Subscription API response, with key difference:

• applied is always false for preview (no changes made)

Note: Preview does not modify the subscription, create invoices, or charge the customer. Use this to show customers what they'll be charged before confirming plan changes.

Customer Structure

Parameter	Type	Description
id	string	Unique customer ID
object	string	Object type, fixed value: "customer"
total_expense	int64	Total actual spending by the customer (in the smallest currency unit, e.g., cents)
total_payment	int64	Total payment by the customer (in the smallest currency unit)
total_refund	int64	Total refund by the customer (in the smallest currency unit)
currency	string	Customer currency code (e.g., USD), optional
created	int64	Customer creation timestamp (Unix), optional
name	string (optional)	Customer name
email	string (optional)	Customer email address
description	string (optional)	Customer description (such as notes, special tags)
metadata	map[string]string	Additional customer metadata (custom key-value pairs), optional
phone	string (optional)	Customer phone number

48. List Invoices

For detailed API reference, see: List Invoices API

Field	Value
API Name	List Invoices
API Endpoint	/v1/customers/me/invoices
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/customers/me/invoices

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
subscription_id	string	No	Filter by subscription ID
status	string	No	Filter by invoice status (draft, open, paid, void, uncollectible)
offset	integer	No	Pagination offset (default: 0)
limit	integer	No	Pagination limit (default: 20, max: 100)

Example:

curl --location --request GET 'https://api.martianpay.com/v1/customers/me/invoices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

49. Get Invoice

For detailed API reference, see: Get Invoice API

Field	Value
API Name	Get Invoice
API Endpoint	/v1/customers/me/invoices/{id}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/customers/me/invoices/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Invoice ID

Example:

curl --location --request GET 'https://api.martianpay.com/v1/customers/me/invoices/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

50. Get Invoice Payment Intent

For detailed API reference, see: Get Invoice Payment Intent API

Field	Value
API Name	Get Invoice Payment Intent
API Endpoint	/v1/customers/me/invoices/{id}/payment_intent
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/customers/me/invoices/{id}/payment_intent

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Invoice ID

Example:

curl --location --request GET 'https://api.martianpay.com/v1/customers/me/invoices/example_id/payment_intent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

51. Get Invoice PDF

For detailed API reference, see: Get Invoice PDF API

Field	Value
API Name	Get Invoice PDF
API Endpoint	/v1/customers/me/invoices/{id}/pdf
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/customers/me/invoices/{id}/pdf

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Invoice ID

Example:

curl --location --request GET 'https://api.martianpay.com/v1/customers/me/invoices/example_id/pdf' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

52. Send Invoice Email

For detailed API reference, see: Send Invoice Email API

Field	Value
API Name	Send Invoice Email
API Endpoint	/v1/invoices/{id}/send
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/invoices/{id}/send

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Invoice ID

Example:

curl --location --request POST 'https://api.martianpay.com/v1/invoices/example_id/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

53. Void Invoice

For detailed API reference, see: Void Invoice API

Field	Value
API Name	Void Invoice
API Endpoint	/v1/invoices/{id}/void
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/invoices/{id}/void

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Invoice ID

Example:

curl --location --request POST 'https://api.martianpay.com/v1/invoices/example_id/void' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

Refund APIs

54. Create Refund

For detailed API reference, see: Create Refund API

Request Method: POST

Request Path: https://api.martianpay.com/v1/refunds

Request Parameters (JSON body):

Parameter	Type	Required	Description	Example
amount	string	Yes	Refund amount	10
metadata	object	No	Custom key-value pairs
payment_intent_id	string	Yes*	Payment Intent ID	pi_0QIQ4rIePsb23lUguKBsIVKS
reason	string	No	Reason for the refund	requested_by_customer

Request Example (cURL):

curl --location --request POST 'https://api.martianpay.com/v1/refunds' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "amount": "10",
    "metadata": {
        "order_id": "order_123",
        "customer_name": "John Doe"
    },
    "payment_intent_id": "pi_0QIQ4rIePsb23lUguKBsIVKS",
    "reason": "requested_by_customer"
}'

Response Structure (JSON):

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "refunds": [
            {
                "id": "rf_KRFVq8IpoMY40Tt143NInoYw",
                "object": "refund",
                "amount": 100,
                "created": -62135596800,
                "currency": "USD",
                "description": "",
                "transactions": [],
                "failure_reason": "",
                "metadata": {
                    "customer_name": "John Doe",
                    "order_id": "order_123"
                },
                "charge": "ch_rmwSC1uJ0NJsezyj9VsNcJla",
                "payment_intent": "pi_Mv1w0RwHEnloacfnivvsktAG",
                "refund_address": "0x36279Ac046498bF0cb742622cCe22F3cE3c2AfD9",
                "reason": "requested_by_customer",
                "status": "Pending"
            }
        ]
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the refund
object	string	Object type, always "refund"
amount	int	Refunded amount in smallest currency unit
created	int64	Timestamp of refund creation (Unix time)
currency	string	Currency code of the refund (e.g., USD)
description	string	Description of the refund
transactions	array	List of blockchain transactions for refund
failure_reason	string	Reason for refund failure, if applicable
metadata	TransactionDetails[]	Additional custom metadata
charge	string	ID of the related charge
payment_intent	string	ID of the related payment intent
refund_address	string	Blockchain address for the refund
reason	string	Reason for the refund
status	string	Current status of the refund

TransactionDetails (Blockchain Transaction Details)

Parameter	Type	Description
tx_id	string	Transaction ID
source_address	string	Source address
destination_address	string	Destination address
tx_hash	string	Transaction hash
amount	string	Transaction amount
token	string	Token name (e.g., BTC, ETH, USDT)
network	string	Network type (e.g., ERC20, TRC20)
created_at	int64	Transaction creation timestamp
status	string	Transaction status

55. Retrieve a Single Refund

For detailed API reference, see: Get Refund API

Request Method: GET

Request Path: https://api.martianpay.com/v1/refunds/{id}

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Unique refund ID	rf_EOexm0yBhLJQhVklANxxnvdX

Request Example (cURL):

curl --location --request GET 'https://api.martianpay.com/v1/refunds/rf_EOexm0yBhLJQhVklANxxnvdX' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Structure (JSON):

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "rf_EOexm0yBhLJQhVklANxxnvdX",
    "object": "refund",
    "amount": 1000,
    "created": 1631234567,
    "currency": "USD",
    "description": "Refund for order #12345",
    "transactions": [
      {
        "tx_id": "tx_123456",
        "source_address": "0x1234...",
        "destination_address": "0x5678...",
        "tx_hash": "0xabcd...",
        "amount": "10.00",
        "token": "USDT",
        "network": "ERC20",
        "created_at": 1631234568,
        "status": "completed"
      }
    ],
    "failure_reason": "",
    "metadata": {
      "order_id": "12345"
    },
    "charge": "ch_abc123",
    "payment_intent": "pi_def456",
    "refund_address": "0x9876...",
    "reason": "requested_by_customer",
    "status": "succeeded"
  }
}

Response Parameter Description:

(Same as the "Create Refund" response parameters)

56. List Refunds

For detailed API reference, see: List Refunds API

Request Method: GET

Request Path: https://api.martianpay.com/v1/refunds

Request Parameters (Query String):

Parameter	Type	Required	Description	Example
page	int	Yes	Page number, starting from 0	0
page_size	int	Yes	Number of records per page	10
payment_intent	string	No	Filter by payment intent ID	pi_MUIAfkuFgzbdaPubOpimfXLD

Request Example (cURL):

curl --location --request GET 'https://api.martianpay.com/v1/refunds?page=0&page_size=10&payment_intent=pi_MUIAfkuFgzbdaPubOpimfXLD' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Structure (JSON):

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "refunds": [
            {
                "id": "rf_EOexm0yBhLJQhVklANxxnvdX",
                "object": "refund",
                "amount": 10,
                "created": 1739104223,
                "currency": "USD",
                "description": "",
                "transactions": [
                    {
                        "source_address": "0xA0C8583f722339Dd4179D34A93Bae139424cB81e",
                        "destination_address": "0x36279Ac046498bF0cb742622cCe22F3cE3c2AfD9",
                        "tx_hash": "0x24459dea89852c6e69058926033a27afff0fd90c3de8604b06ce15d9e26ee715",
                        "amount": "100000",
                        "token": "USDC",
                        "network": "Ethereum Sepolia",
                        "type": "refund",
                        "created_at": 1739104235,
                        "status": "confirmed"
                    }
                ],
                "failure_reason": "",
                "metadata": {
                    "customer_name": "John Doe",
                    "order_id": "order_123"
                },
                "charge": "ch_MUkOLHxz89MqiOoKOB8bcSX7",
                "payment_intent": "pi_MUIAfkuFgzbdaPubOpimfXLD",
                "refund_address": "0x36279Ac046498bF0cb742622cCe22F3cE3c2AfD9",
                "reason": "requested_by_customer",
                "status": "Success"
            }
        ],
        "total": 1,
        "page": 1,
        "page_size": 10
    }
}

Response Parameter Description:

Parameter	Type	Description
code	int	Response code (0 for success)
msg	string	Response message
data	object	Response data containing refund list
refunds	array	List of refund objects
total	int	Total number of refunds
page	int	Current page number
page_size	int	Number of records per page

Refund object parameters are the same as described in the "Retrieve a Single Refund" section.

Wallet/Address APIs

57. Create Wallet Address

For detailed API reference, see: Create Wallet Address API

Field	Value
API Name	Create Wallet Address
API Endpoint	/v1/addresses
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/addresses

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Body (JSON):

{
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "network": "ETH"
}

Request Parameter Description:

Parameter	Type	Required	Description	Example
address	string	Yes	The blockchain address to create	0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
network	string	Yes	Blockchain network (e.g., ETH, BTC, Solana)	ETH

Example:

curl --location --request POST 'https://api.martianpay.com/v1/addresses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "network": "ETH"
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "addr_abc123",
        "merchant_id": "merch_xyz789",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "network": "ETH",
        "alias": "",
        "status": "created",
        "verification_id": "verify_def456",
        "verification": {
            "id": "verify_def456",
            "merchant_address_id": "addr_abc123",
            "status": "pending",
            "asset_id": "USDC-Ethereum-TEST",
            "aml_status": "pending",
            "tried_times": 0,
            "verified_at": 0
        },
        "created_at": 1739090000,
        "updated_at": 1739090000
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the merchant address
merchant_id	string	ID of the merchant who owns this address
address	string	The actual blockchain address
network	string	Blockchain network (e.g., ETH, BTC)
alias	string	User-defined name for this address
status	string	Current status of the address (created, verifying, success, failed)
verification_id	string	Reference to the verification record ID
verification	object	Nested verification details
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

Verification Object Parameters:

Parameter	Type	Description
id	string	Unique identifier for the verification record
merchant_address_id	string	ID of the merchant address being verified
status	string	Current verification status
asset_id	string	Asset used for verification
aml_status	string	Anti-Money Laundering status
tried_times	integer	Number of verification attempts
verified_at	integer	Timestamp when verification was completed

58. List Wallet Addresses

For detailed API reference, see: List Wallet Addresses API

Field	Value
API Name	List Wallet Addresses
API Endpoint	/v1/addresses
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/addresses

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Body (JSON):

{
    "page": 0,
    "page_size": 20,
    "network": "ETH"
}

Request Parameter Description:

Parameter	Type	Required	Description	Example
page	integer	No	Page number, starting from 0	0
page_size	integer	Yes	Number of records per page (min: 1, max: 50)	20
network	string	No	Filter by blockchain network (e.g., ETH, BTC)	ETH

Example:

curl --location --request GET 'https://api.martianpay.com/v1/addresses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "page": 0,
    "page_size": 20,
    "network": "ETH"
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "merchant_addresses": [
            {
                "id": "addr_abc123",
                "merchant_id": "merch_xyz789",
                "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
                "network": "ETH",
                "alias": "Main Wallet",
                "status": "success",
                "verification_id": "verify_def456",
                "verification": {
                    "id": "verify_def456",
                    "merchant_address_id": "addr_abc123",
                    "status": "verified",
                    "asset_id": "USDC-Ethereum-TEST",
                    "aml_status": "approved",
                    "tried_times": 1,
                    "verified_at": 1739091000
                },
                "created_at": 1739090000,
                "updated_at": 1739091000
            }
        ],
        "page": 0,
        "page_size": 20,
        "total": 1
    }
}

Response Parameter Description:

Parameter	Type	Description
merchant_addresses	array	List of merchant address objects
page	integer	Current page number
page_size	integer	Number of records per page
total	integer	Total number of addresses

Merchant Address Object Parameters:

Parameter	Type	Description
id	string	Unique identifier for the merchant address
merchant_id	string	ID of the merchant who owns this address
address	string	The actual blockchain address
network	string	Blockchain network (e.g., ETH, BTC)
alias	string	User-defined name for this address
status	string	Current status of the address (created, verifying, success, failed)
verification_id	string	Reference to the verification record ID
verification	object	Nested verification details
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

59. Get Wallet Address

For detailed API reference, see: Get Wallet Address API

Field	Value
API Name	Get Wallet Address
API Endpoint	/v1/addresses/{id}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)

Request URL: GET https://api.martianpay.com/v1/addresses/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Merchant address ID	addr_abc123

Example:

curl --location --request GET 'https://api.martianpay.com/v1/addresses/addr_abc123' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "addr_abc123",
        "merchant_id": "merch_xyz789",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "network": "ETH",
        "alias": "Main Wallet",
        "status": "success",
        "verification_id": "verify_def456",
        "verification": {
            "id": "verify_def456",
            "merchant_address_id": "addr_abc123",
            "status": "verified",
            "asset_id": "USDC-Ethereum-TEST",
            "aml_status": "approved",
            "tried_times": 1,
            "verified_at": 1739091000
        },
        "created_at": 1739090000,
        "updated_at": 1739091000
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the merchant address
merchant_id	string	ID of the merchant who owns this address
address	string	The actual blockchain address
network	string	Blockchain network (e.g., ETH, BTC)
alias	string	User-defined name for this address
status	string	Current status of the address (created, verifying, success, failed)
verification_id	string	Reference to the verification record ID
verification	object	Nested verification details
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

Verification Object Parameters:

Parameter	Type	Description
id	string	Unique identifier for the verification record
merchant_address_id	string	ID of the merchant address being verified
status	string	Current verification status
asset_id	string	Asset used for verification
aml_status	string	Anti-Money Laundering status
tried_times	integer	Number of verification attempts
verified_at	integer	Timestamp when verification was completed

60. Update Wallet Address

For detailed API reference, see: Update Wallet Address API

Field	Value
API Name	Update Wallet Address
API Endpoint	/v1/addresses/{id}
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/addresses/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Merchant address ID	addr_abc123

Request Body (JSON):

{
    "alias": "Primary ETH Wallet"
}

Request Parameter Description:

Parameter	Type	Required	Description	Example
alias	string	No	User-defined name for this address	Primary ETH Wallet

Example:

curl --location --request POST 'https://api.martianpay.com/v1/addresses/addr_abc123' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "alias": "Primary ETH Wallet"
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "addr_abc123",
        "merchant_id": "merch_xyz789",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "network": "ETH",
        "alias": "Primary ETH Wallet",
        "status": "success",
        "verification_id": "verify_def456",
        "verification": {
            "id": "verify_def456",
            "merchant_address_id": "addr_abc123",
            "status": "verified",
            "asset_id": "USDC-Ethereum-TEST",
            "aml_status": "approved",
            "tried_times": 1,
            "verified_at": 1739091000
        },
        "created_at": 1739090000,
        "updated_at": 1739092000
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the merchant address
merchant_id	string	ID of the merchant who owns this address
address	string	The actual blockchain address
network	string	Blockchain network (e.g., ETH, BTC)
alias	string	User-defined name for this address
status	string	Current status of the address (created, verifying, success, failed)
verification_id	string	Reference to the verification record ID
verification	object	Nested verification details
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

61. Delete Wallet Address

For detailed API reference, see: Delete Wallet Address API

Field	Value
API Name	Delete Wallet Address
API Endpoint	/v1/addresses/{id}
HTTP Method	DELETE
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)

Request URL: DELETE https://api.martianpay.com/v1/addresses/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Merchant address ID	addr_abc123

Example:

curl --location --request DELETE 'https://api.martianpay.com/v1/addresses/addr_abc123' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "Address deleted successfully"
}

Response Parameter Description:

Parameter	Type	Description
code	number	Response code (0 for success)
error_code	string	Error code identifier
msg	string	Human-readable message

62. Verify Wallet Address

For detailed API reference, see: Verify Wallet Address API

Field	Value
API Name	Verify Wallet Address
API Endpoint	/v1/addresses/{id}/verify
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/addresses/{id}/verify

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Path Parameter:

Parameter	Type	Required	Description	Example
id	string	Yes	Merchant address ID	addr_abc123

Request Body (JSON):

{
    "amount": "0.01"
}

Request Parameter Description:

Parameter	Type	Required	Description	Example
amount	string	Yes	Amount to send for verification	0.01

Example:

curl --location --request POST 'https://api.martianpay.com/v1/addresses/addr_abc123/verify' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
    "amount": "0.01"
}'

Response Example:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        "id": "addr_abc123",
        "merchant_id": "merch_xyz789",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "network": "ETH",
        "alias": "Primary ETH Wallet",
        "status": "verifying",
        "verification_id": "verify_def456",
        "verification": {
            "id": "verify_def456",
            "merchant_address_id": "addr_abc123",
            "status": "pending",
            "asset_id": "USDC-Ethereum-TEST",
            "aml_status": "pending",
            "tried_times": 1,
            "verified_at": 0
        },
        "created_at": 1739090000,
        "updated_at": 1739092000
    }
}

Response Parameter Description:

Parameter	Type	Description
id	string	Unique identifier for the merchant address
merchant_id	string	ID of the merchant who owns this address
address	string	The actual blockchain address
network	string	Blockchain network (e.g., ETH, BTC)
alias	string	User-defined name for this address
status	string	Current status of the address (created, verifying, success, failed)
verification_id	string	Reference to the verification record ID
verification	object	Nested verification details
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format

Verification Object Parameters:

Parameter	Type	Description
id	string	Unique identifier for the verification record
merchant_address_id	string	ID of the merchant address being verified
status	string	Current verification status
asset_id	string	Asset used for verification
aml_status	string	Anti-Money Laundering status
tried_times	integer	Number of verification attempts
verified_at	integer	Timestamp when verification was completed

Order APIs

63. List Orders

For detailed API reference, see: List Orders API

Field	Value
API Name	List Orders
API Endpoint	/v1/orders
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/orders

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters (Query String):

search=order_123&status=Paid&page=1&page_size=10

Request Parameter Description:

Parameter	Type	Required	Description	Example
search	string	No	Search by order number, customer name, or email	order_123
status	string	No	Filter by status: Pending, Paid, Shipping, Refunded, Canceled	Paid
page	integer	No	Page number (default: 1)	1
page_size	integer	No	Items per page (default: 10, max: 100)	10

Example:

curl --location --request GET 'https://api.martianpay.com/v1/orders?page=1&page_size=10&status=Paid' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "orders": [
      {
        "order_number": "ord_abc123",
        "external_id": "ext_c40wb",
        "status": "Paid",
        "created_at": 1739090000,
        "updated_at": 1739092000,
        "customer": {
          "id": "cus_xyz789",
          "name": "John Doe",
          "email": "john.doe@example.com",
          "phone": "+1234567890"
        },
        "items": [
          {
            "product": {
              "id": "prod_abc123",
              "name": "Premium T-Shirt",
              "description": "High-quality cotton t-shirt",
              "active": true,
              "default_currency": "USD",
              "fixed_price": {
                "amount": 29.99,
                "asset_id": "USD"
              },
              "collect_shipping_address": true,
              "collect_tax_address": false,
              "created_at": 1739080000
            },
            "option_values": {
              "Color": "Black",
              "Size": "M"
            },
            "quantity": 2,
            "unit_price": {
              "amount": 29.99,
              "asset_id": "USD"
            },
            "subtotal": {
              "amount": 59.98,
              "asset_id": "USD"
            }
          }
        ],
        "total_amount": {
          "amount": 59.98,
          "asset_id": "USD"
        },
        "shipping_address": {
          "name": "John Doe",
          "line1": "123 Main St",
          "line2": "Apt 4B",
          "city": "New York",
          "state": "NY",
          "postal_code": "10001",
          "country": "US"
        }
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10
  }
}

Response Parameter Description:

Top-level structure (OrderListResp)

Parameter	Type	Description
orders	Order[]	List of orders
total	integer	Total number of records matching the criteria
page	integer	Current page number (starting from 1)
page_size	integer	Number of records per page

Order Structure Description

Parameter	Type	Description
order_number	string	Unique order identifier (e.g., ord_xxx)
external_id	string	External system identifier for the order
status	string	Order status (Pending, Paid, Shipping, Refunded, Canceled)
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format
customer	object	Customer information
items	array	List of order items
total_amount	object	Total order amount
shipping_address	object	Shipping address details

Customer Object

Parameter	Type	Description
id	string	Customer ID
name	string	Customer name
email	string	Customer email
phone	string	Customer phone

Order Item Object

Parameter	Type	Description
product	object	Product details
option_values	object	Variant options (e.g., Color, Size)
quantity	integer	Quantity ordered
unit_price	object	Price per unit
subtotal	object	Item subtotal (quantity × unit_price)

Amount Object

Parameter	Type	Description
amount	number	Decimal amount value
asset_id	string	Currency/asset identifier

Shipping Address Object

Parameter	Type	Description
name	string	Recipient name
line1	string	Address line 1
line2	string	Address line 2 (optional)
city	string	City
state	string	State/Province
postal_code	string	Postal/ZIP code
country	string	Country code (ISO 2-letter)

64. Get Order Details

For detailed API reference, see: Get Order Details API

Field	Value
API Name	Get Order Details
API Endpoint	/v1/orders/{order_number}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/orders/{order_number}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Path Parameter:

Parameter	Type	Required	Description	Example
order_number	string	Yes	Order number (e.g., ord_xxx)	ord_abc123

Example:

curl --location --request GET 'https://api.martianpay.com/v1/orders/ord_abc123' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {
    "order": {
      "order_number": "ord_abc123",
      "external_id": "ext_c40wb",
      "status": "Paid",
      "created_at": 1739090000,
      "updated_at": 1739092000,
      "customer": {
        "id": "cus_xyz789",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890"
      },
      "items": [
        {
          "product": {
            "id": "prod_abc123",
            "name": "Premium T-Shirt",
            "description": "High-quality cotton t-shirt",
            "active": true,
            "default_currency": "USD",
            "fixed_price": {
              "amount": 29.99,
              "asset_id": "USD"
            },
            "collect_shipping_address": true,
            "collect_tax_address": false,
            "created_at": 1739080000,
            "metadata": {
              "sku": "TSHIRT-PREM-001"
            },
            "options": [
              {
                "name": "Color",
                "sort_order": 1,
                "values": [
                  {
                    "value": "Black",
                    "sort_order": 1
                  },
                  {
                    "value": "White",
                    "sort_order": 2
                  }
                ]
              },
              {
                "name": "Size",
                "sort_order": 2,
                "values": [
                  {
                    "value": "S",
                    "sort_order": 1
                  },
                  {
                    "value": "M",
                    "sort_order": 2
                  },
                  {
                    "value": "L",
                    "sort_order": 3
                  }
                ]
              }
            ],
            "media_order": ["media_img001"],
            "includes": {
              "media": [
                {
                  "id": "media_img001",
                  "url": "https://cdn.example.com/tshirt-black.jpg",
                  "content_type": "image/jpeg",
                  "width": 1200,
                  "height": 1600,
                  "alt_text": "Black premium t-shirt"
                }
              ]
            }
          },
          "option_values": {
            "Color": "Black",
            "Size": "M"
          },
          "quantity": 2,
          "unit_price": {
            "amount": 29.99,
            "asset_id": "USD"
          },
          "subtotal": {
            "amount": 59.98,
            "asset_id": "USD"
          },
          "media_order": ["media_img001"]
        }
      ],
      "subtotal": {
        "amount": 59.98,
        "asset_id": "USD"
      },
      "shipping_cost": {
        "amount": 5.00,
        "asset_id": "USD"
      },
      "tax": {
        "amount": 3.25,
        "asset_id": "USD"
      },
      "total_amount": {
        "amount": 68.23,
        "asset_id": "USD"
      },
      "shipping_address": {
        "name": "John Doe",
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US",
        "phone": "+1234567890"
      },
      "billing_address": {
        "name": "John Doe",
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
      },
      "payment_intent_id": "pi_xyz789",
      "payment_link_id": "plink_abc123",
      "notes": "Please ship ASAP"
    }
  }
}

Response Parameter Description:

Order Object

Parameter	Type	Description
order_number	string	Unique order identifier (e.g., ord_xxx)
external_id	string	External system identifier for the order
status	string	Order status (Pending, Paid, Shipping, Refunded, Canceled)
created_at	integer	Creation timestamp in Unix format
updated_at	integer	Last update timestamp in Unix format
customer	object	Customer information (see Customer Object below)
items	array	List of order items (see Order Item Object below)
subtotal	object	Subtotal before shipping and tax
shipping_cost	object	Shipping cost
tax	object	Tax amount
total_amount	object	Total order amount (subtotal + shipping + tax)
shipping_address	object	Shipping address details
billing_address	object	Billing address details (optional)
payment_intent_id	string	Associated payment intent ID
payment_link_id	string	Associated payment link ID
notes	string	Customer notes or special instructions

Customer Object

Parameter	Type	Description
id	string	Customer ID
name	string	Customer name
email	string	Customer email
phone	string	Customer phone

Order Item Object

Parameter	Type	Description
product	object	Full product details (see Product Object below)
option_values	object	Selected variant options (e.g., Color, Size)
quantity	integer	Quantity ordered
unit_price	object	Price per unit (Amount Object)
subtotal	object	Item subtotal (quantity × unit_price)
media_order	array	Ordered list of media asset IDs for this item

Product Object

Parameter	Type	Description
id	string	Unique product identifier
name	string	Product name
description	string	Detailed product description
active	boolean	Whether product is currently available
default_currency	string	Base currency for the product
fixed_price	object	Price for simple products (Amount Object)
collect_shipping_address	boolean	Whether to collect shipping address
collect_tax_address	boolean	Whether to collect billing/tax address
created_at	integer	Creation timestamp in Unix format
metadata	object	Additional custom data (key-value pairs)
options	array	Variant option definitions (see Option below)
media_order	array	Ordered list of media asset IDs
includes	object	Included media assets with signed URLs

Option Object

Parameter	Type	Description
name	string	Option name (e.g., "Color", "Size")
sort_order	integer	Display order
values	array	Allowed values for this option

Option Value Object

Parameter	Type	Description
value	string	Option value label
sort_order	integer	Display order
metadata	object	Additional metadata
swatch	object	Visual swatch information

Media Object

Parameter	Type	Description
id	string	Media identifier
url	string	CDN URL for the asset
content_type	string	MIME type (e.g., image/jpeg)
width	integer	Width in pixels
height	integer	Height in pixels
alt_text	string	Alternative text for accessibility

Amount Object

Parameter	Type	Description
amount	number	Decimal amount value
asset_id	string	Currency/asset identifier

Address Object (Shipping/Billing)

Parameter	Type	Description
name	string	Recipient/Billing name
line1	string	Address line 1
line2	string	Address line 2 (optional)
city	string	City
state	string	State/Province
postal_code	string	Postal/ZIP code
country	string	Country code (ISO 2-letter)
phone	string	Contact phone (optional)

Payout APIs

65. Create Payout

For detailed API reference, see: Create Payout API

Field	Value
API Name	Create Payout
API Endpoint	/v1/payouts
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payouts

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
request	string	Yes	Payout parameters including destination, amount, and asset details

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

66. List Payouts

For detailed API reference, see: List Payouts API

Field	Value
API Name	List Payouts
API Endpoint	/v1/payouts/list
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payouts/list

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
page	integer	Yes	Page number (zero-based)
page_size	integer	Yes	Number of items per page (1-50)
external_id	string	No	Filter by external ID

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payouts/list' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

67. Get Payout

For detailed API reference, see: Get Payout API

Field	Value
API Name	Get Payout
API Endpoint	/v1/payouts/{id}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/payouts/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Unique payout identifier

Example:

curl --location --request GET 'https://api.martianpay.com/v1/payouts/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

68. Preview Payout

For detailed API reference, see: Preview Payout API

Field	Value
API Name	Preview Payout
API Endpoint	/v1/payouts/preview
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payouts/preview

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
request	string	Yes	Payout parameters for preview calculation

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payouts/preview' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

Payroll APIs

69. Create Payroll

For detailed API reference, see: Create Payroll API

Field	Value
API Name	Create Payroll
API Endpoint	/v1/payrolls
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payrolls

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
csv_file	file	Yes	CSV file containing payroll items

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payrolls' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

70. Create Direct Payroll

For detailed API reference, see: Create Direct Payroll API

Field	Value
API Name	Create Direct Payroll
API Endpoint	/v1/payrolls/direct
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payrolls/direct

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
request	string	Yes	Direct payroll creation parameters

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payrolls/direct' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

71. List Payrolls

For detailed API reference, see: List Payrolls API

Field	Value
API Name	List Payrolls
API Endpoint	/v1/payrolls
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/payrolls

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number, starting from 0
page_size	integer	Yes	Items per page
start_date	string	No	Start date for filtering
end_date	string	No	End date for filtering
external_id	string	No	Filter by external ID
payroll_id	string	No	Filter by payroll ID
status	string	No	Filter by status (pending, approved, paid, etc.)

Example:

curl --location --request GET 'https://api.martianpay.com/v1/payrolls' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

72. Get Payroll

For detailed API reference, see: Get Payroll API

Field	Value
API Name	Get Payroll
API Endpoint	/v1/payrolls/{id}
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/payrolls/{id}

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Payroll ID

Example:

curl --location --request GET 'https://api.martianpay.com/v1/payrolls/example_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

73. Confirm Payroll

For detailed API reference, see: Confirm Payroll API

Field	Value
API Name	Confirm Payroll
API Endpoint	/v1/payrolls/:id/confirm
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/payrolls/:id/confirm

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Payroll ID

Example:

curl --location --request POST 'https://api.martianpay.com/v1/payrolls/:id/confirm' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

Approval APIs

74. Get Approval Detail

For detailed API reference, see: Get Approval Detail API

Field	Value
API Name	Get Approval Detail
API Endpoint	/v1/approval/detail
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/approval/detail

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
resource_id	string	No	Resource ID
resource_type	string	No	Resource type
instance_id	string	No	Instance ID

Example:

curl --location --request GET 'https://api.martianpay.com/v1/approval/detail' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

75. Approve

For detailed API reference, see: Approve API

Field	Value
API Name	Approve
API Endpoint	/v1/approval/{id}/approve
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/approval/{id}/approve

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Approval instance ID
request	string	Yes	Approval details

Example:

curl --location --request POST 'https://api.martianpay.com/v1/approval/example_id/approve' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

76. Reject

For detailed API reference, see: Reject API

Field	Value
API Name	Reject
API Endpoint	/v1/approval/{id}/reject
HTTP Method	POST
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: POST https://api.martianpay.com/v1/approval/{id}/reject

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Request Parameters:

Parameter	Type	Required	Description
id	string	Yes	Approval instance ID
request	string	Yes	Rejection details

Example:

curl --location --request POST 'https://api.martianpay.com/v1/approval/example_id/reject' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]

Balance/Stats APIs

77. Get Balance Stats

For detailed API reference, see: Get Balance Stats API

Field	Value
API Name	Get Balance Stats
API Endpoint	/v1/stats/balance
HTTP Method	GET
Data Format	JSON
Authentication	Basic Auth (Username is API Key, Password is empty)
Content-Type	application/json

Request URL: GET https://api.martianpay.com/v1/stats/balance

Request Header Example:

Content-Type: application/json
Authorization: Basic {BASE64_ENCODE(api_key + ":")}

You can generate Basic Auth online: https://www.ol-tools.com/basic-auth-generator

Example:

curl --location --request GET 'https://api.martianpay.com/v1/stats/balance' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response Example:

{
  "code": 0,
  "error_code": "success",
  "msg": "success",
  "data": {}
}

[Refer to the API documentation for complete response schema]