v1.0.4
OpenAPI 3.1.1

Straddle API

Straddle

Introduction

The Straddle API uses resource URLs, standard HTTP methods, and JSON request and response bodies.

Environments

Sandbox and Production use separate base URLs and API keys. Use Sandbox for testing and development. Use Production for live transactions.

Environment Base URL Purpose
Sandbox https://sandbox.straddle.com Testing and development
Production https://production.straddle.com Live transactions

Use the API key issued for the request's environment. An API key from another environment does not authenticate the request.

Authentication

Straddle authenticates API requests with JWT bearer tokens. Send your secret API key in the Authorization header:

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

Idempotent requests

Use idempotency to retry a request without performing the same operation twice. Send a unique Idempotency-Key header with the request.

After Straddle processes a request successfully, an identical request with the same key returns the original status code, headers, and body without repeating the operation.

Request headers

Send a unique string of 10 to 40 characters in the Idempotency-Key header.

Header Type Description
Idempotency-Key string A unique identifier for the request. The value must contain 10 to 40 characters.

Response headers

A successfully replayed request returns the original HTTP status code, response headers, and body. The response also includes:

Header Type Description
Idempotent-Replayed boolean true when the response replays a previously successful request.

Idempotency errors

The API returns these errors for invalid or conflicting idempotency keys:

Status Code Error Type Description
400 Bad Request The Idempotency-Key value is shorter than 10 characters or longer than 40 characters.
409 Conflict The key was used for a different request, or an identical request with the key is still in progress.

Key reused for a different request

A request returns 409 Conflict when its Idempotency-Key was used for a request with a different path, method, or body.

{
  "status": 409,
  "type": "/conflict",
  "title": "Conflict",
  "detail": "Idempotency key already used for a different request."
}

Identical request still in progress

An identical request returns 409 Conflict when another request with the same Idempotency-Key is still in progress.

{
  "status": 409,
  "type": "/conflict",
  "title": "Conflict",
  "detail": "Previous identical request currently in progress."
}

Invalid key length

A request returns 400 Bad Request when its Idempotency-Key is shorter than 10 characters or longer than 40 characters.

{
  "status": 400,
  "type": "/bad-request",
  "title": "Bad Request",
  "detail": "The Idempotency-Key header is invalid. It must be between 10 and 40 characters long."
}

Example request

curl -X POST https://sandbox.straddle.com/v1/charges \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-client-key-7890" \
-d '{
  "amount": 100.00,
  "currency": "USD"
}'

Idempotency applies only to authenticated POST, PUT, PATCH, and DELETE requests.

Response structure

API responses use a JSON envelope. Every envelope has meta and response_type. Other fields depend on the response type.

  • Field names

    • Fields use snake_case.
    • Resource identifiers use UUIDs.

  • response_type

    • "object" means data contains one JSON object.
    • "array" means data contains an array of JSON objects.
    • "error" means error contains the error details.
    • "none" means the response contains no data.

  • data

    • Successful object and array responses contain the requested resource data.

  • error

    • Error responses contain the error details.

  • meta

    • api_request_id is the unique identifier for the API request.
    • api_request_timestamp is the ISO 8601 timestamp for the API request.
    • Paginated array responses also include page_number, page_size, total_items, sort_order, and sort_by.

Examples

Object response

{
  "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": "john.doe@example.com",
    "dob": "1990-01-01",
    "address": {
      "street": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701"
    }
  }
}

Paginated array response

{
  "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": "john.doe@example.com"
    },
    {
      "id": "a9b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
      "name": "Steven Martin",
      "email": "steven.martin@example.com"
    }
  ]
}

Error response

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

Metadata

The metadata field stores user-defined key-value pairs on supported Straddle objects.

metadata contains custom data that you provide. It is separate from the response meta object, which contains information about the API request.

Add metadata

Include metadata when you create or update an object that supports the field.

Customer request example

This customer request includes two metadata entries:

{
  "name": "John Doe",
  "type": "individual",
  "email": "john@example.com",
  "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"
  }
}

