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

# Add Bank Account

> Adds a bank account for a customer. Used as the payout destination for off-ramp transactions.

<Prompt description="Add Bank Account" actions={["cursor"]}>
  Integrate the DollarPe Add Bank Account endpoint into my application.

  Endpoint: POST /bank/create
  Base URL: [https://api.dollarpe.in](https://api.dollarpe.in) (production) | [https://sandbox.dollarpe.in](https://sandbox.dollarpe.in) (sandbox)

  Auth headers required on every request:

  * X-API-KEY: your API key
  * X-TIMESTAMP: current Unix time in seconds
  * X-SIGNATURE: Base64(HMAC-SHA256(X-API-KEY + X-TIMESTAMP + sortedJSONBody, apiSecret))

  Task: Write a typed function that:

  1. Accepts customer\_id and bank account details (account number, IFSC, account holder name)
  2. Builds the signed auth headers
  3. Calls POST /bank/create
  4. Returns the created bank account object with its ID
  5. Handles 400 (duplicate account, invalid IFSC, unverified customer) and 500 errors

  Language: TypeScript
</Prompt>

<Note>
  Either **\[account\_number, ifsc]** or **vpa** is required.
</Note>

<Note>
  Only 3 bank accounts and UPI IDs allowed.
</Note>

## Error Codes and Messages

| API Status Code | Response                               | Reason                                             |
| --------------- | -------------------------------------- | -------------------------------------------------- |
| 400             | Customer not found or access denied    | Customer not found                                 |
| 400             | Customer not found or access denied    | Customer does not belong to the organization       |
| 400             | Customer is unverified                 | Customer is not KYC verified                       |
| 400             | VPA already in use                     | UPI ID is already in use                           |
| 400             | Maximum 3 UPI IDs allowed              | 3 UPI IDs are already added for the customer       |
| 400             | Account number already in use          | Account number is already in use                   |
| 400             | Maximum 3 bank account details allowed | 3 Bank Accounts are already added for the customer |
| 400             | KYC already in use                     | KYC is being used by another customer              |
| 500             | Internal Server Error                  | Internal Server Error                              |


## OpenAPI

````yaml POST /bank/create
openapi: 3.1.0
info:
  title: DollarPe API
  description: API for DollarPe - Customer, Payout, and Webhook services
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://sandbox.dollarpe.xyz/pos/api/v1
    description: Payout API Base URL
    variables:
      base_url:
        default: https://sandbox.dollarpe.xyz
  - url: https://sandbox.dollarpe.xyz/cms/api/v1
    description: Customer API Base URL
    variables:
      base_url:
        default: https://sandbox.dollarpe.xyz
security:
  - ApiKeyAuth: []
    TimestampAuth: []
    SignatureAuth: []
tags:
  - name: Customer
    description: Customer related operations
    x-displayName: Customer
    x-traitTag: true
  - name: Payout
    description: Payout related operations
  - name: Webhooks
    description: Webhook related operations
  - name: Widget
    description: Hosted buy/sell widget session initialization
paths:
  /bank/create:
    post:
      tags:
        - Bank
      description: Add a new bank account for a customer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
              oneOf:
                - required:
                    - account_number
                    - ifsc
                  properties:
                    customer_id:
                      type: string
                      format: uuid
                      description: Customer's unique identifier
                      example: c2cf861b-342b-4318-a90e-85cd0312e82f
                    account_number:
                      type: string
                      description: Bank account number
                      example: '7627389201'
                    ifsc:
                      type: string
                      description: IFSC code of the bank
                      example: SBI0001829IU
                    account_name:
                      type: string
                      example: Sandbox Technologies Pvt Ltd
                - required:
                    - vpa
                  properties:
                    customer_id:
                      type: string
                      format: uuid
                      description: Customer's unique identifier
                      example: c2cf861b-342b-4318-a90e-85cd0312e82f
                    vpa:
                      type: string
                      description: Virtual Payment Address (UPI ID)
                      example: johndoe@oksbi
      responses:
        '200':
          description: Bank account added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        example: 4e6f1b20-a73c-11ec-b909-0242ac120002
                      customer_id:
                        type: string
                        format: uuid
                        example: 550e8400-e29b-41d4-a716-446655440000
                      account_number:
                        type: string
                        example: '123456789012'
                      ifsc:
                        type: string
                        example: ABC123456
                      account_name:
                        type: string
                        example: Sandbox Technologies Pvt Ltd
                      vpa:
                        type: string
                        example: testing@upi
                      bank_account_type:
                        type: string
                        example: ACCOUNT_DETAILS
                      bank_account_status:
                        type: string
                        example: VERIFIED
                      failure_reason:
                        type: string
                        example: 'null'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Bad Request
                  err_code:
                    type: string
                    example: REQ_FIELD_MISSING
                  errors:
                    type: object
                    properties:
                      account_number:
                        type: array
                        items:
                          type: string
                        example:
                          - account_number is required
                  data:
                    type: 'null'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Internal Server Error
                  err_code:
                    type: string
                    example: SYS_INTERNAL_ERROR
                  errors:
                    type: string
                    example: Unexpected error occurred. Please try again later.
                  data:
                    type: 'null'
      servers:
        - url: https://sandbox.dollarpe.xyz/cms/api/v1
          description: Bank API Base URL
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key for authentication
    TimestampAuth:
      type: apiKey
      in: header
      name: X-TIMESTAMP
      description: Current timestamp in seconds since epoch
    SignatureAuth:
      type: apiKey
      in: header
      name: X-SIGNATURE
      description: HMAC SHA256 signature of the request encoded in Base64

````