# Integrating with Enkash’s Payout API

Set up API endpoints, obtain credentials, and configure your environment for seamless transfers. Follow the steps below to get started.

## <span style="color:#7b2cbf">API Endpoints</span>

| Environment | Base URL                         |
| ----------- | -------------------------------- |
| **Test**    | `https://ekpayout-uat.enkash.in` |
| **Live**    | `https://api.enkash.in`          |

## <span style="color:#7b2cbf">Setup Guide</span>

<Steps>
  <Step title="Download Postman Collection">
    Click below to access the pre-configured Postman collection for testing API requests:

[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/19089-b05811fc-982e-4060-8acc-1c201a4c3f63?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D19089-b05811fc-982e-4060-8acc-1c201a4c3f63%26entityType%3Dcollection%26workspaceId%3Defb2e830-a170-4108-98d6-c6e5c2243a1c#?env%5BProduction%5D=W3sia2V5IjoidG9rZW4iLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiIiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6ImNvbGxlY3Rpb25OYW1lIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6MX0seyJrZXkiOiJjb2xsZWN0aW9uU2NoZW1hVXJsIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6Mn0seyJrZXkiOiJhY2Nlc3NLZXkiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiIiwic2Vzc2lvbkluZGV4IjozfSx7ImtleSI6IndvcmtzcGFjZUlkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IiIsInNlc3Npb25JbmRleCI6NH0seyJrZXkiOiJjb2xsZWN0aW9uSWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiIiwic2Vzc2lvbkluZGV4Ijo1fV0=)
  </Step>
  <Step title="Configure API Endpoints">
    Set the appropriate **base URL** (`Test` or `Live`) in your API client or environment file.
  </Step>
  <Step title="Obtain API Keys, Client ID & Secret
">
    Sandbox (test) API keys will be emailed to you upon onboarding.
  </Step>
    <Step title="Whitelist Your IP">
    Ensure your system’s IP addresses are whitelisted for both **sandbox** and **production** environments.
  </Step>
</Steps>


<TipInfo> **Production keys**
Will be provided after successfully completing your sandbox test cases</TipInfo>


## <span style="color:#7b2cbf">APIs Available</span>

<Container>
  <span style="color:#7b2cbf">Authentication API</span> 
    | API Name                                | Function                                               |
| --------------------------------------- | ------------------------------------------------------ |
| Get Authentication Token | Retrieve an authentication token for secure API access |
</Container>


<Container>
  <span style="color:#7b2cbf">Beneficiary APIs</span> 
    | API Name                          | Function                           |
| --------------------------------- | ---------------------------------- |
| Create Beneficiary | Add a new beneficiary              |
| Search Beneficiary| Search for an existing beneficiary |
| Delete Beneficiary | Delete a beneficiary               |
</Container>


<Container>
  <span style="color:#7b2cbf">Transfer APIs</span> 
    | API Name                                                         | Function                             |
| ---------------------------------------------------------------- | ------------------------------------ |
| Create Payout                                     | Initiate a single payout transaction |
| Create Batch Payout                              | Create a batch for multiple payouts  |
| Search Payouts | Search for payout transactions       |
</Container>


<Container>
  <span style="color:#7b2cbf">Account APIs</span> 
    | API Name                                                                   | Function                               |
| -------------------------------------------------------------------------- | -------------------------------------- |
| Get Account Balance | Check available payout account balance |
| Add Source Bank Account                                     | Add a source bank account for payouts  |
| Get Source Bank Account Details                            | Fetch details of linked bank accounts  |

</Container>

## <span style="color:#7b2cbf">Payout API Response Codes</span>

Enkash’s Payout API provides response codes to indicate the outcome of API requests, ensuring clear communication and efficient error handling. Properly handling these codes is essential for seamless integration.

**Response Codes**

| Code    | Description                                                                  |
| ------- | ---------------------------------------------------------------------------- |
| **0**   | Success.                                                                     |
| **1**   | Failure.                                                                     |
| **403** | APIs not enabled.                                                            |
| **403** | Encryption failed for response.                                              |
| **409** | Beneficiary ID already exists.                                               |
| **409** | Transaction ID already exists.                                               |
| **409** | Batch Transaction ID already exists.                                         |
| **412** | Bank account and IFSC both are required.                                     |
| **412** | Invalid nodal bank in request.                                               |
| **412** | Invalid checksum in the request.                                             |
| **412** | Invalid Company ID.                                                          |
| **412** | Bank account and VPA both provided. Provide only one to add the beneficiary. |
| **422** | Invalid encrypted request.                                                   |
| **422** | Invalid request format.                                                      |
| **422** | Invalid Client ID.                                                           |
| **422** | Please provide a valid Beneficiary ID.                                       |
| **422** | Please provide a valid name.                                                 |
| **422** | Please provide a valid Virtual Payee Address (VPA).                          |
| **422** | Invalid or missing parameter in the request.                                 |
| **422** | No beneficiary details present.                                              |
| **422** | Please provide a valid email.                                                |
| **422** | Please provide a valid phone number.                                         |


:::tip[]
**Integration Note:**
Ensure your application handles all these response codes effectively
:::

## <span style="color:#7b2cbf">Common Scenarios</span>

1. **Duplicate Entries**

   * `409`: If a Beneficiary ID, Transaction ID, or Batch Transaction ID already exists, avoid duplicates by checking beforehand.

2. **Validation Errors**

   * `422`: Ensure all required fields (Beneficiary ID, name, email, phone number, VPA) are validated before sending the request.

3. **Missing or Incorrect Parameters**

   * `412` / `422`: Verify that the request has all mandatory parameters and follows the correct format.


**Example Error Handling**

```json
{
  "code": 412,
  "message": "Bank account and IFSC both are required."
}
```

:::check[]
**Action:** Ensure both bank account details and the IFSC code are present in your request to proceed
:::

## <span style="color:#7b2cbf">Best Practices</span> 

* **Encrypt API Request Payloads:** Always encrypt sensitive data before sending requests.
* **Decrypt API Responses:** Decrypt responses immediately upon receipt to ensure data integrity.