Conversion

Report a conversion

Signed server-to-server postback that reports a sale against a tracked link. The short code is re-resolved to a real tracked link and the partner code is checked before any commission is recorded.

post/api/postback/conversion

Request

  • Base URL: https://atlas.hellosafe.com
  • URL: https://atlas.hellosafe.com/api/postback/conversion
  • Auth: API key in header x-atlas-key-id and API key in header x-atlas-timestamp and API key in header x-atlas-signature

Request body

refstring required

The tracked ref that carried the sale, partnerCode-shortCode.

externalOrderIdstring required

Your own order id. Replaying it updates that sale instead of creating a second one.

amountnumber required

Premium paid by the traveller, in the sale currency.

commissionnumber

Optional. Left out, it is computed server side from the configured rate.

currencystring

ISO 4217. Defaults to EUR.

status'pending' | 'validated' | 'cancelled' required

State of the sale. A cancelled sale reverses the commission.

partnerFeeAmountnumber

Optional. The uplift slice of the handling fee you actually charged on this sale, in the sale currency. Declarative: the ledger recomputes what it should be from the partner's own grid and pays the lower of the two, so this can only ever reduce what is owed, never inflate it. Leave it out when the offer carried no uplift.

contractVersion'3.1' | '3.2'

Optional. Which version of this contract you are speaking. Omitting it means 3.1, the shape that predates partnerFeeAmount, and stays valid. A version this endpoint does not know is refused with 400 UNKNOWN_CONTRACT_VERSION rather than parsed leniently: a field silently dropped here is a sale booked at the wrong price, and past the 14-day auto-validation that is no longer repairable.

Example request

{
  "ref": "ATL123-a1b2c3d4"
}

Response

Conversion accepted.

Changes

No recorded changes to this operation across all 1 revision of this API.