Limits

  • Keys and values can contain at most 40 characters.
  • The metadata object can contain at most 20 entries.

Embedded accounts

Platforms can send requests in the scope of an embedded account. Send the embedded account's UUID in the Straddle-Account-Id header.

Send a request for an embedded account

Include Straddle-Account-Id with the embedded account UUID. Authenticate the request with the platform's secret API key.

Example charge request

This request creates a charge in the embedded account's scope.

curl --request POST \
  --url https://sandbox.straddle.com/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": {}
  }'

Errors

HTTP status codes indicate whether the API completed a request. Error responses include a JSON error object.

Common status codes include:

Status Code Type Description
200 OK The request completed successfully.
400 Bad Request The request is invalid.
401 Unauthorized The request does not include a valid API key.
403 Forbidden The API key does not have permission to perform the request.
404 Not Found The requested resource does not exist.
409 Conflict The request conflicts with an existing request or operation.
422 Unprocessable Entity The request syntax is valid, but one or more values cannot be processed.
429 Too Many Requests The request exceeded a rate limit.
500, 502, 503, 504 Server Error Straddle could not complete the request because of a server error.

Error response structure

Error responses use the standard response envelope. The error object has these fields:

Attribute Type Description
status integer HTTP status code for the error.
type string Identifier for the error type.
title string Short summary of the error.
detail string Explanation specific to this request.
items array Additional error details, when available.
items[].reference string Request field or error code associated with the detail.
items[].detail string Explanation of the error detail.

Example error response

This example shows a field-validation error:

{
  "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."
      }
    ]
  }
}
Server:https://{environment}.straddle.com

Straddle API server

Client Libraries
npm install @straddlecom/straddle

Customers (Collapsed)

​

Customers are individuals or businesses that send or receive payments through your integration.

Customers Operations

Bridge (Collapsed)

​

Bridge connects customer bank accounts and creates paykeys from supported provider tokens or bank account details.

Bridge Operations

Paykeys (Collapsed)

​

A paykey links a verified customer to a bank account without exposing bank account details. Use a paykey to create charges and payouts.

Paykeys Operations

Funding events (Collapsed)

​

Funding events group charge and payout activity into transfers between Straddle and your linked bank account.

Funding events Operations

Payments (Collapsed)

​

Payments provide a combined view of charges and payouts.

Payments Operations

Organizations (Collapsed)

​

Organizations group related Straddle accounts.

Organizations Operations

Accounts (Collapsed)

​

Accounts represent businesses that use Straddle through a platform.

Accounts Operations

Representatives (Collapsed)

​

Representatives are people associated with a business account for ownership, control, or authorization purposes.

Representatives Operations

Linked bank accounts (Collapsed)

​

Linked bank accounts connect external bank accounts to an account or platform for charges, payouts, or billing.

Linked bank accounts Operations

Capabilities (Collapsed)

​

Capability requests change the payment, customer, and consent types available to an account.

Capabilities Operations

Account settings (Collapsed)

​

Account settings define payment limits, capabilities, statement details, and policy controls for an account.

Account settings Operations

Webhooks (Collapsed)

​
Webhooks Webhooks
Webhook

Webhook event: account.created.v1

​

Straddle sends this event when a platform creates an account. The data field contains the account.

Body

required
application/json

