====== Soap Interface Documentation ====== **Current Version: ** 1.1 (see [[soap#release_notes|release notes]] for more details about current and past versions) The Soap interface provides a collection of methods implementing a large portion of merchant and reseller functionality. ===== Getting Started ===== * [[developer:soap:howto:php|PHP]] * [[developer:soap:howto:vb|Visual Basic]] * [[developer:soap:howto:csharp|C#]] ===== Methods ===== ==== Transactions ==== | [[developer:soap:methods:runTransaction|runTransaction]] | Runs a transaction using the Transaction API. | | [[developer:soap:methods:runTransactionAPI|runTransactionAPI]] | Provides a Soap wrapper for the Transaction API. | | [[developer:soap:methods:runSale|runSale]] | Run a new sale (debit) transaction for credit cards. | | [[developer:soap:methods:runAuthOnly|runAuthOnly]] | Run a new authonly (debit) transaction for credit cards. | | [[developer:soap:methods:runCredit|runCredit]] | Run a credit transaction for credit cards. | | [[developer:soap:methods:runCheckSale|runCheckSale]] | Run a new sale (debit) transaction for checks. | | [[developer:soap:methods:runCheckCredit|runCheckCredit]] | Run a credit transaction for checks. | | [[developer:soap:methods:runQuickSale|runQuickSale]] | Run a sale based on the credit card or check details of a previous transaction. | | [[developer:soap:methods:runQuickCredit|runQuickCredit]] | Run a credit based on the credit card or check details of a previous transaction. | | [[developer:soap:methods:postAuth|postAuth]] | Post an offline authorization | | [[developer:soap:methods:captureTransaction|captureTransaction]] | Capture a queued transaction. | | [[developer:soap:methods:refundTransaction|refundTransaction]] | Refund a specific transaction. | | [[developer:soap:methods:overrideTransaction|overrideTransaction]] | Override a specific transaction. | | [[developer:soap:methods:voidTransaction|voidTransaction]] | Void a specific transaction. | | [[developer:soap:methods:getTransactionStatus|getTransactionStatus]] | Retrieve the current status of a specific transaction. | | [[developer:soap:methods:getTransaction|getTransaction]] | Retrieves all details of a specified transaction. | | [[developer:soap:methods:getTransactionCustom|getTransactionCustom]] | Retrieves only selected details of a specified transaction. | | [[developer:soap:methods:searchTransactions|searchTransactions]] | Search transactions and return full transaction records. | | [[developer:soap:methods:searchTransactionsCustom|searchTransactionsCustom]] | Search transactions and return only specific fields. | | [[developer:soap:methods:getTransactionReport|getTransactionReport]] | Pull a transaction report. | | [[developer:soap:methods:convertTranToCust|convertTranToCust]] | Convert a transaction data to a stored customer record. | ==== Batch Uploads ==== | [[developer:soap:methods:createBatchUpload|createBatchUpload]] | Post a new batch of transactions to the gateway for processing. | | [[developer:soap:methods:runBatchUpload|runBatchUpload]] | Resume processing a paused batch upload. | | [[developer:soap:methods:pauseBatchUpload|pauseBatchUpload]] | Pause a Batch Upload that is already running. | | [[developer:soap:methods:getBatchUploadStatus|getBatchUploadStatus]] | Retrieve the status of a currently running batch. | ==== Credit Card Batches ==== | [[developer:soap:methods:searchBatches]] | Search previously settled batches. | | [[developer:soap:methods:getBatchStatus]] | Retrieves the status of a batch specified by its BatchNum. | | [[developer:soap:methods:closeBatch]] | Close a batch specified by BatchNum. | | [[developer:soap:methods:getBatchTransactions]] | Retrieve transactions in the batch specified by BatchNum | ==== Customers ==== | [[developer:soap:methods:runCustomerTransaction|runCustomerTransaction]] | Run a transaction using payment data stored in the customer database. | | [[developer:soap:methods:enableCustomer|enableCustomer]] | Enable recurring billing for a customer specified by CustNum. | | [[developer:soap:methods:disableCustomer|disableCustomer]] | Disable the recurring billing for a customer specified by CustNum. | | [[developer:soap:methods:deleteCustomer|deleteCustomer]] | Delete the customer specified by CustNum. | | [[developer:soap:methods:searchCustomerID|searchCustomerID]] | Find a CustNum (assigned by the gateway) using a CustID (assigned by merchant). | | [[developer:soap:methods:getCustomer|getCustomer]] | Retrieve the customer details for a given CustNum. | | [[developer:soap:methods:searchCustomers|searchCustomers]] | Search for customers. | | [[developer:soap:methods:searchCustomersCustom|searchCustomersCustom]] | Search for customers, returning custom columns. | | [[developer:soap:methods:getCustomerHistory|getCustomerHistory]] | Pull details of all transactions run for CustNum. | | [[developer:soap:methods:addCustomer|addCustomer]] | Add a customer to your stored customer database. | | [[developer:soap:methods:addCustomerPaymentMethod|addCustomerPaymentMethod]] | Add a payment method for an existing customer. | | [[developer:soap:methods:deleteCustomerPaymentMethod|deleteCustomerPaymentMethod]] | Delete a payment method from an existing customer. | | [[developer:soap:methods:updateCustomer|updateCustomer]] | Replace all data for customer specified by CustNum. | | [[developer:soap:methods:quickUpdateCustomer|quickUpdateCustomer]] | Update customer data in selected fields only. | | [[developer:soap:methods:copyCustomer|copyCustomer]] | Copy customer from one merchant account to another. | | [[developer:soap:methods:moveCustomer|moveCustomer]] | Move customer from one merchant account to another. | ==== General Merchant Methods ==== | [[developer:soap:methods:getAccountDetails|getAccountDetails]] | Retrieves information about merchant account. | | [[developer:soap:methods:getSupportedCurrencies|getSupportedCurrencies]] | Retrieves an array of currencies supported by a merchant account. | | [[developer:soap:methods:currencyConversion|currencyConversion]] | Find currency conversion rate for a transaction amount. | | [[developer:soap:methods:bulkCurrencyConversion|bulkCurrencyConversion]] | Converts multiple amounts in a single method call. | ==== Reseller Methods ==== | [[developer:soap:methods:addMerchantApplication]] | Add a new merchant application to the system. | | [[developer:soap:methods:getMerchantApplicationStatus]] | Retrieve the status of a pending merchant application. | | [[developer:soap:methods:getMerchant]] | Retrieve details of a merchant's account. | | [[developer:soap:methods:updateMerchant]] | Update details in a merchant's account. | | [[developer:soap:methods:deleteMerchant]] | Request deletion of merchant account. | | [[developer:soap:methods:searchMerchants]] | Search active merchants. | | [[developer:soap:methods:getMerchantSummary]] | View summary of merchant activity. | ===== Objects ===== | [[developer:soap:objects:AccountDetails|AccountDetails]] | Contains all relevant data pertaining to a merchant account. | | [[developer:soap:objects:Address|Address]] | Contains customer contact information. | | [[developer:soap:objects:BatchStatus|BatchStatus]] | Contains information about a batch awaiting settlement. | | [[developer:soap:objects:BatchUploadStatus|BatchUploadStatus]] | Contains information on an uploaded batch. | | [[developer:soap:objects:CheckData|CheckData]] | Contains information for electronic check transactions. | | [[developer:soap:objects:CheckTrace|CheckTrace]] | Electronic check transaction tracking data. | | [[developer:soap:objects:CreditCardData|CreditCardData]] | This object contains credit card specific information for a transaction. | | [[developer:soap:objects:CurrencyConversion|CurrencyConversion]] | Contains the results of a currency conversion. | | [[developer:soap:objects:CurrencyObject|CurrencyObject]] | Describes a currency supported by the merchant's account. | | [[developer:soap:objects:CustomerObject|CustomerObject]] | Contains customer data. | | [[developer:soap:objects:CustomerSearchResult|CustomerSearchResult]] | Contains customer search data. | | [[developer:soap:objects:FieldValue|FieldValue]] | Generalized Field-Value Pair | | [[developer:soap:objects:MerchantApplicationObject|MerchantApplicationObject]] | Contains information for a new merchant application. | | [[developer:soap:objects:MerchantObject|MerchantObject]] | Contains contact information for an active merchant. | | [[developer:soap:objects:MerchantSearchResult|MerchantSearchResult]] | Contains the results of a merchant search. | | [[developer:soap:objects:MerchantSummaryObject|MerchantSummaryObject]] | Summary of merchant activity over a given time period. | | [[developer:soap:objects:PaymentMethod|PaymentMethod]] | Describes a customer payment method. | | [[developer:soap:objects:RecurringBilling|RecurringBilling]] | This object stores information relating to specific recurring billing cycles. | | [[developer:soap:objects:SearchParam|SearchParam]] | Used to create a unique search parameter. | | [[developer:soap:objects:TransactionDetail|TransactionDetail]] | Contains transaction specific data. | | [[developer:soap:objects:TransactionObject|TransactionObject]] | Contains all transaction data. | | [[developer:soap:objects:TransactionRequestObject|TransactionRequestObject]] | Used to run a new transaction. | | [[developer:soap:objects:TransactionResponse|TransactionResponse]] | Contains details on the result of a processed transaction. | | [[developer:soap:objects:TransactionSearchResult|TransactionSearchResult]] | Contains results of a transaction search. | | [[developer:soap:objects:ueHash|ueHash]] | Defines the properties of the hash used to validate a source key. | | [[developer:soap:objects:ueSecurityToken|ueSecurityToken]] | Defines a source key used to identify a merchant or reseller. | ===== Release Notes ===== ==== 1.1 ==== The following methods have been implemented: [[developer:soap:methods:copyCustomer]], and [[developer:soap:methods:moveCustomer]]. The following changes have been made in 1.1: * The DUKPT and Signature properties have been added to the [[developer:soap:objects:CreditCardData]] object * The Comments property have been added to the [[developer:soap:objects:TransactionDetail]] object ==== 1.0 ==== The following methods have been implemented: [[developer:soap:methods:convertTranToCust]], [[developer:soap:methods:deleteCustomerPaymentMethod]], [[developer:soap:methods:overrideTransaction]], [[developer:soap:methods:refundTransaction]], [[developer:soap:methods:runAuthOnly]], [[developer:soap:methods:runCheckCredit]], [[developer:soap:methods:runCheckSale]], [[developer:soap:methods:runQuickCredit]] and [[developer:soap:methods:searchCustomersCustom]]. The following changes have been made in 1.0: * [[developer:soap:objects:PaymentMethod]] object has been added to the [[developer:soap:objects:CustomerObject]] * [[developer:soap:methods:runAuthOnly]] method added - run a direct authonly transaction * [[developer:soap:methods:runCheckSale]] method added - run a sale transaction based on bank account rather than credit card information * [[developer:soap:methods:runCheckCredit]] method added - run a credit transaction based on bank account rather than credit card information * [[developer:soap:methods:runQuickCredit]] method added - run a credit based on the credit card details of a previous transaction * [[developer:soap:methods:refundTransaction]] method added - refund a specific transaction using the transaction ID * [[developer:soap:methods:overrideTransaction]] method added - override a specific transaction that has been flagged for manager approval (currently applies only to check transactions) * [[developer:soap:methods:convertTranToCust]] method added - convert the information from a specific transaction to stored customer data * [[developer:soap:methods:deleteCustomerPaymentMethod]] method implemented - delete a payment method from an existing customer account * [[developer:soap:methods:searchCustomersCustom]] method added - search customer records and return only specified fields * [[developer:soap:objects:checkData]] object modified to include AccountType property, denotes type of account being debited * [[developer:soap:objects:customerObject]] modified to include CustomFields parameter, Tax parameter, and PaymentMethods, and to remove CheckData and CreditCardData parameters * [[developer:soap:objects:transactionObject]] modified to include Response property - displays transaction result (approved, declined, error, etc.) * [[developer:soap:objects:transactionResponse]] object modified to include Status and Status Code properties - display description of status and single character transaction status code respectively ==== BETA 6 ==== This is the last beta before our 1.0 release. All methods have now been implemented with the exception of [[developer:soap:methods:addCustomerPaymentMethod]] and [[developer:soap:methods:deleteCustomerPaymentMethod]], which have limited functionality within this beta release. The following changes have been made in Beta6: * All unimplemented methods, such as [[developer:soap:methods:runSale]], have been completed. * runOldApi has been replaced with [[developer:soap:methods:runTransaction]]. * [[developer:soap:methods:getAccountDetails]] has been added to allow automatic retrieval of merchant account capabilities. * Multi Currency methods have been added: [[developer:soap:methods:currencyConversion]], [[developer:soap:methods:bulkCurrencyConversion]], and [[developer:soap:methods:getSupportedCurrencies]]. * [[developer:soap:objects:TransactionResponse]] has been updated to include new result variables such as isDuplicate. * [[developer:soap:methods:getTransactionCustom]] method has been added to allow quick and efficient retrieval of any transaction field. * [[developer:soap:methods:searchTransactionsCustom]] method has been added to allow a customizable list of transaction fields to be returned. * [[developer:soap:methods:getTransactionReport]] method has been added to allow the retrieval of any reports available in the merchant console. * runCustomerSale has been renamed [[developer:soap:methods:runCustomerTransaction]]. * [[developer:soap:methods:runCustomerTransaction]], and [[developer:soap:methods:addCustomer]] have been altered to support electronic check data. * All data types have been fully speced, all AnyTypes have been removed. * Unit testing is now complete for PHP5, VB, .Net v2, and Java NetBeans. ==== BETA 5 ==== The following methods have been implemented: [[developer:soap:methods:searchCustomers]], runCustomerSale, [[developer:soap:methods:addCustomer]], and [[developer:soap:methods:updateCustomer]]. The following new objects have been added: [[developer:soap:objects:CustomerSearchResult]], [[developer:soap:objects:CreditCardData]] & [[developer:soap:objects:CheckData]]. These new objects replace arrays and may break compatibility with beta4 on methods such as [[developer:soap:methods:getCustomer]]. The beta5 release also includes various bug fixes. ==== BETA 4 ==== This release rounds out support for most of the missing methods and improves compatibility with .NET. ==== BETA 3 ==== This release implements PinHash. Many methods now require that a pin is assigned to the source key and that the PinHash component of the SecurityToken is correctly filled out. If you are using a source key that does not have a pin assigned, you will have to log into the merchant console and edit the key. ==== BETA 2 ==== Please be aware that the transaction methods ([[developer:soap:methods:runSale]], [[developer:soap:methods:runCredit]], etc) are currently disabled. We are implementing a new fraud module stack and these methods are tied to the new stack. Once the new fraud system is released, these methods will be enabled. In the meantime, please use the runOldAPI function for transaction processing.