Introduction

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

1. Introduction

The MartianPay API is designed around REST principles, offering a consistent and intuitive interface for developers. Our API features:

• Predictable, resource-oriented URLs
• JSON-encoded request bodies and responses
• Standard HTTP response codes, authentication, and verbs
• A test mode for safe experimentation without affecting live data
• API versioning to ensure compatibility and feature consistency

Authentication is handled via API keys, which determine whether requests are processed in live or test mode. Each request operates on a single object, as bulk updates are not supported.

For the most up-to-date and account-specific documentation, please log in to your MartianPay dashboard. This ensures you're working with the latest API version and functionality tailored to your account.

2. Authentication

2.1 Basic Authentication

• Username: Your API key
• Password: Empty

To calculate the Authorization header:

1. Concatenate your username (API key) and password (empty) with a colon (:)
2. Base64 encode the resulting string
3. Prepend "Basic " to the encoded string

Example in Python:

import base64

api_key = "your_api_key_here"
auth_string = f"{api_key}:"
encoded_auth = base64.b64encode(auth_string.encode()).decode()
authorization_header = f"Basic {encoded_auth}"

Include this calculated value in your request headers as:

Authorization: Basic {encoded_auth}

You can generate Basic Auth online with username (api key) and password (empty): https://www.ol-tools.com/basic-auth-generator

2.2 Request Headers

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

3. Response

MartianPay uses standard HTTP response codes to indicate the success or failure of API requests:

• 200: Success
• 401: UNAUTHORIZED - Authentication failed or not provided
• 403: FORBIDDEN - The authenticated user lacks necessary permissions
• 404: NotFound - The requested resource could not be found
• 429: TooManyRequests - Request rate limit exceeded
• 500: ServerErr - Internal server error (rare)

For 200 OK responses, the structure will be in JSON format with the following fields:

• code: An integer indicating the status of the operation.
  • 0 indicates success
  • Any other value indicates an error
• error_code: A string providing a description of the result or error message
• msg: A string providing a description of the result or error message
• data: An object containing the response data (only present for successful operations)

Example of a successful response:

{
    "code": 0,
    "error_code": "success",
    "msg": "success",
    "data": {
        // Response data object
    }
}

Example of an error response:

{
    "code": 140,
    "error_code": "customer not found",
    "msg": "customer not found"
}

4. Pagination

MartianPay API supports pagination for list endpoints to manage large datasets efficiently. Use the following query parameters to control pagination:

Parameter	Type	Description
page	int	Page number (starting from 0)
page_size	int	Number of items per page

Example request:

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

The response will include pagination metadata:

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

• total: Total number of items across all pages
• page: Current page number
• page_size: Number of items per page

5. Metadata

Many requests include a metadata field, which is a map (key-value pairs) that can be customized by the user. This metadata is always returned unchanged in the response. It allows you to store additional, structured information that you can later use for your own purposes.

Example usage in a request:

{
  "metadata": {
    "internal_id": "12345",
    "user_type": "premium",
    "campaign_source": "email_promo_2023"
  }
}

This metadata will be included in the response, enabling you to associate custom data with MartianPay objects and retrieve it later.