Finik Web SDK

https://quip.com/dTaoApuzXEn1
Admin
Finik Web SDK provides documentation and tools for integrating the Finik Payment System and...
Tokens:7,447
Snippets:27
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Payment Initiation (Python)

Source: https://quip.com/dTaoApuzXEn1/index

This section details how to initiate a payment using the AversPay Acquiring API with the python-authorizer package. It includes setup, request construction, and sending the request.

```APIDOC
## POST /v1/payment

### Description
Initiates a payment transaction through the AversPay Acquiring API.

### Method
POST

### Endpoint
/v1/payment

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **Amount** (integer) - Required - The amount of the payment.
- **CardType** (string) - Required - The type of card, e.g., "FINIK_QR".
- **PaymentId** (string) - Required - A unique identifier for the payment (UUID format).
- **RedirectUrl** (string) - Required - The URL to redirect the user after payment.
- **Data** (object) - Required - Additional data for the payment.
  - **accountId** (string) - Required - The account ID.
  - **merchantCategoryCode** (string) - Required - The merchant category code.
  - **name_en** (string) - Required - The name of the merchant in English.

### Request Example
```json
{
  "Amount": 100,
  "CardType": "FINIK_QR",
  "PaymentId": "00000000-0000-0000-0000-000000000000",
  "RedirectUrl": "https://example.com/success",
  "Data": {
    "accountId": "your-account-id",
    "merchantCategoryCode": "0742",
    "name_en": "your-qr-name"
  }
}
```

### Response
#### Success Response (200)
Details of the successful payment initiation (specific fields depend on API response).

#### Response Example
(Example response structure not provided in source text)
```

--------------------------------

### Finik Webhook Inbound Request Example

Source: https://quip.com/dTaoApuzXEn1/index

This example demonstrates the structure of an inbound POST request from Finik to a merchant's webhook URL. It includes essential headers like `Host`, `Content-Type`, `x-api-timestamp`, and `signature`, along with a JSON payload containing transaction details.

```HTTP
POST /webhooks/finik HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
x-api-timestamp: 1737369012345
signature: Gk3GqQ1O0z+4wC3…(Base64)…u1U=

{
"id": "transaction-id-15423_CREDIT",
"transactionId": "transaction-id-241234",
"status": "SUCCEEDED", // or "FAILED"
"amount": 100,
"net": 100,
"accountId": "your account id",
"fields": {
"amount": 100,
"fieldId1": "value1",
"fieldId2": "value2"
},
"requestDate": 1737369012345,
"transactionDate": 1737369012345,
"transactionType": "DEBIT",
"receiptNumber": "some-number"
}
```

--------------------------------

### cURL POST Request with Headers and JSON Data

Source: https://quip.com/dTaoApuzXEn1/index

This example shows how to make a POST request using the cURL command-line tool. It includes setting custom headers such as API key, timestamp, signature, and content type, along with sending JSON data in the request body.

```bash
curl -i -X POST https://api.acquiring.averspay.kg/v1/payment \
-H 'x-api-key: ...' -H 'x-api-timestamp: ...' -H 'signature: ...' \
-H 'content-type: application/json' \
--data '{"Amount":100,"CardType":"FINIK_QR", ... }'
```

--------------------------------

### Node.js Finik API Authorization and Request

Source: https://quip.com/dTaoApuzXEn1/index

Example demonstrating how to use the '@mancho.devs/authorizer' package in Node.js to generate a signature for Finik API requests. It includes setting up credentials, constructing the request data, signing, and sending the request using fetch.

