Built on REST principles, the Straddle API uses intuitive, resource-oriented URLs and communicates via JSON-encoded request bodies and responses. We employ standard HTTP methods, authentication, and status codes to ensure consistency and predictability.

Straddle provides two separate environments to support your development workflow: the Sandbox environment for testing and development, and the Production environment for live transactions.

Warning: Always ensure you're using the correct environment and API keys. Using Sandbox credentials in Production will cause requests to fail and negatively impact the user experience.

Straddle uses Bearer Token authentication via JWT API keys. Include your secret API key in the Authorization header of every request:

curl https://sandbox.straddle.io/v1/customers \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY"

Generate an API key from the Straddle Dashboard:

1. Log in to your Straddle Dashboard.
2. Navigate to Developers > API Keys.
3. Click Create API Key to generate a new key.

Warning: Your secret API key grants full access to your Straddle account. Keep it secure and never share it publicly or include it in client-side code.

Straddle provides separate API keys for sandbox and production environments:

• Sandbox API Keys: Use these keys for development and testing.
• Production API Keys: Use these keys in production when you're ready to accept real transactions.

Tip: Always test your integration thoroughly using sandbox API keys before switching to production keys.

Follow these guidelines to keep your API keys secure:

1. Keep Secret Keys Confidential: Do not share your secret keys in emails, chat messages, or public repositories.
2. Use Environment Variables: Store keys securely using environment variables or a secrets management system.
3. Rotate Keys Regularly: Periodically rotate your API keys to reduce risk.
4. Monitor Usage: Regularly review your API logs in the Dashboard for any suspicious activity.

With authentication and environments configured, you can start making requests to Straddle's API. Keep reading to learn more.

The Straddle API provides responses with consistent structure to ensure readability and ease of integration. All API responses follow these conventions to ensure consistency and ease of integration across different client applications.

• Field Naming
  • Use snake_case for all field names
  • Use descriptive full words, except common acronyms (e.g., dob, SSN)
• Resource IDs
  • All IDs are UUIDs for cross-system uniqueness and compatibility
• Response Type (response_type)
  • "object": Single resource response
  • "array": List of resources, typically paginated
  • "error": Error response with details in error field
• Primary Data (data)
  • Contains main response payload
  • Holds resource(s) for "object" and "array" types
  • For "error" type, error details go in error field
• Meta Information (meta)
  • Standard fields:
    • api_request_id: Unique request identifier
    • api_request_timestamp: ISO 8601 request time (e.g., "2023-11-07T05:31:56Z")
  • Pagination fields (for "array" responses):
    • page_number: Current page
    • page_size: Items per page
    • total_items: Total available items
    • sort_order: "asc" or "desc"
    • sort_by: Sort field name

{
  "meta": {
    "api_request_id": "3a2b1c4d-0e6f-4a88-9876-123456abcdef",
    "api_request_timestamp": "2023-11-07T05:31:56Z"
  },
  "response_type": "object",
  "data": {
    "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "John Doe",
    "email": "[email protected]",
    "dob": "1990-01-01",
    "address": {
      "street": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701"
    }
  }
}

{
  "meta": {
    "api_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "api_request_timestamp": "2023-11-07T05:31:56Z",
    "page_number": 2,
    "page_size": 50,
    "total_items": 500,
    "sort_order": "asc",
    "sort_by": "name"
  },
  "response_type": "array",
  "data": [
    {
      "id": "c1b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
      "name": "John Doe",
      "email": "[email protected]"
    },
    {
      "id": "a9b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
      "name": "Steven Martin",
      "email": "[email protected]"
    }
  ]
}

{
  "meta": {
    "api_request_id": "f1b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b"
  },
  "response_type": "error",
  "error": {
    "status": 400,
    "type": "/field_validation",
    "title": "Invalid Input Data",
    "detail": "The request contains invalid field values.",
    "items": [
      {
        "reference": "customer.email",
        "detail": "Email address must be unique."
      }
    ]
  }
}

1. Check the response_type: Determine how to parse the response based on the response_type field.
2. Handle Pagination: Use pagination metadata to navigate through paginated data effectively.
3. Implement Robust Error Handling: Examine the error object in error responses to understand and address issues.
4. Log api_request_id: Record the api_request_id for each request to assist with troubleshooting and support.
5. Access Data via data Property: Retrieve the main payload from the data property for successful responses.
6. Synchronize Timestamps: Use api_request_timestamp for event logging and synchronization.
7. Consistent Parsing Logic: Apply a consistent parsing strategy across all responses for reliability.
8. Avoid Sensitive Data in Logs: When logging responses, ensure that sensitive information is excluded to maintain security.

