Authentication

Obtaining Credentials

To access Tumipay’s APIs you must request credentials from our support team. Send an email to 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.

Basic Authentication

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

cURL
JavaScript
Python
PHP
Rust

# 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

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();

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
)

<?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
);
?>

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(())
}

The Authorization header must accompany all requests.

Token Authentication

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

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 to issue a new token. Update your systems to use the new value immediately.

Required Headers

Include the following headers in requests:

string

required

Basic credentials in the format Basic base64(username:password)

string

required

Your merchant authentication token

string

required

application/json

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.

Getting Started

Merchant API

PayIn API

PayOut API

Card Payment API

Integration

Obtaining Credentials

Basic Authentication

Token Authentication

Token Renewal

Required Headers

Security Best Practices

​Obtaining Credentials

​Basic Authentication

​Token Authentication

​Token Renewal

​Required Headers

​Security Best Practices

Obtaining Credentials

Basic Authentication

Token Authentication

Token Renewal

Required Headers

Security Best Practices