Payload for the account.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 14
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postaccount.created.v1
{
  "event_type": "account.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "organization_id": "",
    "type": "business",
    "status": "created",
    "status_detail": {
      "reason": "unverified",
      "source": "watchtower",
      "code": "",
      "message": ""
    },
    "business_profile": {
      "name": "",
      "website": "",
      "legal_name": null,
      "description": null,
      "use_case": null,
      "tax_id": null,
      "phone": null,
      "address": {
        "line1": null,
        "line2": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": null
      },
      "industry": {
        "mcc": null,
        "sector": null,
        "category": null
      },
      "support_channels": {
        "email": null,
        "phone": null,
        "url": null
      }
    },
    "capabilities": {
      "payment_types": {
        "charges": {
          "capability_status": "active"
        },
        "payouts": {
          "capability_status": "active"
        }
      },
      "customer_types": {
        "individuals": {
          "capability_status": "active"
        },
        "businesses": {
          "capability_status": "active"
        }
      },
      "consent_types": {
        "signed_agreement": {
          "capability_status": "active"
        },
        "internet": {
          "capability_status": "active"
        }
      }
    },
    "settings": {
      "charges": {
        "max_amount": 1,
        "monthly_amount": 1,
        "daily_amount": 1,
        "monthly_count": 1,
        "funding_time": "immediate",
        "linked_bank_account_id": ""
      },
      "payouts": {
        "max_amount": 1,
        "monthly_amount": 1,
        "daily_amount": 1,
        "monthly_count": 1,
        "funding_time": "immediate",
        "linked_bank_account_id": ""
      }
    },
    "terms_of_service": {
      "accepted_date": "",
      "accepted_ip": null,
      "accepted_user_agent": null,
      "agreement_url": null,
      "agreement_type": "embedded"
    },
    "metadata": null,
    "access_level": "standard",
    "external_id": null,
    "created_at": null,
    "updated_at": null
  }
}
No Body

Webhook received.

Webhook

Webhook event: account.event.v1

​

Straddle sends this event when an account changes, including updates to its profile, status, settings, limits, or capabilities. The data field contains the updated account.

Body

required
application/json

Payload for the account.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 14
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postaccount.event.v1
{
  "event_type": "account.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "organization_id": "",
    "type": "business",
    "status": "created",
    "status_detail": {
      "reason": "unverified",
      "source": "watchtower",
      "code": "",
      "message": ""
    },
    "business_profile": {
      "name": "",
      "website": "",
      "legal_name": null,
      "description": null,
      "use_case": null,
      "tax_id": null,
      "phone": null,
      "address": {
        "line1": null,
        "line2": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": null
      },
      "industry": {
        "mcc": null,
        "sector": null,
        "category": null
      },
      "support_channels": {
        "email": null,
        "phone": null,
        "url": null
      }
    },
    "capabilities": {
      "payment_types": {
        "charges": {
          "capability_status": "active"
        },
        "payouts": {
          "capability_status": "active"
        }
      },
      "customer_types": {
        "individuals": {
          "capability_status": "active"
        },
        "businesses": {
          "capability_status": "active"
        }
      },
      "consent_types": {
        "signed_agreement": {
          "capability_status": "active"
        },
        "internet": {
          "capability_status": "active"
        }
      }
    },
    "settings": {
      "charges": {
        "max_amount": 1,
        "monthly_amount": 1,
        "daily_amount": 1,
        "monthly_count": 1,
        "funding_time": "immediate",
        "linked_bank_account_id": ""
      },
      "payouts": {
        "max_amount": 1,
        "monthly_amount": 1,
        "daily_amount": 1,
        "monthly_count": 1,
        "funding_time": "immediate",
        "linked_bank_account_id": ""
      }
    },
    "terms_of_service": {
      "accepted_date": "",
      "accepted_ip": null,
      "accepted_user_agent": null,
      "agreement_url": null,
      "agreement_type": "embedded"
    },
    "metadata": null,
    "access_level": "standard",
    "external_id": null,
    "created_at": null,
    "updated_at": null
  }
}
No Body

Webhook received.

Webhook

Webhook event: representative.event.v1

​

Straddle sends this event when a representative's status or fields change. The data field contains the updated representative.

Body

required
application/json

Payload for the representative.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 18
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postrepresentative.event.v1
{
  "event_type": "representative.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "account_id": "",
    "user_id": null,
    "status": "created",
    "status_detail": {
      "reason": "unverified",
      "source": "watchtower",
      "code": "",
      "message": ""
    },
    "first_name": "Ron",
    "last_name": "Swanson",
    "dob": "1980-01-01",
    "ssn_last4": "1234",
    "email": "ron.swanson@pawnee.com",
    "mobile_number": "+12128675309",
    "relationship": {
      "primary": true,
      "control": true,
      "owner": true,
      "percent_ownership": null,
      "title": null
    },
    "external_id": null,
    "created_at": "",
    "updated_at": "",
    "name": "",
    "phone": null,
    "metadata": null
  }
}
No Body