By adhering to these practices, you can build a robust integration with the Straddle API that gracefully handles various response scenarios.

Metadata allows you to attach custom key-value pairs to Straddle objects like customers, charges, and payouts. Use metadata to store additional information important to your business that isn't captured by Straddle's standard fields.

Important: Do not confuse the metadata field with the meta object. The meta object contains system-level information about the API request, while metadata is for custom data you provide.

You can add metadata when creating or updating objects through the Straddle API. Here's how:

Include a metadata object in your request:

{
  "name": "John Doe",
  "type": "individual",
  "email": "[email protected]",
  "address": {
    "address1": "123 Main St",
    "address2": null,
    "type": "residential",
    "city": "Springfield",
    "state": "IL",
    "zip": "62701"
  },
  "phone": "+1234567890",
  "external_id": "CUS-123",
  "device": {
    "ip_address": "192.168.1.1"
  },
  "metadata": {
    "order_id": "6735",
    "customer_group": "premium"
  }
}

• Use Consistent Keys: Establish and follow a consistent naming convention for your metadata keys.
• Keep It Simple: Store simple key-value pairs. For complex data, store a reference ID in metadata and keep the full data in your own database.
• Avoid Sensitive Data: Do not store sensitive information like credit card numbers or social security numbers in metadata.

• Metadata keys and values must be 40 characters or fewer.
• You can have up to 20 key-value pairs in the metadata object.

Platforms building on Embed can make API calls on behalf of their embedded accounts, allowing you to perform actions for your users seamlessly. To issue requests as an embedded account, include the Straddle-Account-Id header with the embedded account's ID (prefixed with acct_) in each request. You can make API calls for your embedded accounts in two ways:

1. Server-side: Use the Straddle-Account-Id header with the embedded account ID in each request.
2. Client-side: Pass the Straddle-Account-Id as an argument when initializing the Straddle client library.

Note: To ensure optimal performance and reliability, Straddle enforces rate limits on API endpoints. These limits apply collectively to all requests made by your platform, including those made on behalf of embedded accounts.

When making server-side API calls, include the Straddle-Account-Id header with the embedded account's ID to execute requests on their behalf.

The following example demonstrates how to create a charge using your platform's secret API key and your user's account ID.

curl --request POST \
  --url https://api.straddle.io/v1/charges \
  --header 'Authorization: Bearer <your-secret-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Straddle-Account-Id: <uuid>' \
  --data '{
    "paykey": "<string>",
    "description": "<string>",
    "amount": 123,
    "currency": "<string>",
    "payment_date": "2023-12-25",
    "consent_type": "internet",
    "device": {
      "ip_address": "<string>"
    },
    "external_id": "<string>",
    "config": {
      "balance_check": "required"
    },
    "metadata": {}
  }'

To make client-side API calls on behalf of an embedded account, pass the embedded account ID when initializing the Straddle client. This feature is coming soon.

Warning: Exercise caution when making client-side requests as an embedded account. Ensure you are not exposing sensitive information or providing unnecessary permissions to the client.

Straddle uses standard HTTP status codes to indicate the success or failure of API requests. Understanding these codes and how to handle errors will help you build robust and user-friendly applications.

Here is a summary of the HTTP status and error codes that Straddle may return:

When an error occurs, Straddle returns an HTTP response with the appropriate status code and a JSON body containing an error object with details about the error.

When an error occurs, Straddle returns an HTTP response with the appropriate status code and a JSON body containing an error object with details about the error.

The error object includes the following attributes:

Here's an example of a validation error response:

{
  "meta": {
    "api_request_id": "3a2b1c4d-0e6f-4a88-9876-123456abcdef",
    "api_request_timestamp": "2023-11-07T05:31:56Z"
  },
  "response_type": "error",
  "error": {
    "status": 400,
    "type": "validation_error",
    "title": "Invalid Input Data",
    "detail": "The request contains invalid field values.",
    "items": [
      {
        "reference": "customer.email",
        "detail": "Email address must be unique."
      }
    ]
  }
}

• The error type is validation_error, indicating issues with the input data.
• The items array provides specific details about which field caused the error.