openapi: 3.2.0
info:
  title: External Trans ACH Debit Webhook API
  description: '# Overview


    External Trans API is a webhook that allows clients to participate in

    the decisioning for:

    * Approving/denying bill payments

    * Approving/denying ACH debits


    It''s similar to Auth API, but for bill pay and ACH debits.'
  version: 1.0.0
servers:
- url: https://client.domain.com
  description: Clients will provide the URLs they would like to use for External Trans API. The URLs should use HTTPS.
tags:
- name: ACH Debit Webhook
paths:
  /achdebit:
    post:
      summary: ACH Debit Webhook
      description: Use the ACH Debit webhook to approve or deny incoming ACH debits. Use the `response_code` field in the response to communicate your decision to SoFi Tech Solutions.
      operationId: webhook_ach_debit_post
      tags:
      - ACH Debit Webhook
      parameters:
      - name: X-Request-ID
        in: header
        description: A unique identifier for the HTTP request.
        schema:
          type: string
          format: uuid
        required: true
      requestBody:
        description: Information about the ACH debit transaction.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account_number:
                  type: string
                  minLength: 12
                  maxLength: 12
                  description: '<a href="doc:about-accounts#prn" target="_blank">Payment reference number</a> for the account Example: `"999200002022"`'
                  example: '999200002022'
                account_status:
                  type: string
                  description: 'Account status code. See the possible values in the <a href="ref:api-reference-account-statuses" target="_blank">Account Statuses</a> enumeration.


                    Example: `"N"`'
                transaction_amount:
                  type: number
                  format: float
                  description: 'The amount of the ACH debit. Example: `150.00`'
                  example: 150
                currency:
                  type: string
                  minLength: 3
                  maxLength: 3
                  description: 'The three-digit currency code for the amounts. ISO 4217 Numeric Currency Code. 3 digits. Example: `"840"`'
                  example: '840'
                available_funds:
                  type: number
                  format: float
                  description: 'Amount of funds available to the account holder. Example: `500.00`'
                  example: 500
                ach_name:
                  type: string
                  maxLength: 30
                  description: 'Name of the ACH account holder. Example: `"John Doe"`'
                  example: John Doe
                recipient:
                  type: string
                  maxLength: 35
                  description: 'Name of the <<glossary:ODFI>> that receives the debited funds. Example: `"Widgets Incorporated"`'
                  example: Widgets Incorporated
                sec:
                  type: string
                  minLength: 3
                  maxLength: 3
                  description: 'The three-character <a href="ref:api-reference-sec-codes-requirements-for-ach" target="_blank">standard entry class (SEC)</a> code. Example: `"WEB"`'
                  example: WEB
                is_international:
                  type: boolean
                  description: 'Whether this is an international transaction. Example: `"false"`'
                  example: false
                description:
                  type: string
                  maxLength: 10
                  description: 'Description from the ACH header. Example: `"PAYROLL   "`'
                  example: 'PAYROLL  '
                timestamp:
                  type: string
                  description: 'Timestamp when this webhook message was sent. Format is `<timestamp><timezone>` where `timestamp` is `YYYYmmdd:HHMMSS` and `timezone` is always `MST`. Example: `"20270315:121504MST"`'
                  example: 20270315:121504MST
                transaction_id:
                  type: integer
                  maxLength: 18
                  description: 'The unique identifier of the ACH transaction. Also called `ach_trans_id` and `deposit_transaction_id` in the Program API. Example: `32146803`'
                  example: 32146803
                version:
                  type: string
                  maxLength: 16
                  description: The version of this API. Hard-coded to `"1.0"`.
                  enum:
                  - '1.0'
                batch_header:
                  type: string
                  maxLength: 94
                  description: 'The batch header for the <<glossary:Nacha file>> that contained this ACH debit entry detail record. Example: `"5225WIDGET INC      DISCRETIONARY DATA  1234567890POSPAYROLL   2027052003070642123456780000001"`'
                  example: 5225WIDGET INC      DISCRETIONARY DATA  1234567890POSPAYROLL   2027052003070642123456780000001
                source_trace:
                  type: string
                  maxLength: 20
                  description: 'The source trace number from the ACH record. Example: `"123456781234567"`'
                  example: '123456781234567'
                jwt:
                  type: string
                  description: The JSON web token (JWT) that authenticates the HTTP request from SoFi Tech Solutions. See the <a href="ref:api-reference-external-trans-api-about-external-trans-api-security" target="_blank">security overview</a> for more information and an example.
                  example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnYWxpbGVvIiwiaWF0IjoxNTM0Mjc0ODgxLCJleHAiOjE1MzQyNzQ4ODZ9.1xUk4iNFGWLo01MyJUHXRlyrNlzwPvDMSXpN38TrblU
              required:
              - account_number
              - account_status
              - transaction_amount
              - currency
              - available_funds
              - ach_name
              - recipient
              - sec
              - is_international
              - description
              - timestamp
              - transaction_id
              - version
              - batch_header
              - source_trace
      responses:
        '200':
          description: Your decision and instructions for SoFi Tech Solutions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response_code:
                    type: string
                    description: "Response code indicating how to process the ACH debit transaction. Possible response codes:\n\n- `00` &mdash; Approve\n\n- `R01` &mdash; Reject; Insufficient funds\n\n- `R07` &mdash; Reject; Authorization revoked by customer\n\n- `R08` &mdash; Reject; Payment stopped\n\n- `R10` &mdash; Reject; Customer advises not authorized\n\n- `R16` &mdash; Reject; Bank account frozen\n\n- `R20` &mdash; Reject; Non-payment bank account\n\n- `98` &mdash; System Error; Reject and do not retry\n\n- `99` &mdash; System Error; Retry later\n\n\nYou can use `99` to tell SoFi Tech Solutions to retry later if your product is configured for retries. \n"
                required:
                - response_code
              examples:
                response:
                  value: "{\n  \"response_code\": \"00\"\n}\n"
x-explorer-enabled: false
x-samples-enabled: false
x-readme:
  proxy-enabled: true