Request a payment report

Accepts the full payment-list filter set by composition, so a report and the payments list can never diverge. Freezes the upper date bound to the request time, dedupes identical requests on a canonical hash of merchant + format + filters, then runs generation asynchronously. There is no request-time row cap: an over-large request is accepted and later fails as MAX_ROWS_EXCEEDED, visible on the report row.

POST

https://api.lite.sa

payments

reports

Request a payment report

curl --request POST \
  --url https://api.lite.sa/payments/reports \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "format": "CSV",
  "recipient_email": "finance@merchant.example"
}
'

import requests

url = "https://api.lite.sa/payments/reports"

payload = {
    "format": "CSV",
    "recipient_email": "finance@merchant.example"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({format: 'CSV', recipient_email: 'finance@merchant.example'})
};

fetch('https://api.lite.sa/payments/reports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({format: 'CSV', recipient_email: 'finance@merchant.example'})
};

fetch('https://api.lite.sa/payments/reports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lite.sa/payments/reports"

	payload := strings.NewReader("{\n  \"format\": \"CSV\",\n  \"recipient_email\": \"finance@merchant.example\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lite.sa/payments/reports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'format' => 'CSV',
    'recipient_email' => 'finance@merchant.example'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "id": "3f1c0b2a-0e5d-4a1b-9c2f-6a7b8c9d0e1f",
  "status": "QUEUED",
  "created_at": "2026-09-06T12:00:00.000Z",
  "row_count": 1284,
  "completed_at": "2026-09-06T12:03:11.000Z",
  "expires_at": "2026-12-05T12:03:11.000Z"
}

{
  "id": "3f1c0b2a-0e5d-4a1b-9c2f-6a7b8c9d0e1f",
  "status": "QUEUED",
  "created_at": "2026-09-06T12:00:00.000Z",
  "row_count": 1284,
  "completed_at": "2026-09-06T12:03:11.000Z",
  "expires_at": "2026-12-05T12:03:11.000Z"
}

{
  "error": {
    "code": "PAYMENT_DETAILS_MISMATCH",
    "message": "The request was invalid or malformed",
    "timestamp": "2024-12-16T10:30:00.000Z",
    "details": {},
    "correlationId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "PAYMENT_DETAILS_MISMATCH",
    "message": "The request was invalid or malformed",
    "timestamp": "2024-12-16T10:30:00.000Z",
    "details": {},
    "correlationId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Authorizations

x-api-key

string

header

required

API key for service-to-service or merchant authentication.

Headers

x-correlation-id

string<uuid>

Unique identifier for request tracing. Generated by the client or server if not provided.

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

Request a payment report

format

enum<string>

required

Report file format. Only CSV is supported in v1.

Available options:

CSV

Example:

"CSV"

recipient_email

string<email>

required

Email address notified once the report completes.

Example:

"finance@merchant.example"

filters

object

Same filter set accepted by GET /payments. Omit entirely to include every payment for the merchant in the report (still bounded by the frozen upper date and the row ceiling).

Show child attributes

Response

Deduped to an existing report matching the same merchant, format, and filters. Adds row_count / completed_at / expires_at when that report is already COMPLETED.

string<uuid>

required

Report identifier

Example:

"3f1c0b2a-0e5d-4a1b-9c2f-6a7b8c9d0e1f"

status

enum<string>

required

Available options:

QUEUED,

RUNNING,

COMPLETED,

FAILED

Example:

"QUEUED"

created_at

string<date-time>

required

Example:

"2026-09-06T12:00:00.000Z"

row_count

integer

Exact row count. Present when a deduped report is already COMPLETED.

Example:

1284

completed_at

string<date-time>

Example:

"2026-09-06T12:03:11.000Z"

expires_at

string<date-time>

Example:

"2026-12-05T12:03:11.000Z"

Request a payment report

curl --request POST \
  --url https://api.lite.sa/payments/reports \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "format": "CSV",
  "recipient_email": "finance@merchant.example"
}
'

import requests

url = "https://api.lite.sa/payments/reports"

payload = {
    "format": "CSV",
    "recipient_email": "finance@merchant.example"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({format: 'CSV', recipient_email: 'finance@merchant.example'})
};

fetch('https://api.lite.sa/payments/reports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({format: 'CSV', recipient_email: 'finance@merchant.example'})
};

fetch('https://api.lite.sa/payments/reports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lite.sa/payments/reports"

	payload := strings.NewReader("{\n  \"format\": \"CSV\",\n  \"recipient_email\": \"finance@merchant.example\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lite.sa/payments/reports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'format' => 'CSV',
    'recipient_email' => 'finance@merchant.example'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "id": "3f1c0b2a-0e5d-4a1b-9c2f-6a7b8c9d0e1f",
  "status": "QUEUED",
  "created_at": "2026-09-06T12:00:00.000Z",
  "row_count": 1284,
  "completed_at": "2026-09-06T12:03:11.000Z",
  "expires_at": "2026-12-05T12:03:11.000Z"
}

{
  "id": "3f1c0b2a-0e5d-4a1b-9c2f-6a7b8c9d0e1f",
  "status": "QUEUED",
  "created_at": "2026-09-06T12:00:00.000Z",
  "row_count": 1284,
  "completed_at": "2026-09-06T12:03:11.000Z",
  "expires_at": "2026-12-05T12:03:11.000Z"
}

{
  "error": {
    "code": "PAYMENT_DETAILS_MISMATCH",
    "message": "The request was invalid or malformed",
    "timestamp": "2024-12-16T10:30:00.000Z",
    "details": {},
    "correlationId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "PAYMENT_DETAILS_MISMATCH",
    "message": "The request was invalid or malformed",
    "timestamp": "2024-12-16T10:30:00.000Z",
    "details": {},
    "correlationId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Payment Acceptance

Tokenization

Account Settlement

Request a payment report

Authorizations

Headers

Body

Response