# Parameters to Retrieve Donation History source: https://developer.mastercard.com/donations/documentation/parameters/track-donations-param/history/index.md ## Method to Retrieve a Donation History {#method-to-retrieve-a-donation-history} | Method | Endpoint | |--------------|-------------------------------------------------------------| | ~~POST~~ GET | /donations/donors/{donorId}/transactions?offset=0\&limit=50 | Note: ~~The Entire Request Body need not to be encrypted!~~ ## Path parameters {#path-parameters} | Name | Type | Description | Notes | |-------------|--------|------------------------------------------------------------------------------|--------------| | **donorId** | string | Unique ID of the donor generated by Mastercard when a new donor is enrolled. | **Required** | ## Query parameters {#query-parameters} | Name | Type | Description | Notes | |------------|---------|-------------------------------------------------|----------| | **limit** | integer | The page size of the total items | Optional | | **offset** | integer | The starting index of the page size total items | Optional | Request parameters (limit and offset) are optional. If not provided the default value will be page_size = 25 and offset = 0. ## Request parameters {#request-parameters} | Name | Type | Description | Notes | |-----------------------|--------|-------------------------------------------------------------------------------------------------|--------------| | **fromDate** | string | The date to start the search. In YYYY-MM-DD format. | **Required** | | **toDate** | string | The date to end the search. In YYYY-MM-DD format. | **Required** | | **cardId** | string | Unique ID for the card on file. Generated by Mastercard at the time the card was added. | Optional | | **charityId** | string | The charity's unique identifier. Assigned by Mastercard at the time the charity was onboarded. | Optional | | **donationType** | string | The type of donation. Options include: **One-Time** , **Micro** , **Monthly** and **Roundup** | Optional | | **transactionStatus** | string | The status of transaction. Options include: **ALL** , **SUCCESS** , **FAILURE** and **PENDING** | Optional | ## Response Parameters {#response-parameters} A successful request returns the `HTTP 200 (Success)` status code and a JSON response body that includes a unique donor identifier. ### ~~realTimeTransaction~~ (Deprecated) {#realtimetransaction-deprecated} | Name | Type | Description | |---------------------|---------|-----------------------------------------------------| | ~~**limit**~~ | integer | ~~The page size of the total items~~ | | ~~**offset**~~ | integer | ~~The starting index of the page size total items~~ | | ~~**total items**~~ | integer | ~~The total number of items in the result~~ | | ~~**items**~~ | object | ~~The items returned in the response~~ | > ⚠️ **Note:** `realTimeTransaction` is no longer returned as a top-level object. > > The response is now unified under the **`data`** object. *** ** * ** *** ### data (Current Response Structure) {#data-current-response-structure} | Name | Type | Description | |------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **limit** | integer | The page size of the total items. | | **offset** | integer | The starting index of the page. | | **total** | integer | **(New)** Total number of transactions available in the database. | | **count** | integer | **(New)** Number of transactions returned in the current response. | | **items** | array | List of transaction objects returned in the response. See [items](https://developer.mastercard.com/donations/documentation/parameters/track-donations-param/history/index.md#items) attributes. | *** ** * ** *** ### ~~Child Attributes~~ (Deprecated) {#child-attributes-deprecated} #### ~~items~~ {#items} | Name | Type | Description | |------------------------------------|---------|------------------------------------------------------------------------| | ~~**charityName**~~ | integer | ~~The name of the charity that received the donation~~ | | ~~**primaryAccountNumberSuffix**~~ | integer | ~~The last four digits of the payment card used to make the donation~~ | | ~~**donationType**~~ | integer | ~~The type of donation. Results include ROUNDUP, MICRO or MONTHLY~~ | | ~~**date**~~ | object | ~~The date of the transaction in YYYY-DD-MM format~~ | | ~~**updatedDate**~~ | object | ~~The updated date in YYYY-DD-MM format~~ | | ~~**amount**~~ | number | ~~The amount of the donation~~ | | ~~**currency**~~ | string | ~~The currency associated with the donation~~ | | ~~**paymentNetwork**~~ | string | ~~The payment network used for transactions~~ | | ~~**clientId**~~ | string | ~~The client's unique identifier~~ | | ~~**programId**~~ | string | ~~The program's unique identifier~~ | | ~~**donorId**~~ | string | ~~Unique ID of the donor~~ | | ~~**cardId**~~ | string | ~~Unique ID for the card on file~~ | | ~~**charityId**~~ | string | ~~The Id of the charity~~ | | ~~**transactionId**~~ | string | ~~Unique transaction ID~~ | | ~~**orderId**~~ | string | ~~Unique order ID~~ | | ~~**transactionStatus**~~ | string | ~~Returns status of the transaction~~ | | ~~**reasonCode**~~ | string | ~~Failure reason code~~ | | ~~**reasonMessage**~~ | string | ~~Failure reason message~~ | *** ** * ** *** ### items (Current) {#items-current} The `items` array contains individual donation transaction records. | Name | Type | Description | |--------------------------------|----------------|-------------------------------------------------------------------------------------------------| | **charityName** | string | The name of the charity that received the donation. | | **primaryAccountNumberSuffix** | string | The last four digits of the payment card used to make the donation. | | **donationType** | string | The type of donation (e.g., `ONE-TIME`, `MICRO`, `ROUNDUP`, `MONTHLY`). | | **date** | string | The date of the transaction in `YYYY-MM-DD` format. | | **updatedDate** | string | The last updated date of the transaction in `YYYY-MM-DD` format. | | **amount** | number | The amount of the donation. | | **currency** | string | The currency associated with the donation, in ISO 4217 format (e.g., `USD`). | | **paymentNetwork** | string | The payment network used for the transaction (e.g., `mastercard`). | | **dedication** | string \| null | **(New)** Optional dedication message associated with the donation. | | **clientId** | string | The client's unique identifier assigned by Mastercard. | | **programId** | string | The program's unique identifier assigned by Mastercard. | | **donorId** | string | Unique identifier of the donor generated by Mastercard. | | **cardId** | string | Unique identifier for the card on file. | | **charityId** | string | Unique identifier of the charity that received the donation. | | **transactionId** | string | Unique transaction identifier generated by Mastercard. | | **orderId** | string | Unique order identifier generated by Mastercard. | | **transactionStatus** | string | Status of the transaction (e.g., `SUCCESS`, `FAILURE`). | | **reasonCode** | string | **(Conditional)** Failure reason code (returned only when `transactionStatus` is `FAILURE`). | | **reasonMessage** | string | **(Conditional)** Failure reason message (returned only when `transactionStatus` is `FAILURE`). | *** ** * ** *** #### Notes {#notes} * `realTimeTransaction` and its child structure are **fully deprecated** * All transactions are now returned under **`data.items`** * New pagination fields **`total`** and **`count`** replace earlier totals * `dedication`, `reasonCode`, and `reasonMessage` are **new/conditional fields** *** ** * ** *** ### Example Response {#example-response} ```json { "data": { "limit": 10, "offset": 0, "total": 5, "count": 5, "items": [ { "charityName": "Stripe Charity", "primaryAccountNumberSuffix": "1118", "donationType": "ONE-TIME", "date": "2023-07-03", "updatedDate": "2023-07-03", "amount": 10, "currency": "USD", "paymentNetwork": "mastercard", "dedication": null, "clientId": "C7i6WOvQp2obVbB_EtX8XCsQ5YwQ_FN2yIz7Mf9m31e6102d", "programId": "aa0f99f5-75d2-46ed-81b8-7ac80ccd0f6c", "donorId": "bdacdcfc-7d74-406c-9be3-a9f46dcfa27f", "cardId": "88b34e2d-4c80-4469-8049-f713c39530f1", "charityId": "4b6047c8-b71a-f8e1-4a1f-7b00e09d19ab", "transactionId": "OTsb7v4QRGqR1Ci9xIcPEAsdfklnskfioPcK", "orderId": "b53bc97b-25b2-4116-927b-ba1f5fa3d809", "transactionStatus": "FAILURE" } ] } } ```