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

# Authentication

> Learn how to authenticate Payin API requests

## Overview

The CashQ Payin API uses **Basic Authentication** with your API Key and PIN from Approvely Gateway.

## Getting Your Credentials

<Steps>
  <Step title="Access Control Panel">
    Log in to the Approvely Gateway Control Panel:

    **Sandbox:** [https://sandbox.approvelygateway.com/](https://sandbox.approvelygateway.com/)

    **Production:** Contact support for production access
  </Step>

  <Step title="Navigate to Sources">
    Go to [Control Panel → Sources](https://sandbox.approvelygateway.com/control-panel/sources)
  </Step>

  <Step title="Get API Credentials">
    You'll find three important credentials:

    * **API Key** - Used for API authentication
    * **Tokenization Token** - Used for frontend card tokenization
    * **PIN** - Used with API Key for authentication

    <Info>
      Keep these credentials secure. You'll need the API Key and PIN to authenticate API requests.
    </Info>
  </Step>
</Steps>

## Authentication Method

The Payin API uses **HTTP Basic Authentication**. You need to:

1. Concatenate your API Key and PIN with a colon: `[API_KEY]:[PIN]`
2. Encode the string to Base64
3. Add it to the `Authorization` header as `Basic [base64_string]`

### Example

```
API Key: iebfzJJUCN6HMmLVhXbMo6faby9HITH2
PIN: 552dd6e5a202469a7f535d3a1e09a

Concatenated: iebfzJJUCN6HMmLVhXbMo6faby9HITH2:552dd6e5a202469a7f535d3a1e09a

Base64 Encoded: aWViZnpKSlVDTjZITW1MVmhYYk1vNmZhYnk5SElUSDI6NTUyZGQ2ZTVhMjAyNDY5M2E3ZjUzNWQzYTFlzOWE=

Authorization Header: Basic aWViZnpKSlVDTjZITW1MVmhYYk1vNmZhYnk5SElUSDI6NTUyZGQ2ZTVhMjAyNDY5M2E3ZjUzNWQzYTFlzOWE=
```

## Implementation Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.sandbox.approvelygateway.com/api/v2/transactions/charge' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Basic aWViZnpKSlVDTjZITW1MVmhYYk1vNmZhYnk5SElUSDI6NTUyZGQ2ZTVhMjAyNDY5M2E3ZjUzNWQzYTFlzOWE=' \
    -d '{
      "amount": 5,
      "source": "nonce-token-here"
    }'
  ```

  ```javascript Node.js theme={null}
  // Encode credentials
  const apiKey = 'your_api_key';
  const pin = 'your_pin';
  const credentials = Buffer.from(`${apiKey}:${pin}`).toString('base64');

  // Make request
  const response = await fetch(
    'https://api.sandbox.approvelygateway.com/api/v2/transactions/charge',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${credentials}`
      },
      body: JSON.stringify({
        amount: 5,
        source: 'nonce-token-here'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests
  import base64

  # Encode credentials
  api_key = 'your_api_key'
  pin = 'your_pin'
  credentials = base64.b64encode(f'{api_key}:{pin}'.encode()).decode()

  # Make request
  response = requests.post(
      'https://api.sandbox.approvelygateway.com/api/v2/transactions/charge',
      headers={
          'Content-Type': 'application/json',
          'Authorization': f'Basic {credentials}'
      },
      json={
          'amount': 5,
          'source': 'nonce-token-here'
      }
  )

  data = response.json()
  print(data)
  ```

  ```php PHP theme={null}
  <?php
  $apiKey = 'your_api_key';
  $pin = 'your_pin';
  $credentials = base64_encode($apiKey . ':' . $pin);

  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, 'https://api.sandbox.approvelygateway.com/api/v2/transactions/charge');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Content-Type: application/json',
      'Authorization: Basic ' . $credentials
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'amount' => 5,
      'source' => 'nonce-token-here'
  ]));

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

  $data = json_decode($response, true);
  print_r($data);
  ?>
  ```
</CodeGroup>

## Environment URLs

Use the appropriate base URL for your environment:

| Environment | Base URL                                   |
| ----------- | ------------------------------------------ |
| Sandbox     | `https://api.sandbox.approvelygateway.com` |
| Production  | `https://banking.cashqbot.com`             |

<Warning>
  **Production Credentials**

  For production access, contact [support@mycashq.com](mailto:support@mycashq.com). Production credentials are separate from sandbox credentials.
</Warning>

## Sandbox Login

For testing in the sandbox environment:

* **URL:** [https://sandbox.approvelygateway.com/](https://sandbox.approvelygateway.com/)
* **Login:** Contact support for credentials
* **Password:** Contact support for credentials

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Store Securely" icon="lock">
    Never hardcode credentials in your source code. Use environment variables or secure vaults.
  </Card>

  <Card title="Use HTTPS Only" icon="shield">
    All API requests must use HTTPS. Never send credentials over HTTP.
  </Card>

  <Card title="Separate Environments" icon="split">
    Use different credentials for sandbox and production. Never use production credentials in testing.
  </Card>

  <Card title="Rotate Regularly" icon="rotate">
    Periodically rotate your API credentials for enhanced security.
  </Card>
</CardGroup>

## Testing Authentication

Test your authentication setup with a simple request:

```bash theme={null}
curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -d '{"amount": 1, "source": "test-nonce"}' \
  'https://api.sandbox.approvelygateway.com/api/v2/transactions/charge'
```

If authentication fails, you'll receive a `401 Unauthorized` response.

## Common Authentication Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    **Cause:** Invalid or missing credentials

    **Solution:**

    * Verify your API Key and PIN are correct
    * Ensure credentials are properly Base64 encoded
    * Check that you're using the correct environment credentials
  </Accordion>

  <Accordion title="403 Forbidden">
    **Cause:** Valid credentials but insufficient permissions

    **Solution:**

    * Contact support to verify your account permissions
    * Ensure your account is active and in good standing
  </Accordion>

  <Accordion title="Invalid Base64 Encoding">
    **Cause:** Credentials not properly encoded

    **Solution:**

    * Verify the format: `[API_KEY]:[PIN]`
    * Use a proper Base64 encoding function
    * Don't include extra spaces or line breaks
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tokenization" icon="shield" href="/payin/tokenization">
    Learn how to tokenize card data securely
  </Card>

  <Card title="Charge Endpoint" icon="bolt" href="/payin/charge">
    Process payments using the charge API
  </Card>
</CardGroup>