```javascript
import { Signer, RequestData } from '@mancho.devs/authorizer';
import fetch from 'node-fetch'; // or axios

// Choose the environment you call:
const baseUrl = 'https://api.acquiring.averspay.kg'; // prod
// const baseUrl = 'https://beta.api.acquiring.averspay.kg'; // beta

// IMPORTANT: Host header must match the URL host exactly.
const host = new URL(baseUrl).host;

// Your credentials
const apiKey = process.env.FINIK_API_KEY!; // from Finik
const privateKey = process.env.FINIK_PRIVATE_PEM!; // contents of finik_private.pem
const timestamp = Date.now().toString(); // UNIX ms

// Create Payment body per spec
const body = {
Amount: 100,
CardType: 'FINIK_QR',
PaymentId: '00000000-0000-0000-0000-000000000000', // use a real UUID
RedirectUrl: 'https://example.com/success',
Data: {
accountId: 'your-account-id',
merchantCategoryCode: '0742',
name_en: 'your-qr-name',
},
};

// Build the canonical input for signing
const requestData: RequestData = {
httpMethod: 'POST',
path: '/v1/payment', // absolute path only (no query)
headers: {
Host: host, // must match baseUrl host
'x-api-key': apiKey, // included in signature
'x-api-timestamp': timestamp, // UNIX ms; same value used in signature
// You may send other headers, but only `host` and `x-api-*` are included in the signature.
},
queryStringParameters: undefined, // or { ... } if you have query; lib sorts & encodes
body,
};

// Produce Base64 RSA-SHA256 signature
const signature = await new Signer(requestData).sign(privateKey);

// Send the actual HTTP request
const url = `${baseUrl}${requestData.path}`;
const res = await fetch(url, {
method: requestData.httpMethod,
headers: {
'content-type': 'application/json',
'x-api-key': apiKey,
'x-api-timestamp': timestamp,
signature, // <- attach signature header
},
body: JSON.stringify(body),
// If your API currently returns 302 (HTML) on S2S calls, prevent auto-follow:
redirect: 'manual', // remove once API returns 201 JSON by default
});

if (res.status === 302) {
// Read Location when you opt into redirects
}
```

--------------------------------

### Finik API Error Response Examples

Source: https://quip.com/dTaoApuzXEn1/index

These examples illustrate common error responses from the Finik API, typically returned with a `statusCode` and an `ErrorMessage`. They cover scenarios like invalid timestamps, amounts, signatures, and authorization issues.

```JSON
{
  "statusCode": 400,
  "ErrorMessage": "A valid UNIX timestamp must be provided in the header"
}
```

```JSON
{
  "statusCode": 400,
  "ErrorMessage": "An invalid amount is provided. Amount must be greater than 0."
}
```

```JSON
{
  "statusCode": 401,
  "ErrorMessage": "An invalid signature is provided"
}
```

```JSON
{
  "statusCode": 403,
  "ErrorMessage": "Forbidden"
}
```

--------------------------------

### Error Responses

Source: https://quip.com/dTaoApuzXEn1/index

Examples of error responses that Finik might send.

```APIDOC
## Error Responses

### Description
These are sample error responses indicating issues with the payment or request.

### Bad Request (400)
- **Invalid UNIX timestamp**: `{"statusCode": 400, "ErrorMessage": "A valid UNIX timestamp must be provided in the header"}`
- **Invalid amount**: `{"statusCode": 400, "ErrorMessage": "An invalid amount is provided. Amount must be greater than 0."}`

### Unauthorized (401)
- **Invalid signature**: `{"statusCode": 401, "ErrorMessage": "An invalid signature is provided"}`

### Forbidden (403)
- **Forbidden**: `{"statusCode": 403, "ErrorMessage": "Forbidden"}`
```

--------------------------------

### Node.js Axios POST Request with Redirect Handling

Source: https://quip.com/dTaoApuzXEn1/index

This example demonstrates making a POST request using the Axios library in Node.js. It configures Axios to not automatically follow redirects, validates specific status codes (201, 302) or codes >= 400, and extracts the payment URL from the response headers.

```javascript
const res = await axios.post(url, body, {
  headers: { "x-api-key": apiKey, "x-api-timestamp": ts, signature },
  maxRedirects: 0, // <-- don't auto-follow
  validateStatus: s => [201, 302].includes(s) || s >= 400
});

const paymentUrl = res.headers.location;
```

--------------------------------

### Payment Initiation (Node.js)

Source: https://quip.com/dTaoApuzXEn1/index

This snippet demonstrates how to initiate a payment using the Finik Web SDK in a Node.js environment. It includes setting up credentials, defining the payment body, generating a signature for authorization, and sending the payment request.

