openapi: 3.0.3
info:
  title: Tithe.ly Accounts Payments 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: Payments
  description: V1 tokenized payment methods and charges.
paths:
  /payment-methods:
    post:
      operationId: createPaymentMethod
      tags:
      - Payments
      summary: Attach a tokenized payment method to a user
      description: V1 endpoint. Attaches a card or bank token produced by Tithely.js to a user so it can be charged repeatedly (e.g. recurring giving). Base URL is the V1 host (live https://tithe.ly/api/v1, test https://tithelydev.com/api/v1).
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentMethodInput'
      responses:
        '200':
          description: The stored payment method.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /charge:
    post:
      operationId: charge
      tags:
      - Payments
      summary: Charge a stored payment method
      description: V1 endpoint. Charges a previously stored payment method - used for repeat and recurring giving.
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeInput'
      responses:
        '200':
          description: The charge result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Payment failed / declined.
  /charge-once:
    post:
      operationId: chargeOnce
      tags:
      - Payments
      summary: One-time charge of a token
      description: V1 endpoint. Executes a single one-time charge against a token produced by Tithely.js without storing the payment method.
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeOnceInput'
      responses:
        '200':
          description: The charge result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Payment failed / declined.
components:
  schemas:
    PaymentMethodInput:
      type: object
      required:
      - user_id
      - token
      properties:
        user_id:
          type: string
        token:
          type: string
          description: Card or bank token from Tithely.js.
    ChargeOnceInput:
      type: object
      required:
      - token
      - amount
      properties:
        token:
          type: string
        amount:
          type: integer
        currency:
          type: string
          default: USD
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    PaymentMethod:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: string
        last4:
          type: string
        type:
          type: string
          enum:
          - card
          - bank
    ChargeResult:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        amount:
          type: integer
        currency:
          type: string
    ChargeInput:
      type: object
      required:
      - payment_method_id
      - amount
      properties:
        payment_method_id:
          type: string
        amount:
          type: integer
        currency:
          type: string
          default: USD
  responses:
    Unauthorized:
      description: Missing or invalid API credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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.'