Tithe.ly Payments API

openapi: 3.2.0
info:
  title: Tithe.ly Payments API
  description: The Tithe.ly API lets churches and approved partners integrate with the Tithe.ly giving and church-technology platform.
  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:
    PaymentMethod:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: string
        last4:
          type: string
        type:
          type: string
          enum:
          - card
          - bank
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    ChargeInput:
      type: object
      required:
      - payment_method_id
      - amount
      properties:
        payment_method_id:
          type: string
        amount:
          type: integer
        currency:
          type: string
          default: USD
    ChargeOnceInput:
      type: object
      required:
      - token
      - amount
      properties:
        token:
          type: string
        amount:
          type: integer
        currency:
          type: string
          default: USD
    PaymentMethodInput:
      type: object
      required:
      - user_id
      - token
      properties:
        user_id:
          type: string
        token:
          type: string
          description: Card or bank token from Tithely.js.
    ChargeResult:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        amount:
          type: integer
        currency:
          type: string
  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.'