> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ach.netevia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a Merchant into the ACH application ( STABLE )

> This endpoint allows for updating a Merchant to the GrailPay ACH API Ecosystem.



## OpenAPI

````yaml https://api.grailpay.com/docs?api-docs.json patch /api/v3/merchants/{uuid}
openapi: 3.0.0
info:
  title: GrailPay ACH API
  description: API Documentation for moving funds via ACH using the GrailPay ACH API
  version: 2025.12.19.2
servers:
  - url: https://api.grailpay.com
    description: Production environment
  - url: https://api-sandbox.grailpay.com
    description: Sandbox environment
security: []
tags:
  - name: Users
    description: >-
      API Endpoints used for the onboarding and managing People, Businesses, and
      Merchants.
  - name: Transactions
    description: API Endpoints used for creating and managing transactions.
  - name: Payouts
    description: API Endpoints used for fetching payout information.
  - name: Refunds
    description: API Endpoints used for creating and retrieving refunds.
  - name: Bank Accounts
    description: API Endpoints used for adding and managing bank accounts.
  - name: Webhooks
    description: API Endpoints used for registering and de-registering webhooks.
  - name: Billing
    description: API Endpoints used for retrieving billing information.
  - name: Stable
    description: Stable, up-to-date APIs that are recommended for current integration.
  - name: Sunsetting
    description: Sunsetting APIs that are still supported but scheduled for deprecation.
  - name: Deprecated
    description: Deprecated APIs that are no longer supported and should be removed.
  - name: SUNSETTING
    description: SUNSETTING
paths:
  /api/v3/merchants/{uuid}:
    patch:
      tags:
        - Users
        - Stable
      summary: Update a Merchant into the ACH application ( STABLE )
      description: >-
        This endpoint allows for updating a Merchant to the GrailPay ACH API
        Ecosystem.
      operationId: 6680b96fb19eb86c8aea7805cbada282
      parameters:
        - name: uuid
          in: path
          description: merchant UUID
          required: true
          schema:
            type: string
            format: uuid
            example: 7c41f6a2-a4b9-4df8-9225-2c1b7312042e
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                client_reference_id:
                  type: string
                  example: reference_12345
                billing_merchant_uuid:
                  type: string
                  format: uuid
                  example: 6a8fc154-1a50-483b-a690-fd1dfaf9408b
                billing_processor_mid:
                  type: string
                  example: '12345678'
                payout_type:
                  type: string
                  enum:
                    - batch
                    - individual
                  example: batch
                person:
                  required:
                    - first_name
                    - last_name
                    - email
                    - phone
                  type: object
                  allOf:
                    - $ref: '#/components/schemas/V3PersonRequestObject'
                merchant:
                  $ref: '#/components/schemas/V3MerchantRequestObject'
                beneficial_owners:
                  type: array
                  items:
                    $ref: '#/components/schemas/V3BeneficialOwnerRequestObject'
                bank_account:
                  $ref: '#/components/schemas/V3BankAccountObject'
                actions:
                  properties:
                    account_intelligence:
                      $ref: '#/components/schemas/V3AccountIntelligenceRequestObject'
                  type: object
              type: object
      responses:
        '200':
          description: The response returned from a successful call to update a merchant.
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: This merchant was updated successfully.
                  data:
                    properties:
                      merchant:
                        $ref: '#/components/schemas/V3MerchantResponseObject'
                      beneficial_owners:
                        type: array
                        items:
                          $ref: '#/components/schemas/V3BeneficialOwnerResponseObject'
                      relations:
                        properties:
                          person:
                            properties:
                              uuid:
                                type: string
                                format: uuid
                                example: 7c41f6a2-a4b9-4df8-9225-2c1b7312042e
                            type: object
                        type: object
                      account_intelligence:
                        oneOf:
                          - $ref: >-
                              #/components/schemas/V3AccountIntelligenceV3Response
                          - $ref: >-
                              #/components/schemas/V3AccountIntelligenceV2Response
                          - $ref: >-
                              #/components/schemas/V3AccountIntelligenceV1Response
                          - $ref: >-
                              #/components/schemas/V3AccountIntelligenceThresholdResponse
                    type: object
                  errors:
                    type: object
                    example: null
                    nullable: true
                  request_id:
                    type: string
                    format: uuid
                    example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
                type: object
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/V3ErrorInvalidParameters400'
                  - $ref: '#/components/schemas/V3ErrorInvalidAcceptHeader400'
        '401':
          description: 401 - Unauthorized
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/V3ErrorInvalidToken401'
                  - $ref: '#/components/schemas/V3ErrorUnauthorized401'
        '403':
          description: 403 - Forbidden
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: >-
                      This merchant is not available as they have been scheduled
                      for deletion.
                  data:
                    type: object
                    example: null
                    nullable: true
                  errors:
                    type: object
                    example: null
                    nullable: true
                  request_id:
                    type: string
                    format: uuid
                    example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
                type: object
        '404':
          description: 404 - Not Found
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: A merchant matching this UUID was not found.
                  data:
                    type: object
                    example: null
                    nullable: true
                  errors:
                    type: object
                    example: null
                    nullable: true
                  request_id:
                    type: string
                    format: uuid
                    example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
                type: object
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorIdempotency409'
        '422':
          description: 422 - Unprocessable Entity
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: The given data was invalid.
                  data:
                    type: object
                    example: null
                    nullable: true
                  errors:
                    type: object
                    allOf:
                      - $ref: '#/components/schemas/V3OnboardingValidationErrors'
                      - $ref: '#/components/schemas/V3PersonValidationError'
                      - $ref: '#/components/schemas/V3BusinessValidationError'
                  request_id:
                    type: string
                    format: uuid
                    example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
                type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: >-
                      There was a problem on the server and the action could not
                      be completed. Please try again.
                  data:
                    type: object
                    example: null
                    nullable: true
                  errors:
                    type: object
                    example: null
                    nullable: true
                  request_id:
                    type: string
                    format: uuid
                    example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
                type: object
      security:
        - ApiToken: []
