Client Servlet	Server Servlet	HTTP Methods Supported	Requires Authentication
None.	SRDonationAPI	POST	No.

Usage Notes

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

It must reference a previously-created offline donation by that transaction's confirmation code. which is returned in the response from the addOfflineDonation method. The confirmation code is passed to refundOfflineDonation via the refund_user_confirm_code parameter.

Restrictions

Because a third-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:

{"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:

{"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

{"offlineRefundResponse":{"refund":{"is_full_refund":"false","final_amount":{"formatted":"$25.00","decimal":"25.00"},"initial_amount":{"formatted":"$100.00","decimal":"100.00"},"refund_amount":{"formatted":"$75.00","decimal":"75.00"},"info":"refund info"}}}