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

# GET Merchant Balance

> Retrieve current merchant information and status

Retrieves the current balance information for the authenticated merchant account. This endpoint provides the merchant's wallet balance in both raw numeric format and formatted currency display.

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl --location 'https://api-empresas.staging.topup.com.co/production/api/v1/merchant/balance' \
  --header 'Token-Top: your_auth_token' \
  --header 'Authorization: Basic your_auth_key'
  ```

  ```rust Rust theme={null}
  use reqwest::Client;
  use serde_json::json;

  async fn get_merchant_balance() -> Result<(), reqwest::Error> {
      let client = Client::new();
      let response = client.get("https://api-empresas.staging.topup.com.co/production/api/v1/merchant/balance")
          .header("Token-Top", "your_auth_token")
          .header("Authorization", "Basic your_auth_key")
          .send()
          .await?;

      let response_json: serde_json::Value = response.json().await?;
      println!("{:#?}", response_json);

      Ok(())
  }
  ```

  ```typescript TypeScript theme={null}
  import axios from 'axios';

  const getMerchantBalance = async () => {
    try {
      const response = await axios.get('https://api-empresas.staging.topup.com.co/production/api/v1/merchant/balance', {
        headers: {
          'Token-Top': 'your_auth_token',
          'Authorization': 'Basic your_auth_key'
        }
      });
      console.log(response.data);
    } catch (error) {
      console.error(error);
    }
  };

  getMerchantBalance();
  ```

  ```php PHP theme={null}
  <?php

  $url = "https://api-empresas.staging.topup.com.co/production/api/v1/merchant/balance";
  $headers = [
      'Token-Top: your_auth_token',
      'Authorization: Basic your_auth_key'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  ```

  ```java Java theme={null}
  import java.io.IOException;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class Main {
      public static void main(String[] args) throws IOException, InterruptedException {
          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
                  .uri(URI.create("https://api-empresas.staging.topup.com.co/production/api/v1/merchant/balance"))
                  .header("Token-Top", "your_auth_token")
                  .header("Authorization", "Basic your_auth_key")
                  .build();

          HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
          System.out.println(response.body());
      }
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"io/ioutil"
  	"net/http"
  )

  func main() {
  	req, err := http.NewRequest("GET", "https://api-empresas.staging.topup.com.co/production/api/v1/merchant/balance", nil)
  	if err != nil {
  		// handle err
  	}
  	req.Header.Set("Token-Top", "your_auth_token")
  	req.Header.Set("Authorization", "Basic your_auth_key")

  	resp, err := http.DefaultClient.Do(req)
  	if err != nil {
  		// handle err
  	}
  	defer resp.Body.Close()
  	body, _ := ioutil.ReadAll(resp.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

<ResponseExample>
  ```json theme={null}
  {
      "code": "01",
      "status": "SUCCESS",
      "message": "",
      "data": {
          "currency": "COP",
          "balance": 138827007.4,
          "balance_formatted": "COP 138.827.007,40"
      }
  }
  ```
</ResponseExample>

## Required Headers

<ParamField header="Token-Top" type="string" required>
  Your merchant authentication token
</ParamField>

<ParamField header="Authorization" type="string" required>
  Basic authentication credentials
</ParamField>

## Response

<ResponseField name="code" type="string">
  Response code indicating success or failure
</ResponseField>

<ResponseField name="status" type="string">
  Status of the response (e.g., "SUCCESS")
</ResponseField>

<ResponseField name="message" type="string">
  Additional message about the response
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="Balance Information">
    <ResponseField name="currency" type="string">
      The currency code for the balance (e.g., "COP")
    </ResponseField>

    <ResponseField name="balance" type="number">
      Current wallet balance in raw numeric format
    </ResponseField>

    <ResponseField name="balance_formatted" type="string">
      Human-readable formatted balance with currency symbol and thousands separators
    </ResponseField>
  </Expandable>
</ResponseField>


## OpenAPI

````yaml get /merchant/balance
openapi: 3.0.0
info:
  title: Merchant API
  version: 1.0.0
  description: API for merchant operations
servers:
  - url: https://api-empresas.staging.topup.com.co/production/api/v1
    description: Staging server
security: []
paths:
  /merchant/balance:
    get:
      summary: Get Merchant Information
      description: Retrieve current merchant information and status
      operationId: getMerchantInfo
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique identifier for the merchant
                  name:
                    type: string
                    description: Commercial name of the merchant
                  legal_name:
                    type: string
                    description: Legal registered name of the business
                  document_number:
                    type: string
                    description: Tax ID or business registration number
                  business_type:
                    type: string
                    enum:
                      - COMPANY
                      - INDIVIDUAL
                    description: Type of business
                  status:
                    type: string
                    enum:
                      - ACTIVE
                      - INACTIVE
                      - PENDING
                    description: Current merchant status
                  email:
                    type: string
                    format: email
                    description: Primary contact email
                  phone:
                    type: string
                    description: Contact phone number with country code
                  country:
                    type: string
                    description: Two-letter country code (ISO 3166-1 alpha-2)
                  created_at:
                    type: string
                    format: date-time
                    description: UTC timestamp of merchant account creation
                  updated_at:
                    type: string
                    format: date-time
                    description: UTC timestamp of last account update
        '401':
          description: Unauthorized
        '404':
          description: Merchant not found
      security:
        - Token-Top: []
          BasicAuth: []
components:
  securitySchemes:
    Token-Top:
      type: apiKey
      name: Token-Top
      in: header
      description: Merchant authentication token
    BasicAuth:
      type: http
      scheme: basic
      description: Basic authentication with username and password

````