The Subscription Payments API from Smokeball — 4 operation(s) for subscription payments.
openapi: 3.0.1
info:
title: Smokeball Activity Codes Subscription Payments API
version: '1.0'
description: REST API for integrating with Smokeball legal practice management software. Supports matters, contacts, documents, time entries, billing, trust accounting, staff, webhooks, and law firm workflows across US, AU, and UK regions. Uses OAuth 2.0 (client credentials) authentication.
contact:
name: Smokeball Developer Support
url: https://docs.smokeball.com/docs/api-docs/1e13a13124aee-introduction
x-api-id: smokeball
x-audience: external-public
servers:
- url: https://api.smokeball.com
- url: https://api.smokeball.com.au
- url: https://api.smokeball.co.uk
- url: https://stagingapi.smokeball.com
- url: https://stagingapi.smokeball.com.au
- url: https://stagingapi.smokeball.co.uk
security:
- api-key: []
token: []
tags:
- name: Subscription Payments
paths:
/subscriptions/paymentmethods:
get:
tags:
- Subscription Payments
summary: Get all customer payment methods
description: Returns all payment methods attached to the current account's payment customer.
operationId: GetCustomerPaymentMethodsAsync
parameters:
- name: Offset
in: query
schema:
maximum: 2147483647
minimum: 0
type: integer
format: int32
- name: Limit
in: query
schema:
maximum: 500
minimum: 1
type: integer
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodPagedCollection'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'500':
description: Internal Server Error
x-excluded: true
post:
tags:
- Subscription Payments
summary: Add payment method
description: "Adds a new payment method to the account.\r\n\r\nImportant notes:\r\n* Can optionally set as default payment method for the entire account\r\n* Can force immediate charge for overdue invoices for all active subscriptions\r\n* Payment information format depends on payment system"
operationId: AddPaymentMethodAsync
requestBody:
description: Payment method details including system and payment information
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/AddPaymentMethodRequest'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddPaymentMethodRequest'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/AddPaymentMethodRequest'
responses:
'202':
description: When request is accepted. Returns a 'Link' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When subscription with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'500':
description: When an error occurs while adding payment method.
x-excluded: true
/subscriptions/{subscriptionId}/paymentmethods:
get:
tags:
- Subscription Payments
summary: Get payment methods
description: Returns the payment methods actively set on the specified subscription.
operationId: GetPaymentMethodsAsync
parameters:
- name: subscriptionId
in: path
description: The unique identifier of the subscription
required: true
schema:
type: string
- name: Offset
in: query
schema:
maximum: 2147483647
minimum: 0
type: integer
format: int32
- name: Limit
in: query
schema:
maximum: 500
minimum: 1
type: integer
format: int32
responses:
'200':
description: When request is successful. Returns a paged collection of 'PaymentMethod' objects.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodPagedCollection'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When subscription with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'500':
description: When an error occurs while retrieving payment methods.
x-excluded: true
put:
tags:
- Subscription Payments
operationId: UpdateSubscriptionPaymentMethodAsync
parameters:
- name: subscriptionId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/SetDefaultPaymentMethodRequest'
description: Request to set or clear a subscription default payment method.
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SetDefaultPaymentMethodRequest'
description: Request to set or clear a subscription default payment method.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/SetDefaultPaymentMethodRequest'
description: Request to set or clear a subscription default payment method.
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'500':
description: Internal Server Error
x-excluded: true
post:
tags:
- Subscription Payments
summary: Add payment method
description: "Adds a new payment method to the account and sets it for the specified subscription \r\n\r\nImportant notes:\r\n* Can optionally set as default payment method for the entire account, or the specified subscription\r\n* Can force immediate charge for overdue invoices for the specified subscription\r\n* Payment information format depends on payment system"
operationId: AddSubscriptionPaymentMethodAsync
parameters:
- name: subscriptionId
in: path
description: The unique identifier of the subscription
required: true
schema:
type: string
requestBody:
description: Payment method details including system and payment information
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/AddPaymentMethodRequest'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddPaymentMethodRequest'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/AddPaymentMethodRequest'
responses:
'202':
description: When request is accepted. Returns a 'Link' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When subscription with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'500':
description: When an error occurs while adding payment method.
x-excluded: true
/subscriptions/{subscriptionId}/paymentmethods/{id}:
get:
tags:
- Subscription Payments
summary: Get payment method
description: Returns a specific payment method associated with a subscription.
operationId: GetPaymentMethodAsync
parameters:
- name: subscriptionId
in: path
description: The unique identifier of the subscription
required: true
schema:
type: string
- name: id
in: path
description: The unique identifier of the payment method
required: true
schema:
type: string
format: uuid
responses:
'200':
description: When request is successful. Returns a 'PaymentMethod' object.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethod'
'400':
description: When an unsupported request is made.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: When subscription or payment method with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'500':
description: When an error occurs while retrieving payment method.
x-excluded: true
delete:
tags:
- Subscription Payments
summary: Remove payment method
description: "Removes a payment method from a subscription.\r\n\r\nImportant notes:\r\n* Can optionally specify a new default payment method\r\n* Removing default without replacement may cause subscription to go OVERDUE"
operationId: RemovePaymentMethodAsync
parameters:
- name: subscriptionId
in: path
description: The unique identifier of the subscription
required: true
schema:
type: string
- name: id
in: path
description: The ID of the payment method to remove
required: true
schema:
type: string
format: uuid
requestBody:
description: Optional request containing new default payment method ID
content:
application/json-patch+json:
schema:
allOf:
- $ref: '#/components/schemas/RemovePaymentMethodRequest'
application/json:
schema:
allOf:
- $ref: '#/components/schemas/RemovePaymentMethodRequest'
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/RemovePaymentMethodRequest'
responses:
'202':
description: When request is accepted. Returns a 'Link' object.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
'404':
description: When subscription or payment method with specified id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'500':
description: When an error occurs while removing payment method.
x-excluded: true
/subscriptions/paymentsystems:
get:
tags:
- Subscription Payments
summary: Get supported payment systems
description: "Returns all supported payment systems and their supported payment method types.\r\nCurrently supports:\r\n* STRIPE with CREDIT_CARD payment type"
operationId: GetSupportedPaymentSystemsAsync
responses:
'200':
description: When request is successful. Returns a collection of 'PaymentSystem' objects.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentSystemCollection'
'500':
description: When an error occurs while retrieving supported payment systems.
x-excluded: true
components:
schemas:
AddPaymentMethodRequest:
type: object
properties:
paymentSystemId:
type: string
description: Payment system to use.
nullable: true
example: STRIPE
paymentInformation:
allOf:
- $ref: '#/components/schemas/PaymentInformation'
description: "Payment information specific to the payment system.\r\n\r\nFor Stripe, this should be StripePaymentInformation."
nullable: true
isDefault:
type: boolean
description: "Whether to set this as the default payment method for the entire account \r\n\r\nThis does not set the default payment method for the subscription."
nullable: true
example: true
chargeImmediately:
type: boolean
description: "Whether to charge immediately if subscription(s) are overdue.\r\n\r\nIf true, the payment system will attempt to charge the customer immediately if there are any overdue subscriptions.\r\n\r\nIf a subscription id is passed as a parameter to the request, only that subscription will be charged immediately if overdue."
nullable: true
example: true
additionalProperties: false
PaymentSystem:
type: object
properties:
id:
type: string
description: Id of payment system.
nullable: true
example: STRIPE
supportedPaymentTypes:
type: array
items:
type: string
description: "The payment type.\r\n\r\n* None - The payment type is missing or unknown.\r\n\r\n* CreditCard - Credit Card payment type.\r\n\r\n* DirectDeposit - Direct Deposit payment type. (not currently supported)"
description: List of supported payment method types.
nullable: true
additionalProperties: false
SetDefaultPaymentMethodRequest:
type: object
properties:
paymentMethodId:
type: string
description: Public payment method id. Null clears the subscription override which reverts behavior to the Customer's default.
format: uuid
nullable: true
subscriptionType:
allOf:
- $ref: '#/components/schemas/SubscriptionType'
description: Deprecated. The subscription type is inferred from the route subscription id.
additionalProperties: false
description: Request to set or clear a subscription default payment method.
SubscriptionType:
enum:
- 0
- 1
type: integer
format: int32
PaymentInformation:
type: object
additionalProperties: false
description: Base class for payment information.
PaymentMethodDetails:
type: object
properties:
brand:
type: string
description: The brand of the credit card.
nullable: true
lastFourDigits:
type: string
description: Last four digits of the credit card.
nullable: true
example: '1234'
expiry:
type: string
description: Expiry date of the credit card in MM/YY format.
nullable: true
example: 10/28
expiryMonth:
type: integer
description: Expiry month.
format: int64
nullable: true
example: 10
expiryYear:
type: integer
description: Expiry year.
format: int64
nullable: true
example: 2028
accountNumber:
type: integer
description: "The account number of the direct deposit account.\r\n\r\nNot yet supported."
format: int64
nullable: true
example: 123456789
bsb:
type: integer
description: "The BSB of the direct deposit account.\r\n\r\nNot yet supported."
format: int64
nullable: true
additionalProperties: false
Link:
type: object
properties:
id:
type: string
nullable: true
href:
type: string
nullable: true
relation:
type: string
nullable: true
method:
type: string
default: GET
nullable: true
additionalProperties: false
PaymentMethodPagedCollection:
type: object
properties:
id:
type: string
nullable: true
href:
type: string
nullable: true
relation:
type: string
nullable: true
method:
type: string
default: GET
nullable: true
self:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
value:
type: array
items:
$ref: '#/components/schemas/PaymentMethod'
nullable: true
offset:
type: integer
format: int32
nullable: true
limit:
type: integer
format: int32
nullable: true
size:
type: integer
format: int64
first:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
previous:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
next:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
last:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
additionalProperties: false
PaymentMethod:
type: object
properties:
href:
type: string
nullable: true
relation:
type: string
nullable: true
method:
type: string
default: GET
nullable: true
self:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
id:
type: string
description: Unique identifier of the payment method.
nullable: true
example: 784b3497-bf1f-47d2-93e6-1d38b96b8d3f
paymentSystem:
type: string
description: Payment system.
nullable: true
example: STRIPE
type:
type: string
description: "The payment type.\r\n\r\n* None - The payment type is missing or unknown.\r\n\r\n* CreditCard - Credit Card payment type.\r\n\r\n* DirectDeposit - Direct Deposit payment type. (not currently supported)"
example: CreditCard
isDefault:
type: boolean
description: Whether this is the default payment method for the customer.
example: true
details:
allOf:
- $ref: '#/components/schemas/PaymentMethodDetails'
description: Payment method specific details for display.
nullable: true
lastPaymentState:
type: string
description: "The status of a payment.\r\n\r\n* None: The payment status is unknown.\r\n\r\n* Succeeded: The payment was successful.\r\n\r\n* Processing: The payment is being processed.\r\n\r\n* Canceled: The payment was canceled.\r\n\r\n* Failed: The payment requires a payment method to be provided, the provided payment method failed or other action is required (e.g. confirmation or other action by the customer)"
example: Succeeded
createdDate:
type: string
description: When this payment method was added.
format: date-time
example: '2022-04-23T14:00:00Z'
additionalProperties: false
PaymentSystemCollection:
type: object
properties:
id:
type: string
nullable: true
href:
type: string
nullable: true
relation:
type: string
nullable: true
method:
type: string
default: GET
nullable: true
self:
allOf:
- $ref: '#/components/schemas/Link'
nullable: true
value:
type: array
items:
$ref: '#/components/schemas/PaymentSystem'
nullable: true
additionalProperties: false
ProblemDetails:
type: object
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
nullable: true
detail:
type: string
nullable: true
instance:
type: string
nullable: true
additionalProperties: {}
RemovePaymentMethodRequest:
type: object
properties:
newDefaultPaymentMethodId:
type: string
description: Optional ID of payment method to set as new default.
nullable: true
additionalProperties: false
securitySchemes:
api-key:
type: apiKey
name: x-api-key
in: header
token:
type: apiKey
name: Authorization
in: header
x-amazon-apigateway-authtype: cognito_user_pools