Overview

Customer APIs enable you to create and manage customer profiles in MartianPay. A customer object represents an individual or entity making purchases through your platform, serving as the central point for tracking transactions, subscriptions, and payment history.

What is a Customer?

A customer object stores information about a buyer and their relationship with your business. Each customer:

• 👤 Represents an individual or business entity
• 💰 Tracks total payments, expenses, and refunds
• 🔗 Links to payment intents and subscriptions
• 💳 Stores saved payment methods
• 🏷️ Supports custom metadata for your use cases

🔗 Related APIs: Customers are associated with Payment Intents, Subscriptions, and Refunds.

Key Features

Feature	Description
Unified Profile	Single customer record across all transactions
Transaction History	Automatic tracking of total payments and refunds
Saved Payment Methods	Store customer wallet addresses for future use
Subscription Management	Link recurring subscriptions to customer profiles
Custom Metadata	Attach your own data for internal tracking
Email & Name Tracking	Store contact information for communication
Spending Analytics	View total expense, payment, and refund amounts

Why Use Customer Objects?

Benefits:

• ✅ Unified View: See all customer activity in one place
• ✅ Recurring Payments: Simplify subscription billing
• ✅ Better Analytics: Track customer lifetime value
• ✅ Saved Payment Info: Faster checkout for returning customers
• ✅ Personalization: Tailor experiences based on customer data
• ✅ Internal Tracking: Link to your user database via metadata

Use Cases

Common Scenarios:

• 🛍️ E-commerce: Track customer purchase history and preferences
• 💼 SaaS Platforms: Manage recurring subscription customers
• 🎫 Ticketing: Store attendee information for events
• 📱 Mobile Apps: Link in-app purchases to user accounts
• 💳 Payment Processing: Save payment methods for one-click checkout
• 📊 Analytics: Analyze customer spending patterns

Customer Data Structure

Key Fields:

Field	Type	Description
id	string	Unique customer identifier (e.g., cus_N6eQ18Ngl5aWega0tQwYBzkp)
name	string	Customer's full name
email	string	Customer's email address
phone	string	Customer's phone number (optional)
description	string	Internal notes about the customer
metadata	object	Custom key-value pairs for your use
total_payment	number	Total amount customer has paid (USD)
total_refund	number	Total amount refunded to customer (USD)
total_expense	number	Net amount (payments - refunds)
currency	string	Currency for totals (USD)
created	integer	Unix timestamp of customer creation

Best Practices

✅ DO:

• Create customers before or during first payment
• Use metadata to link to your internal user IDs
• Keep email addresses up to date for receipts
• Use descriptive names and descriptions
• Query customers by email for quick lookup

❌ DON'T:

• Create duplicate customers for the same user
• Store sensitive data in metadata (use your database)
• Forget to update customer info when changed
• Use customer objects for non-recurring scenarios only

Important Notes

A customer represents an individual or entity that makes purchases through your platform. Creating a customer object allows you to associate transactions, subscriptions, and other relevant information with a specific user. This can be useful for tracking customer behavior, managing recurring payments, and providing personalized services.

Key Capabilities:

• Track complete customer payment history
• Manage recurring subscriptions efficiently
• Store payment methods for faster checkout
• Analyze customer spending patterns
• Personalize customer experiences

---

API Reference

1. Create Customer

For detailed API reference, see: Create Customer API

Request:

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

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "cus_N6eQ18Ngl5aWega0tQwYBzkp",
    "object": "customer",
    "total_expense": 0,
    "total_payment": 0,
    "total_refund": 0,
    "currency": "USD",
    "created": 1748506412,
    "name": "John Doe",
    "email": "john11@example.com",
    "description": "New customer",
    "metadata": {
      "user_id": "12345"
    },
    "phone": ""
  }
}

Understanding the Response

How to Check if the Request Was Successful:

Field	Value	Meaning
error_code	"success"	✅ Customer created successfully
error_code	Other value	❌ Error occurred (e.g., "duplicate_email", "invalid_request")

Key Fields:

Field	Description
id	Unique customer identifier (use for future API calls)
total_expense	Net amount (total_payment - total_refund) in USD
total_payment	Total amount customer has paid
total_refund	Total amount refunded to customer
metadata	Custom key-value pairs you provided

Next Steps:

• Use the id to link payments, subscriptions, or refunds to this customer
• Store the id in your database alongside your internal user ID
• Update customer info as needed using Update Customer API

2. Update Customer

For detailed API reference, see: Update Customer API

Request:

curl --location --request POST 'https://api.martianpay.com/v1/customers/\{id\}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data-raw '{
  "name": "John Updated",
  "email": "john_updated@example.com",
  "description": "Updated customer info",
  "metadata": {
    "user_id": "12345",
    "status": "active"
  }
}'

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "cus_N6eQ18Ngl5aWega0tQwYBzkp",
    "object": "customer",
    "total_expense": 0,
    "total_payment": 0,
    "total_refund": 0,
    "currency": "USD",
    "created": 1748506412,
    "name": "John Updated",
    "email": "john_updated@example.com",
    "description": "Updated customer info",
    "metadata": {
      "status": "active",
      "user_id": "12345"
    },
    "phone": ""
  }
}