Webhook received.

Webhook

Webhook event: representative.created.v1

​

Straddle sends this event when a platform creates a representative. The data field contains the representative.

Body

required
application/json

Payload for the representative.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 18
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postrepresentative.created.v1
{
  "event_type": "representative.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "account_id": "",
    "user_id": null,
    "status": "created",
    "status_detail": {
      "reason": "unverified",
      "source": "watchtower",
      "code": "",
      "message": ""
    },
    "first_name": "Ron",
    "last_name": "Swanson",
    "dob": "1980-01-01",
    "ssn_last4": "1234",
    "email": "ron.swanson@pawnee.com",
    "mobile_number": "+12128675309",
    "relationship": {
      "primary": true,
      "control": true,
      "owner": true,
      "percent_ownership": null,
      "title": null
    },
    "external_id": null,
    "created_at": "",
    "updated_at": "",
    "name": "",
    "phone": null,
    "metadata": null
  }
}
No Body

Webhook received.

Webhook

Webhook event: linked_bank_account.event.v1

​

Straddle sends this event when a linked bank account's status or fields change. The data field contains the updated linked bank account.

Body

required
application/json

Payload for the linked_bank_account.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 11
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postlinked_bank_account.event.v1
{
  "event_type": "linked_bank_account.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "account_id": null,
    "status": "created",
    "status_detail": {
      "reason": "unverified",
      "source": "watchtower",
      "code": "",
      "message": ""
    },
    "bank_account": {
      "institution_name": "",
      "account_holder": "",
      "routing_number": "",
      "account_mask": ""
    },
    "metadata": null,
    "created_at": "",
    "updated_at": "",
    "platform_id": null,
    "purposes": [
      "charges"
    ],
    "description": null
  }
}
No Body

Webhook received.

Webhook

Webhook event: linked_bank_account.created.v1

​

Straddle sends this event when a platform creates a linked bank account. The data field contains the linked bank account.

Body

required
application/json

Payload for the linked_bank_account.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 11
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postlinked_bank_account.created.v1
{
  "event_type": "linked_bank_account.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "account_id": null,
    "status": "created",
    "status_detail": {
      "reason": "unverified",
      "source": "watchtower",
      "code": "",
      "message": ""
    },
    "bank_account": {
      "institution_name": "",
      "account_holder": "",
      "routing_number": "",
      "account_mask": ""
    },
    "metadata": null,
    "created_at": "",
    "updated_at": "",
    "platform_id": null,
    "purposes": [
      "charges"
    ],
    "description": null
  }
}
No Body

Webhook received.

Webhook

Webhook event: capability_request.event.v1

​

Straddle sends this event when a capability request's status or fields change. The data field contains the updated capability request.

Body

required
application/json

Payload for the capability_request.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 9
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postcapability_request.event.v1
{
  "event_type": "capability_request.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "account_id": "",
    "type": "charges",
    "category": "payment_type",
    "settings": null,
    "status": "active",
    "created_at": "",
    "updated_at": "",
    "enable": true
  }
}
No Body

Webhook received.

Webhook

Webhook event: capability_request.created.v1

​

Straddle sends this event when a platform creates a capability request. The data field contains the capability request.

Body

required
application/json

Payload for the capability_request.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 9
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postcapability_request.created.v1
{
  "event_type": "capability_request.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "account_id": "",
    "type": "charges",
    "category": "payment_type",
    "settings": null,
    "status": "active",
    "created_at": "",
    "updated_at": "",
    "enable": true
  }
}
No Body

Webhook received.

Webhook

Webhook event: customer.event.v1

​

Reports changes to a customer's profile or status, including verification, compliance, and risk updates.

Body

required
application/json