```APIDOC
## POST /v1/payment

### Description
Initiates a payment transaction through the Finik Acquiring Service.

### Method
POST

### Endpoint
/v1/payment

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **Amount** (number) - Required - The payment amount.
- **CardType** (string) - Required - The type of card, e.g., 'FINIK_QR'.
- **PaymentId** (string) - Required - A unique identifier for the payment.
- **RedirectUrl** (string) - Required - The URL to redirect the user after payment.
- **Data** (object) - Required - Additional data for the payment.
  - **accountId** (string) - Required - The account ID.
  - **merchantCategoryCode** (string) - Required - The merchant category code.
  - **name_en** (string) - Required - The merchant name in English.

### Request Example
```json
{
  "Amount": 100,
  "CardType": "FINIK_QR",
  "PaymentId": "00000000-0000-0000-0000-000000000000",
  "RedirectUrl": "https://example.com/success",
  "Data": {
    "accountId": "your-account-id",
    "merchantCategoryCode": "0742",
    "name_en": "your-qr-name"
  }
}
```

### Response
#### Success Response (200 or 302)
- The API may return a 302 redirect with a `Location` header for payment processing.

#### Response Example
(If 302)
```
HTTP/1.1 302 Found
Location: https://redirect.example.com/payment/uuid
```
```

--------------------------------

### Create Payment

Source: https://quip.com/dTaoApuzXEn1/index

Initiates a payment request. Requires a signature generated from request details and includes options for production and beta environments. Handles redirects by returning a 'Location' header.

```APIDOC
## POST /v1/payment

### Description
Creates a new payment. The request must be signed, and the response may contain a redirect URL.

### Method
POST

### Endpoint
* Beta: https://beta.api.acquiring.averspay.kg/v1/payment
* Production: https://api.acquiring.averspay.kg/v1/payment

### Headers
- `signature`: The generated signature for the request.
- `x-api-key`: Your unique API key.
- `x-api-timestamp`: The timestamp of the API request.

### Request Body
* `Amount` (number) - The payment amount.
* `CardType` (string) - The type of card or payment method (e.g., "FINIK_QR").
* `PaymentId` (string) - A unique identifier for the payment (e.g., a UUID).
* `RedirectUrl` (string) - The URL to redirect the user to after payment completion.
* `Data` (object) - Additional data required for specific payment types:
    * `accountId` (string) - Your account ID.
    * `merchantCategoryCode` (string) - The merchant category code.
    * `name_en` (string) - The name of the merchant in English.
    * `webhookUrl` (string) - The URL for receiving payment status webhooks.

### Request Example
```json
{
    "Amount": 100,
    "CardType": "FINIK_QR",
    "PaymentId": "uuid()",
    "RedirectUrl": "https://example.com/success",
    "Data": {
        "accountId": "your-account-id",
        "merchantCategoryCode": "0742",
        "name_en": "your-qr-name",
        "webhookUrl": "your-payment-status-webhook-api"
    }
}
```

### Response
#### Success Response (302 Found)
- `Location` (string) - The URL of the payment page. **Do not auto-follow this redirect**; instead, redirect the user's browser to this URL.

#### Response Example (Redirect)
```
HTTP/1.1 302 Found
Location: https://qr.finik/<payment-path>
```

### Error Handling
- If the status code is not 201 (Created) or a redirect status (301, 302, 303, 307, 308), the response will contain the status code and text. Handle these errors appropriately.
```

--------------------------------

### Finik Public Keys

Source: https://quip.com/dTaoApuzXEn1/index

Public keys for verifying Finik signatures in production and beta environments.

```APIDOC
## Public Keys

### Description
Use these public keys to verify the authenticity of requests received from Finik.

### Prod Public Key
```
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuF/PUmhMPPidcMxhZBPb
BSGJoSphmCI+h6ru8fG8guAlcPMVlhs+ThTjw2LHABvciwtpj51ebJ4EqhlySPyT
hqSfXI6Jp5dPGJNDguxfocohaz98wvT+WAF86DEglZ8dEsfoumojFUy5sTOBdHEu
g94B4BbrJvjmBa1YIx9Azse4HFlWhzZoYPgyQpArhokeHOHIN2QFzJqeriANO+wV
aUMta2AhRVZHbfyJ36XPhGO6A5FYQWgjzkI65cxZs5LaNFmRx6pjnhjIeVKKgF99
4OoYCzhuR9QmWkPl7tL4Kd68qa/xHLz0Psnuhm0CStWOYUu3J7ZpzRK8GoEXRcr8
tQIDAQAB
-----END PUBLIC KEY-----
```

### Beta Public Key
```
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwlrlKz/8gLWd1ARWGA/8
o3a3Qy8G+hPifyqiPosiTY6nCHovANMIJXk6DH4qAqqZeLu8pLGxudkPbv8dSyG7
F9PZEAryMPzjoB/9P/F6g0W46K/FHDtwTM3YIVvstbEbL19m8yddv/xCT9JPPJTb
LsSTVZq5zCqvKzpupwlGS3Q3oPyLAYe+ZUn4Bx2J1WQrBu3b08fNaR3E8pAkCK27
JqFnP0eFfa817VCtyVKcFHb5ij/D0eUP519Qr/pgn+gsoG63W4pPHN/pKwQUUiAy
uLSHqL5S2yu1dffyMcMVi9E/Q2HCTcez5OvOllgOtkNYHSv9pnrMRuws3u87+hNT
ZwIDAQAB
-----END PUBLIC KEY-----
```
```

