refundTransaction

This method processes and/or records refunds for transactions that were processed through COM.

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

Server API Syntax

https://secure2.convio.net/organization/site/SRDonationAPI?method=refundTransaction & api_key =value & login_name =value & login_password =value & v =value & refund_transaction_request =value

Usage Notes

This Server API method permits an external processor to record refunds for one or more transactions and optionally request that Luminate Online process the refunds through its payment gateway.

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". This permission is not assigned to the built-in "API Administrators" group by default.

Input data is passed url-encoded as the value of the refund_request parameter in the following format (the format is defined in the Donation API XML Schema):

<refundRequest xmlns="http://convio.com/crm/v1.0">
      <donRefundInfoList>
        <donRefundInfo>
          <transaction_id>5579</transaction_id>
          <processor_transaction_id>02RYXSPGD7WD4</processor_transaction_id>
          <user_confirmation_code>709-1201-1-5470-5579</user_confirmation_code>
          <process_transaction>false</process_transaction>
          <refund_type>full</refund_type>
          <send_autoresponder>false</send_autoresponder>
          <refund_amount>10000</refund_amount>
        </donRefundInfo>
        <donRefundInfo>
          <user_confirmation_code>709-1201-1-4215-5508</user_confirmation_code>
        </donRefundInfo>
      <donRefundInfoList>
      <trRefundInfoList>
        <trRefundInfo>
          <transaction_id>5510</transaction_id>
          <processor_transaction_id>02MCM1XXV1ID1</processor_transaction_id>
          <user_confirmation_code>709-1201-1-0258-5510</user_confirmation_code>
          <process_transaction>false</process_transaction>
          <refund_type>partial</refund_type>
          <send_autoresponder>false</send_autoresponder>
          <regRefundDataList>
            <regRefundData>
              <registration_id>1001</registration_id>
              <reg_refund_amount>1000</reg_refund_amount>
              <gift_refund_amount>1300</gift_refund_amount>
            </regRefundData>
          </regRefundDataList>
        </trRefundInfo>
        <trRefundInfo>
          <transaction_id>5511</transaction_id>
          <refund_type>full</refund_type>
        </trRefundInfo>
      </trRefundInfoList>
      <pfRefundInfoList>
        <pfRefundInfo>
          <transaction_id>5422</transaction_id>
          <processor_transaction_id>02LCV1DGC0WX1</processor_transaction_id>
          <user_confirmation_code>709-1201-1-3532-5422</user_confirmation_code>
          <process_transaction>false</process_transaction>
          <refund_type>partial</refund_type>
          <send_autoresponder>false</send_autoresponder>
          <gift_refund_amount>10000</gift_refund_amount>
        </pfRefundInfo>
        <pfRefundInfo>
          <user_confirmation_code>709-1201-1-9872-5429</user_confirmation_code>
        </pfRefundInfo>
      </pfRefundInfoList>
      <ticketRefundInfoList>
        <ticketRefundInfo>
          <transaction_id>5589</transaction_id>
          <processor_transaction_id>01PNXSPGC8QA5</processor_transaction_id>
          <user_confirmation_code>709-1201-1-5470-5589</user_confirmation_code>
          <process_transaction>false</process_transaction>
          <refund_type>partial</refund_type>
          <send_autoresponder>false</send_autoresponder>
          <gift_refund_amount>10000</gift_refund_amount>
          <cancel_all_tickets>false</cancel_all_tickets>
          <ticket_refund_item>
            <ticket_class_id>101</ticket_class_id>
            <ticket_refund_amount>6500</ticket_refund_amount>
            <num_of_tickets>1<num_of_tickets>
          </ticket_refund_item>
        <ticketRefundInfo>
        <ticketRefundInfo>
          <transaction_id>5590</transaction_id>
          <cancel_all_tickets>true</cancel_all_tickets>
        <ticketRefundInfo>
      </ticketRefundInfoList>
      <ecommerceRefundInfoList>
        <ecommerceRefundInfo>
          <transaction_id>5599</transaction_id>
          <processor_transaction_id>02TBPXLBC4PC5</processor_transaction_id>
          <user_confirmation_code>709-1201-1-4815-5599</user_confirmation_code>
          <process_transaction>false</process_transaction>
          <refund_type>partial</refund_type>
          <send_autoresponder>false</send_autoresponder>
          <gift_refund_amount>10000</gift_refund_amount>
          <shipping_refund_amount>795</shipping_refund_amount>
          <refund_item_id>502</refund_item_id>
        </ecommerceRefundInfo>
        <ecommerceRefundInfo>
          <processor_transaction_id>02LWZAMGA9ID3</processor_transaction_id>
        </ecommerceRefundInfo>
    </refundRequest>

Callers can specify up to 200 transactions per API call. For each refund transaction, the caller must specify a unique identifier for the payment transaction to be refunded: one of transaction_id, processor_transaction_id, or user_confirmation_code.

Optionally, the caller can specify other parameters as described below. The following parameters are common to all transaction types:

transaction_id

Optional. The system's primary key identifying the transaction being refunded. For each transaction, you must supply one unique ID: transaction_id, processor_transaction_id, or user_confirmation_code.

Type: xsd:nonNegativeInteger

processor_transaction_id

Optional. The unique transaction identifier returned by the credit card processor. For each transaction, you must supply one unique ID.

Type: xsd:string