Payload for the customer.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 13
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postcustomer.event.v1
{
  "event_type": "customer.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "address": {
      "address1": "",
      "address2": null,
      "city": "",
      "state": "",
      "zip": ""
    },
    "compliance_profile": {
      "dob": null,
      "ssn": null,
      "ein": null,
      "legal_business_name": null,
      "website": null
    },
    "device": {
      "ip_address": "**.**.**.**"
    },
    "name": "",
    "type": "individual",
    "email": "",
    "phone": "",
    "external_id": null,
    "status": "pending",
    "created_at": "",
    "updated_at": "",
    "metadata": null
  }
}
No Body

Webhook received.

Webhook

Webhook event: customer.created.v1

​

Reports the creation of a customer. The payload includes the customer profile and initial verification status.

Body

required
application/json

Payload for the customer.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 13
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postcustomer.created.v1
{
  "event_type": "customer.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "address": {
      "address1": "",
      "address2": null,
      "city": "",
      "state": "",
      "zip": ""
    },
    "compliance_profile": {
      "dob": null,
      "ssn": null,
      "ein": null,
      "legal_business_name": null,
      "website": null
    },
    "device": {
      "ip_address": "**.**.**.**"
    },
    "name": "",
    "type": "individual",
    "email": "",
    "phone": "",
    "external_id": null,
    "status": "pending",
    "created_at": "",
    "updated_at": "",
    "metadata": null
  }
}
No Body

Webhook received.

Webhook

Webhook event: paykey.event.v1

​

Reports changes to a paykey's status, verification result, balance, or bank account details.

Body

required
application/json

Payload for the paykey.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 14
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postpaykey.event.v1
{
  "event_type": "paykey.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "customer_id": null,
    "label": "",
    "source": "bank_account",
    "institution_name": null,
    "status": "pending",
    "status_details": {
      "message": "",
      "reason": "insufficient_funds",
      "source": "watchtower",
      "code": null,
      "changed_at": ""
    },
    "expires_at": null,
    "created_at": "",
    "updated_at": "",
    "paykey": "",
    "bank_data": {
      "routing_number": "",
      "account_number": "",
      "account_type": "checking"
    },
    "metadata": null,
    "balance": {
      "account_balance": null,
      "updated_at": null,
      "status": "pending"
    }
  }
}
No Body

Webhook received.

Webhook

Webhook event: paykey.created.v1

​

Reports the creation of a paykey that links a customer to a bank account. The payload includes the paykey's status and bank account details.

Body

required
application/json

Payload for the paykey.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 14
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postpaykey.created.v1
{
  "event_type": "paykey.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "customer_id": null,
    "label": "",
    "source": "bank_account",
    "institution_name": null,
    "status": "pending",
    "status_details": {
      "message": "",
      "reason": "insufficient_funds",
      "source": "watchtower",
      "code": null,
      "changed_at": ""
    },
    "expires_at": null,
    "created_at": "",
    "updated_at": "",
    "paykey": "",
    "bank_data": {
      "routing_number": "",
      "account_number": "",
      "account_type": "checking"
    },
    "metadata": null,
    "balance": {
      "account_balance": null,
      "updated_at": null,
      "status": "pending"
    }
  }
}
No Body

Webhook received.

Webhook

Webhook event: charge.created.v1

​

Sent when a charge is created. The payload contains the charge's current details.

Body

required
application/json