--------------------------------

### Generate SSL Keys using OpenSSL

Source: https://quip.com/dTaoApuzXEn1/index

Commands to generate a private key and a public key using OpenSSL. The private key is used for signing requests, and the public key is shared with Finik for verification. Keep the private key secret.

```bash
openssl genrsa -out finik_private.pem 2048
```

```bash
openssl rsa -in finik_private.pem -pubout > finik_public.pem
```

--------------------------------

### Pseudocode: Concatenate Header Parts for Signature

Source: https://quip.com/dTaoApuzXEn1/index

Illustrates the pseudocode for concatenating header information, including 'Host' and 'x-api-*' headers, sorted alphabetically, with a specific format.

```pseudocode
parts = "host" + ":" + String(header["Host"]) + "&"  

parts += Lowercase(<HeaderName1>) + ":" + String(<value>) + "&"  
parts += Lowercase(<HeaderName2>) + ":" + String(<value>) + "&"  
...
parts += Lowercase(<HeaderNameN>) + ":" + String(<value>)
```

--------------------------------

### Node.js: Create Payment Request (Fetch API)

Source: https://quip.com/dTaoApuzXEn1/index

Demonstrates how to make a POST request to the Averspay payment API using Node.js Fetch API. It highlights the importance of not auto-following redirects.

```javascript
const res = await fetch("https://api.acquiring.averspay.kg/v1/payment", {

```

--------------------------------

### Python API Request with Authorizer

Source: https://quip.com/dTaoApuzXEn1/index

This snippet shows how to use the `authorizer` package in Python to sign and send an API request. It includes setting up environment variables for API keys, defining the request body and headers, generating an RSA-SHA256 signature, and sending a POST request with the signature.

```python
from authorizer import Signer
import json
import os
import time
import requests
from urllib.parse import urljoin

# Choose environment
BASE_URL = "https://api.acquiring.averspay.kg" # prod
# BASE_URL = "https://beta.api.acquiring.averspay.kg" # beta

HOST = "api.acquiring.averspay.kg" # must match BASE_URL host exactly
# HOST = "beta.api.acquiring.averspay.kg"

API_KEY = os.environ["FINIK_API_KEY"] # from Finik
PRIVATE_KEY_PEM = os.environ["FINIK_PRIVATE_PEM"] # contents of finik_private.pem

timestamp = str(int(time.time() * 1000)) # UNIX ms

body = {
"Amount": 100,
"CardType": "FINIK_QR",
"PaymentId": "00000000-0000-0000-0000-000000000000", # use a real UUID
"RedirectUrl": "https://example.com/success",
"Data": {
"accountId": "your-account-id",
"merchantCategoryCode": "0742",
"name_en": "your-qr-name"
}
}

request_data = {
"http_method": "POST",
"path": "/v1/payment",
"headers": {
"Host": HOST, # must equal BASE_URL's host
"x-api-key": API_KEY,
"x-api-timestamp": timestamp,
},
# If you have queries, set a dict here; signer will encode/sort them
"query_string_parameters": None,
"body": body, # plain dict; signer will canonicalize/JSON-stringify
}

# Produce Base64 RSA-SHA256 signature
signature = Signer(**request_data).sign(PRIVATE_KEY_PEM)

# Send the request
url = urljoin(BASE_URL, request_data["path"])
resp = requests.post(
url,
headers={
"content-type": "application/json",
"x-api-key": API_KEY,
"x-api-timestamp": timestamp,
"signature": signature,
},
data=json.dumps(body, separators=(',', ':')),
)
```

