Create a charge

POST

charges

curl --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
  --url https://sandbox.straddle.io/v1/charges \
  --header 'Content-Type: application/json' \
  --data '{
  "paykey": "<string>",
  "description": "Monthly subscription fee",
  "amount": "10000",
  "currency": "<string>",
  "payment_date": "2019-12-27",
  "consent_type": "internet",
  "device": {
    "ip_address": "192.168.1.1"
  },
  "external_id": "<string>",
  "config": {
    "balance_check": "required"
  }
}'

{
  "meta": {
    "api_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "api_request_timestamp": "2023-11-07T05:31:56Z"
  },
  "response_type": "object",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "paykey": "<string>",
    "description": "Monthly subscription fee",
    "payment_rail": "ach",
    "paykey_details": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "label": "Bank of America ****1234",
      "balance": "100.00"
    },
    "customer_details": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "Ron Swanson",
      "customer_type": "individual",
      "email": "ron@swanson.com",
      "phone": "+1234567890"
    },
    "amount": "10000",
    "currency": "USD",
    "payment_date": "2023-12-25",
    "consent_type": "internet",
    "device": {
      "ip_address": "192.168.1.1"
    },
    "external_id": "<string>",
    "config": {
      "balance_check": "enabled"
    },
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "processed_at": "2023-11-07T05:31:56Z",
    "effective_at": "2023-11-07T05:31:56Z",
    "status": "created",
    "status_details": {
      "message": "Payment successfully created and awaiting validation.",
      "reason": "OK",
      "source": "system",
      "changed_at": "2023-11-07T05:31:56Z",
      "code": null
    },
    "status_history": [
      {
        "reason": "insufficient_funds",
        "source": "watchtower",
        "message": "Payment successfully created and awaiting validation.",
        "code": null,
        "changed_at": "2023-11-07T05:31:56Z",
        "status": "created"
      }
    ],
    "metadata": {},
    "funding_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ]
  }
}

Authorizations

Authorization

string

header

required

Use your Straddle API Key in the Authorization header as Bearer <token> to authorize API requests.

Headers

Straddle-Account-Id

string

For use by platforms to specify an account id and set scope of a request.

Request-Id

string

Optional client generated identifier to trace and debug a request.

Correlation-Id

string

Optional client generated identifier to trace and debug a series of requests.

Body

paykey

string

required

Value of the paykey used for the charge.

description

string

required

An arbitrary description for the charge.

Example:

"Monthly subscription fee"

amount

integer

required

The amount of the charge in cents.

Example:

"10000"

currency

string

default:USD

required

The currency of the charge. Only USD is supported.

payment_date

string

required

The desired date on which the payment should be occur. For charges, this means the date you want the customer to be debited on.

The channel or mechanism through which the payment was authorized. Use internet for payments made online or through a mobile app and signed for signed agreements where there is a consent form or contract. Use signed for PDF signatures.

Available options:

internet,

signed

device

object

required

external_id

string

required

Unique identifier for the charge in your database. This value must be unique across all charges.

config

object

required

metadata

object | null

Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the charge in a structured format.

Response

201

text/plain

Created

meta

object

required

Metadata about the API request, including an identifier and timestamp.

response_type

enum<string>

required

Indicates the structure of the returned content.

"object" means the data field contains a single JSON object.
"array" means the data field contains an array of objects.
"error" means the data field contains an error object with details of the issue.
"none" means no data is returned.

Available options:

object,

array,

error,

none

data

object

required

data.id

string

required

Unique identifier for the charge.

data.paykey

string

required

Value of the paykey used for the charge.

data.description

string

required

An arbitrary description for the charge.

Example:

"Monthly subscription fee"

data.amount

integer

required

The amount of the charge in cents.

Example:

"10000"

data.currency

string

default:USD

required

The currency of the charge. Only USD is supported.

data.payment_date

string

required

The desired date on which the payment should be occur. For charges, this means the date you want the customer to be debited on.

Available options:

internet,

signed

data.device

object

required

Information about the device used when the customer authorized the payment.

data.external_id

string

required

Unique identifier for the charge in your database. This value must be unique across all charges.

data.config

object

required

Configuration options for the charge.

data.created_at

string | null

required

Timestamp of when the charge was created.

data.updated_at

string | null

required

Timestamp of when the charge was last updated.

data.status

enum<string>

default:created

required

The current status of the charge.

Available options:

created,

scheduled,

failed,

cancelled,

on_hold,

pending,

paid,

reversed

data.status_details

object

required

Additional details about the current status of the charge.

data.status_history

object[]

required

Status history.

A record of the charge's status changes over time.

data.funding_ids

string[]

required

Funding Ids

data.payment_rail

enum<string>

The payment rail that the charge will be processed through.

Available options:

ach

data.paykey_details

object

Information about the paykey used for the charge.

data.customer_details

object

Information about the customer associated with the charge.

data.processed_at

string | null

Timestamp of when the charge was processed by Straddle and originated to the payment rail.

data.effective_at

string | null

Timestamp of when the charge was effective in the customer's bank account, otherwise known as the date on which the customer is debited.

data.metadata

object | null

Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the charge in a structured format.

Suggest edits Raise issue

Search paykeys

Update a charge

curl --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
  --url https://sandbox.straddle.io/v1/charges \
  --header 'Content-Type: application/json' \
  --data '{
  "paykey": "<string>",
  "description": "Monthly subscription fee",
  "amount": "10000",
  "currency": "<string>",
  "payment_date": "2019-12-27",
  "consent_type": "internet",
  "device": {
    "ip_address": "192.168.1.1"
  },
  "external_id": "<string>",
  "config": {
    "balance_check": "required"
  }
}'

{
  "meta": {
    "api_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "api_request_timestamp": "2023-11-07T05:31:56Z"
  },
  "response_type": "object",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "paykey": "<string>",
    "description": "Monthly subscription fee",
    "payment_rail": "ach",
    "paykey_details": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "label": "Bank of America ****1234",
      "balance": "100.00"
    },
    "customer_details": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "Ron Swanson",
      "customer_type": "individual",
      "email": "ron@swanson.com",
      "phone": "+1234567890"
    },
    "amount": "10000",
    "currency": "USD",
    "payment_date": "2023-12-25",
    "consent_type": "internet",
    "device": {
      "ip_address": "192.168.1.1"
    },
    "external_id": "<string>",
    "config": {
      "balance_check": "enabled"
    },
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "processed_at": "2023-11-07T05:31:56Z",
    "effective_at": "2023-11-07T05:31:56Z",
    "status": "created",
    "status_details": {
      "message": "Payment successfully created and awaiting validation.",
      "reason": "OK",
      "source": "system",
      "changed_at": "2023-11-07T05:31:56Z",
      "code": null
    },
    "status_history": [
      {
        "reason": "insufficient_funds",
        "source": "watchtower",
        "message": "Payment successfully created and awaiting validation.",
        "code": null,
        "changed_at": "2023-11-07T05:31:56Z",
        "status": "created"
      }
    ],
    "metadata": {},
    "funding_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ]
  }
}

Fundamentals

SDKs

Customers

Bridge

Paykeys

Charges

Payouts

Funding

Payments

Embed

Authorizations

Headers

Body

Response