> ## 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.

# Authentication

> Credential Request and Authentication Procedures.

## Obtaining Credentials

To access Tumipay's APIs you must request credentials from our support team. Send an email to [it@tumipay.co](mailto:it@tumipay.co) with your company details. After verification you will receive:

* A username and password for **Basic Authentication**.
* A merchant token provided as the `Token-Top` value.

Tokens remain valid until they are rotated or revoked. If your token is at risk of exposure or requires renewal, please contact [Tumipay support](mailto:it@tumipay.co).

## Basic Authentication

Every API call uses **HTTP Basic Auth**. Combine your username and password and encode them in Base64:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # Method 1: Using curl built-in basic auth
    curl -u "username:password" \
      -H "Token-Top: your_access_token" \
      -H "Content-Type: application/json" \
      https://api-empresas.staging.topup.com.co/production/api/v1/merchant/me

    # Method 2: Manual base64 encoding
    curl -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
      -H "Token-Top: your_access_token" \
      -H "Content-Type: application/json" \
      https://api-empresas.staging.topup.com.co/production/api/v1/merchant/me
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const username = 'your_username';
    const password = 'your_password';
    const token = 'your_access_token';

    // Method 1: Using btoa()
    const basicAuth = 'Basic ' + btoa(username + ':' + password);

    const response = await fetch('https://api-empresas.staging.topup.com.co/production/api/v1/merchant/me', {
      method: 'GET',
      headers: {
        'Authorization': basicAuth,
        'Token-Top': token,
        'Content-Type': 'application/json'
      }
    });

    const data = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    import base64

    username = 'your_username'
    password = 'your_password'
    token = 'your_access_token'

    # Method 1: Using requests built-in basic auth
    response = requests.get(
        'https://api-empresas.staging.topup.com.co/production/api/v1/merchant/me',
        auth=(username, password),
        headers={
            'Token-Top': token,
            'Content-Type': 'application/json'
        }
    )

    # Method 2: Manual base64 encoding
    credentials = base64.b64encode(f"{username}:{password}".encode()).decode()
    headers = {
        'Authorization': f'Basic {credentials}',
        'Token-Top': token,
        'Content-Type': 'application/json'
    }

    response = requests.get(
        'https://api-empresas.staging.topup.com.co/production/api/v1/merchant/me',
        headers=headers
    )
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    $username = 'your_username';
    $password = 'your_password';
    $token = 'your_access_token';

    // Method 1: Using cURL with CURLOPT_USERPWD
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://api-empresas.staging.topup.com.co/production/api/v1/merchant/me');
    curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $password);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Token-Top: ' . $token,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

    // Method 2: Manual base64 encoding
    $credentials = base64_encode($username . ':' . $password);
    $headers = [
        'Authorization: Basic ' . $credentials,
        'Token-Top: ' . $token,
        'Content-Type: application/json'
    ];

    $context = stream_context_create([
        'http' => [
            'header' => implode("\r\n", $headers),
            'method' => 'GET'
        ]
    ]);

    $response = file_get_contents(
        'https://api-empresas.staging.topup.com.co/production/api/v1/merchant/me',
        false,
        $context
    );
    ?>
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use reqwest;
    use base64::{Engine as _, engine::general_purpose};

    #[tokio::main]
    async fn main() -> Result<(), reqwest::Error> {
        let username = "your_username";
        let password = "your_password";
        let token = "your_access_token";

        // Method 1: Using reqwest's built-in basic auth
        let client = reqwest::Client::new();
        let response = client.get("https://api-empresas.staging.topup.com.co/production/api/v1/merchant/me")
            .basic_auth(username, Some(password))
            .header("Token-Top", token)
            .header("Content-Type", "application/json")
            .send()
            .await?;

        let body = response.text().await?;
        println!("{}", body);

        // Method 2: Manual base64 encoding
        let credentials = format!("{}:{}", username, password);
        let encoded = general_purpose::STANDARD.encode(credentials.as_bytes());
        let auth_header = format!("Basic {}", encoded);

        let response2 = client.get("https://api-empresas.staging.topup.com.co/production/api/v1/merchant/me")
            .header("Authorization", auth_header)
            .header("Token-Top", token)
            .header("Content-Type", "application/json")
            .send()
            .await?;

        let body2 = response2.text().await?;
        println!("{}", body2);

        Ok(())
    }
    ```
  </Tab>
</Tabs>

The `Authorization` header must accompany all requests.

## Token Authentication

Most endpoints also require the merchant's token in the `Token-Top` header:

```bash theme={null}
Token-Top: your_access_token
```

Treat this token as a secret. Store it securely and rotate it regularly.

### Token Renewal

Tokens do not expire automatically. If you suspect compromise, or as part of routine security maintenance, contact [Tumipay support](mailto:it@tumipay.co) to issue a new token. Update your systems to use the new value immediately.

## Required Headers

Include the following headers in requests:

<ParamField header="Authorization" type="string" required>
  Basic credentials in the format `Basic base64(username:password)`
</ParamField>

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

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Security Best Practices

* Use HTTPS for every request.
* Keep your username, password and token in a secure environment variable or secret manager.
* Rotate credentials periodically and revoke them immediately if exposed.
* Never commit credentials or tokens to public repositories or client-side code.