Sales report automation

Sales report automation delivers your transactions to your system on a recurring schedule, without any manual export. Paylead generates an encrypted file, notifies you through a signed Webhook, and lets you download the file through a single-use URL that you decrypt with your own key. This guide describes how the service works and what you set up on your side.

How it works

On a recurring schedule, Paylead exports the transactions accumulated since the previous run into a secure file, then notifies your endpoint. You verify the notification, download the file, and decrypt it.

Key points

Each report covers the period since the previous generation: a daily schedule delivers the previous day’s transactions, a monthly schedule delivers roughly the last 30 days. The exact window is the period field in the Webhook payload.
By default it is generated once a day at 09:00, Europe/Paris time (UTC+1, or UTC+2 during daylight saving time). The trigger time and the frequency are both configurable.
The file is encrypted with your PGP public key (asymmetric encryption), so only you can decrypt it.
The Webhook can be signed with HMAC-SHA256 (optional, strongly recommended) so you can verify its authenticity.
The download URL is single-use and expires after 24 hours.

Before you start, you need:

An HTTPS endpoint that can receive Webhooks (POST requests with a JSON body).
The ability to generate a PGP key pair and decrypt PGP files.

The Webhook

Method and endpoint

Paylead sends an HTTP POST request to the Webhook URL you provide.

Payload

The request body is a JSON object.

{
  "type": "sales_report",
  "url": "<pre-signed download URL>",
  "content_type": "application/pgp-encrypted",
  "inner_content_type": "text/csv",
  "headers": ["transaction_id", "brand", "..."],
  "period": {
    "start_date": "2026-04-01T00:00:00Z",
    "end_date": "2026-04-30T23:59:59Z"
  },
  "brand_reference": "BRAND_REF_123",
  "expire_at": "2026-05-07T00:00:00Z"
}

string

Event type. Always sales_report.

string

Pre-signed URL used to download the report file.

string

Type of the delivered file. Always application/pgp-encrypted.

string

Type of the file once decrypted. Always text/csv.

array

List of the CSV column names, in order.

object

Period covered by the report.

Show period

string

Start of the period (ISO 8601).

string

End of the period (ISO 8601).

string

Reference of the Brand covered by the report.

string

Expiration timestamp of the pre-signed URL.

Authentication with HMAC

Signing Webhooks with HMAC-SHA256 is optional.

Paylead strongly recommends enabling HMAC signing. It lets you confirm that each Webhook was sent by Paylead and was not tampered with in transit.

When signing is enabled, each request carries a signature of the request body in the following header:

X-paylead-signature-256: <hmac-sha256-hex>

Verify this signature on every Webhook you receive, using the shared HMAC secret key that Paylead provides.

Encode the secret to bytes as UTF-8 to obtain the verification key. Do not base64-decode it, even though its format may look like base64.

The following example verifies a signature in Python. The values are illustrative.

import hashlib
import hmac

signature = "75d6c5e87f06bcf3f7b3460336927a9572f09e6407610f09c9e259e05ed2e380"
content = '{"url":"https://example.com/sales-report.csv","brand_reference":"BRAND_REF_123"'.encode("utf-8")
hmac_secret = "vmj8isJ5tDstao3s/L1yJovx5XsOGz/8NWo8RvYR5l4=".encode("utf-8")
expected_signature = hmac.new(hmac_secret, content, digestmod=hashlib.sha256).hexdigest()
assert expected_signature == signature

Retry policy

Any 2xx response is treated as a successful delivery. On failure, Paylead retries the request up to 8 times with exponential backoff (1 minute to 1 hour) for the status codes below. All other error codes are not retried.

Code	Reason
`429`	Too Many Requests
`500`	Internal Server Error
`502`	Bad Gateway
`503`	Service Unavailable
`504`	Gateway Timeout

Report file format

The delivered file is a PGP-encrypted CSV. Each row is one commissioned transaction, with the Brand, the Cashback strategy, the Campaign, and the resulting merchant cost. Once decrypted, it contains the following columns.

#	Column	Description
1	`transaction_id`	Unique transaction identifier.
2	`brand_country_code`	Country code of the Brand.
3	`brand`	Brand name.
4	`transaction_amount`	Transaction amount (absolute value).
5	`transaction_purchase_date`	Purchase date (Europe/Paris timezone).
6	`transaction_debit_date`	Debit date.
7	`partner_name`	Loyalty Program name.
8	`strategy`	Cashback strategy name.
9	`strategy_reference`	Strategy reference.
10	`strategy_objective`	Strategy objective.
11	`cost_per_acquisition`	Cost per acquisition (CPA) level.
12	`paid_commissions`	Merchant Cashback cost.
13	`invoice_date`	Invoice creation date.
14	`invoice_reference`	Invoice reference.
15	`campaign_id`	Campaign identifier.
16	`campaign_name`	Campaign name.
17	`user_id`	Paylead user identifier.

Set up the integration

Setup is a one-time exchange: you send Paylead an encryption key and an endpoint, Paylead sends you a signing secret, and you implement the verification and decryption steps. The delivery schedule (trigger time) and frequency are agreed with Paylead during setup; the defaults are once a day at 09:00 Europe/Paris.

What you provide to Paylead

Item	Description	Format
PGP public key	Used by Paylead to encrypt the report file. Must have the encryption capability `[E]`. Minimum validity: 1 year.	ASCII-armored `.asc` file. Ed25519 or RSA-4096 recommended.
Webhook URL	HTTPS endpoint Paylead sends the Webhook notifications to.	HTTPS URL.

What Paylead provides

Item	Description
HMAC secret key	Provided only when HMAC signing is enabled (recommended). Shared secret that lets you verify the Webhook signature. Generated by Paylead and delivered over a secure channel.

Checklist

To send to Paylead:

PGP public key (ASCII-armored .asc, Ed25519 or RSA-4096, capability [E], validity 1 year or more).
Webhook endpoint URL (HTTPS).

To validate on your side:

If HMAC signing is enabled (recommended): verify the signature in the X-paylead-signature-256 header.
Respond with an HTTP 2xx code on correct receipt.
Decrypt the PGP files with your private key.

Notes

Download window. The pre-signed URL is no longer accessible after 24 hours. Retrieve the file within this window.

Key rotation. If you renew your PGP key pair, provide the new public key to Paylead in advance, so delivery stays continuous before the old key expires.

​How it works

​Key points

​The Webhook

​Method and endpoint

​Payload

​Authentication with HMAC

​Retry policy

​Report file format

​Set up the integration

​What you provide to Paylead

​What Paylead provides

​Checklist

​Notes

How it works

Key points

The Webhook

Method and endpoint

Payload

Authentication with HMAC

Retry policy

Report file format

Set up the integration

What you provide to Paylead

What Paylead provides

Checklist

Notes