openapi: 3.2.0 info: title: Management Direct Deposit API description: 'Internal, front-end VA applications can use this API to let eligible Veterans or their beneficiaries manage direct deposit information for VA disability, pension, and education benefit payments.' contact: name: VA.gov version: 0.0.1 servers: - url: https://sandbox-api.va.gov/services/direct-deposit-management/{version} description: Sandbox variables: version: default: v1 - url: https://api.va.gov/services/direct-deposit-management/{version} description: Production variables: version: default: v1 tags: - name: Direct Deposit paths: /direct-deposit: get: tags: - Direct Deposit summary: Get direct deposit account and eligibility and control information description: Get direct deposit account and eligibility and control information. operationId: GET:/direct-deposit parameters: - name: icn in: query description: The authenticated Veteran or beneficiary Master Patient Index (MPI) ICN required: true schema: maxLength: 17 minLength: 17 pattern: ^\d{10}V\d{6}$ type: string example: 1000000000V100000 responses: '200': description: A Response which indicates a successful Request. content: application/json: schema: $ref: '#/components/schemas/DirectDepositResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' '401': description: Not authorized content: application/json: schema: maxLength: 8000 minLength: 1 type: string example: message: Invalid authentication credentials '403': description: Forbidden content: application/json: schema: maxLength: 8000 minLength: 1 type: string example: message: You cannot consume this service '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/UserNotFound' '413': description: Payload too large content: application/json: schema: type: object properties: message: type: string example: message: Request size limit exceeded '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' '429': description: Too many requests content: application/json: schema: type: object properties: message: type: string example: message: API rate limit exceeded '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' '502': description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/BadGateway' '504': description: Gateway Timeout content: application/json: schema: type: object properties: message: type: string example: message: The server took too long to respond security: - OAuth: [] put: tags: - Direct Deposit summary: Create or update direct deposit account information description: Create or update direct deposit account information. operationId: PUT:/direct-deposit parameters: - name: icn in: query description: The authenticated Veteran or beneficiary Master Patient Index (MPI) ICN required: true schema: maxLength: 17 minLength: 17 pattern: ^\d{10}V\d{6}$ type: string example: 1000000000V100000 requestBody: description: The Update request content: application/json: schema: $ref: '#/components/schemas/UpdateRequest' required: true responses: '200': description: A Response which indicates successfully modified direct deposit information. content: application/json: schema: $ref: '#/components/schemas/DirectDepositResponse' '201': description: A Response which indicates successfully created direct deposit entry. content: application/json: schema: $ref: '#/components/schemas/DirectDepositResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequest' '401': description: Not authorized content: application/json: schema: maxLength: 8000 minLength: 1 type: string example: message: Invalid authentication credentials '403': description: Forbidden content: application/json: schema: maxLength: 8000 minLength: 1 type: string example: message: You cannot consume this service '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/UserNotFound' '406': description: Not Acceptable content: application/json: schema: $ref: '#/components/schemas/NotAcceptable' '413': description: Payload too large content: application/json: schema: type: object properties: message: type: string example: message: Request size limit exceeded '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' '429': description: Too many requests content: application/json: schema: type: object properties: message: type: string example: message: API rate limit exceeded '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' '502': description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/BadGateway' '504': description: Gateway Timeout content: application/json: schema: type: object properties: message: type: string example: message: The server took too long to respond security: - OAuth: [] components: schemas: ControlInformation: type: object properties: canUpdateDirectDeposit: type: boolean description: "All control information elements from the source system must be true (\"Y\") for update deposit to be set to true (\"Y\"), with the following exception:\none of the three payment type fields must also be true (\"Y\").\n 1. isEduClaimAvailable\n 2. hasCpClaim\n 3. hasCpAward\n\nMore than one of these payment types can be true, but at least one of them must be for update deposit to be set to true (\"Y\")." example: true isCorpAvailable: type: boolean description: If user record is found corpAvailInd is set to 'Y', else it is not returned. In case of any exception, it is set to 'N'. example: true isEduClaimAvailable: type: boolean description: If user record is found eduClaimInd is set to 'Y', else it is not returned. In case of any exception, it is set to 'N'. example: true hasCpClaim: type: boolean description: If user record is found cpClaimInd is set to 'Y', else it is not returned. In case of any exception, it is set to 'N'. example: true hasCpAward: type: boolean description: If user record is found authAwdInd is set to 'Y', else it is not returned. In case of any exception, it is set to 'N'. example: true isCorpRecFound: type: boolean description: If user record is found, corpRecFoundInd is set to 'Y', else it is set to 'N' for retrieve operation. In case of update, it is set to 'N' if user record is not found or else it is not populated. example: true hasNoBdnPayments: type: boolean description: This indicator only checks for Chapter 18 payments. If the PaymentInformationService has no paymentType for "Benefits for Children of Vietnam Veterans (inc. Spina Bifida)" this indicator is set to 'Y'. example: true hasIndentity: type: boolean description: If the user record is found and the last name and birth date matches with the queried parameters, indentityInd is set to 'Y' or else it is set to 'N'. example: true hasIndex: type: boolean description: If index record is found on BDN, indexInd is set based on who owns the Index (Award) record. If it is owned by VETSNET, it is set to 'V' and if it is owned by BDN it is set to 'B'. If index record is not found, it is set to 'X'. example: true isCompetent: type: boolean description: If person is incompetent, incompetentInd is set to 'Y' or else it is set to 'N'. If the user has an existing fiduciary or is incompetent (by rating or by court), no address information will be displayed or updatable. example: true hasMailingAddress: type: boolean description: If the Mailing address exists this field was set to 'Y', else it was set to 'N'. example: true hasNoFiduciaryAssigned: type: boolean description: If person record has a fiduciary, fiduciaryInd is set to 'Y' or else it is set to 'N'. If the user has an existing fiduciary, no address information will be displayed or updatable. example: true isNotDeceased: type: boolean description: If person record is found and has Date of Death, deathDtInd is set to 'Y' or else it is set to 'N'. example: true hasPaymentAddress: type: boolean description: If the Payment Address exists this field is set to 'Y', else it was set to 'N'. example: true EftInformation: type: object properties: accountType: maxLength: 8 minLength: 7 type: string description: The User Banking Account Type for Direct Deposit (Checking or Savings) example: Checking enum: - CHECKING - SAVINGS accountNumber: maxLength: 17 minLength: 4 type: string description: 'The User Account Number for Direct Deposit. Minimum 4 and maximum 17 alphanumeric characters are required for this value. ' example: ABC1234567 financialInstitutionRoutingNumber: type: string description: The Routing Number of the User's Bank example: '123456789' financialInstitutionName: type: string description: The Name of the User's Bank readOnly: true example: First National Bank USA UnprocessableEntity: type: object properties: type: maxLength: 8000 minLength: 1 type: string description: A URI reference that identifies the problem type. example: https://example.net/validation-error title: maxLength: 8000 minLength: 1 type: string description: A short, human-readable summary of the problem type. example: Invalid field value status: type: integer description: The HTTP status code generated by the origin server for this occurrence of the problem. format: int32 example: 400 detail: maxLength: 8000 minLength: 1 type: string description: A human-readable explanation specific to this occurrence of the problem. example: This error occurred because of... instance: maxLength: 36 minLength: 36 type: string description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: e6d1119e-dc91-4b4d-b583-0f309de0807b errorCodes: type: array items: $ref: '#/components/schemas/ErrorCode' example: type: https://api.va.gov/services/direct-deposit-management/errors/unable-to-update title: Unable To Update status: 422 detail: 'Unable to update: account fraud indicator = true.' instance: e48e3aeb-f312-11ec-88e8-f55e56a472a2 errorCodes: - errorCode: payment.restriction.indicators.present detail: hasNoBdnPayments is false. UserNotFound: type: object properties: type: maxLength: 8000 minLength: 1 type: string description: A URI reference that identifies the problem type. example: https://example.net/validation-error title: maxLength: 8000 minLength: 1 type: string description: A short, human-readable summary of the problem type. example: Invalid field value status: type: integer description: The HTTP status code generated by the origin server for this occurrence of the problem. format: int32 example: 400 detail: maxLength: 8000 minLength: 1 type: string description: A human-readable explanation specific to this occurrence of the problem. example: This error occurred because of... instance: maxLength: 36 minLength: 36 type: string description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: e6d1119e-dc91-4b4d-b583-0f309de0807b example: type: https://api.va.gov/services/direct-deposit-management/errors/generic/not-found title: Person for ICN not found status: 404 detail: No data found for ICN instance: e6d1119e-dc91-4b4d-b583-0f309de0807b InternalServerError: type: object properties: type: maxLength: 8000 minLength: 1 type: string description: A URI reference that identifies the problem type. example: https://example.net/validation-error title: maxLength: 8000 minLength: 1 type: string description: A short, human-readable summary of the problem type. example: Invalid field value status: type: integer description: The HTTP status code generated by the origin server for this occurrence of the problem. format: int32 example: 400 detail: maxLength: 8000 minLength: 1 type: string description: A human-readable explanation specific to this occurrence of the problem. example: This error occurred because of... instance: maxLength: 36 minLength: 36 type: string description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: e6d1119e-dc91-4b4d-b583-0f309de0807b example: type: https://api.va.gov/services/direct-deposit-management/errors/generic/internal-server-error title: Internal Server Error status: 500 detail: Internal Server Error instance: e6d1119e-dc91-4b4d-b583-0f309de0807b BadRequest: type: object properties: type: maxLength: 8000 minLength: 1 type: string description: A URI reference that identifies the problem type. example: https://example.net/validation-error title: maxLength: 8000 minLength: 1 type: string description: A short, human-readable summary of the problem type. example: Invalid field value status: type: integer description: The HTTP status code generated by the origin server for this occurrence of the problem. format: int32 example: 400 detail: maxLength: 8000 minLength: 1 type: string description: A human-readable explanation specific to this occurrence of the problem. example: This error occurred because of... instance: maxLength: 36 minLength: 36 type: string description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: e6d1119e-dc91-4b4d-b583-0f309de0807b errorCodes: type: array items: $ref: '#/components/schemas/ErrorCode' example: type: https://api.va.gov/services/direct-deposit-management/errors/constraint-violation title: Bad Request status: 400 detail: getDirectDeposit.icn must be between 17 and 17 instance: e48e3aeb-f312-11ec-88e8-f55e56a472a2 errorCodes: [] UpdateRequest: type: object properties: paymentAccount: $ref: '#/components/schemas/EftInformation' BadGateway: type: object properties: type: maxLength: 8000 minLength: 1 type: string description: A URI reference that identifies the problem type. example: https://example.net/validation-error title: maxLength: 8000 minLength: 1 type: string description: A short, human-readable summary of the problem type. example: Invalid field value status: type: integer description: The HTTP status code generated by the origin server for this occurrence of the problem. format: int32 example: 400 detail: maxLength: 8000 minLength: 1 type: string description: A human-readable explanation specific to this occurrence of the problem. example: This error occurred because of... instance: maxLength: 36 minLength: 36 type: string description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: e6d1119e-dc91-4b4d-b583-0f309de0807b debuggingPayload: maxLength: 8000 type: string description: Encrypted message to assist with debugging that occur while managing direct deposit information. example: VkEgUHJvZmlsZSBDb250YWN0IEluZm9ybWF0aW9uIF... example: type: https://api.va.gov/services/direct-deposit-management/errors/generic/bad-gateway title: Bad Gatewayr status: 502 detail: Bad Gateway instance: e6d1119e-dc91-4b4d-b583-0f309de0807b debuggingPayload: asdfghjklasdfghjkl DirectDepositResponse: required: - controlInformation - paymentAccount type: object properties: paymentAccount: $ref: '#/components/schemas/EftInformation' veteranStatus: type: string example: VETERAN enum: - VETERAN - DEPENDENT - NEITHER_VETERAN_NOR_DEPENDENT - COULD_NOT_DETERMINE_DUE_TO_EXCEPTION controlInformation: $ref: '#/components/schemas/ControlInformation' ErrorCode: type: object properties: errorCode: type: string example: payment.restriction.indicators.present detail: type: string example: hasNoBdnPayments was false NotAcceptable: type: object properties: type: maxLength: 8000 minLength: 1 type: string description: A URI reference that identifies the problem type. example: https://example.net/validation-error title: maxLength: 8000 minLength: 1 type: string description: A short, human-readable summary of the problem type. example: Invalid field value status: type: integer description: The HTTP status code generated by the origin server for this occurrence of the problem. format: int32 example: 400 detail: maxLength: 8000 minLength: 1 type: string description: A human-readable explanation specific to this occurrence of the problem. example: This error occurred because of... instance: maxLength: 36 minLength: 36 type: string description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: e6d1119e-dc91-4b4d-b583-0f309de0807b example: type: https://api.va.gov/direct-deposit-management/errors/not-acceptable title: Media type not acceptable status: 406 detail: Could not find acceptable representation instance: e6d1119e-dc91-4b4d-b583-0f309de0807b securitySchemes: OAuth: type: oauth2 flows: clientCredentials: tokenUrl: https://api.va.gov/oauth2/direct-deposit-management/system/v1/token scopes: direct-deposit-management.read: The veteran's access to direct deposit management that provides viewing of current EFT settings. direct-deposit-management.write: The veteran's access to direct deposit management that provides updating of current EFT settings.