--------------------------------

### Pseudocode: Generate Signature Data

Source: https://quip.com/dTaoApuzXEn1/index

Defines the pseudocode steps for collecting data required for signature generation, including HTTP method, URI, headers, query parameters, and JSON payload.

```pseudocode
data = Lowercase(HTTP method) + "\n"
data += URIAbsolutePath + "\n"
data += ( header["Host"] and headers that start with x-api-*) + "\n"
data += queryStringParams + "\n" // **Note: Don't add "\n" to data** if there are no queryStringParams
data += json(request.body)
```

--------------------------------

### JavaScript Fetch POST Request with Redirect Handling

Source: https://quip.com/dTaoApuzXEn1/index

This snippet shows how to make a POST request using the Fetch API in JavaScript. It includes setting headers, stringifying the request body, and manually handling redirects by checking the response status and retrieving the payment URL from the 'location' header.

```javascript
fetch(url, {
  method: "POST",
  headers: { "content-type": "application/json", "x-api-key": apiKey, "x-api-timestamp": ts, signature },
  body: JSON.stringify(body),
  redirect: "manual" // <-- don't auto-follow
});

if (res.status === 302) {
  const paymentUrl = res.headers.get("location"); // send this to the browser
}
```

--------------------------------

### Finik Beta Public Key

Source: https://quip.com/dTaoApuzXEn1/index

This is the public key to be used for verifying signatures of requests coming from the Finik beta environment. Use this key during testing and development phases.

```text
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwlrlKz/8gLWd1ARWGA/8
o3a3Qy8G+hPifyqiPosiTY6nCHovANMIJXk6DH4qAqqZeLu8pLGxudkPbv8dSyG7
F9PZEAryMPzjoB/9P/F6g0W46K/FHDtwTM3YIVvstbEbL19m8yddv/xCT9JPPJTb
LsSTVZq5zCqvKzpupwlGS3Q3oPyLAYe+ZUn4Bx2J1WQrBu3b08fNaR3E8pAkCK27
JqFnP0eFfa817VCtyVKcFHb5ij/D0eUP519Qr/pgn+gsoG63W4pPHN/pKwQUUiAy
uLSHqL5S2yu1dffyMcMVi9E/Q2HCTcez5OvOllgOtkNYHSv9pnrMRuws3u87+hNT
ZwIDAQAB
-----END PUBLIC KEY-----
```

--------------------------------

### POST /v1/payment

Source: https://quip.com/dTaoApuzXEn1/index

Initiates a payment transaction. The API may respond with a 302 redirect to a payment URL.

```APIDOC
## POST /v1/payment

### Description
Initiates a payment transaction. The API may respond with a 302 redirect to a payment URL.

### Method
POST

### Endpoint
https://api.acquiring.averspay.kg/v1/payment

### Headers
- **x-api-key** (string) - Required - Your API key.
- **x-api-timestamp** (string) - Required - Timestamp of the request.
- **signature** (string) - Required - Signature of the request.
- **content-type** (string) - Required - Must be `application/json`.

### Request Body
- **Amount** (number) - Required - The amount of the payment.
- **CardType** (string) - Required - The type of card, e.g., `FINIK_QR`.

### Request Example
```json
{
  "Amount": 100,
  "CardType": "FINIK_QR"
}
```

### Response
#### Success Response (201)
Indicates the payment was successfully initiated and processed.

#### Redirect Response (302)
- **location** (string) - The URL to redirect the user for payment completion.

#### Response Example (302)
Headers:
```
Location: https://example.com/pay?token=...
```
```

--------------------------------

### Pseudocode: Concatenate Query String Parameters for Signature

Source: https://quip.com/dTaoApuzXEn1/index

Provides pseudocode for collecting and concatenating query string parameters, ensuring they are sorted alphabetically and URL-encoded.

