# Authentication and Signature Calculation

### <mark style="color:blue;">Authentication</mark>

To authenticate you, our withdrawal API uses API Keys in all requests. API Keys can be obtained from Settings -> API -> Withdrawals.

{% hint style="info" %}
The API keys between Staging and Production are different.
{% endhint %}

There are 3 credentials you will need:

* Your user: [<mark style="color:blue;">**API**</mark> ](#user-content-fn-1)[^1]<mark style="color:blue;">**Key**</mark>
* Your password: <mark style="color:blue;">**API Passphrase**</mark>
* Your secret key to generate the signature: <mark style="color:blue;">**API Signature**</mark>

<mark style="color:blue;">**PUT IMAGE**</mark>

Authentication to the API is done using HTTP Basic Auth. The API Keys must be in all requests such as the username and password.

Your username and password are sent as API KEY and API Passphrase respectively in the body of the request.

API keys, like whitelisted IPs, are ways to authenticate yourself, therefore, please do not share credentials in any public setting.

## <mark style="color:blue;">Headers</mark>

All requests sent through Cashouts API must have the following headers.

<table data-header-hidden><thead><tr><th width="139">Header</th><th width="105" align="center">Format</th><th width="120" align="center">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>Header</td><td align="center">Format</td><td align="center">Mandatory</td><td>Description</td></tr><tr><td>Payload-Signature</td><td align="center">String</td><td align="center">Yes</td><td>HMAC256 of the whole JSON Payload using your API Signature</td></tr><tr><td>Content-Type</td><td align="center">String</td><td align="center">Yes</td><td><code>application/json</code></td></tr><tr><td>User-Agent</td><td align="center">String</td><td align="center">Yes</td><td>Server client user agent</td></tr></tbody></table>

### <mark style="color:blue;">Calculating the Signature</mark> <a href="#calculating-the-signature" id="calculating-the-signature"></a>

All calls to our Cashouts APIs must contain a `Payload-Signature` field on the header used to ensure request integrity and to authenticate yourself since you will use your own API Signature (secret key) to generate and encrypt a hash.

It has to be created using **HMAC-SHA-256 (RFC 2104)** encoding and the payload is made of the entire JSON Payload sent in the body of the requests and notifications.

{% hint style="success" %}
Use your API Signature to create the HASH
{% endhint %}

The `Payload-Signature` field on the header of the requests will contain the hash generated from hashing the entire JSON Payload:

> Payload-Signature: HMAC256(jsonPayload)

Example:

> Payload-Signature: 223a9dd4784726f1536c926da7dc69155a57612c5c3c1e1b429c367a5eee67cf

<details>

<summary>Notes</summary>

The `Payload-Signature` value is case-sensitive and must be sent in lower case.

In case the `jsonPayload` value is empty, use an empty string instead.

The `jsonPayload` should be converted to UTF-8 before hashing it to prevent `Invalid Signature` error when sending characters with different encodings.

</details>

## Examples <a href="#examples" id="examples"></a>

Check the examples below on how to calculate the `Payload-Signature`.<br>

{% tabs %}
{% tab title="Java" %}

```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.net.util.Base64;

String json_payload = "{ \"login\": \"cashout_API_Key\", \"pass\": \"cashout_API_Passphrase\",   \"external_id\": \"123456789\",  \"document_id\": \"1234567899\",  \"document_type\": \"\",   \"cashout_type\": \"BANK\", \"beneficiary_name\": \"Test User\", \"beneficiary_lastname\": \"Test User\",  \"country\": \"MX\",  \"amount\": 2000,  \"currency\": \"MXN\",  \"email\": \"test@test.com\", \"notification_url\": \"http:\\/\\/tupaypagos.com\\/notification\",  \"bank_code\": \"072\",\"bank_branch\": \"\",  \"bank_account\": \"1234567890\", \"account_type\": \"C\", \"address\": \"\"}";
String secretKey = "cashout_secret_key";
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));
String payload_signature = Base64.encodeBase64String(hasher.doFina
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$json_payload = '{
"login": "cashout_API_Key",
"pass": "cashout_API_Passphrase",
"external_id": "123456789",
"document_id": "1234567899",
"document_type": "", 
"cashout_type": "BANK",
"beneficiary_name": "Test User",
"beneficiary_lastname": "Test User",
"country": "MX",
"amount": 2000,
"currency": "MXN",
"email": "test@test.com",
"notification_url": "http://www.tupayonline.com/notification",
"bank_code": "072",
"bank_branch": "",
"bank_account": "1234567890",
"account_type": "C",
"address": ""
}';
$secretKey = "cashout_secret_key";
$payload_signature = strtolower(hash_hmac('sha256', pack('A*', $json_payload), pack('A*', $secretKey)));
?>
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Text;
using System.Security.Cryptography;

string jsonPayload = "{ \"login\": \"cashout_API_Key\", \"pass\": \"cashout_API_Passphrase\",   \"external_id\": \"123456789\",  \"document_id\": \"1234567899\",  \"document_type\": \"\",   \"cashout_type\": \"BANK\", \"beneficiary_name\": \"Test User\", \"beneficiary_lastname\": \"Test User\",  \"country\": \"MX\",  \"amount\": 2000,  \"currency\": \"MXN\",  \"email\": \"test@test.com\", \"notification_url\": \"http:\\/\\/www.tupayonline.com\\/notification\",  \"bank_code\": \"072\",\"bank_branch\": \"\",  \"bank_account\": \"1234567890\", \"account_type\": \"C\", \"address\": \"\"}";
string secretKey = "cashout_secret_key";        
byte[] keyByte = new ASCIIEncoding().GetBytes(secretKey);
byte[] jsonPayloadBytes = new ASCIIEncoding().GetBytes(jsonPayload);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(jsonPayloadBytes);
string payloadSignature = BitConverter.ToString(hashmessage).Replace("-", "").ToLower();
```

{% endtab %}
{% endtabs %}

[^1]:


---

# 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.tupayonline.com/english/api-documentation/cashout/authentication-and-signature-calculation.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.