Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
299 lines (279 sloc) 15.8 KB
# This is the Moov API OpenAPI specification.
#
# The purpose of this document is to provide a specification for the Moov API from a user's
# point of view. This means viewing the services combined under https://api.moov.io (or another
# URL).
#
# If you're working on internal service calls you may or may not be able to use a generated
# client from this document.
#
# Docs: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
#
# TODO amount fields now take a currency code. USD default
# - Look at https://godoc.org/golang.org/x/text/currency
#
# TODO GET endpoints should use the OAS 3 Link Object specification
# - https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#linkObject
#
# TODO Transfers objects now have an estimated ?posting? date
# TODO add Documents allowing Receiver ID(passport, drivers license, idCard) to be uploaded and verified
# TODO Webhooks have been documented for retrieving events
# TODO add support for retrieving 1099-k for Originators
#
# Property names must conform to the following guidelines:
# - Resources are plural nouns (i.e. /receivers/)
# - Property names should be meaningful names with defined semantics.
# - Property names must be camel-cased, ASCII strings.
# - The first character must be a letter, an underscore (_) or a dollar sign ($).
# - Subsequent characters can be a letter, a digit, an underscore, or a dollar sign.
# - Reserved JavaScript keywords should be avoided
#
# See: https://swagger.io/docs/specification/using-ref/#escape
# This page documents what characters escape others and which are useful for URI encoding $ref values.
openapi: "3.0.2"
info:
description: |
_Note_: We're currently in pre-release of our API. We expect breaking changes before launching v1 so please join our [slack organization](http://moov-io.slack.com/) ([request an invite](https://join.slack.com/t/moov-io/shared_invite/enQtNDE5NzIwNTYxODEwLTRkYTcyZDI5ZTlkZWRjMzlhMWVhMGZlOTZiOTk4MmM3MmRhZDY4OTJiMDVjOTE2MGEyNWYzYzY1MGMyMThiZjg)) or [mailing list](https://groups.google.com/forum/#!forum/moov-users) for more updates and notices.
The Moov API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support [cross-origin resource sharing](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing), allowing you to interact securely with our API from client-side web applications (never expose your secret API key in any public website's client-side code). [JSON](http://www.json.org/) is returned by all API responses, including errors, although you can generate client code via [OpenAPI code generation](https://github.com/OpenAPITools/openapi-generator) or the [OpenAPI editor](https://editor.swagger.io/) to convert responses to appropriate language-specific objects.
The Moov API offers two methods of authentication, Cookie and OAuth2 access tokens. The cookie auth is designed for web browsers while the OAuth2 authentication is designed for automated access of our API.
When an API requires a token generated using OAuth (2-legged), no end user is involved. You generate the token by passing your client credentials (Client Id and Client Secret) in a simple call to Create access token (`/oauth2/token`). The operation returns a token that is valid for a few hours and can be renewed; when it expires, you just repeat the call and get a new token. Making additional token requests will keep generating tokens. There are no hard or soft limits.
Cookie auth is setup by provided (`/users/login`) a valid email and password combination. A `Set-Cookie` header is returned on success, which can be used in later calls. Cookie auth is required to generate OAuth2 client credentials.
The following order of API operations is suggested to start developing against the Moov API:
1. [Create a Moov API user](#operation/createUser) with a unique email address
1. [Login with user/password credentials](#operation/userLogin)
1. [Create an OAuth2 client](#operation/createOAuth2Client) and [Generate an OAuth access token](#operation/createOAuth2Token)
1. Using the OAuth credentials create:
- [Originator](#operation/addOriginator) and [Originator Depository](#operation/addDepository) (requires micro deposit setup)
- [Receiver](#operation/addReceivers) and [Receiver Depository](#operation/addDepository) (requires micro deposit setup)
1. [Submit the Transfer](#operation/addTransfer)
After signup clients can [submit ACH files](#operation/addFile) (either in JSON or plaintext) for [validation](#operation/validateFile) and [tabulation](#operation/getFileContents).
The Moov API offers many services:
- Automated Clearing House (ACH) origination and file management
- Transfers and ACH Receiver management.
- X9 / Image Cash Ledger (ICL) specification support (image uplaod)
ACH is implemented a RESTful API enabling ACH transactions to be submitted and received without a deep understanding of a full NACHA file specification.
An Originator can initiate a Transfer as either a push (credit) or pull (debit) to a Receiver. Originators and Receivers must have a valid Depository account for a Transfer. A Transfer is initiated by an Originator to a Receiver with an amount and flow of funds.
```
Originator -> Gateway -> Receiver
- OriginatorDepository - ReceiverDepository
- Type (Push or Pull)
- Amount (USD 12.43)
- Status (Pending)
```
If you find a security related problem please contact us at [`security@moov.io`](mailto:security@moov.io).
version: "v1"
title: "Moov API"
contact:
email: security@moov.io
url: "https://groups.google.com/forum/#!forum/moov-users"
license:
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
servers:
- url: https://api.moov.io
description: Production server
- url: http://localhost:9000
description: Moov local development setup
# - url: https://sbx.moov.io
# description: Development server
tags:
- name: Monitor
description: TODO(adam)
paths:
# Auth routes
/v1/users/create:
$ref: 'https://raw.githubusercontent.com/moov-io/auth/master/openapi.yaml#/paths/~1users~1create'
/v1/users/login:
$ref: 'https://raw.githubusercontent.com/moov-io/auth/master/openapi.yaml#/paths/~1users~1login'
/v1/users/{user_id}:
$ref: 'https://raw.githubusercontent.com/moov-io/auth/master/openapi.yaml#/paths/~1users~1%7Buser_id%7D'
/v1/oauth2/authorize:
$ref: 'https://raw.githubusercontent.com/moov-io/auth/master/openapi.yaml#/paths/~1oauth2~1authorize'
/v1/oauth2/clients:
$ref: 'https://raw.githubusercontent.com/moov-io/auth/master/openapi.yaml#/paths/~1oauth2~1clients'
/v1/oauth2/client:
$ref: 'https://raw.githubusercontent.com/moov-io/auth/master/openapi.yaml#/paths/~1oauth2~1client'
/v1/oauth2/token:
$ref: 'https://raw.githubusercontent.com/moov-io/auth/master/openapi.yaml#/paths/~1oauth2~1token'
# ACH Files
/v1/ach/files:
$ref: 'https://raw.githubusercontent.com/moov-io/ach/master/openapi.yml#/paths/~1files'
/v1/ach/files/create:
$ref: 'https://raw.githubusercontent.com/moov-io/ach/master/openapi.yml#/paths/~1files~1create'
/v1/ach/files/{file_id}:
$ref: 'https://raw.githubusercontent.com/moov-io/ach/master/openapi.yml#/paths/~1files~1%7Bfile_id%7D'
/v1/ach/files/{file_id}/contents:
$ref: 'https://raw.githubusercontent.com/moov-io/ach/master/openapi.yml#/paths/~1files~1%7Bfile_id%7D~1contents'
/v1/ach/files/{file_id}/validate:
$ref: 'https://raw.githubusercontent.com/moov-io/ach/master/openapi.yml#/paths/~1files~1%7Bfile_id%7D~1validate'
/v1/ach/files/{file_id}/batches:
$ref: 'https://raw.githubusercontent.com/moov-io/ach/master/openapi.yml#/paths/~1files~1%7Bfile_id%7D~1batches'
/v1/ach/files/{file_id}/batches/{batch_id}:
$ref: 'https://raw.githubusercontent.com/moov-io/ach/master/openapi.yml#/paths/~1files~1%7Bfile_id%7D~1batches~1%7Bbatch_id%7D'
# Paygate Routes
/v1/ach/originators:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1originators'
/v1/ach/originators/{originatorId}:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1originators~1%7BoriginatorId%7D'
/v1/ach/receivers:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1receivers'
/v1/ach/receivers/{receiverId}:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1receivers~1%7BreceiverId%7D'
/v1/ach/receivers/{receiverId}/depositories:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1receivers~1%7BreceiverId%7D~1depositories'
/v1/ach/receivers/{receiverId}/depositories/{depositoryId}:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1receivers~1%7BreceiverId%7D~1depositories~1%7BdepositoryId%7D'
/v1/ach/depositories:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1depositories'
/v1/ach/depositories/{depositoryId}:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1depositories~1%7BdepositoryId%7D'
/v1/ach/depositories/{depositoryId}/micro-deposits:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1depositories~1%7BdepositoryId%7D~1micro-deposits'
/v1/ach/depositories/{depositoryId}/micro-deposits/confirm:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1depositories~1%7BdepositoryId%7D~1micro-deposits~1confirm'
/v1/ach/transfers:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1transfers'
/v1/ach/transfers/batch:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1transfers~1batch'
/v1/ach/transfers/{transferId}:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1transfers~1%7BtransferId%7D'
/v1/ach/transfers/{transferId}/failed:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1transfers~1%7BtransferId%7D~1failed'
/v1/ach/transfers/{transferId}/files:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1transfers~1%7BtransferId%7D~1files'
/v1/ach/transfers/{transferId}/events:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1transfers~1%7BtransferId%7D~1events'
/v1/ach/events:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1events'
/v1/ach/events/{eventId}:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1events~1%7BeventId%7D'
/v1/ach/gateways:
$ref: 'https://raw.githubusercontent.com/moov-io/paygate/master/openapi.yaml#/paths/~1gateways'
# OFAC endpoints
/v1/ofac/customers/{customerId}:
$ref: 'https://raw.githubusercontent.com/moov-io/ofac/master/openapi.yaml#/paths/~1customers~1%7BcustomerId%7D'
/v1/ofac/customers/{customerId}/watch:
$ref: 'https://raw.githubusercontent.com/moov-io/ofac/master/openapi.yaml#/paths/~1customers~1%7BcustomerId%7D~1watch'
/v1/ofac/customers/{customerId}/watch/{watchId}:
$ref: 'https://raw.githubusercontent.com/moov-io/ofac/master/openapi.yaml#/paths/~1customers~1%7BcustomerId%7D~1watch~1%7BwatchId%7D'
/v1/ofac/customers/watch:
$ref: 'https://raw.githubusercontent.com/moov-io/ofac/master/openapi.yaml#/paths/~1customers~1watch'
/v1/ofac/customers/watch/{watchId}:
$ref: 'https://raw.githubusercontent.com/moov-io/ofac/master/openapi.yaml#/paths/~1customers~1watch~1%7BwatchId%7D'
/v1/ofac/downloads:
$ref: 'https://raw.githubusercontent.com/moov-io/ofac/master/openapi.yaml#/paths/~1downloads'
/v1/ofac/search:
$ref: 'https://raw.githubusercontent.com/moov-io/ofac/master/openapi.yaml#/paths/~1search'
/v1/ofac/sdn/{sdnId}:
$ref: 'https://raw.githubusercontent.com/moov-io/ofac/master/openapi.yaml#/paths/~1sdn~1%7BsdnId%7D'
/v1/ofac/sdn/{sdnId}/alts:
$ref: 'https://raw.githubusercontent.com/moov-io/ofac/master/openapi.yaml#/paths/~1sdn~1%7BsdnId%7D~1alts'
/v1/ofac/sdn/{sdnId}/addresses:
$ref: 'https://raw.githubusercontent.com/moov-io/ofac/master/openapi.yaml#/paths/~1sdn~1%7BsdnId%7D~1addresses'
# FED endpoints
/v1/fed/ach/search:
$ref: 'https://raw.githubusercontent.com/moov-io/fed/master/openapi.yaml#/paths/~1fed~1ach~1search'
/v1/fed/wire/search:
$ref: 'https://raw.githubusercontent.com/moov-io/fed/master/openapi.yaml#/paths/~1fed~1wire~1search'
# GL Endpoints
/v1/gl/accounts/search:
$ref: 'https://raw.githubusercontent.com/moov-io/gl/master/openapi.yaml#/paths/~1accounts~1search'
/v1/gl/customers:
$ref: 'https://raw.githubusercontent.com/moov-io/gl/master/openapi.yaml#/paths/~1customers'
/v1/gl/customers/{customer_id}:
$ref: 'https://raw.githubusercontent.com/moov-io/gl/master/openapi.yaml#/paths/~1customers~1%7Bcustomer_id%7D'
/v1/gl/customers/{customer_id}/accounts:
$ref: 'https://raw.githubusercontent.com/moov-io/gl/master/openapi.yaml#/paths/~1customers~1%7Bcustomer_id%7D~1accounts'
# Ping Routes (Used to ensure app is running, but apps likely support /ready and /live as well)
/v1/ach/ping:
get:
tags:
- Monitor
operationId: pingACH
summary: Check that the moov-io/ach service is running
parameters:
- $ref: '#/components/parameters/requestId'
responses:
'200':
description: Service is running properly
/v1/auth/ping:
get:
tags:
- Monitor
operationId: pingAuth
summary: Check that the moov-io/auth service is running
parameters:
- $ref: '#/components/parameters/requestId'
responses:
'200':
description: Service is running properly
/v1/fed/ping:
get:
tags:
- Monitor
operationId: pingFED
summary: Check that the moov-io/fed service is running
parameters:
- $ref: '#/components/parameters/requestId'
responses:
'200':
description: Service is running properly
/v1/gl/ping:
get:
tags:
- Monitor
operationId: pingGL
summary: Check that the moov-io/gl service is running
parameters:
- $ref: '#/components/parameters/requestId'
responses:
'200':
description: Service is running properly
/v1/ofac/ping:
get:
tags:
- Monitor
operationId: pingOFAC
summary: Check that the moov-io/ofac service is running
parameters:
- $ref: '#/components/parameters/requestId'
responses:
'200':
description: Service is running properly
/v1/paygate/ping:
get:
tags:
- Monitor
operationId: pingPaygate
summary: Check that the moov-io/paygate service is running
parameters:
- $ref: '#/components/parameters/requestId'
responses:
'200':
description: Service is running properly
components:
parameters:
requestId:
in: header
name: X-Request-Id
description: Optional Request ID allows application developer to trace requests through the systems logs
example: rs4f9915
schema:
type: string
securitySchemes:
bearerAuth:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.moov.io/v1/oauth2/token
# TODO(adam): more fine grained controls..
scopes: {}
cookieAuth:
type: apiKey
in: header
name: Cookie
description: moov_auth Cookie header
# We should be able to use 'in: cookie'
# https://github.com/OpenAPITools/openapi-generator/issues/208
# in: cookie
# name: moov_auth
You can’t perform that action at this time.