```pseudocode
parts = URiEncode(<QueryParameter1>) + "=" + URiEncode(<value>) + "&"  
parts += URiEncode(<QueryParameter2>) + "=" + URiEncode(<value>) + "&"  
...
parts += URiEncode(<QueryParameterN>) + "=" + URiEncode(<value>)
If the query parameter value is empty, use an empty string as a value. For example, in `http://mancho.dev/examplebucket?acl` the `acl` query parameter has no value. Then, the concatenation should be as follows:
`parts += URiEncode("acl") + "=" + ""`
```

--------------------------------

### Signature Generation (Pseudocode)

Source: https://quip.com/dTaoApuzXEn1/index

Details the process of generating a signature for API requests, involving HTTP method, URI, headers, query parameters, and request body.

```APIDOC
## Signature Generation Process

### 1. Collect Data for Signature

Construct a string `data` by concatenating the following components:

1.  Lowercase HTTP method (e.g., `post`, `get`).
2.  Absolute path of the URI (starting with `/`).
3.  Host header and all headers starting with `x-api-*`. Sort these headers alphabetically by header name, then concatenate them in the format `header_name:header_value` separated by `&`.
4.  Query string parameters, sorted alphabetically by parameter name and encoded. Concatenate them in the format `encoded_param_name=encoded_param_value` separated by `&`. If a query parameter has no value, use an empty string.
5.  The JSON string of the request body, with keys sorted alphabetically.

### 2. Generate Signature

Use the collected `data` and your private key to generate a signature (e.g., using SHA256withRSA). The signature should be Base64 encoded.

### Example (Java Snippet for Signing)

```java
public String sign(String payload, String privatePath) {
    try{
        Signature signature = Signature.getInstance("SHA256withRSA");
        String privateKeyFile = new String(Files.readAllBytes(Paths.get(privatePath)));
        RSAKey rsaKey = (RSAKey) JWK.parseFromPEMEncodedObjects(privateKeyFile);
        PrivateKey privateKey = rsaKey.toPrivateKey();
        signature.initSign(privateKey);
        signature.update(payload.getBytes(StandardCharsets.UTF_8));
        byte[] signatureValue = signature.sign();
        return Base64.encodeBase64String(signatureValue);
    }catch (Exception e){
        throw new AppException(e.getMessage());
    }
}
```
```

--------------------------------

### SPA Redirect to Payment URL

Source: https://quip.com/dTaoApuzXEn1/index

Alternatively, the backend can return payment URL details as JSON to a Single Page Application (SPA). The SPA's frontend JavaScript then handles the redirection using `window.location`. This approach decouples the redirection logic.

```JSON
{
  "paymentUrl": "<paymentUrl>"
}
```

```JavaScript
window.location = paymentUrl;
```

--------------------------------

### Payments Status Webhook (Callback)

Source: https://quip.com/dTaoApuzXEn1/index

Finik sends a POST request to your webhook URL after each completed payment. You must verify the request signature and process the payment status.

```APIDOC
## POST /webhooks/finik

### Description
Receives payment status updates from Finik. Requires signature verification using the provided headers and body against the Finik public key.

### Method
POST

### Endpoint
/webhooks/finik

### Parameters
#### Headers
- **Host** (string) - Required - The host of the merchant's domain.
- **x-api-timestamp** (integer) - Required - UNIX timestamp of the request.
- **signature** (string) - Required - Base64 encoded signature of the request.

#### Request Body
- **id** (string) - Required - Finik's internal transaction ID.
- **transactionId** (string) - Required - Merchant's transaction ID.
- **status** (string) - Required - Status of the transaction (e.g., "SUCCEEDED", "FAILED").
- **amount** (integer) - Required - The amount of the transaction.
- **net** (integer) - Required - The net amount after fees.
- **accountId** (string) - Required - The merchant's account ID.
- **fields** (object) - Optional - Additional fields provided during the payment.
  - **amount** (integer) - Required - The amount of the transaction.
  - **fieldId1** (string) - Optional - Example of an additional field.
  - **fieldId2** (string) - Optional - Example of an additional field.
- **requestDate** (integer) - Required - UNIX timestamp when the request was made.
- **transactionDate** (integer) - Required - UNIX timestamp when the transaction occurred.
- **transactionType** (string) - Required - Type of transaction (e.g., "DEBIT").
- **receiptNumber** (string) - Optional - Receipt number for the transaction.

