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

# Merchant API

> The Merchant API lets you access your merchant profile and query transactions by various filters or identifiers.

# Merchant API

This API provides information about the merchant and allows for transaction searches. With these endpoints, you can retrieve merchant profile data and search for specific transactions using their unique identifiers.

## Endpoints

### Retrieve Merchant Information

<Card title="/api/v1/merchant/me" icon="circle-info" iconType="solid">
  Provides a concise summary of the registered merchant's corporate and financial profile.
  The response includes key data such as tax ID, electronic contact information, operating currency, and current e-wallet balance.
</Card>

#### Request Headers

<ParamField header="Token-Top" type="string" required>
  Token for authentication
</ParamField>

#### Response

<ResponseField name="code" type="string" required>
  Response code (e.g., "01")
</ResponseField>

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

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

<ResponseField name="data" type="object" required>
  <Expandable title="Merchant data object">
    <ResponseField name="name" type="string">
      Merchant's registered name (e.g., "Acme Corporation")
    </ResponseField>

    <ResponseField name="nit" type="string">
      Merchant's tax ID (e.g., "2523423")
    </ResponseField>

    <ResponseField name="email" type="string">
      Merchant's registered email (e.g., "[example@tumipay.co](mailto:example@tumipay.co)")
    </ResponseField>

    <ResponseField name="currency" type="string">
      Operating currency (e.g., "COP")
    </ResponseField>

    <ResponseField name="wallet" type="integer">
      Current e-wallet balance (e.g., 954943500)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl --request GET 'https://api-empresas.staging.topup.com.co/production/api/v1/merchant/me' \
  --header 'Token-Top: your_auth_token'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "code": "01",
    "status": "SUCCESS",
    "message": "",
    "data": {
      "name": "Acme Corporation",
      "nit": "2523423",
      "email": "example@tumipay.co",
      "currency": "COP",
      "wallet": 954943500
    }
  }
  ```
</ResponseExample>

### Search Transactions

<Card title="/api/v1/transaction/{ticket}" icon="magnifying-glass" iconType="solid">
  Search for transaction details using either the ticket provided by TumiPay or the reference supplied by the merchant.
  The "ticket" parameter accepts both the TumiPay ticket and the merchant's reference for payin or payout transactions.
</Card>

#### Request Headers

<ParamField header="Token-Top" type="string" required>
  Token for authentication
</ParamField>

#### Request Body

<ParamField body="ticket" type="string" required>
  Ticket or reference of the transaction (e.g., "1740ed7e-bbab-11ee-8335-02530a7dec0f")
</ParamField>

#### Response

<ResponseField name="code" type="string" required>
  Response code (e.g., "01")
</ResponseField>

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

<ResponseField name="data" type="object" required>
  <Expandable title="Transaction data object">
    <ResponseField name="ticket" type="string">
      TumiPay ticket for the transaction (e.g., "41ac80c3-2f50-11ef-a534-02530a7dec0f")
    </ResponseField>

    <ResponseField name="reference" type="string">
      Reference provided by the merchant (e.g., "uel7aWiavpwR8uXBkqMH3AiC165855")
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Transaction amount (e.g., 5000000)
    </ResponseField>

    <ResponseField name="currency" type="string">
      Transaction currency (e.g., "COP", "PEN")
    </ResponseField>

    <ResponseField name="type_transaction" type="string">
      Type of transaction (e.g., "Deposit")
    </ResponseField>

    <ResponseField name="customer" type="object">
      <Expandable title="Customer details object">
        <ResponseField name="legal_doc_type" type="string">
          Type of customer's legal document (e.g., "CC")
        </ResponseField>

        <ResponseField name="legal_doc" type="string">
          Customer's legal document number (e.g., "9012286480")
        </ResponseField>

        <ResponseField name="phone_code" type="string">
          Country code for the customer's phone number (e.g., "57")
        </ResponseField>

        <ResponseField name="phone_number" type="string">
          Customer's phone number (e.g., "3216132616")
        </ResponseField>

        <ResponseField name="email" type="string">
          Customer's email address (e.g., "[approved@tumipay.co](mailto:approved@tumipay.co)")
        </ResponseField>

        <ResponseField name="full_name" type="string">
          Full name of the customer (e.g., "3013540830")
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the transaction (e.g., "APPROVED")
    </ResponseField>

    <ResponseField name="response_message" type="string">
      Message associated with the transaction's status (e.g., "Transaction approved")
    </ResponseField>

    <ResponseField name="date" type="string" format="date-time">
      Timestamp of the transaction (e.g., "2024-06-20 16:58:55")
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v1/transaction/{ticket}' \
  --header 'Token-Top: your_auth_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "ticket": "1740ed7e-bbab-11ee-8335-02530a7dec0f"
  }'
  ```

  ```javascript theme={null}
  // Using fetch API
  const response = await fetch('https://api-empresas.staging.topup.com.co/production/api/v1/transaction/{ticket}', {
    method: 'POST',
    headers: {
      'Token-Top': 'your_auth_token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ticket: '1740ed7e-bbab-11ee-8335-02530a7dec0f'
    })
  });
  const data = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "code": "01",
    "status": "SUCCESS",
    "data": {
      "ticket": "41ac80c3-2f50-11ef-a534-02530a7dec0f",
      "reference": "uel7aWiavpwR8uXBkqMH3AiC165855",
      "amount": 5000000,
      "currency": "COP",
      "type_transaction": "Deposit",
      "customer": {
        "legal_doc_type": "CC",
        "legal_doc": "9012286480",
        "phone_code": "57",
        "phone_number": "3216132616",
        "email": "approved@tumipay.co",
        "full_name": "3013540830"
      },
      "status": "APPROVED",
      "response_message": "Transaction approved",
      "date": "2024-06-20 16:58:55"
    }
  }
  ```
</ResponseExample>