openapi: 3.0.1
info:
title: ACH Origination
description: Use the ACH Origination API to submit a payment. This API is more than a single action. With the ACH Origination API, you can submit a payment, check on its status, and undo a request.
contact:
name: "KeyBank Developer Support"
email: "developers@keybank.com"
version: 1.3.4
servers:
#---------------------------------------------------
# List of environments for the API
#---------------------------------------------------
- url: https://partner-api-qv.key.com
- url: https://partner-api.key.com
paths:
#---------------------------------------------------
# List of API flows
#---------------------------------------------------
/ach/payments/v1/healthCheck:
get:
tags: # Apigee Product: Logical group based on functionality
- HealthCheck
summary: Health check
description: Verify you can connect to the API service. A bearer token is required.
operationId: healthCheck
security:
- bearerAuth: []
responses:
'200':
description: Successful response
headers:
X-CorrelationId:
schema:
type: string
description: Universal id to trace the transaction across all the systems involved.
content:
application/json:
schema:
$ref: '#/components/schemas/healthResponse'
example:
Status: Ok
Source: Roundtrip
Timestamp: '2022-09-15T04:49:03'
ClientIp: 156.77.111.28
X-Forwarded-For: '[156.77.111.28]'
/ach/payments/v1/status:
post:
tags:
- ACH Payment Request Inquiry
summary: Check the status of a payment request
description: Check the return status of one or more transactions. Use this request to see if the originated item failed, was accepted, is waiting for one or more addenda items, or is being processed.
operationId: achPaymentStatus
security:
- bearerAuth: []
requestBody:
description: Contains the parameters to initiate a status request for an existing ACH Payment request.
content:
application/json:
schema:
$ref: '#/components/schemas/detailStatusRequestEnvelopePaymentInquiryDetailRequest'
example:
detailStatus:
- uuid: qas220602x-49eb-47664-b94rhd1-e52e2re11001
required: true
responses:
200:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/detailStatusResponseEnvelopeDetailStatusResponse'
example:
detailStatusResponseEnvelopeDetailStatusResponse:
detailStatusResponse:
- uuid: qas220602x-49eb-47664-b94rhd1-e52e2re11001
status: accepted
errorMessages: []
informationMessages: []
traceNumber: '041001030009002'
requestAcceptedUTCTime: '2022-06-02T17:38:28Z'
point: 'APITEST'
collectionApplicationId: 'QASTEST01'
collectionApplicationType: ''
secCode: 'CCD'
effectiveDate: '220411'
companyDescriptiveDate: '220411'
companyName: 'APITEST'
companyDiscretionaryData: ''
companyIdentification: '1123456789'
companyEntryDescription: 'API/QAS '
originatingDFIId: '04100103'
accountType: C
creditDebitCode: C
transactionType: L
transactionCode: '22'
receivingDFIId: '04100103'
checkDigit: '2'
dfiAccountNumber: '123456789'
amount: '555.54'
identificationNumber: '099999999a'
receivingCompanyName: 'QASTEST001'
discretionaryData: 'AB'
numberOfAddendaRecords: '0'
numberOfAddendaReceived: '0'
addenda:
addendaTypeCode: '05'
addendaSequenceNumber: '1'
paymentRelatedInformation: 'Testing API'
'400':
description: Missing mandatory information
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Mandatory data not provided, please verify the data and resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/status"
'401':
description: Unauthorized request
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Received request is unauthorized, please provide valid credentials"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/status"
'403':
description: Forbidden request access
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Access to requested resource is forbidden"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/status"
'404':
description: Resource not found
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Requested resource is not found, please verify the resource then resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/status"
'405':
description: Invalid request method
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Requested method is not allowed, please verify the method and resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/status"
'415':
description: Invalid request type
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Requested media type is not allowed, please verify the media type and resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/status"
'429':
description: Request timeout
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Number requests threshold reached, please resubmit the request after sometime"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/status"
'500':
description: Unknown error
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Runtime error occurred in the service, please check with application support team before resubmitting the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/status"
'502':
description: Bad gateway
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Error received from backend"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
TransactionTime: "2021-06-11T16:31:34.041Z"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
Api-Url: "/ach/payments/v1/status"
ServiceError:
ConnectError : "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
'503':
description: Unavailable service
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Error received from backend"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/status"
ServiceError:
ConnectError : "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
'504':
description: Unable to process request
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Error received from backend"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/status"
ServiceError:
ConnectError : "Please verify your payment status UUID and send the request again. The request could not be processed on time (GatewayTimeout)."
/ach/payments/v1/status/addenda:
post:
tags:
- ACH Payment Request Inquiry
summary: Check the status of addenda records
description: Check the return status of one or more addenda records
operationId: achPaymentAddendasStatus
security:
- bearerAuth: []
requestBody:
description: Contains the parameters to initiate a status inquiry for addenda records related to an ACH Payment request.
content:
application/json:
schema:
$ref: '#/components/schemas/addendaStatusRequestEnvelope'
example:
uuid: qas220517x-49eb-47664-b94rhd1-e52e2re13001
pageSize: '10'
startAddendaSequenceNumber: '0001'
required: true
responses:
200:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/addendaStatusResponseEnvelope'
example:
uuid: qas220517x-49eb-47664-b94rhd1-e52e2re13001
status: accepted
traceNumber: '041001030009004'
informationMessages:
- code: 1002040-50I
moreInfo: All addenda have been received.
errorMessages: []
addenda:
- addendaTypeCode: '05'
addendaSequenceNumber: '0001'
paymentRelatedInformation: Undo WEB PAYMENT GOOD ITEM
'400':
description: Missing mandatory information
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Mandatory data not provided, please verify the data and resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/addenda"
'401':
description: Unauthorized request
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Received request is unauthorized, please provide valid credentials"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/addenda"
'403':
description: Forbidden request access
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Access to requested resource is forbidden"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/addenda"
'404':
description: Resource not found
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Requested resource is not found, please verify the resource then resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/addenda"
'405':
description: Invalid request method
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Requested method is not allowed, please verify the method and resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/addenda"
'415':
description: Invalid request type
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Requested media type is not allowed, please verify the media type and resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/addenda"
'429':
description: Request timeout
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Number requests threshold reached, please resubmit the request after sometime"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/addenda"
'500':
description: Unknown error
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Runtime error occurred in the service, please check with application support team before resubmitting the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/addenda"
'502':
description: Bad gateway
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Error received from backend"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
TransactionTime: "2021-06-11T16:31:34.041Z"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
Api-Url: "/ach/payments/v1/addenda"
ServiceError:
ConnectError : "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
'503':
description: Unavailable service
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Error received from backend"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/addenda"
ServiceError:
ConnectError : "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
'504':
description: Unable to process request
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Error received from backend"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/addenda"
ServiceError:
ConnectError : "Please verify your payment status UUID and send the request again. The request could not be processed on time (GatewayTimeout)."
/ach/payments/v1/ccd:
post:
tags:
- ACH Payment Origination
summary: Send or collect a payment
description: Make or collect payments to a corporate account. This call originates an ACH transaction for SEC code CCD (Corporate Credit or Debit). Use this request to send or collect cash, debit, or credit transactions between the buyer and seller financial institution accounts. This can also be used by companies to move funds and deposit to a central bank account.
operationId: achPaymentCCD
security:
- bearerAuth: []
requestBody:
description: Contains mandatory parameters for initiating a ACH payment request for CCD.
content:
application/json:
schema:
$ref: '#/components/schemas/batchRequestEnvelopeBatchRequestCCDDetailRequest'
example:
batch:
collectionApplicationId: TEST
point: APITEST1
secCode: CCD
uuid: daily001-qas230109-010300-005
collectionApplicationType: ''
effectiveDate: '230211'
companyDescriptiveDate: '230211'
companyEntryDescription: Payroll
details:
- DFIAccountNumber: '123456'
accountType: C
amount: '0.01'
checkDigit: '9'
creditDebitCode: C
receivingCompanyName: ProdTest001
receivingDFIId: '04100103'
transactionType: L
uuid: daily001-qas230109-010301-0026
identificationNumber: '099999999a'
discretionaryData: AB
addenda:
- paymentRelatedInformation: DAILYTEST0103A
required: true
responses:
200:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/batchResponseEnvelopeAccepted'
example:
batch:
uuid: daily001-qas230109-010300-005
status: accepted
requestAcceptedUTCTime: '2023-05-03T17:04:03Z'
effectiveDate: '230211'
informationMessages:
- code: 1006040-65I
moreInfo: Effective date assigned 230211.
errorMessages: []
details:
- uuid: daily001-qas230109-010301-0026
status: accepted
errorMessages: []
informationMessages: []
traceNumber: '041001030013025'
requestAcceptedUTCTime: '2023-05-03T17:04:03Z'
'400':
description: Missing mandatory information
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Mandatory data not provided, please verify the data and resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/ccd"
'401':
description: Unauthorized request
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Received request is unauthorized, please provide valid credentials"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/ccd"
'403':
description: Forbidden request access
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Access to requested resource is forbidden"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/ccd"
'404':
description: Resource not found
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Requested resource is not found, please verify the resource then resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/ccd"
'405':
description: Invalid request method
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Requested method is not allowed, please verify the method and resubmit the request"
TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
X-CorrelationId: "929618f2-6163-bf73-51b0-6c54a8533c74"
TransactionTime: "2021-06-11T16:31:34.041Z"
Api-Url: "/ach/payments/v1/ccd"
'415':
description: Invalid request type
headers:
X-CorrelationId:
schema:
type: string
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
content:
application/json:
schema:
$ref: '#/components/schemas/exception'
example:
ErrorMessage: "Requested
# --- truncated at 32 KB (165 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/keycorp/refs/heads/main/openapi/keycorp-ach-originations-openapi.yml