user_confirmation_code

Optional. The user confirmation code uniquely identifying the transaction to be refunded. For each transaction, you must supply one unique ID.

Type: xsd:string

process_transaction

Optional. Boolean flag indicating whether Luminate Online should attempt to process the refund transaction before recording it. Default is false.

Type: xsd:boolean

refund_type

Optional. Refund type. If you are refunding full amount, value should be "full" otherwise "partial". Default is "full". If you specify "partial," you must also specify at least one amount.

Type: xsd:string

Options: full, partial

send_autoresponder

Optional. Whether to send an autoresponder email for this transaction to the constituent. Default is false (do not send).

Type: xsd:boolean

The gift_refund_amount element may be used for Personal Fundraising <pfRefundInfo>, Ticketed Event <ticketRefundInfo>, and Ecommmerce Purchase <ecommerceRefundInfo> transaction types to specify a partial refund of an additional gift amount:

gift_refund_amount

Optional. The amount of the additional gift to be refunded in the smallest denomination (cents).

Type: xsd:nonNegativeInteger

The refund_amount element may be used for Donation <donRefundInfo>, TeamRaiser <trRefundInfo>, and Personal Fundraising <pfRefundInfo> transaction types to specify a partial refund:

refund_amount

Optional. The amount to be refunded in the smallest denomination (cents).

Type: xsd:nonNegativeInteger

For partial refunds of TeamRaiser <trRefundInfo> transaction types, you must specify either the refund_amount element or a <regRefundDataList> structure. The <regRefundDataList> structure can contain one or more <regRefundData> elements indicating registrations to be refunded. Note that refunding a registration fee does not cancel the constituent's registration for the event. Each <regRefundData> element can include the following information:

registration_id

Optional. Primary key of the associated team registration record.

Type: xsd:nonNegativeInteger

reg_refund_amount

Optional. The registration amount to refund (in cents).

Type: xsd:nonNegativeInteger

gift_refund_amount

Optional. The amount to be refunded of any additional gift made in conjunction with the registration (in cents).

Type: xsd:nonNegativeInteger

If TeamRaiser Upsells are configured for the TeamRaiser Event and included in the registration transaction, specify an <addOnRefundDataList> containing one or more <addOnRefundData> elements to identify each Upsell to refund with the following elements:

addon_id

Optional. Primary key of the associated Upsell record.

Type: xsd:nonNegativeIntegeraddon_name

Optional. Upsell name.

Type: xsd:string

addon_refund_amount

Optional. Upsell amount to refund (in cents).

Type: xsd:nonNegativeInteger

For Ticketed Event <ticketRefundInfo> transaction types, the following parameters also apply:

cancel_all_tickets

Optional. Whether or not to cancel all tickets purchased through the refunded transaction. Default is false.

Type: xsd:boolean

You also can refund individual tickets by listing them in one or more <ticket_refund_item> nodes:

ticket_class_id

The system's primary key of the ticket class.

Type: xsd:nonNegativeInteger

ticket_refund_amount

The amount to refund for tickets of this class (in cents).

Type: xsd:nonNegativeInteger

num_of_tickets

The number of tickets of this class to cancel.

Type: xsd:nonNegativeInteger

For Ecommerce Purchase <ecommerceRefundInfo> transaction types, the following parameters also apply:

shipping_refund_amount

Optional. The shipping amount to refund (in cents).

Type: xsd:nonNegativeInteger

refund_item_id

Optional. The system's primary key of the eCommerce item refunded. A transaction may specify more than one refund_item_id.

Type: xsd:nonNegativeInteger

Note: You may not use this API to refund the seed (initial) transaction in an active series of recurring payments if subsequent payments have been made. To refund a seed transaction, an administrator or the constituent must first cancel the recurring gift, see also cancelRecurringGift.

Server API Parameters

Common Server Parameters

See topic Common Parameters.

refund_transaction_request

Required. XML document specifying refund transactions to be processed and(or) recorded.

Type crm:refundRequest.

Response

See topic HTTP Status Codes.

XML response

<?xml version="1.0" encoding="UTF-8"?>
<refundResponse 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">
  <refundResultList>
    <refundResult>
      <full_refund>false</full_refund>
      <initial_amount>
        <decimal>2000</decimal>
        <formatted>$10.00</formatted>
      </initial_amount>
      <final_amount>
        <decimal>1000</decimal>
        <formatted>$10.00</formatted>
      </final_amount>
      <refund_amount>
        <decimal>1000</decimal>
        <formatted>$20.00</formatted>
      </refund_amount>
      <payment_processor_transaction_id>123</payment_processor_transaction_id>
      <payment_transaction_id>1000</payment_transaction_id>
      <refund_transaction_id>1001</refund_transaction_id>
      <success>true</success>
    </refundResult>
  </refundResultList>
</refundResponse>

JSON response

{"refundResponse":{"refundResultList":{"refundResult":{"payment_transaction_id":"1000","refund_transaction_id":"1001","full_refund":"false","final_amount":{"formatted":"$10.00","decimal":"1000"},"initial_amount":{"formatted":"$10.00","decimal":"2000"},"refund_amount":{"formatted":"$20.00","decimal":"1000"},"payment_processor_transaction_id":"123","success":"true"}}}}

Luminate Online

refundTransaction

Server API Syntax

Usage Notes

Server API Parameters

Response

Leave a Comment