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

# Check Transfer

> Validate transfer details before sending money

## Overview

Validate transfer details before executing a money transfer. This endpoint validates all transfer parameters and returns the foreign exchange (FX) rate for the corridor without actually sending money.

<Info>
  **Best Practice:** Always call this endpoint before executing a transfer to validate the transaction and get the current FX rate for the transfer.
</Info>

## Endpoint

```http theme={null}
POST /api/checkTransfer
```

## Authentication

<ParamField header="API-KEY" type="string" required>
  Your CashQ API Key for authentication
</ParamField>

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

## Request Body

<ParamField body="id" type="string" required>
  Unique numeric identifier for this transfer. Use this same ID when executing the transfer. Must be numeric only.
</ParamField>

<ParamField body="sender_phone" type="string" required>
  Sender's phone number in E.164 format (e.g., `"+15615019469"`)
</ParamField>

<ParamField body="receiver_phone" type="string" required>
  Receiver's phone number in E.164 format (e.g., `"+201234567890"`)
</ParamField>

<ParamField body="amount" type="string" required>
  Transfer amount in dollars (e.g., `"5.0"` for \$5.00)
</ParamField>

<ParamField body="service" type="string" required>
  ID of corridor (e.g., `"1271"` for EGP). Payment attributes depend on the corridor and will be provided for the requested corridor upon request.
</ParamField>

<ParamField body="receiver_country" type="string" required>
  Country code of receiver (e.g., `"MX"` for Mexico, `"EG"` for Egypt).
</ParamField>

<ParamField body="receiver_currency" type="string" required>
  Currency code for the receiver (e.g., `"MXN"` for Mexican Peso, `"EGP"` for Egyptian Pound)
</ParamField>