Understanding the Response

How to Check if the Request Was Successful:

Field	Value	Meaning
error_code	"success"	✅ Customer updated successfully
error_code	Other value	❌ Error occurred (e.g., "customer_not_found", "invalid_request")

Key Fields:

• Updated fields: Name, email, description, and metadata reflect your changes
• Unchanged fields: Customer ID, creation date, and payment totals remain the same
• Metadata merging: New metadata keys are added, existing keys are updated

Next Steps:

• Verify the updated fields match your request
• Use the same id for future operations on this customer

3. Get Customer

For detailed API reference, see: Get Customer API

Request:

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

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "cus_N6eQ18Ngl5aWega0tQwYBzkp",
    "object": "customer",
    "total_expense": 0,
    "total_payment": 0,
    "total_refund": 0,
    "currency": "USD",
    "created": 1748506412,
    "name": "John Updated",
    "email": "john_updated@example.com",
    "description": "Updated customer info",
    "metadata": {
      "status": "active",
      "user_id": "12345"
    },
    "phone": ""
  }
}

Understanding the Response

How to Check if the Request Was Successful:

Field	Value	Meaning
error_code	"success"	✅ Customer retrieved successfully
error_code	"customer_not_found"	❌ No customer exists with this ID
error_code	Other value	❌ Other error occurred

Key Fields:

• total_payment: Sum of all successful payments from this customer
• total_refund: Sum of all refunds issued to this customer
• total_expense: Net amount (total_payment - total_refund)
• metadata: Custom data you previously stored

Next Steps:

• Use customer data to display in your application
• Check total_expense for customer lifetime value
• Update customer info if needed using Update Customer API

4. List Customers

For detailed API reference, see: List Customers API

Request:

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

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "customers": [
      {
        "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"
      }
    ],
    "total": 1,
    "page": 0,
    "page_size": 10
  }
}

Understanding the Response

How to Check if the Request Was Successful:

Field	Value	Meaning
error_code	"success"	✅ Customers retrieved successfully
error_code	Other value	❌ Error occurred

Key Fields:

• total: Total number of customers matching your query
• page: Current page number (0-based)
• page_size: Number of items per page
• customers: Array of customer objects

Pagination:

• Use page and page_size to navigate through results
• If total > page_size, there are more pages available
• Next page: page=1, previous page: page=0

Filtering:

• Use email parameter to find specific customer by email
• Empty customers array means no matches found

Next Steps:

• Loop through customers array to process each customer
• Use customer id to fetch more details or perform operations
• Adjust page and page_size for pagination

These examples demonstrate how to use the Customer API with curl:

1. Replace {BASE64_ENCODE(api_key + ":")} with your actual encoded API key.
2. For update and get operations, replace \{id\} with the actual customer ID.
3. Adjust the request data according to your needs.
4. Use appropriate HTTP methods (POST, GET) as shown in the examples.
5. Include the necessary headers, especially 'Content-Type' and 'Authorization'.
6. For list operations, you can customize the pagination and filtering parameters.

5. List Customer Payment Methods

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

List all saved payment methods for a specific customer (merchant authentication required).

Endpoint: GET /v1/customers/payment_methods

Request:

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

Response:

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

Understanding the Response

How to Check if the Request Was Successful:

Field	Value	Meaning
error_code	"success"	✅ Payment methods retrieved successfully
error_code	"customer_not_found"	❌ No customer exists with this ID
error_code	Other value	❌ Other error occurred

Key Fields:

• payment_methods: Array of saved payment methods for this customer
• Empty array means customer has no saved payment methods

Use Cases:

• Display saved payment methods in your checkout UI
• Allow customers to select from previously used payment methods
• Check last4 and brand to show user-friendly card information
• Use id to process payments with saved methods

Next Steps:

• Display payment methods in your UI for customer selection
• Use payment method id when creating payment intents
• Check exp_month and exp_year to identify expired cards

Payment Method Fields:

Field	Type	Description
id	string	Payment method ID
provider	string	Payment provider (stripe, paypal, etc.)
type	string	Payment method type (card, wallet, bank_account)
last4	string	Last 4 digits of card number
brand	string	Card brand (visa, mastercard, amex, etc.)
exp_month	integer	Card expiration month (1-12)
exp_year	integer	Card expiration year
funding	string	Card funding type (credit, debit, prepaid)
country	string	Card issuing country (ISO 2-letter code)
fingerprint	string	Unique card fingerprint for deduplication

Authentication Types

Merchant Authentication

Used for merchant-initiated operations (creating customers, listing customer data):

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

Endpoints using Merchant Auth:

• GET /v1/customers/payment_methods - List payment methods for any customer