Create a charge - Straddle Docs

cURL

curl --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
  --url https://sandbox.straddle.com/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"
  },
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "paykey": "<string>",
    "description": "Monthly subscription fee",
    "amount": "10000",
    "currency": "USD",
    "payment_date": "2023-12-25",
    "device": {
      "ip_address": "192.168.1.1"
    },
    "external_id": "<string>",
    "config": {
      "balance_check": "enabled",
      "auto_hold": true,
      "auto_hold_message": "<string>"
    },
    "created_at": "2023-11-07T05:31:56Z",
    "updated_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": [
      {
        "message": "Payment successfully created and awaiting validation.",
        "changed_at": "2023-11-07T05:31:56Z",
        "status": "created",
        "code": null
      }
    ],
    "funding_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "trace_ids": {},
    "has_refund": true,
    "is_resubmit": true,
    "has_resubmit": true,
    "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",
      "email": "[email protected]",
      "phone": "+1234567890"
    },
    "processed_at": "2023-11-07T05:31:56Z",
    "effective_at": "2023-11-07T05:31:56Z",
    "metadata": {},
    "related_payments": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ]
  }
}

POST

charges

cURL

curl --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
  --url https://sandbox.straddle.com/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"
  },
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "paykey": "<string>",
    "description": "Monthly subscription fee",
    "amount": "10000",
    "currency": "USD",
    "payment_date": "2023-12-25",
    "device": {
      "ip_address": "192.168.1.1"
    },
    "external_id": "<string>",
    "config": {
      "balance_check": "enabled",
      "auto_hold": true,
      "auto_hold_message": "<string>"
    },
    "created_at": "2023-11-07T05:31:56Z",
    "updated_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": [
      {
        "message": "Payment successfully created and awaiting validation.",
        "changed_at": "2023-11-07T05:31:56Z",
        "status": "created",
        "code": null
      }
    ],
    "funding_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "trace_ids": {},
    "has_refund": true,
    "is_resubmit": true,
    "has_resubmit": true,
    "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",
      "email": "[email protected]",
      "phone": "+1234567890"
    },
    "processed_at": "2023-11-07T05:31:56Z",
    "effective_at": "2023-11-07T05:31:56Z",
    "metadata": {},
    "related_payments": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ]
  }
}

In ACH terminology, Straddle charges are ACH debit transactions that pull money from customer bank accounts. Learn more about ACH debits and authorization requirements to ensure compliant payment collection.

Authorizations

Authorization

string

header

required

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

Headers

Straddle-Account-Id

string<uuid>

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.

Idempotency-Key

string

Optional client generated value to use for idempotent requests.

Required string length: 10 - 40

Body

paykey

string

required

Value of the paykey used for the charge.

description

string | null

required

An arbitrary description for the charge.

Example:

"Monthly subscription fee"

amount

integer<int32>

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<date>

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

Show child attributes

external_id

string

required

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

config

object

required

Show child attributes

metadata

object

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

Show child attributes

Response

Created