REST

refundOfflineDonation

This method processes a refund of a donation by a constituent to a Donations 2 (not "Donation Classic") donation form.
Client ServletServer ServletHTTP Methods SupportedRequires Authentication
None.SRDonationAPIPOSTNo.

Server API Syntax

https://secure2.convio.net/organization/site/SRDonationAPI?method=refundOfflineDonation &api_key=value &v=value
[ &center_id=value ] [ &response_format=xml |json ] [ &source=value ] [ &sub_source=value ]
[ &suppress_response_codes=value ] &login_name=value &login_password=value  &refund_user_confirm_code=value
[ &refund_amount=value ] [ &send_auto_responder=value ]

Usage Notes

The addOfflineDonation and refundOfflineDonation methods record monetary transactions processed outside the Luminate OnlineĀ® system. These methods provide only Server APIs and are accessible only to allow-listed servers. You must create an API Administrator account to call these methods and assign it to an Administrative Security Group having appropriate permissions of the "Offline Donation API" permission type. The built-in "API Administrators" group does not have "Offline Donation API" permissions by default. If these APIs will be used by a third-party payment processor to record transactions on your site, you should limit the permissions on the accounts you create for that purpose, and not grant additional permissions by assigning these accounts to the "API Administrators" group.

This method is used to fully or partially refund offline donation transactions logged through the addOfflineDonation method.

Use the refund_user_confirm_code parameter returned in the addOfflineDonation method.

Restrictions

Because a third-party service provider may implement this API for multiple clients, you should strictly limit the permissions of the API Administrator account that has access to this API.

API Administrator accounts that access this API must be assigned the Offline Donation API permission type with permission to "Add and Refund Offline Donations via API".

Any given API Administrator account is restricted to only refunding the offline transactions added through the addOfflineDonation method by the same account. An API user may not fully or partially refund transactions created online through the donate method, or transactions created by another Administrative user, API user, or constituent.

An API user may not refund more than the initial transaction value. The optional refund_amount is used to specify the dollar amount to refund. If the value specified is less than the current transaction value a partial refund for the amount specified is processed. If the refund_amount parameter value is not specified, is equal to 0, or is equal to the current transaction value a full refund is processed.

Error Responses

For common API errors such as authentication errors, the common error response is returned. An XML example:

<errorResponse
  xmlns="http://convio.com/crm/v1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd">
    <code>2</code>
    <message>Incorrect API key.  Verify that the value of the parameter api_key matches the value of the SDP
    CONVIO_API_KEY.</message>
</errorResponse>

A JSON example:

JSON
{"errorResponse":{
  "code": "2",
  "message": "Incorrect API key. Verify that the value of the parameter api_key matches the value of the SDP
  CONVIO_API_KEY.",
}}

For refund-specific errors, the "offlineRefundResponse" is returned and contains a list of the error messages. An XML example:

<offlineRefundResponse
  xmlns="http://convio.com/crm/v1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd">
  <errors>
    <code>108<code>
          <message>
            Error: Could not find transaction corresponding to user confirmation code '1-1001-1-1001-1200'
          </message>
          <reason>UNSPECIFIED</reason>
        </errors>
</offlineRefundResponse>

A JSON example:

JSON
{"offlineRefundResponse":
  {"errors":{
    "code":"108",
    "reason":"UNSPECIFIED",
    "message":"Error: Could not find transaction corresponding to user confirmation code '1-1001-1-1001-12000'"
  }}
}

Server API Parameters

Common Server Parameters
See topic Common Parameters.
refund_user_confirm_code
Required. Confirmation code of the transaction to be refunded
Type xsd:string.
refund_amount
Optional. Amount to be refunded. If refund_amount is less than the initial transaction value a partial refund will be applied. If refund_amount is the same as the initial transaction value, is 0, or is not specified a full refund will be applied.
Type crm:monetaryAmount.
send_auto_responder
Optional. Send auto responder informing donor about refund amount.
Type xsd:boolean.

Response

See topic HTTP Status Codes.

XML response
<?xml version="1.0" encoding="UTF-8"?>
<offlineRefundResponse
  xsi:schemaLocation="http://convio.com/crm/v1.0
  http://service.convio.net/xmlschema/crm.public.v1.xsd"
  xmlns="http://convio.com/crm/v1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <refund>
    <info>refund info</info>
    <is_full_refund>false</is_full_refund>
    <initial_amount>
      <decimal>100.00</decimal>
      <formatted>$100.00</formatted>
    </initial_amount>
    <refund_amount>
      <decimal>75.00</decimal>
      <formatted>$75.00</formatted>
    </refund_amount>
    <final_amount>
      <decimal>25.00</decimal>
      <formatted>$25.00</formatted>
    </final_amount>
  </refund>
</offlineRefundResponse>
JSON response
JSON
{"offlineRefundResponse":{
  "refund":{
    "is_full_refund":"false",
    "refund_amount":{
      "formatted":"$75.00",
      "decimal":"75.00"
    },
    "initial_amount":{
      "formatted":"$100.00",
      "decimal":"100.00"
    },
    "final_amount":{
      "formatted":"$25.00",
      "decimal":"25.00"
    },
    "info":"refund info"
  }
}}