OpenAPI Specification
openapi: 3.0.3
info:
title: Tithe.ly Accounts Transactions API
description: 'The Tithe.ly API lets churches and approved partners integrate with the Tithe.ly giving and church-technology platform. Access is gated: it is granted by request to organizations that use (or are moving to) Tithe.ly, and approved requesters receive public and private API keys by email. Two documented generations are modeled here. The V1 payments API handles PCI-safe tokenization (via the hosted Tithely.js library) and charging of tokenized cards and bank accounts. The V2 REST API handles login, organizations, payment categories (giving funds), donation transactions, and templated mail. Endpoint paths and methods are drawn from Tithe.ly''s public documentation; request and response schemas are modeled from the documented behavior because the full field-level schemas are only exposed to approved API-key holders in the private developer docs. Test traffic uses the tithelydev.com hosts; production uses tithe.ly.'
version: '2.0'
contact:
name: Tithe.ly Support
url: https://docs.tithe.ly/reference/introduction
email: support@tithe.ly
servers:
- url: https://tithe.ly/api/v2
description: V2 REST API (live)
- url: https://tithe.ly/api/v1
description: V1 payments/tokenization API (live)
- url: https://tithelydev.com/api/v1
description: V1 payments/tokenization API (test/sandbox)
tags:
- name: Transactions
description: Create donation transactions.
paths:
/transaction:
post:
operationId: createTransaction
tags:
- Transactions
summary: Create a donation transaction
description: Records a giving transaction against an organization and payment category using a tokenized payment method. Supports one-time and recurring giving.
security:
- apiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionInput'
responses:
'200':
description: The created transaction.
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Validation error (e.g. invalid amount, token, or fund).
components:
responses:
Unauthorized:
description: Missing or invalid API credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Transaction:
type: object
description: Modeled.
properties:
id:
type: string
organization_id:
type: string
payment_category_id:
type: string
amount:
type: integer
currency:
type: string
status:
type: string
recurring:
type: boolean
created_at:
type: string
format: date-time
Error:
type: object
properties:
error:
type: string
message:
type: string
TransactionInput:
type: object
description: Modeled donation transaction request.
required:
- organization_id
- amount
properties:
organization_id:
type: string
payment_category_id:
type: string
description: The giving fund this donation is allocated to.
amount:
type: integer
description: Amount in the smallest currency unit (e.g. cents).
currency:
type: string
default: USD
token:
type: string
description: Payment token from Tithely.js.
recurring:
type: boolean
description: Whether this establishes a recurring gift.
frequency:
type: string
description: Recurrence interval when recurring is true.
enum:
- weekly
- biweekly
- monthly
cover_fees:
type: boolean
description: Whether the donor is covering transaction fees.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: 'V2 requests use the header "Authorization: {API_ID}:{API_TOKEN}", where the ID and token come from the public/private API keys issued on access approval (and via the login endpoint). V1 payment calls use the private key issued on approval.'