REST

recordRecurringTransaction

Record recurring transactions processed outside of Blackbaud Payment Services.
Client ServletServer ServletHTTP Methods SupportedRequires Authentication
None.SRDonationAPIPOSTNo.

Server API Syntax

https://secure2.convio.net/organization/site/SRDonationAPI?method=recordRecurringTransaction
&record_recurring_transaction=value

Usage Notes

This Server API method permits an external processor to record payments against one or more Sustaining Gifts or pledges.

API Administrator accounts that access this API must be assigned the Offline Donation API permission type with permission to "Add 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 record_recurring_transaction parameter in the format defined in the Donation API XML Schema:

<recordRecurringTransactionRequest xmlns="http://convio.com/crm/v1.0">
    <recurPledgeRecord>
        <seed_transaction_id>23118</seed_transaction_id>
        <recur_amount>5000</recur_amount>
        <recur_date>2010-05-30T09:30:10-06:00</recur_date>
        <recur_next_payment_date>2010-06-30<recur_next_payment_date>
        <recur_success>true</recur_success>
        <send_autoresponder>false</send_autoresponder>
        <process_lapsed>false</process_lapsed>
    </recur_next_payment_date></recur_next_payment_date></recurPledgeRecord>
    <recurPledgeRecord>
        <processor_ref_id>02RYXSPGD7WD4</processor_ref_id>
        <recur_amount>7500</recur_amount>
    </recurPledgeRecord>
</recordRecurringTransactionRequest>

Callers can specify up to 200 transactions per call. For each payment transaction, the caller must specify a unique identifier for the initial payment transaction in the series: either seed_transaction_id or processor_ref_id, and the recur_amount, the amount of the transaction in the smallest denomination (cents). Optionally, the caller can specify other parameters as described below.

seed_transaction_id
Optional. The system's primary key of the initial payment record. Either this or processor_ref_id must be specified for each transaction.
Type: xsd:nonNegativeInteger
processor_ref_id
Optional. The payment processor's reference ID for the initial payment record. Either this or seed_transaction_id must be specified for each transaction.
Type: xsd:string
recur_amount
Required. Transaction value for this recurring payment in cents.
Type: xsd:integer
recur_date
Optional. Date on which the payment was processed. Default is the current server time.
Type: xsd:date
recur_next_payment_date
Optional. Expected date of next payment. Default is none.
Type: xsd:date
recur_success
Optional. Whether to record the transaction as a successful payment or a failed transaction. Default is true (successful).
Type: xsd:boolean
send_autoresponder
Optional. Whether to send an autoresponder email for this transaction to the constituent. Default is false.
Type: xsd:boolean
process_lapsed
Optional. Whether to process the pledge if it is in the lapsed state. Default is false.
Type: xsd:boolean

If there are structural errors in the request XML or if one of the transaction IDs cannot be found, no transactions will be processed and an error will be returned. If the XML request can be processed, a success or error result will be returned for each transaction. For example, a transaction posted against a pledge for which all the recurring payments have been made will return an error for the transaction, but will not interrupt processing of other transactions in the batch.

Server API Parameters

Common Server Parameters
See topic Common Parameters.
record_recurring_transaction
Required. XML document specifying the recurring transactions to record.
Type crm:recordRecurringTransactionList.

Response

See topic HTTP Status Codes.

XML response
<?xml version="1.0" encoding="UTF-8"?>
<recordRecurringTransactionResponse 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">
  <transactionRecordResult>
    <success>true</success>
    <seed_transaction_id>1001</seed_transaction_id>
    <processor_ref_id>T1001</processor_ref_id>
    <transaction_id>1021</transaction_id>
  </transactionRecordResult>
</recordRecurringTransactionResponse>
JSON response
JSON
{"recordRecurringTransactionResponse":{
  "transactionRecordResult":{
    "transaction_id":"1021",
    "processor_ref_id":"T1001",
    "success":"true",
    "seed_transaction_id":"1001"
  }
}}