# T-Lync Service

#### Pay

Pay the transaction.

## Confirm (Pay)

<mark style="color:green;">`POST`</mark> `https://api.plutus.ly/api/v1/transaction/tlync/confirm`

Pay the transaction

#### Headers

| Name                                            | Type   | Description             |
| ----------------------------------------------- | ------ | ----------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer: \[Access token] |
| X-API-KEY<mark style="color:red;">\*</mark>     | String | API Key                 |

#### Request Body

| Name                                             | Type   | Description                                                                                                                                                                                                                                     |
| ------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount<mark style="color:red;">\*</mark>         | String | <p>Transaction amount in Libyan dinars.</p><p>Formatting is allowed with a maximum of two decimal places: <strong>XXX</strong>, <strong>XX.X</strong>, <strong>XX.XX</strong></p>                                                               |
| invoice\_no<mark style="color:red;">\*</mark>    | String | Invoice number associated with transaction, **must be unique and not previously used.**                                                                                                                                                         |
| mobile\_number<mark style="color:red;">\*</mark> | String | Valid mobile number format start with 9x or 09                                                                                                                                                                                                  |
| email                                            | String | \[Optional] Email address                                                                                                                                                                                                                       |
| return\_url<mark style="color:red;">\*</mark>    | String | URL after payment is completed to allow the customer to return to the order/invoice                                                                                                                                                             |
| callback\_url<mark style="color:red;">\*</mark>  | String | <p>The URL of your Instant update Server URL to track your order/invoice, instantly sent by Plutu when the transaction is complete.<br><strong>This URL must be publicly accessible; private and localhost URLs are not supported.</strong></p> |
| customer\_ip                                     | String | \[Optional] Customer IP address                                                                                                                                                                                                                 |
| lang                                             | String | \[Optional]  **ar** or **en**, by default **ar**                                                                                                                                                                                                |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "status": 200,
    "result": {
        "code": "CHECKOUT_REDIRECT",
        "redirect_url": "https://xxxxxxxxxxxxxxx"
    }
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "error": {
        "status": 4xx,
        "code": "ERROR_CODE_PLACEHOLDER",
        "message": "ERROR_MESSAGE_PLACEHOLDER"
    }
}
```

You can review the [Errors](/api-documentation/errors.md) section for all possible errors
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="CURL" %}
{% code overflow="wrap" %}

```php
curl --location --request POST 'https://api.plutus.ly/api/v1/transaction/tlync/confirm' \
--header 'X-API-KEY: [API_KEY]' \
--header 'Authorization: Bearer [ACCESS_TOKEN]' \
--form 'amount="[AMONUT]"' \
--form 'invoice_no="[INVOICE_NO]"' \
--form 'return_url="[RETURN_URL]"' \
--form 'callback_url="[CALLBACK_URL]"' \
--form 'mobile_number="[MOBILE_NUMBER]"' \
--form 'customer_ip="[CUSTOMER_IP]"'
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code overflow="wrap" lineNumbers="true" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.plutus.ly/api/v1/transaction/tlync/confirm',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array(
    'amount' => '[AMONUT]', 
    'invoice_no' => '[INVOICE_NO]', 
    'return_url' => '[RETURN_URL]', 
    'callback_url' => '[CALLBACK_URL]', 
    'mobile_number' => '[MOBILE_NUMBER]', 
    'customer_ip' => '[CUSTOMER_IP]'
  ),
  CURLOPT_HTTPHEADER => array(
    'X-API-KEY: [API_KEY]',
    'Authorization: Bearer [ACCESS_TOKEN]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endcode %}
{% endtab %}

{% tab title="Plutu PHP Package" %}
{% code lineNumbers="true" %}

```php
<?php

use Plutu\Services\PlutuTlync;

$amount = 5.0; // amount in float format
$invoiceNo = 'inv-12345'; // invoice number
$returnUrl = 'https://example.com/return/handler'; // the url to handle the return from plutu after payment completed from T-Lync
$callbackUrl = 'https://example.com/callback/handler'; // the url to handle the callback trgigger from plutu after payment completed from T-Lync

try {

    $api = new PlutuTlync;
    $api->setCredentials('api_key', 'access_token', 'secret_key');
    $apiResponse = $api->confirm($amount, $invoiceNo, $returnUrl, $callbackUrl);

    if ($apiResponse->getOriginalResponse()->isSuccessful()) {

        // Redirect URL for Plutu and T-Lync checkout page
        $redirectUrl = $apiResponse->getRedirectUrl();

        // You should rediect the customer to payment checkout page
        // header("location: " . $redirectUrl);

    } elseif ($apiResponse->getOriginalResponse()->hasError()) {

        // Possible errors from Plutu API
        // @see https://docs.plutu.ly/api-documentation/errors Plutu API Error Documentation
        $errorCode = $apiResponse->getOriginalResponse()->getErrorCode();
        $errorMessage = $apiResponse->getOriginalResponse()->getErrorMessage();
        $statusCode = $apiResponse->getOriginalResponse()->getStatusCode();
        $responseData = $apiResponse->getOriginalResponse()->getBody();

    }

// Handle exceptions that may be thrown during the execution of the code
// The following are the expected exceptions that may be thrown:
// Check the "Handle Exceptions and Errors" section for more details
// 
// InvalidAccessTokenException, InvalidApiKeyException, InvalidSecretKeyException,
// InvalidAmountException, InvalidInvoiceNoException, InvalidReturnUrlException, InvalidCallbackUrlException
} catch (\Exception $e) {
    $exception = $e->getMessage();
}
```

{% endcode %}

Check out the example [Confirm (Pay)](https://github.com/getplutu/plutu-php/blob/main/examples.md#confirm-pay-1) in the Plutu PHP Examples document on GitHub.
{% endtab %}
{% endtabs %}

### Callback handler

The callback will be received from Plutu when the transaction is completed. This gives a Merchant better control of how the transaction is processed on the Merchant's side. This is useful e.g. when you want to mark an order as paid, update your shop's inventory, or add appropriate records to Merchant’s internal accounting system.

**Callback parameters:**

The callback is called with HTTP **POST** as JSON

<table><thead><tr><th width="150">Parameter</th><th>Description</th><th data-hidden>Value</th></tr></thead><tbody><tr><td>gateway</td><td>Gateway name: <strong>tlync</strong></td><td></td></tr><tr><td>approved</td><td>1 or 0 (true, false), the transaction is completed <strong>and</strong> <strong>must be checked</strong> <strong>to be 1 (true)</strong></td><td>1</td></tr><tr><td>invoice_no</td><td>Invoice number sent in the pay request</td><td></td></tr><tr><td>amount</td><td>The amount sent in the request</td><td></td></tr><tr><td>paymet_method</td><td>The payment method in which the transaction was completed on T-Lync.<br>Supported payment methods: tadawul, edfaly, sadad, mobicash, and moamalat</td><td></td></tr><tr><td>transaction_id</td><td>Plutu transaction id</td><td></td></tr><tr><td>hashed</td><td>Hash message authorization code (HMAC) is used to verify both the data integrity and the authorization of a message.</td><td></td></tr></tbody></table>

### Return handler

Once the payment has been completed client can be redirected to the merchant-provided return URL.

**Return parameters:**

The callback is called with HTTP **GET** and with the same query string parameters as in the redirect

<table><thead><tr><th width="150">Parameter</th><th>Description</th><th data-hidden>Value</th></tr></thead><tbody><tr><td>approved</td><td>Transaction completed</td><td>1</td></tr><tr><td>invoice_no</td><td>Invoice number sent in the pay request</td><td></td></tr><tr><td>hashed</td><td>Hash message authorization code (HMAC) is used to verify both the data integrity and the authorization of a message.</td><td></td></tr></tbody></table>

{% hint style="info" %}
SHA-256 HMAC is calculated as follows:

* The SHA-256 HMAC calculation includes all response parameters and key-value pairs except the “**hashed**” parameter.&#x20;
* Create an SHA-256 HMAC of the resultant string using the secret key created in the Plutu account, convert it to uppercase, and compare it with the “**hashed**” parameter received in the callback or return handler.
  {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.plutu.ly/api-documentation/payments/t-lync.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.