<ParamField body="attribute" type="array" required>
  Array of corridor-specific payment attributes. Required attributes vary by corridor and include receiver details, bank information, address, and identification. Contact support for specific corridor requirements.

  <Expandable title="Attribute structure">
    Each attribute object contains:

    * `name` (string): Attribute name
    * `value` (string): Attribute value

    **Common attributes:**

    * **`receivedAmount`** - Amount in receiver's currency (e.g., amount in EGP)
    * **`receiverName`** - Full name of receiver
    * **`receiverFirstName`** - Receiver's first name
    * **`receiverLastName`** - Receiver's last name
    * **`receiverAddressStreet`** - Street address
    * **`receiverAddressCity`** - City
    * **`receiverAddressState`** - State/Region
    * **`receiverAddressCountry`** - Country code (e.g., "EG")
    * **`receiverAccType`** - Account type (e.g., "1" for bank account)
    * **`receiverIssuerCode`** - Bank issuer code
    * **`receiverAccountNumber`** - Bank account number
    * **`receiverBankBranchCode`** - Bank branch code (optional, if applicable)
    * **`receiverBankName`** - Bank name
    * **`receiverIdType`** - ID type ("2" for International Passport, "3" for Identification ID)
    * **`receiverIdNumber`** - Identification number
  </Expandable>

  <Warning>
    **Important: `approvelyId` Attribute**

    If you're using the Payout API with our Payin API, you must include the `approvelyId` attribute to link the payout with the payin transaction:

    ```json theme={null}
    {
      "name": "approvelyId",
      "value": "46364493"
    }
    ```

    Without this attribute, the transaction will be created but will wait for automated/manual reconciliation checking, which may cause delays.
  </Warning>
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.cashqbot.com/api/checkTransfer' \
    -H 'API-KEY: your_api_key_here' \
    -H 'Content-Type: application/json' \
    -d '{
      "id": "123456789",
      "sender_phone": "+15551234567",
      "receiver_phone": "+525551234568",
      "amount": "5.0",
      "service": "1234",
      "receiver_country": "MX",
      "receiver_currency": "MXN",
      "attribute": []
    }'
  ```

  ```javascript Node.js theme={null}
  const transferData = {
    id: '123456789',
    sender_phone: '+15551234567',
    receiver_phone: '+525551234568',
    amount: '5.0',
    service: '1234',
    receiver_country: 'MX',
    receiver_currency: 'MXN',
    attribute: []
  };

  const response = await fetch('https://api.cashqbot.com/api/checkTransfer', {
    method: 'POST',
    headers: {
      'API-KEY': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(transferData)
  });

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

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

  transfer_data = {
      'id': '123456789',
      'sender_phone': '+15551234567',
      'receiver_phone': '+525551234568',
      'amount': '5.0',
      'service': '1234',
      'receiver_country': 'MX',
      'receiver_currency': 'MXN',
      'attribute': []
  }

  response = requests.post(
      'https://api.cashqbot.com/api/checkTransfer',
      headers={
          'API-KEY': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json=transfer_data
  )

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

  ```php PHP theme={null}
  <?php
  $transferData = [
      'id' => '123456789',
      'sender_phone' => '+15551234567',
      'receiver_phone' => '+525551234568',
      'amount' => '5.0',
      'service' => '1234',
      'receiver_country' => 'MX',
      'receiver_currency' => 'MXN',
      'attribute' => []
  ];

  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, 'https://api.cashqbot.com/api/checkTransfer');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'API-KEY: your_api_key_here',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($transferData));

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

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

## Response

<ResponseField name="success" type="boolean" required>
  Indicates if the validation was successful
</ResponseField>

<ResponseField name="error" type="string">
  Error message if validation failed, empty string if successful
</ResponseField>

<ResponseField name="attribute" type="array">
  Array of response attributes containing additional information

  <Expandable title="Response attributes">
    <ResponseField name="fx_rate" type="string">
      Foreign exchange rate for the corridor. Shows the conversion rate from the sender's currency to the receiver's currency.

      **Example:** `"47.2945"` means 1 USD = 47.2945 EGP
    </ResponseField>
  </Expandable>
</ResponseField>

## Response Examples

<ResponseExample>
  ```json Success theme={null}
  {
    "error": "",
    "success": true,
    "attribute": [
      {
        "name": "fx_rate",
        "value": "47.2945"
      }
    ]
  }
  ```

  ```json Validation Error theme={null}
  {
    "error": {
      "message": "Invalid phone number format",
      "code": "invalid_phone_number"
    },
    "success": "false"
  }
  ```
</ResponseExample>

## Validation Checks

The endpoint validates:

<CardGroup cols={2}>
  <Card title="Phone Numbers" icon="phone">
    Validates sender and receiver phone number formats
  </Card>

  <Card title="Amount" icon="dollar-sign">
    Checks if amount is valid and within limits
  </Card>

  <Card title="Receiver Status" icon="user">
    Checks if receiver exists on CashQ network
  </Card>

  <Card title="KYC Limits" icon="shield">
    Validates against receiver's KYC limits
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Always check before transfer">
    Call this endpoint before every transfer to validate parameters and check receiver status.
  </Accordion>

  <Accordion title="Use unique transfer IDs">
    Generate unique numeric IDs for each transfer. Use the same ID for check and actual transfer. IDs must be numeric only.
  </Accordion>

  <Accordion title="Handle validation errors">
    Don't proceed with transfer if validation fails. Show clear error messages to users.
  </Accordion>
</AccordionGroup>

## Error Responses

| Error Code              | Description                   | Solution                                        |
| ----------------------- | ----------------------------- | ----------------------------------------------- |
| `authentication_error`  | Invalid or missing API key    | Verify your API key                             |
| `invalid_phone_number`  | Phone number format incorrect | Use E.164 format without `+`                    |
| `invalid_amount`        | Amount is invalid             | Check amount is positive and properly formatted |
| `invalid_request`       | Missing or invalid parameters | Verify all required fields are included         |
| `kyc_not_verified`      | Receiver KYC limits exceeded  | Reduce amount or ask receiver to verify         |
| `internal_server_error` | Server error occurred         | Retry the request                               |

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Money Transfer" icon="money-bill-transfer" href="/api-reference/transfer">
    Execute the transfer after validation
  </Card>

  <Card title="Check KYC" icon="shield" href="/api-reference/kyc">
    Check receiver's KYC status and limits
  </Card>

  <Card title="Check Status" icon="clock" href="/api-reference/status">
    Monitor transfer status after execution
  </Card>
</CardGroup>