In This Article:

    Offline Donations

    In This Article:

      This API enables add and update functionality for offline donations. Offline donations can be classified as those donations that were captured/processed by a system other than the Salsa Online/CRM system. These donations can be added to include them in the Online dashboard, reports, and segmentation functionality as well as the equivalent functionality in CRM system.

      Note: Donations added via the API cannot be deleted. This is due to the number of places where this data is propagated. They can only be zeroed out or refunded. 

      Method End Point Detail
      POST /api/integration/ext/v1/offlineDonations Adds or updates the provided offline donation


      Note:
      All calls listed below require that the API token be sent in the HTTP header using the parameter name authToken=<your_auth_token>

      Adding/Updating Offline Donations

      Adding as well as updating supporter is performed via the following endpoint:

      PUT  /api/integration/ext/v1/offlineDonations

      • You must include your api token with within an HTTP header parameter named authToken

       The following table details the attributes of an offline donation:

      Field Description Detail Required
      type The type of the transaction

      Must be one of the following:

      • CHARGE

      • REFUND - can only be specified if there is a corresponding charge for the same gateway transactionId

      Yes
      date Date of the transaction ISO_8601 formatted String with a GMT timezone(E.g. 2018-02-20T16:44:28.231Z) Yes
      amount Amount of the transaction Any non-negative value up to 10000000 Yes
      gatewayTransactionId Unique ID of the transaction

      The unique id of the transaction up to 32 characters. This id will be used for determining if an add or update is to be performed and is also used to associate a refund transaction with its corresponding charge.

      Yes
      supporter Details of the person who performed the donation

      This can be the full details of the supporter which will be added or updated - the details of the fields as well as what is required can be found here.

      OR...

      If the supporter is already known to exist within the Online system, an association only supporter object can be provided instead of the full supporter detail. The following properties are required.

      • readOnly = true - to instruct the API that the supporter should be looked up instead of inserted or updated-- AND one or more of the following --

      • supporterId - the UUID of the supporter from the Online system

      • externalSystemId - the external id of the supporter
      • contacts - the email contact of the supporter
      Yes
      accountType; Type of the account used for the donation

      Must be one of the following:

      • CREDIT_CARD

      • ECHECK
      no
      accountNumber Account number Up to 32 characters no
      accountExpiration Date of the account expiration ISO_8601 formatted String with a GMT timezone (E.g. 2018-02-20T16:44:28.231Z) no

      accountProvider

      Name of the account provided Up to 64 characters no
      fund Fund name to associate the Donation Must be defined within the Online system no
      campaign Campaign name to associate the Donation Must be defined within the Online system no
      appeal Appeal name to associate the Donation Must be defined within the Online system no
      dedicationType  

      Must be one of:

      • IN_HONOR_OF
      • IN_MEMORY_OF

      no
      designation Where the funds for the donation should be allocated Up to 256 characters no
      dedication Details of the dedication Up to 256 characters no
      notify Instructions for notifying another person/entity external to the system Up to 1024 characters no
      deductibleAmount Amount which the supporter may deduct from taxes Any non-negative value less than or equal to the Amount no
      feesPaid Any fees which the supporter may have paid Any non-negative value less than or equal to the Amount no
      gatewayAuthorizationCode Result code provided by a payment gateway Up to 32 characters no
      activityFormId Id of an Online form(Activity) to associate the donation The UUID of the online form. no
      activityFormName Name of the form which this donation was entered. If no activityFormId is provided, then the literal provided in the activityFormName field will remain. If a valid activityFormId is provided, then the activityFormName field will be ignored. no
      customFieldValues List of activity custom fields

      The custom fields must already be defined within the online system and must be Activity custom fields that are either General or Fundraising.

      See the following page for more information regarding custom fields, click here.

       

       

      no
      activityId ID of the activity which contains the Offline Transaction(s) associated with the gatewayTransactionId This is the ID that can be used to get the offline transaction data via the Salsa Online Activity endpoints. ready only

      result

      Result of an operation 16 characters

      Will be one of...

      • ADDED - the provided donation was added to the system
      • UPDATED - the provided donation was updated
      • VALIDATION_ERROR - indicates if a validation error exists for the provided data
      • SYSTEM_ERROR - indicates if an unrecoverable occurs on the Salsa Online System
      • NOT_FOUND - the specified donation or supporter was not found
      • NOT_ALLOWED - if the requested operation could not be performed.

       

      Supported Use Cases

      Offline donations are uniquely defined within Salsa Online using the combination of the type and gatewayTransactionId. The following examples illustrate the various use cases supported by the API.

      Adding a New Donation

      Note: The gateway transaction Id must be unique.

      {"payload":{
        "donations":[
            {"accountType":"CREDIT_CARD","accountNumber":"123456789","accountExpiration":"2018-02-20T16:44:28.231Z",
              "accountProvider":"USA Bank","fund":"fund1","campaign":"campaign1","appeal":"appeal1","dedicationType":"IN_MEMORY_OF",
              "dedication":"In memory of wounded warriors","type":"CHARGE","date":"2015-09-04T16:44:28.231Z","amount":50.0,"deductibleAmount":0.0,
              "feesPaid":0.0,"gatewayTransactionId":"1519145068231","gatewayAuthorizationCode":"success","activityFormName":"Spring Donation",
              "customFieldValues":[
                {"name":"Activity Custom field 1","value":"Value"},
                {"name":"Activity Custom field 2","value":"Value"},
                {"name":"Activity Custom field 3","value":"Value"}
              ],
              "supporter":{"title":"Mr","firstName":"John","middleName":"James","lastName":"Smith","suffix":"Jr.",
                  "dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE","externalSystemId":"96548",
                  "address":{"addressLine1":"123 Main St","addressLine2":"Suite 200","city":"Anytown","state":"NY","postalCode":"10001","county":"New York","country":"US"},
                  "contacts":[
                     {"type":"EMAIL","value":"email@mail.com","status":"OPT_IN"}
                  ],
                  "customFieldValues":[
                    {"name":"Custom field 2","value":"Value"},
                    {"name":"Custom field 1","value":"Value"},
                    {"name":"Custom field 0","value":"Value"}
                  ]
              }
            }
          ]
        }
      }
      
       
       

      Updating an Existing Donation

      Note: The gateway transaction ID must exist and the payload must be holistic (partial updates are not allowed).

      // update the amount to 500 and remove the custom fields
      {"payload":{
        "donations":[
            {"accountType":"CREDIT_CARD","accountNumber":"123456789","accountExpiration":"2018-02-20T16:44:28.231Z",
              "accountProvider":"USA Bank","fund":"fund1","campaign":"campaign1","appeal":"appeal1","dedicationType":"IN_MEMORY_OF",
              "dedication":"In memory of wounded warriors","type":"CHARGE","date":"2015-09-04T16:44:28.231Z","amount":500.0,"deductibleAmount":0.0,
              "feesPaid":0.0,"gatewayTransactionId":"1519145068231","gatewayAuthorizationCode":"success","activityFormName":"Spring Donation",
              "supporter":{"title":"Mr","firstName":"John","middleName":"James","lastName":"Smith","suffix":"Jr.",
                  "dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE","externalSystemId":"96548",
                  "address":{"addressLine1":"123 Main St","addressLine2":"Suite 200","city":"Anytown","state":"NY","postalCode":"10001","county":"New York","country":"US"},
                  "contacts":[
                     {"type":"EMAIL","value":"email@mail.com","status":"OPT_IN"}
                  ]
              }
            }
          ]
        }
      }
      

       

      Submitting a Payload  Where a Supporter Update Is Not Needed 

      {"payload":{
        "donations":[
            {"accountType":"CREDIT_CARD","accountNumber":"123456789","accountExpiration":"2018-02-20T16:44:28.231Z",
              "accountProvider":"USA Bank","fund":"fund1","campaign":"campaign1","appeal":"appeal1","dedicationType":"IN_MEMORY_OF",
              "dedication":"In memory of wounded warriors","type":"CHARGE","date":"2015-09-04T16:44:28.231Z","amount":50.0,"deductibleAmount":0.0,
              "feesPaid":0.0,"gatewayTransactionId":"1519145068231","gatewayAuthorizationCode":"success","activityFormName":"Spring Donation",
              "customFieldValues":[
                {"name":"Activity Custom field 1","value":"Value"},
                {"name":"Activity Custom field 2","value":"Value"},
                {"name":"Activity Custom field 3","value":"Value"}
              ],
      		// associate the supporter by via finding them by one of the following ids 
              "supporter":{"readOnly":"true","externalSystemId":"96548", "supporterId":"29BB490D-4EEF-4BB5-838A-1A8216526827",
                  "contacts":[
                      {"type":"EMAIL","value":"email@mail.com"}
                  ]
              }
            }
          ]
        }
      }

       

      Marking an Existing Donation as "Refunded" 

      Refund operations are a complete reversal of a charge. (Note: Partial refunds are not supported at this time.)

      // only the following fields are supported for a refund and a charge record must exist for the provided gateway id
      {"payload": {
      		"donations": [{
      			"gatewayTransactionId": "1519145068231",
      			"type": "REFUND",
      			"amount": 500.0,
      			"date": "2015-09-04T16:44:28.231Z",
      			"gatewayAuthorizationCode": "success",
      			"supporter": {
      				"readOnly": "true",
      				"externalSystemId": "96548",
      				"supporterId": "29BB490D-4EEF-4BB5-838A-1A8216526827",
      				"contacts": [{
      					"type": "EMAIL",
      					"value": "email@mail.com"
      				}]
      			}
      		}]
      	}
      }

       

      Response

      All responses will always contain what was provided within the call. Additionally, each returned object will contain any new internal identifiers (for example, activityId) as well as the status of the call. The details of various validation errors, as well as system errors, can be found here

      Valid Submission

      {"payload":{
        "donations":[
            {"activityId":"732B5F15-C7E4-4EE7-9202-C5B79CDD90AF", "result":"ADDED","accountType":"CREDIT_CARD","accountNumber":"123456789","accountExpiration":"2018-02-20T16:44:28.231Z",
              "accountProvider":"USA Bank","fund":"fund1","campaign":"campaign1","appeal":"appeal1","dedicationType":"IN_MEMORY_OF",
              "dedication":"In memory of wounded warriors","type":"CHARGE","date":"2015-09-04T16:44:28.231Z","amount":50.0,"deductibleAmount":0.0,
              "feesPaid":0.0,"gatewayTransactionId":"1519145068231","gatewayAuthorizationCode":"success","activityFormName":"Spring Donation",
              "customFieldValues":[
                {"name":"Activity Custom field 1","value":"Value"},
                {"name":"Activity Custom field 2","value":"Value"},
                {"name":"Activity Custom field 3","value":"Value"}
              ],
              "supporter":{"supporterId":"732B5F15-C7E4-4EE7-9202-C5B79CDD90AF", "result":"ADDED", "title":"Mr","firstName":"John","middleName":"James","lastName":"Smith","suffix":"Jr.",
                  "dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE","externalSystemId":"96548",
                  "address":{"addressLine1":"123 Main St","addressLine2":"Suite 200","city":"Anytown","state":"NY","postalCode":"10001","county":"New York","country":"US"},
                  "contacts":[
                     {"type":"EMAIL","value":"email@mail.com","status":"OPT_IN"}
                  ],
                  "customFieldValues":[
                    {"name":"Custom field 2","value":"Value"},
                    {"name":"Custom field 1","value":"Value"},
                    {"name":"Custom field 0","value":"Value"}
                  ]
              }
            }
          ]
        }
      }
      

       

      Invalid Submission 

      {
          "id": "058ed9d5-4ba4-48bf-b33c-21f18f491a00",
          "timestamp": "2018-02-20T18:56:14.184Z",
          "header": {
              "processingTime": 103,
              "serverId": "server1"
          },
          "payload": {
              "donations": [
                  {
                    "errors": [
                          {"id": "8d285a78-def2-48af-9237-8e225de4f9b3","code": 0,"message": "Validation errors","fieldName": "supporter"},
                          {"id": "92c5d213-a4b4-4365-bb02-954a0ef7dbbf","code": 2011,"message": "The value provided is invalid for this field","fieldName": "fund"},
                          {"id": "a2a17284-7be8-4290-a00d-eb3a67c94e33","code": 2011,"message": "The value provided is invalid for this field","fieldName": "campaign"},
                          {"id": "4c60162f-a9fa-4208-b55c-b47c4f5c3fcb","code": 2011,"message": "The value provided is invalid for this field","fieldName": "appeal"}
                      ],
                      "activityId": "732b5f15-c7e4-4ee7-9202-c5b79cdd90af","accountType": "CREDIT_CARD","accountNumber": "123456789",
                      "accountExpiration": "2018-02-20T16:44:28.231Z","accountProvider": "USA Bank","fund": "fund1","campaign": "campaign1","appeal": "appeal1",
                      "dedicationType": "IN_MEMORY_OF","dedication": "In memory of wounded warriors","type": "CHARGE","date": "2015-09-04T16:44:28.231Z",
                      "amount": 50,"deductibleAmount": 0,"feesPaid": 0,"gatewayTransactionId": "1519145068231","gatewayAuthorizationCode": "success",
                      "activityFormName": "Spring Donation",
                      "supporter": {"readOnly": true,"supporterId": "732b5f15-c7e4-4ee7-9202-c5b79cdd90af","externalSystemId": "96548",
                          "contacts": [
                            {"type": "EMAIL","value": "email@mail.com","status": "OPT_IN"}
                          ],
                          "result": "NOT_FOUND"
                      },
                      "result": "VALIDATION_ERROR"
                  }
              ],
              "count": 1
          }
      }

       

      Was this article helpful?
      0 out of 0 found this helpful
      Have more questions? Submit a request

      Comments

      0 comments

      Please sign in to leave a comment.