# Register ACH account

Register a new Automated Clearing House (ACH) bank account. 

ACH is an electronic network for financial transactions in the United States. ACH processes large volumes of credit and debit transactions in batches.

To read about Pismo's banking offerings, see [Banking overview](doc:banking-overview).

This endpoint generates a [Bank account registered](https://developers.pismo.io/events/docs/intl-bankaccounts-intl-bankaccount-register-1) event.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Banking - Bank accounts",
    "version": "1.0.0",
    "description": "API for managing bank accounts in global formats",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/intl-bankaccounts",
      "description": "Sandbox API server for testing"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Bank accounts",
      "description": "Bank account management endpoints"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Account token - token encoded with Pismo account ID. Tokens can expire quickly, which can result in an **401 Unauthorized** error.",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "accountIDpath": {
        "name": "accountId",
        "in": "path",
        "description": "Pismo account ID",
        "required": true,
        "schema": {
          "type": "string"
        },
        "example": "78123456"
      },
      "auth": {
        "name": "AuthorizationHeader",
        "in": "header",
        "description": "Account token - Token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a **401 Unauthorized** error. \n",
        "required": true,
        "schema": {
          "type": "string"
        },
        "example": 1234
      }
    },
    "schemas": {
      "accountID": {
        "type": "integer",
        "description": "Account ID",
        "example": 78123456
      },
      "usaAccountNumber": {
        "type": "string",
        "minLength": 17,
        "maxLength": 17,
        "example": "12345678901234567",
        "description": "Account number"
      },
      "usaRoutingNumber": {
        "type": "string",
        "minLength": 9,
        "maxLength": 9,
        "example": "123456789",
        "description": "A routing number is a nine-digit number used to identify a financial institution in the United States. It is also known as an ABA (American Bankers Association) number.\n"
      },
      "creationDatetime": {
        "type": "string",
        "format": "date-time",
        "description": "Account creation date time displayed in ISO 8601 format `2023-04-12T23:20:50.52Z`.",
        "example": "2023-04-12T23:20:50.52Z"
      },
      "domain.Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error type code",
            "example": "EIBA0001"
          },
          "details": {
            "type": "string",
            "description": "Error details",
            "example": "Key not found"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Key not found"
          }
        }
      },
      "intlbankaccounts.AchScheme": {
        "type": "object",
        "required": [
          "account_number",
          "routing_number"
        ],
        "properties": {
          "account_number": {
            "$ref": "#/components/schemas/usaAccountNumber"
          },
          "routing_number": {
            "$ref": "#/components/schemas/usaRoutingNumber"
          }
        }
      },
      "intlbankaccounts.IntlBankAccountAchRequest": {
        "type": "object",
        "required": [
          "scheme"
        ],
        "properties": {
          "scheme": {
            "$ref": "#/components/schemas/intlbankaccounts.AchScheme"
          },
          "metadata": {
            "$ref": "#/components/schemas/metadata"
          }
        }
      },
      "intlbankaccounts.IntlBankAccountAchResponse": {
        "type": "object",
        "required": [
          "scheme"
        ],
        "properties": {
          "account_id": {
            "$ref": "#/components/schemas/accountID"
          },
          "creation_datetime": {
            "$ref": "#/components/schemas/creationDatetime"
          },
          "metadata": {
            "$ref": "#/components/schemas/metadata"
          },
          "scheme": {
            "$ref": "#/components/schemas/intlbankaccounts.AchScheme"
          }
        }
      },
      "metadata": {
        "additionalProperties": true,
        "type": "object",
        "description": "A set of key-value pairs used to store custom data or additional information."
      }
    }
  },
  "paths": {
    "/v2/accounts/{accountId}/bank-accounts/ach": {
      "post": {
        "tags": [
          "Bank accounts"
        ],
        "summary": "Register ACH account",
        "description": "Register a new Automated Clearing House (ACH) bank account. \n\nACH is an electronic network for financial transactions in the United States. ACH processes large volumes of credit and debit transactions in batches.\n\nTo read about Pismo's banking offerings, see [Banking overview](https://developers.pismo.io/pismo-docs/docs/banking-overview).\n\nThis endpoint generates a [Bank account registered](https://developers.pismo.io/events/docs/intl-bankaccounts-intl-bankaccount-register-1) event.\n",
        "operationId": "post-intl-bank-accounts-v2-accounts-account-id-bank-accounts-ach",
        "parameters": [
          {
            "$ref": "#/components/parameters/auth"
          },
          {
            "$ref": "#/components/parameters/accountIDpath"
          }
        ],
        "requestBody": {
          "description": "Register ACH request Body",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/intlbankaccounts.IntlBankAccountAchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Response body",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/intlbankaccounts.IntlBankAccountAchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0009": {
                    "summary": "Validation Error",
                    "value": {
                      "code": "EIBA0009",
                      "message": "Validation error"
                    }
                  },
                  "EIBA0012": {
                    "summary": "Accounts API invalid request",
                    "value": {
                      "code": "EIBA0012",
                      "message": "Accounts - API returned 4xx error"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0006": {
                    "summary": "Missing tenant header",
                    "value": {
                      "code": "EIBA0006",
                      "message": "Missing required header: 'x-tenant'"
                    }
                  },
                  "EIBA0007": {
                    "summary": "Invalid account ID header",
                    "value": {
                      "code": "EIBA0007",
                      "message": "Invalid account ID header: 'x-account-id'"
                    }
                  },
                  "EIBA0023": {
                    "summary": "Account status not NORMAL",
                    "value": {
                      "code": "EIBA0023",
                      "message": "Account status not NORMAL"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0010": {
                    "summary": "Account not found",
                    "value": {
                      "code": "EIBA0010",
                      "message": "Account not found"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0028": {
                    "summary": "IntlBankAccount Already Exists",
                    "value": {
                      "code": "EIBA0028",
                      "message": "IntlBankAccount - Already Exists"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0005": {
                    "summary": "HTTP error",
                    "value": {
                      "code": "EIBA0005",
                      "message": "HTTP error"
                    }
                  },
                  "EIBA0011": {
                    "summary": "Accounts API server error",
                    "value": {
                      "code": "EIBA0011",
                      "message": "Accounts - API returned 5xx error"
                    }
                  },
                  "EIBA0013": {
                    "summary": "Accounts API timeout",
                    "value": {
                      "code": "EIBA0013",
                      "message": "Accounts - API timeout"
                    }
                  },
                  "EIBA0015": {
                    "summary": "Database error",
                    "value": {
                      "code": "EIBA0015",
                      "message": "Database internal error"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codegen-request-body-name": "RequestBody"
      }
    }
  }
}
```