donations

Records a donation that has already been collected on the partner platform against the fundraiser identified by source.fundraiserId. ASF creates an internal donation record and returns its donationReferenceId — partners should persist this for later remittance reconciliation.

HTTP request

POST /donations

Authentication

client_id and client_secret headers. See Authentication.

Parameters

Header

Parameter	Required	Type	Description
X-Correlation-ID	Yes	uuid	Fresh UUID per request.

Body

Field	Required	Type	Description
source	Yes	Source	Partner channel + fundraiser identifiers.
source.channel	Yes	SourceChannel	Partner platform making the request.
source.fundraiserId	Yes	string	ASF Member Number
donor	Yes	Donor	Donor details.
donor.email	Yes	string	Donor email.
donor.firstName	Yes	string	Donor first name.
donor.lastName	Yes	string	Donor last name.
donor.mobile	No	string	E.164 preferred; local Australian format accepted.
donor.billingAddress	Yes (postalCode)	BillingAddress	Street, city, state, postalCode, country.
donor.businessName	No	string	Set if the donation is on behalf of a company.
donor.verifiedEmail	No	string	Email verified by the partner platform, if different from email.
transaction	Yes	Transaction	Partner-side transaction record.
transaction.id	No	string	Partner transaction identifier.
transaction.date	No	date-time	ISO 8601 timestamp.
transaction.amount	No	string	Decimal string in AUD.
sourceMetadata	No	object	Free-form metadata stored verbatim.

Returns

SuccessEnvelope with data.items:

Field	Type	Description
donationReferenceId	string	ASF-issued reference for the recorded donation. Persist this — it is the key for createRemittances.

Sample

Python

import os
import uuid
import requests

BASE_URL = "https://sit.api.asf.org.au/fundraisers/api/v1"

body = {
    "source": {
        "channel": "XYZ Platform",
        "fundraiserId": "ASF123456",
    },
    "donor": {
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Smith",
        "mobile": "0438000222",
        "billingAddress": {
            "street": "1 Flinders Street",
            "city": "Melbourne",
            "state": "VIC",
            "postalCode": "3000",
            "country": "AU",
        },
    },
    "transaction": {
        "id": "56789",
        "date": "2024-03-13T16:09:54-04:00",
        "amount": "250",
    },
    "sourceMetadata": {"orderNumber": "2026-1234"},
}

response = requests.post(
    f"{BASE_URL}/donations",
    json=body,
    headers={
        "client_id": os.environ["ASF_CLIENT_ID"],
        "client_secret": os.environ["ASF_CLIENT_SECRET"],
        "X-Correlation-ID": str(uuid.uuid4()),
    },
    timeout=10,
)
response.raise_for_status()

reference_id = response.json()["data"]["items"]["donationReferenceId"]

TypeScript

import { randomUUID } from 'node:crypto';

const BASE_URL = 'https://sit.api.asf.org.au/fundraisers/api/v1';

const body = {
  source: { channel: 'XYZ Platform', fundraiserId: 'ASF123456' },
  donor: {
    email: 'john@example.com',
    firstName: 'John',
    lastName: 'Smith',
    mobile: '0438000222',
    billingAddress: {
      street: '1 Flinders Street',
      city: 'Melbourne',
      state: 'VIC',
      postalCode: '3000',
      country: 'AU',
    },
  },
  transaction: {
    id: '56789',
    date: '2024-03-13T16:09:54-04:00',
    amount: '250',
  },
  sourceMetadata: { orderNumber: '2026-1234' },
};

const response = await fetch(`${BASE_URL}/donations`, {
  method: 'POST',
  headers: {
    client_id: process.env.ASF_CLIENT_ID!,
    client_secret: process.env.ASF_CLIENT_SECRET!,
    'X-Correlation-ID': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);

const { data } = await response.json();
const referenceId = data.items.donationReferenceId;

PHP

<?php
$baseUrl = 'https://sit.api.asf.org.au/fundraisers/api/v1';
$correlationId = bin2hex(random_bytes(16));

$body = [
    'source' => [
        'channel' => 'XYZ Platform',
        'fundraiserId' => 'ASF123456',
    ],
    'donor' => [
        'email' => 'john@example.com',
        'firstName' => 'John',
        'lastName' => 'Smith',
        'mobile' => '0438000222',
        'billingAddress' => [
            'street' => '1 Flinders Street',
            'city' => 'Melbourne',
            'state' => 'VIC',
            'postalCode' => '3000',
            'country' => 'AU',
        ],
    ],
    'transaction' => [
        'id' => '56789',
        'date' => '2024-03-13T16:09:54-04:00',
        'amount' => '250',
    ],
    'sourceMetadata' => ['orderNumber' => '2026-1234'],
];

$ch = curl_init("$baseUrl/donations");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_HTTPHEADER => [
        'client_id: ' . getenv('ASF_CLIENT_ID'),
        'client_secret: ' . getenv('ASF_CLIENT_SECRET'),
        'X-Correlation-ID: ' . $correlationId,
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status >= 400) throw new Exception("HTTP $status: $response");

$referenceId = json_decode($response, true)['data']['items']['donationReferenceId'];

Example response

{
  "apiVersion": "1.0.0",
  "correlationId": "210c68180-2ac6-11ee-b000-111",
  "method": "/donations",
  "data": {
    "items": {
      "donationReferenceId": "0000468-000788"
    }
  }
}

Errors

Status	Code	When it fires
400	FUNDRAISER:VALIDATION	Fundraiser isn’t enrolled with the channel, or required fields failed validation.
401	—	Basic credentials or client_id/client_secret are invalid.
429	—	Request quota exhausted.
500	FUNDRAISER:UNKNOWN	Unhandled server error. Retry with backoff.
503	—	Server temporarily unavailable.