components:
  schemas:
    V3PersonRequestObject:
      title: Person Request Object
      description: Schema for a person request object
      properties:
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        email:
          type: string
          format: email
          example: john.doe@example.com
        phone:
          type: string
          example: '2457856490'
        address:
          $ref: '#/components/schemas/V3AddressObject'
      type: object
    V3MerchantRequestObject:
      title: Merchant Request Object
      description: Schema for a merchant request object
      required:
        - name
        - tin
        - trading_name
        - entity_type
        - address
      properties:
        name:
          type: string
          example: Acme Inc.
        tin:
          type: string
          example: '123456789'
        trading_name:
          type: string
          example: Acme Corp
        entity_type:
          type: string
          example: Sole Trader
        incorporation_date:
          type: string
          format: date
          example: '2024-02-02'
        incorporation_state:
          type: string
          example: CO
        address_type:
          type: string
          example: Registered
        address:
          required:
            - line_1
            - city
            - state
            - zip
          type: object
          allOf:
            - $ref: '#/components/schemas/V3AddressObject'
        transaction_fee_percent:
          type: number
          format: float
          example: 2.5
        transaction_fee_fixed:
          type: number
          example: 100
        maximum_transaction_fee:
          type: number
          example: 5000
      type: object
    V3BeneficialOwnerRequestObject:
      title: Beneficial Owner Request Object
      description: Schema for a beneficial owner request object
      required:
        - first_name
        - last_name
        - dob
        - ssn9
        - address
        - is_beneficial_owner
        - is_director
        - is_significant_control_person
        - ownership_percentage
        - email
        - phone
        - occupation
      properties:
        first_name:
          type: string
          example: Jane
        last_name:
          type: string
          example: Doe
        dob:
          type: string
          format: date
          example: '2023-04-11'
        ssn9:
          type: string
          example: '123456789'
        address:
          required:
            - line_1
            - city
            - state
            - zip
          type: object
          allOf:
            - $ref: '#/components/schemas/V3AddressObject'
        is_beneficial_owner:
          type: boolean
          example: true
        is_director:
          type: boolean
          example: false
        is_significant_control_person:
          type: boolean
          example: false
        ownership_percentage:
          type: number
          format: float
          example: 25
        email:
          type: string
          example: owner@test.com
        phone:
          type: string
          example: '2457856490'
        occupation:
          type: string
          example: Co-founder
      type: object
    V3BankAccountObject:
      properties:
        plaid_account_id:
          type: string
          nullable: true
        plaid_access_token:
          type: string
          nullable: true
        account_number:
          type: string
          example: '9876543210'
        routing_number:
          type: string
          example: '021000021'
        account_name:
          type: string
          example: John Doe
        account_type:
          type: string
          enum:
            - checking
            - savings
          example: checking
      type: object
    V3AccountIntelligenceRequestObject:
      required:
        - version
      properties:
        version:
          type: string
          enum:
            - v1
            - v2
            - v3
          example: v3
        name_match:
          type: boolean
          example: true
          nullable: true
      type: object
    V3MerchantResponseObject:
      properties:
        uuid:
          type: string
          example: c6bcfbbb-98ff-4d8b-a8f5-1559c3dcb718
        business_type:
          type: string
          example: merchant
        kyb_status:
          type: string
          example: IN_REVIEW
        kyb_rejected_reason:
          type: string
          example: null
        name:
          type: string
          example: Acme Inc.
        tin:
          type: string
          example: '123456789'
        trading_name:
          type: string
          example: Acme Corp
        entity_type:
          type: string
          example: Sole Trader
        incorporation_date:
          type: string
          example: '2024-02-02'
        incorporation_state:
          type: string
          example: CO
        address_type:
          type: string
          example: Registered
        address:
          $ref: '#/components/schemas/V3AddressObject'
        transaction_fee_percent:
          type: number
          format: float
          example: 2.5
        transaction_fee_fixed:
          type: number
          example: 100
        maximum_transaction_fee:
          type: number
          example: 5000
        payout_type:
          type: string
          example: batch
        client_reference_id:
          type: string
          example: reference_12345
        timestamps:
          $ref: '#/components/schemas/V3TimestampsObject'
      type: object
    V3BeneficialOwnerResponseObject:
      properties:
        first_name:
          type: string
          example: Jane
        last_name:
          type: string
          example: Doe
        dob:
          type: string
          example: '2023-04-11'
        ssn9:
          type: string
          example: '123456789'
        address:
          $ref: '#/components/schemas/V3AddressObject'
        is_beneficial_owner:
          type: boolean
          example: true
        is_director:
          type: boolean
          example: false
        is_significant_control_person:
          type: boolean
          example: false
        ownership_percentage:
          type: number
          format: float
          example: 25
        email:
          type: string
          example: owner@test.com
        phone:
          type: string
          example: '2457856490'
        occupation:
          type: string
          example: Co-founder
        timestamps:
          $ref: '#/components/schemas/V3TimestampsObject'
      type: object
    V3AccountIntelligenceV3Response:
      properties:
        confidence_score:
          type: number
          format: float
          example: 0.81
        decisioning_insights:
          properties:
            account_duplicate:
              type: boolean
              example: false
            days_since_first_seen:
              type: integer
              example: -1
            days_since_last_transaction:
              type: integer
              example: -1
            has_negative_transactions:
              type: boolean
              example: false
            has_paid_transactions:
              type: boolean
              example: false
            has_positive_transactions:
              type: boolean
              example: true
            name_match:
              type: string
              example: 'yes'
            phone_number_present:
              type: boolean
              example: false
            valid_routing_number:
              type: boolean
              example: true
          type: object
        version:
          type: string
          example: v3
      type: object
    V3AccountIntelligenceV2Response:
      properties:
        confidence_score:
          type: number
          format: float
          example: 0.81
        confidence_level:
          type: string
          enum:
            - very low
            - low
            - medium
            - high
            - very high
          example: very high
        version:
          type: string
          example: v2
      type: object
    V3AccountIntelligenceV1Response:
      properties:
        validity:
          type: string
          enum:
            - valid
            - invalid
            - not_validated
          example: valid
        version:
          type: string
          example: v1
      type: object
    V3AccountIntelligenceThresholdResponse:
      properties:
        confidence_score:
          type: number
          format: float
          example: 0.81
        threshold:
          type: number
          format: float
          example: 0.6
        confidence_level:
          type: string
          enum:
            - very low
            - low
            - medium
            - high
            - very high
          example: very high
        version:
          type: string
          example: v2
      type: object
    V3ErrorInvalidParameters400:
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid Parameters Received
        data:
          type: string
          example: null
          nullable: true
        errors:
          type: string
          example: null
          nullable: true
        request_id:
          type: string
          format: uuid
          example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
      type: object
    V3ErrorInvalidAcceptHeader400:
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid value provided for Accept header.
        data:
          type: object
          example: null
          nullable: true
        errors:
          type: object
          example: null
          nullable: true
        request_id:
          type: string
          format: uuid
          example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
      type: object
    V3ErrorInvalidToken401:
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid token.
        data:
          type: object
          example: null
          nullable: true
        errors:
          type: object
          example: null
          nullable: true
        request_id:
          type: string
          format: uuid
          example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
      type: object
    V3ErrorUnauthorized401:
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: This action is unauthorized.
        data:
          type: object
          example: null
          nullable: true
        errors:
          type: object
          example: null
          nullable: true
        request_id:
          type: string
          format: uuid
          example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
      type: object
    V3ErrorIdempotency409:
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: >-
            The request cannot be executed due to a detected conflict with a
            duplicate request.
        data:
          type: object
          example: null
          nullable: true
        errors:
          type: object
          example: null
          nullable: true
        request_id:
          type: string
          format: uuid
          example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
      type: object
    V3OnboardingValidationErrors:
      properties:
        client_reference_id:
          type: object
          example:
            - The client reference ID must be a string.
            - The client reference ID may not be greater than 255 characters.
        billing_merchant_uuid:
          type: object
          example:
            - The billing merchant UUID must be a valid UUID.
            - The billing merchant UUID does not exist.
            - >-
              The billing merchant UUID is deleted and cannot be used for
              billing purposes.
        billing_processor_mid:
          type: object
          example:
            - The billing processor MID must be a string.
            - The billing processor MID does not exist.
            - >-
              The billing processor MID is deleted and cannot be used for
              billing purposes.
        payout_type:
          type: object
          example:
            - The payout type must be a string.
            - 'The payout type must be one of the followings: individual, batch'
        bank_account:
          type: object
          example:
            - >-
              You cannot provide both plaid details and manual bank account
              fields.
            - >-
              This person did not meet the confidence score threshold of 0.5 and
              has been rejected.
            - Invalid plaid account ID or access token.
            - The bank routing number is not valid.
        bank_account.plaid_account_id:
          type: object
          example:
            - >-
              The plaid account ID is required when plaid account details is
              present.
            - The plaid account ID must be a string.
        bank_account.plaid_access_token:
          type: object
          example:
            - >-
              The plaid access token is required when plaid account details is
              present.
            - The plaid access token must be a string.
        bank_account.account_number:
          type: object
          example:
            - >-
              The bank account number is required when any manual bank account
              field is provided.
            - The bank account number must be a string.
            - The bank account number may not be greater than 17 characters.
        bank_account.routing_number:
          type: object
          example:
            - >-
              The bank routing number is required when any manual bank account
              field is provided.
            - The bank routing number must be 9 digits.
        bank_account.account_name:
          type: object
          example:
            - >-
              The bank account name is required when any manual bank account
              field is provided.
            - The bank account name must be a string.
            - The bank account name may not be greater than 255 characters.
        bank_account.account_type:
          type: object
          example:
            - >-
              The bank account type is required when any manual bank account
              field is provided.
            - >-
              The bank account type must be one of the followings: savings,
              checking
        actions.account_intelligence:
          type: object
          example:
            - >-
              The person first and last name are required when name match is
              true.
            - >-
              Name Match is only available when using Account Intelligence
              Version 3. Please update your request and try again.
        actions.account_intelligence.version:
          type: object
          example:
            - The version is required when account intelligence is present.
            - The version must be a string.
            - 'The version must be one of the followings: v1, v2, v3'
        actions.account_intelligence.name_match:
          type: object
          example:
            - The name match field must be true or false.
      type: object
    V3PersonValidationError:
      properties:
        person.first_name:
          type: object
          example:
            - The first name must be a string.
            - The first name may not be greater than 56 characters.
        person.last_name:
          type: object
          example:
            - The last name must be a string.
            - The last name may not be greater than 56 characters.
        person.email:
          type: object
          example:
            - The email must be a valid email address.
        person.phone:
          type: object
          example:
            - The phone must be a string.
            - >-
              Phone numbers should consist of 10 digits and should not contain
              the +1 prefix or any special characters.
        person.address.line_1:
          type: object
          example:
            - The address line 1 is required when address is present.
            - The address line 1 must be a string.
            - The address line 1 may not be greater than 255 characters.
        person.address.line_2:
          type: object
          example:
            - The address line 2 must be a string.
            - The address line 2 may not be greater than 255 characters.
        person.address.city:
          type: object
          example:
            - The city name is required when address is present.
            - The city name must be a string.
            - The city name may not be greater than 56 characters.
            - >-
              The city name field only accepts letters (a-z, A-Z), numbers
              (0-9), hyphens (-), periods (.), apostrophes ('), and spaces.
        person.address.state:
          type: object
          example:
            - The state is required when address is present.
            - The state must be a string.
            - The state may not be greater than 2 characters.
            - The state must be valid US state.
        person.address.zip:
          type: object
          example:
            - The zip code is required when address is present.
            - The zip code must be a string.
            - The zip code must consist of 5 digit.
      type: object
    V3BusinessValidationError:
      properties:
        business.name:
          type: object
          example:
            - The name must be a string.
            - The name may not be greater than 255 characters.
        business.trading_name:
          type: object
          example:
            - The trading name must be a string.
            - The trading name may not be greater than 255 characters.
        business.address.line_1:
          type: object
          example:
            - The address line 1 is required when address is present.
            - The address line 1 must be a string.
            - The address line 1 may not be greater than 255 characters.
        business.address.line_2:
          type: object
          example:
            - The address line 2 must be a string.
            - The address line 2 may not be greater than 255 characters.
        business.address.city:
          type: object
          example:
            - The city name is required when address is present.
            - The city name must be a string.
            - The city name may not be greater than 56 characters.
            - >-
              The city name field only accepts letters (a-z, A-Z), numbers
              (0-9), hyphens (-), periods (.), apostrophes ('), and spaces.
        business.address.state:
          type: object
          example:
            - The state is required when address is present.
            - The state must be a string.
            - The state may not be greater than 2 characters.
            - The state must be valid US state.
        business.address.zip:
          type: object
          example:
            - The zip code is required when address is present.
            - The zip code must be a string.
            - The zip code must consist of 5 digit.
      type: object
    V3AddressObject:
      properties:
        line_1:
          type: string
          example: 10554 W Quarles Ave
        line_2:
          type: string
          example: Suite 123
          nullable: true
        city:
          type: string
          example: Littleton
        state:
          type: string
          example: CO
        zip:
          type: string
          example: '80127'
      type: object
    V3TimestampsObject:
      properties:
        created_at:
          type: string
          example: '2024-06-25 13:57:03'
      type: object
  securitySchemes:
    ApiToken:
      type: http
      description: >-
        Token-based authentication using Authorization: Bearer <YOUR_API_KEY>
        provided by the GrailPay Support Team.
      bearerFormat: Token
      scheme: bearer

````