### Request Example
```makefile
POST /webhooks/finik HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
x-api-timestamp: 1737369012345
signature: Gk3GqQ1O0z+4wC3...(Base64)...u1U=

{
"id": "transaction-id-15423_CREDIT",
"transactionId": "transaction-id-241234",
"status": "SUCCEEDED",
"amount": 100,
"net": 100,
"accountId": "your account id",
"fields": {
"amount": 100,
"fieldId1": "value1",
"fieldId2": "value2"
},
"requestDate": 1737369012345,
"transactionDate": 1737369012345,
"transactionType": "DEBIT",
"receiptNumber": "some-number"
}
```

### Response
#### Success Response (200)
- **Acknowledge fast**: Respond with `200 OK` to acknowledge receipt of the callback. Heavy processing should be done asynchronously.

### Troubleshooting
- **Invalid signature**: Ensure the `Host` header, all `x-api-*` headers, and the body are included in the canonical string exactly as required. Check that request body keys are sorted alphabetically.
- **Multiple callbacks**: Implement idempotency using `transactionId` to handle at-least-once delivery guarantees.
```

--------------------------------

### Python Requests POST Request with Redirect Handling

Source: https://quip.com/dTaoApuzXEn1/index

This Python snippet utilizes the 'requests' library to perform a POST request. It disables automatic redirection, sends headers and JSON body, and checks the response status code to extract the payment URL from the 'Location' header.

```python
resp = requests.post(url, headers=hdrs, json=body, allow_redirects=False) # <-- don't auto-follow

if resp.status_code == 302:
  payment_url = resp.headers["Location"]
```

--------------------------------

### Backend Redirect to Payment URL

Source: https://quip.com/dTaoApuzXEn1/index

The backend can redirect the browser to a payment URL obtained from Finik by returning a 302 response with the `Location` header set to the payment URL. This is a common pattern for initiating payment flows.

```HTTP
302 Location: <paymentUrl>
```

--------------------------------

### Finik Production Public Key

Source: https://quip.com/dTaoApuzXEn1/index

This is the public key to be used for verifying signatures of requests coming from the Finik production environment. It's crucial for ensuring the authenticity and integrity of webhook callbacks.

```text
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuF/PUmhMPPidcMxhZBPb
BSGJoSphmCI+h6ru8fG8guAlcPMVlhs+ThTjw2LHABvciwtpj51ebJ4EqhlySPyT
hqSfXI6Jp5dPGJNDguxfocohaz98wvT+WAF86DEglZ8dEsfoumojFUy5sTOBdHEu
g94B4BbrJvjmBa1YIx9Azse4HFlWhzZoYPgyQpArhokeHOHIN2QFzJqeriANO+wV
aUMta2AhRVZHbfyJ36XPhGO6A5FYQWgjzkI65cxZs5LaNFmRx6pjnhjIeVKKgF99
4OoYCzhuR9QmWkPl7tL4Kd68qa/xHLz0Psnuhm0CStWOYUu3J7ZpzRK8GoEXRcr8
tQIDAQAB
-----END PUBLIC KEY-----
```

--------------------------------

### Java: RSA Signature Generation

Source: https://quip.com/dTaoApuzXEn1/index

A Java method to sign a given payload using an RSA private key from a specified file path. It utilizes SHA256withRSA algorithm and returns the Base64 encoded signature.

```java
public String sign(String payload, String privatePath) {
try{
Signature signature = Signature.getInstance("SHA256withRSA");

String privateKeyFile = new String(Files.readAllBytes(Paths.get(privatePath)));

RSAKey rsaKey = (RSAKey) JWK.parseFromPEMEncodedObjects(privateKeyFile);

PrivateKey privateKey = rsaKey.toPrivateKey();

signature.initSign(privateKey);

signature.update(payload.getBytes(StandardCharsets.UTF_8));

byte[] signatureValue = signature.sign();

return Base64.encodeBase64String(signatureValue);
}catch (Exception e){
throw new AppException(e.getMessage());
}
}
```

--------------------------------

### Python: Handle Payment API Response

Source: https://quip.com/dTaoApuzXEn1/index

Processes the response from the payment API, checking for successful creation (201) or redirects (301-308). Handles invalid responses by printing status and text.

```python
if resp.status_code == 201:
print("Created:", resp.json()) # -> { paymentId, paymentUrl, status }
elif resp.status_code in (301, 302, 303, 307, 308):
print("Redirect to:", resp.headers.get("Location"))
else:
print(resp.status_code, resp.text)
```
Tokens:
Raw