Payload for the charge.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 27
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postcharge.created.v1
{
  "event_type": "charge.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "paykey": "",
    "description": null,
    "payment_rail": "ach",
    "paykey_details": {
      "id": "",
      "customer_id": "",
      "label": "",
      "balance": null
    },
    "customer_details": {
      "id": "",
      "name": "",
      "email": "",
      "phone": "",
      "customer_type": "individual"
    },
    "amount": 1,
    "currency": "",
    "payment_date": "",
    "consent_type": "internet",
    "device": {
      "ip_address": "**.**.**.**"
    },
    "external_id": null,
    "config": {
      "balance_check": "required"
    },
    "created_at": null,
    "updated_at": null,
    "processed_at": null,
    "effective_at": null,
    "status": "created",
    "status_details": {
      "message": "",
      "reason": "insufficient_funds",
      "source": "watchtower",
      "code": null,
      "changed_at": ""
    },
    "status_history": [
      {
        "reason": "insufficient_funds",
        "source": "watchtower",
        "message": "",
        "code": null,
        "changed_at": "",
        "status": "created"
      }
    ],
    "metadata": null,
    "funding_ids": [
      ""
    ],
    "related_payments": [
      {
        "id": "019e1bab-2ab4-751d-be80-f51c82c2ea64",
        "relationship": "original",
        "payment_type": "charge"
      }
    ],
    "is_resubmit": true,
    "has_resubmit": true,
    "has_refund": true,
    "documents": [
      {
        "document_id": "",
        "document_name": "",
        "document_type": "payment_authorization",
        "document_size": 1,
        "uploaded_at": ""
      }
    ]
  }
}
No Body

Webhook received.

Webhook

Webhook event: charge.event.v1

​

Sent when a charge is created or its status changes. The payload contains the charge's current details.

Body

required
application/json

Payload for the charge.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 27
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postcharge.event.v1
{
  "event_type": "charge.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "paykey": "",
    "description": null,
    "payment_rail": "ach",
    "paykey_details": {
      "id": "",
      "customer_id": "",
      "label": "",
      "balance": null
    },
    "customer_details": {
      "id": "",
      "name": "",
      "email": "",
      "phone": "",
      "customer_type": "individual"
    },
    "amount": 1,
    "currency": "",
    "payment_date": "",
    "consent_type": "internet",
    "device": {
      "ip_address": "**.**.**.**"
    },
    "external_id": null,
    "config": {
      "balance_check": "required"
    },
    "created_at": null,
    "updated_at": null,
    "processed_at": null,
    "effective_at": null,
    "status": "created",
    "status_details": {
      "message": "",
      "reason": "insufficient_funds",
      "source": "watchtower",
      "code": null,
      "changed_at": ""
    },
    "status_history": [
      {
        "reason": "insufficient_funds",
        "source": "watchtower",
        "message": "",
        "code": null,
        "changed_at": "",
        "status": "created"
      }
    ],
    "metadata": null,
    "funding_ids": [
      ""
    ],
    "related_payments": [
      {
        "id": "019e1bab-2ab4-751d-be80-f51c82c2ea64",
        "relationship": "original",
        "payment_type": "charge"
      }
    ],
    "is_resubmit": true,
    "has_resubmit": true,
    "has_refund": true,
    "documents": [
      {
        "document_id": "",
        "document_name": "",
        "document_type": "payment_authorization",
        "document_size": 1,
        "uploaded_at": ""
      }
    ]
  }
}
No Body

Webhook received.

Webhook

Webhook event: payout.created.v1

​

Sent when a payout is created. The payload contains the payout's current details.

Body

required
application/json

Payload for the payout.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 27
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postpayout.created.v1
{
  "event_type": "payout.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "paykey": "",
    "description": null,
    "payment_rail": "ach",
    "paykey_details": {
      "id": "",
      "customer_id": "",
      "label": "",
      "balance": null
    },
    "customer_details": {
      "id": "",
      "name": "",
      "email": "",
      "phone": "",
      "customer_type": "individual"
    },
    "amount": 1,
    "currency": "",
    "payment_date": "",
    "consent_type": "internet",
    "device": {
      "ip_address": "**.**.**.**"
    },
    "external_id": null,
    "config": {},
    "created_at": null,
    "updated_at": null,
    "processed_at": null,
    "effective_at": null,
    "status": "created",
    "status_details": {
      "message": "",
      "reason": "insufficient_funds",
      "source": "watchtower",
      "code": null,
      "changed_at": ""
    },
    "status_history": [
      {
        "reason": "insufficient_funds",
        "source": "watchtower",
        "message": "",
        "code": null,
        "changed_at": "",
        "status": "created"
      }
    ],
    "metadata": null,
    "funding_ids": [
      ""
    ],
    "related_payments": [
      {
        "id": "019e1bab-2ab4-751d-be80-f51c82c2ea64",
        "relationship": "original",
        "payment_type": "charge"
      }
    ],
    "is_resubmit": true,
    "has_resubmit": true,
    "is_refund": true,
    "documents": [
      {
        "document_id": "",
        "document_name": "",
        "document_type": "payment_authorization",
        "document_size": 1,
        "uploaded_at": ""
      }
    ]
  }
}
No Body

