Charge

Create a charge

Changed on

Use charges to collect money from a customer for the sale of goods or services.

post/v1/charges

Request

  • Base URL
    https://sandbox.straddle.com
  • URL
    https://sandbox.straddle.com/v1/charges
  • Auth
    HTTP bearer

Headers

Straddle-Account-Idstring uuid

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

Request-Idstring

Optional client generated identifier to trace and debug a request.

Correlation-Idstring

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

Idempotency-Keystring

Optional client generated value to use for idempotent requests.

Request body

paykeystring required

Value of the paykey used for the charge.

descriptionstring nullable required

An arbitrary description for the charge.

amountinteger required

The amount of the charge in cents.

currencystring required

The currency of the charge. Only USD is supported.

payment_datestring 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.

consent_type'internet' | 'signed' required

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.

external_idstring required

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

metadataobject nullable

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

Example request

{
  "description": "Monthly subscription fee",
  "device": {
    "ip_address": "192.168.1.1"
  }
}

Response

Created

response_type'object' | 'array' | 'error' | 'none' 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.

Example response

{
  "data": {
    "description": "Monthly subscription fee",
    "paykey_details": {
      "label": "Bank of America ****1234"
    },
    "customer_details": {
      "name": "Ron Swanson",
      "email": "ron@swanson.com",
      "phone": "+1234567890"
    },
    "device": {
      "ip_address": "192.168.1.1"
    },
    "status_details": {
      "message": "Payment successfully created and awaiting validation."
    },
    "status_history": [
      {
        "message": "Payment successfully created and awaiting validation."
      }
    ]
  }
}

Changes

  • de39a60c562eRevision changes
    • breaking

      the / response's property type changed from object to array for status (media type: text/plain)

    • breaking

      the / response's property type changed from object to array for status (media type: application/json)

    • breaking

      the / response's property type changed from object to array for status (media type: text/json)

    • warning

      added the new failed_not_authorized enum value to the // response property for the response status (media type: text/plain)

    • warning

      added the new failed_not_authorized enum value to the // response property for the response status (media type: application/json)

    • warning

      added the new failed_not_authorized enum value to the // response property for the response status (media type: text/json)

    • warning

      added the new reversed_not_authorized enum value to the // response property for the response status (media type: text/plain)

    • warning

      added the new reversed_not_authorized enum value to the // response property for the response status (media type: application/json)

    • warning

      added the new reversed_not_authorized enum value to the // response property for the response status (media type: text/json)

    • info

      added the new failed_not_authorized enum value to the request property / (media type: application/json)

    • info

      added the new failed_not_authorized enum value to the request property / (media type: text/json)

    • info

      added the new failed_not_authorized enum value to the request property / (media type: application/*+json)

    • info

      added the new reversed_not_authorized enum value to the request property / (media type: application/json)

    • info

      added the new reversed_not_authorized enum value to the request property / (media type: text/json)

    • info

      added the new reversed_not_authorized enum value to the request property / (media type: application/*+json)

    • info

      added the optional property / to the response with the status (media type: text/plain)

    • info

      added the optional property / to the response with the status (media type: application/json)

    • info

      added the optional property / to the response with the status (media type: text/json)

    • info

      added the required property / to the response with the status (media type: text/plain)

    • info

      added the required property / to the response with the status (media type: application/json)

    • info

      added the required property / to the response with the status (media type: text/json)

    • info

      added the required property / to the response with the status (media type: text/plain)

    • info

      added the required property / to the response with the status (media type: application/json)

    • info

      added the required property / to the response with the status (media type: text/json)

    • info

      added the required property / to the response with the status (media type: text/plain)

    • info

      added the required property / to the response with the status (media type: application/json)

    • info

      added the required property / to the response with the status (media type: text/json)

  • 940c74c551fcRevision changes
    • info

      removed the unknown enum value from the // response property for the response status (media type: text/plain)

    • info

      removed the unknown enum value from the // response property for the response status (media type: application/json)

    • info

      removed the unknown enum value from the // response property for the response status (media type: text/json)