Payout Bank Account Management

Manage bank accounts for wallet payouts. Users can add multiple accounts, set defaults, and verify account details.

POST

/wallets/payout-bank-accounts

Add Payout Bank Account

Add a new bank account for receiving payouts. Requires Authorization: Bearer <token>.

Request Body

Request

{
  "chapaBankCode": "130",
  "accountNumber": "1234567890",
  "accountHolderName": "John Doe",
  "bankName": "Abay Bank",
  "isDefault": false
}

Response

Response (200 OK)

{
  "data": {
    "id": "uuid",
    "referenceId": "ByF-PAY-BANK-1B7A8C",
    "chapaBankCode": "130",
    "accountNumber": "1234567890",
    "accountHolderName": "John Doe",
    "bankName": "Abay Bank",
    "status": "Pending_Verification",
    "isDefault": false,
    "createdAt": "2025-08-31T13:34:21.700Z"
  },
  "message": "Payout bank account added successfully",
  "success": true
}

GET

/wallets/payout-bank-accounts

Get All Payout Bank Accounts

Retrieve all bank accounts for the authenticated user. Requires Authorization: Bearer <token>.

Response

Response (200 OK)

{
  "data": [
    {
      "referenceId": "ByF-PAY-BANK-1B7A8C",
      "accountNumber": "1234567890",
      "accountHolderName": "John Doe",
      "bankName": "Abay Bank",
      "status": "Verified",
      "isDefault": true,
      "usageCount": 5,
      "lastUsedAt": "2025-08-31T10:00:00Z"
    }
  ],
  "success": true
}

GET

/wallets/payout-bank-accounts/{referenceId}

Get Payout Bank Account

Retrieve details of a specific bank account by referenceId. Requires Authorization: Bearer <token>.

Query Parameters

Path:
referenceId: string (e.g., "ByF-PAY-BANK-1B7A8C")

PUT

/wallets/payout-bank-accounts/{referenceId}

Update Payout Bank Account

Update bank account information. Requires Authorization: Bearer <token>.

Request Body

Request

{
  "accountHolderName": "John Smith Doe",
  "bankName": "Commercial Bank of Ethiopia",
  "notes": "Updated account information"
}

PUT

/wallets/payout-bank-accounts/{referenceId}/set-default

Set Default Payout Bank Account

Set a bank account as the default for payouts. Requires Authorization: Bearer <token>.

Request Body

Request

{
  "isDefault": true
}

Response

Response (200 OK)

{
  "data": { "referenceId": "ByF-PAY-BANK-1B7A8C", "isDefault": true },
  "message": "Default payout bank account set successfully",
  "success": true
}

GET

/wallets/users/{userReferenceId}/payout-bank-accounts/default

Get Default Payout Bank Account

Retrieve the default bank account for a user. Requires Authorization: Bearer <token>.

Response

Response (200 OK)

{
  "data": {
    "referenceId": "ByF-PAY-BANK-1B7A8C",
    "accountNumber": "1234567890",
    "accountHolderName": "John Doe",
    "bankName": "Abay Bank",
    "status": "Verified",
    "isDefault": true
  },
  "message": "Default payout bank account retrieved",
  "success": true
}

DELETE

/wallets/payout-bank-accounts/{referenceId}

Delete Payout Bank Account

Remove a bank account from the user's payout options. Requires Authorization: Bearer <token>.

Response

Response (200 OK)

{
  "success": true,
  "message": "Payout bank account deleted successfully"
}