Webhook received.

Webhook

Webhook event: payout.event.v1

​

Sent when a payout is created or its status changes. The payload contains the payout's current details.

Body

required
application/json

Payload for the payout.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 27
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postpayout.event.v1
{
  "event_type": "payout.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "paykey": "",
    "description": null,
    "payment_rail": "ach",
    "paykey_details": {
      "id": "",
      "customer_id": "",
      "label": "",
      "balance": null
    },
    "customer_details": {
      "id": "",
      "name": "",
      "email": "",
      "phone": "",
      "customer_type": "individual"
    },
    "amount": 1,
    "currency": "",
    "payment_date": "",
    "consent_type": "internet",
    "device": {
      "ip_address": "**.**.**.**"
    },
    "external_id": null,
    "config": {},
    "created_at": null,
    "updated_at": null,
    "processed_at": null,
    "effective_at": null,
    "status": "created",
    "status_details": {
      "message": "",
      "reason": "insufficient_funds",
      "source": "watchtower",
      "code": null,
      "changed_at": ""
    },
    "status_history": [
      {
        "reason": "insufficient_funds",
        "source": "watchtower",
        "message": "",
        "code": null,
        "changed_at": "",
        "status": "created"
      }
    ],
    "metadata": null,
    "funding_ids": [
      ""
    ],
    "related_payments": [
      {
        "id": "019e1bab-2ab4-751d-be80-f51c82c2ea64",
        "relationship": "original",
        "payment_type": "charge"
      }
    ],
    "is_resubmit": true,
    "has_resubmit": true,
    "is_refund": true,
    "documents": [
      {
        "document_id": "",
        "document_name": "",
        "document_type": "payment_authorization",
        "document_size": 1,
        "uploaded_at": ""
      }
    ]
  }
}
No Body

Webhook received.

Webhook

Webhook event: platform.event.v1

​

Fired when a platform is created. This webhook is only supposed to be consumed by Straddle.

Body

required
application/json

Payload for the platform.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 8
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postplatform.event.v1
{
  "event_type": "platform.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "status": "created",
    "status_detail": {
      "reason": "unverified",
      "source": "watchtower",
      "code": "",
      "message": ""
    },
    "business_profile": {
      "name": "",
      "website": "",
      "legal_name": null,
      "description": null,
      "use_case": null,
      "tax_id": null,
      "phone": null,
      "address": {
        "line1": null,
        "line2": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": null
      },
      "industry": {
        "mcc": null,
        "sector": null,
        "category": null
      },
      "support_channels": {
        "email": null,
        "phone": null,
        "url": null
      }
    },
    "metadata": null,
    "external_id": null,
    "created_at": null,
    "updated_at": null
  }
}
No Body

Webhook received.

Webhook

Webhook event: platform.created.v1

​

Triggered when any significant change occurs to a platform. This webhook is only supposed to be consumed by Straddle.

Body

required
application/json

Payload for the platform.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 8
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postplatform.created.v1
{
  "event_type": "platform.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "status": "created",
    "status_detail": {
      "reason": "unverified",
      "source": "watchtower",
      "code": "",
      "message": ""
    },
    "business_profile": {
      "name": "",
      "website": "",
      "legal_name": null,
      "description": null,
      "use_case": null,
      "tax_id": null,
      "phone": null,
      "address": {
        "line1": null,
        "line2": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": null
      },
      "industry": {
        "mcc": null,
        "sector": null,
        "category": null
      },
      "support_channels": {
        "email": null,
        "phone": null,
        "url": null
      }
    },
    "metadata": null,
    "external_id": null,
    "created_at": null,
    "updated_at": null
  }
}
No Body

