OpenAPI Specification
openapi: 3.0.3
info:
title: ChargeDesk REST Charges Gateway API
description: 'RESTful API for managing charges, customers, subscriptions, products, and webhooks across multiple payment gateways including Stripe, Braintree, PayPal, Authorize.Net, WooCommerce, Shopify, Square, GoCardless, and 14+ others. Supports creating and capturing charges, processing refunds, cancelling subscriptions, requesting payments, and managing customer data.
'
version: v1
contact:
name: ChargeDesk Support
url: https://chargedesk.com/api-docs
termsOfService: https://chargedesk.com/terms
servers:
- url: https://api.chargedesk.com/v1
description: Production API
security:
- basicAuth: []
tags:
- name: Gateway
description: Live payment processing operations
paths:
/gateway/products/charge:
post:
operationId: gatewayCreateCharge
summary: Create a live charge, subscription, or payment request via gateway
tags:
- Gateway
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
using:
type: string
description: Payment method. Set to 'card' for charge, 'invoice' for payment request.
example: card
customer[id]:
type: string
description: Customer identifier
amount:
type: number
description: Charge amount
currency:
type: string
description: 3-letter ISO currency code
description:
type: string
product[interval]:
type: string
description: Billing interval for subscriptions (day, week, month, year)
enum:
- day
- week
- month
- year
product[interval_count]:
type: integer
description: Number of intervals between billings
product[trial_period_days]:
type: integer
description: Number of trial days
product[billing_cycles_total]:
type: integer
description: Total number of billing cycles
contact:
type: string
description: Contact email for payment request
link_only:
type: boolean
description: Return only pay link, do not send email
lines[]:
type: array
items:
type: string
description: Line items for payment request
metadata[key]:
type: string
description: Arbitrary metadata key-value pairs
responses:
'200':
description: Gateway charge/subscription created
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/gateway/charges/{charge_id}/refund:
post:
operationId: gatewayRefundCharge
summary: Refund a charge via gateway
tags:
- Gateway
parameters:
- $ref: '#/components/parameters/ChargeId'
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
amount:
type: number
description: Amount to refund (omit for full refund)
log_reason:
type: string
description: Reason for the refund
responses:
'200':
description: Charge refunded
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/gateway/charges/{charge_id}/capture:
post:
operationId: gatewayCapturCharge
summary: Capture an authorized charge via gateway
tags:
- Gateway
parameters:
- $ref: '#/components/parameters/ChargeId'
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
amount:
type: number
description: Amount to capture (0 to void)
responses:
'200':
description: Charge captured
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/gateway/charges/{charge_id}/void:
post:
operationId: gatewayCancelPaymentRequest
summary: Cancel a payment request (void)
tags:
- Gateway
parameters:
- $ref: '#/components/parameters/ChargeId'
responses:
'200':
description: Payment request cancelled
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/gateway/subscriptions/{subscription_id}/cancel:
post:
operationId: gatewayCancelSubscription
summary: Cancel a subscription via gateway
tags:
- Gateway
parameters:
- $ref: '#/components/parameters/SubscriptionId'
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
log_reason:
type: string
description: Reason for cancellation
responses:
'200':
description: Subscription cancelled
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/gateway/subscriptions/{subscription_id}/plans:
post:
operationId: gatewayEditSubscriptionPlans
summary: Edit subscription plans via gateway
tags:
- Gateway
parameters:
- $ref: '#/components/parameters/SubscriptionId'
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
plans[][id]:
type: string
description: Plan identifier
trial_end:
type: string
format: date-time
description: When the trial period ends
prorate:
type: boolean
description: Whether to prorate the subscription change
invoice:
type: boolean
description: Whether to generate an invoice
responses:
'200':
description: Subscription plans updated
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
ProductRef:
type: object
properties:
id:
type: string
name:
type: string
Subscription:
type: object
properties:
id:
type: string
object:
type: string
example: subscription
subscription_id:
type: string
customer_id:
type: string
status:
type: string
enum:
- requested
- pending
- new
- trialing
- active
- past_due
- canceled
- unpaid
- suspended
- pending_cancel
amount:
type: number
currency:
type: string
interval:
type: string
enum:
- day
- week
- month
- year
interval_count:
type: integer
quantity:
type: integer
trial_start:
type: string
format: date-time
trial_end:
type: string
format: date-time
billing_cycles_total:
type: integer
billing_cycles_current:
type: integer
items:
type: array
items:
type: object
metadata:
type: object
additionalProperties:
type: string
SubscriptionRef:
type: object
properties:
id:
type: string
ChargeLineItem:
type: object
properties:
id:
type: string
description:
type: string
amount:
type: number
quantity:
type: integer
currency:
type: string
CustomerRef:
type: object
properties:
id:
type: string
email:
type: string
name:
type: string
Charge:
type: object
properties:
id:
type: string
description: Unique charge identifier
object:
type: string
example: charge
status:
type: string
enum:
- pending
- paid
- partially refunded
- refunded
- failed
- authorized
- void
- invoiced
- invoice canceled
- unpaid
- past due
- subscription pending
- disputed
- trial
- credit
- uncollectible
- open
- draft
- unclaimed
amount:
type: number
description: Charge amount
currency:
type: string
description: 3-letter ISO currency code
amount_refunded:
type: number
description: Total amount refunded
description:
type: string
transaction_id:
type: string
description: Gateway transaction ID
last_4_digits:
type: string
description: Last 4 digits of the card used
customer:
$ref: '#/components/schemas/CustomerRef'
product:
$ref: '#/components/schemas/ProductRef'
subscription:
$ref: '#/components/schemas/SubscriptionRef'
lines:
type: array
items:
$ref: '#/components/schemas/ChargeLineItem'
metadata:
type: object
additionalProperties:
type: string
occurred:
type: string
format: date-time
pay_link:
type: string
format: uri
description: Payment link (for payment requests)
Error:
type: object
properties:
error:
type: object
properties:
message:
type: string
type:
type: string
code:
type: string
parameters:
ChargeId:
name: charge_id
in: path
required: true
schema:
type: string
description: Unique charge identifier
SubscriptionId:
name: subscription_id
in: path
required: true
schema:
type: string
description: Unique subscription identifier
securitySchemes:
basicAuth:
type: http
scheme: basic
description: 'Use your ChargeDesk secret key as the username with an empty password. Format: Authorization: YOUR_SECRET_KEY:
'