Webhook received.

Webhook

Webhook event: user.event.v1

​

Fired when a user is created. This webhook is only supposed to be consumed by Straddle.

Body

required
application/json

Payload for the user.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 13
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postuser.event.v1
{
  "event_type": "user.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "organization_id": null,
    "platform_id": null,
    "authenticator_id": null,
    "status": "invited",
    "first_name": "",
    "last_name": "",
    "email": "",
    "level": "none",
    "roles": [
      "none"
    ],
    "created_at": "",
    "updated_at": "",
    "memberships": [
      {
        "level": "none",
        "entity_id": null,
        "entity_name": "",
        "roles": [
          "none"
        ],
        "authenticator_organization_id": ""
      }
    ]
  }
}
No Body

Webhook received.

Webhook

Webhook event: user.created.v1

​

Triggered when any significant change occurs to a user. This webhook is only supposed to be consumed by Straddle.

Body

required
application/json

Payload for the user.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 13
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postuser.created.v1
{
  "event_type": "user.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "organization_id": null,
    "platform_id": null,
    "authenticator_id": null,
    "status": "invited",
    "first_name": "",
    "last_name": "",
    "email": "",
    "level": "none",
    "roles": [
      "none"
    ],
    "created_at": "",
    "updated_at": "",
    "memberships": [
      {
        "level": "none",
        "entity_id": null,
        "entity_name": "",
        "roles": [
          "none"
        ],
        "authenticator_organization_id": ""
      }
    ]
  }
}
No Body

Webhook received.

Webhook

Webhook event: funding_event.created.v1

​

Straddle sends this webhook when it creates a funding event. The payload includes the amount, transfer direction, event type, and initial status.

Body

required
application/json

Payload for the funding_event.created.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 12
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postfunding_event.created.v1
{
  "event_type": "funding_event.created.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "amount": 1,
    "direction": "deposit",
    "event_type": "charge_deposit",
    "trace_ids": {
      "additionalProperty": ""
    },
    "payment_count": 1,
    "transfer_date": "",
    "created_at": "",
    "updated_at": "",
    "status": "created",
    "status_details": {
      "message": "",
      "reason": "insufficient_funds",
      "source": "watchtower",
      "code": null,
      "changed_at": ""
    },
    "status_history": [
      {
        "reason": "insufficient_funds",
        "source": "watchtower",
        "message": "",
        "code": null,
        "changed_at": "",
        "status": "created"
      }
    ]
  }
}
No Body

Webhook received.

Webhook

Webhook event: funding_event.event.v1

​

Straddle sends this webhook when it creates or updates a funding event. The payload includes the current status and complete status history.

Body

required
application/json

Payload for the funding_event.event.v1 event.

  • account_id
    Type: stringFormat: uuid
    required

    Unique identifier for the account associated with this event.

  • data
    Type:
    required
    Properties: 12
  • event_id
    Type: stringFormat: uuid
    required

    Unique identifier for this event.

  • event_type
    Type: string
    required

    Type of this event.

Responses

  • 200

    Webhook received.

Request Example for postfunding_event.event.v1
{
  "event_type": "funding_event.event.v1",
  "event_id": "85df84c7-a298-44bc-8040-7bd2ae372cbf",
  "account_id": "857c679a-8e80-47f1-9334-39dd08ea801f",
  "data": {
    "id": "",
    "amount": 1,
    "direction": "deposit",
    "event_type": "charge_deposit",
    "trace_ids": {
      "additionalProperty": ""
    },
    "payment_count": 1,
    "transfer_date": "",
    "created_at": "",
    "updated_at": "",
    "status": "created",
    "status_details": {
      "message": "",
      "reason": "insufficient_funds",
      "source": "watchtower",
      "code": null,
      "changed_at": ""
    },
    "status_history": [
      {
        "reason": "insufficient_funds",
        "source": "watchtower",
        "message": "",
        "code": null,
        "changed_at": "",
        "status": "created"
      }
    ]
  }
}
No Body

Webhook received.

Models