This shows you the differences between two versions of the page.
developer:soap-1.6:methods:getcustomfields [2012/08/04 11:32] tem created |
developer:soap-1.6:methods:getcustomfields [2013/04/05 13:44] (current) kat |
||
---|---|---|---|
Line 1: | Line 1: | ||
<embed ..:contents/> | <embed ..:contents/> | ||
- | ====== getCustomerReport ====== | + | ====== getCustomFields ====== |
- | An alias of [[getreport]]. Pull a built-in or custom report from the merchant console. | + | Retrieve the custom fields for a specific gateway account. |
===== Description ===== | ===== Description ===== | ||
- | This method retrieves a report from the merchant console. Any reports, including custom reports, may be retrieved. The returned data is base 64 encoded. The format of the returned data can be HTML, comma separated (cvs), or tab separated (tab). | + | This method allows you to retrieve the custom fields for a specific gateway account. |
- | Names of built-in reports are prefaced with "CreditCard:", "Check:" or "Customer:". For example, to pull "Sales by Date" for credit cards, the "Report" parameter would be set to "CreditCard:Sales by Date." | + | Use this method to identify which custom fields exist. |
- | To pull a custom credit card or check report, prefix the name with "Custom:" or "CustomCheck:" For example, to pull a custom report titled "Recurring Declines" set the "Report" parameter to "Custom:Recurring Declines." Customer reports can only be created from within the merchant console. If none of the built-in or custom reports provide data required, see the custom search methods (ie searchTransactionsCustom) for more flexibility. | + | To retrieve the list of custom fields a token must me provided as an argument. The token will be used to identify the specific gateway account. |
- | + | ||
- | See also [[searchTransactionCustom]], [[getReport]], [[searchCustomersCustom]] | + | See also [[..:objects:CustomerObject]], [[..:objects:TransactionObject]] |
===== Syntax ===== | ===== Syntax ===== | ||
- | string **getCustomerReport** ( [[..:objects:ueSecurityToken]] Token, string Report, [[..:objects:FieldValue]] Options, string Format ) | + | [[..:objects:fieldvalue]] **getCustomFields** ( [[..:objects:ueSecurityToken]]) |
Line 25: | Line 23: | ||
^Type ^Name ^Description ^ | ^Type ^Name ^Description ^ | ||
- | |[[..:objects:ueSecurityToken]] |Token |Merchant security token: used to identify merchant and validate transaction.| | + | |[[..:objects:ueSecurityToken]] |Token |Merchant security token: used to identify merchant and retrieve the custom fields.| |
- | |string |Report |Name of report to retrieve.| | + | |
- | |[[..:objects:FieldValue]] |Options |Array of FieldValue objects specifying report options such as (StartDate and EndDate)| | + | |
- | |string |Format |Format of returned report data. Possible values are: html, csv, or tab.| | + | |
===== Return Value ===== | ===== Return Value ===== | ||
- | |string |Returns specified report data according to parameters set in search. | | + | |[[..:objects:FieldValue]] |Returns a FieldValue object containing the custom field and its name. | |
+ | ===== Exceptions ===== | ||
- | ===== Available Reports ===== | + | The following exceptions (errors) are applicable to this method. |
- | ^Credit Card Reports ^^ | + | ^Code ^Message ^Advice ^ |
- | |creditcard:errors by date |Credit card transactions resulting in errors, sorted by date | | + | |40470 |No custom fields defined. |Merchant has not configured any custom fields. They must log into the merchant console to [[merchant:console:settings_customfields|configure custom fields]]. | |
- | |creditcard:errors by source |Credit card transactions resulting in errors, sorted by source key | | + | |
- | |creditcard:errors by reason |Credit card transactions resulting in errors, sorted by reason | | + | ===== Examples ===== |
- | |creditcard:errors by user |Credit card transactions resulting in errors, sorted by user | | + | |
- | |creditcard:declines by date |Credit card transactions resulting in declines, sorted by date | | + | |
- | |creditcard:declines by source |Credit card transactions resulting in declines, sorted by source key | | + | ==== PHP ==== |
- | |creditcard:declines by reason |Credit card transactions resulting in declines, sorted by reason | | + | |
- | |creditcard:declines by user |Credit card transactions resulting in declines, sorted by user | | + | For directions on how to set up the WSDL link, create "$token" and "$client", go to [[..:howto:php|PHP Soap How-to]]. |
- | |creditcard:sales by date |Credit card transactions resulting in approval, sorted by date | | + | |
- | |creditcard:sales by source |Credit card transactions resulting in approval, sorted by source key | | + | <code php> |
- | |creditcard:sales by reason |Credit card transactions resulting in approval, sorted by reason | | + | <?php |
- | |creditcard:sales by user |Credit card transactions resulting in approval, sorted by user | | + | |
- | ^Check Reports ^^ | + | try { |
- | |check:Deposit Report |Check transactions sorted by estimated deposit date | | + | |
- | |check:All Transactions by Date|All Check transactions sorted by date (does not include errors) | | + | $res = $client->getCustomFields($token); |
- | |check:settled by date|Check transactions that have been marked as settled, sorted by date | | + | print_r($res); |
- | |check:settled by source|Check transactions that have been marked as settled, sorted by source | | + | } |
- | |check:settled by users|Check transactions that have been marked as settled, sorted by user | | + | |
- | |check:returns by date|Check transactions that have been marked as returned, sorted by date | | + | catch(SoapFault $e) { |
- | |check:returns by source|Check transactions that have been marked as returned, sorted by source | | + | |
- | |check:returns by reason|Check transactions that have been marked as returned, sorted by reason | | + | echo $e->getMessage(); |
- | |check:returns by user|Check transactions that have been marked as returned, sorted by user | | + | |
- | |check:declines by date|Check transactions were rejected by check processor, sorted by date | | + | } |
- | |check:declines by source|Check transactions were rejected by check processor, sorted by sourcekey | | + | |
- | |check:declines by reason|Check transactions were rejected by check processor, sorted by reason | | + | ?> |
- | |check:declines by user|Check transactions were rejected by check processor, sorted by user | | + | </code> |
- | ^Customer Reports ^^ | + | |
- | |customer:Pending Billing by Date |Customers that are pending for recurring billing, sorted by next bill date | | + | ==== .NET C# ==== |
- | |customer:Pending Billing by Source |Customers that are pending for recurring billing, sorted by Source | | + | <code c> |
- | |customer:Billing History by Date |Transactions results for recurring billing, sorted by billing date | | + | try |
- | |customer:Billing History by Source |Transactions results for recurring billing, sorted by Source | | + | { |
- | |customer:Expired Cards |Customers who have an expired credit card on file | | + | usaepay.FieldValue[] response = client.getCustomFields(token); |
- | |customer:Expiring before Next Billing |Customers that have a credit card that will expire before the next payment is scheduled to run | | + | MessageBox.Show(string.Concat(response.Length)); |
- | |customer:Expiring by Date Range |Customers that have a credit card expiring in the future | | + | |
+ | } | ||
+ | catch (Exception err) | ||
+ | { | ||
+ | MessageBox.Show(err.Message); | ||
+ | } | ||
+ | </code> | ||
+ | |||
+ | ==== VB ==== | ||
+ | |||
+ | <code vb> | ||
+ | Dim trace() As usaepay.FieldValue | ||
+ | |||
+ | trace = client.getCustomFields(token) | ||
+ | MsgBox(trace(0).Value) | ||
+ | </code> | ||
+ | ==== XML ==== | ||
+ | Request: | ||
+ | <code xml> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <SOAP-ENV:Envelope | ||
+ | xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" | ||
+ | xmlns:ns1="urn:usaepay" xmlns:xsd="http://www.w3.org/2001/XMLSchema" | ||
+ | xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
+ | xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" | ||
+ | SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> | ||
+ | <SOAP-ENV:Body> | ||
+ | <ns1:getCustomFields> | ||
+ | <Token xsi:type="ns1:ueSecurityToken"> | ||
+ | <ClientIP xsi:type="xsd:string">192.168.0.1</ClientIP> | ||
+ | <PinHash xsi:type="ns1:ueHash"> | ||
+ | <HashValue xsi:type="xsd:string">11ac55b0a0b59f8f028dbf85bc32266fa973dd0e</HashValue> | ||
+ | <Seed xsi:type="xsd:string">12678150211876663375</Seed> | ||
+ | <Type xsi:type="xsd:string">sha1</Type> | ||
+ | </PinHash> | ||
+ | <SourceKey xsi:type="xsd:string">HB4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey> | ||
+ | </Token> | ||
+ | </ns1:getCustomFields> | ||
+ | </SOAP-ENV:Body> | ||
+ | </SOAP-ENV:Envelope> | ||
+ | </code> | ||
+ | |||
+ | Response: | ||
+ | <code xml> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <SOAP-ENV:Envelope | ||
+ | xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" | ||
+ | xmlns:ns1="urn:usaepay" | ||
+ | xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" | ||
+ | xmlns:xsd="http://www.w3.org/2001/XMLSchema" | ||
+ | xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
+ | SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> | ||
+ | <SOAP-ENV:Body> | ||
+ | <ns1:getCustomFieldsResponse> | ||
+ | <getCustomFieldsReturn SOAP-ENC:arrayType="ns1:FieldValue[3]" xsi:type="ns1:FieldValueArray"> | ||
+ | <item xsi:type="ns1:FieldValue"> | ||
+ | <Field xsi:type="xsd:string">custom1</Field> | ||
+ | <Value xsi:type="xsd:string">Favorite Color</Value> | ||
+ | </item> | ||
+ | <item xsi:type="ns1:FieldValue"> | ||
+ | <Field xsi:type="xsd:string">custom2</Field> | ||
+ | <Value xsi:type="xsd:string">Favorite Movie</Value> | ||
+ | </item> | ||
+ | <item xsi:type="ns1:FieldValue"> | ||
+ | <Field xsi:type="xsd:string">custom3</Field> | ||
+ | <Value xsi:type="xsd:string">Favorite Icecream</Value> | ||
+ | </item> | ||
+ | </getCustomFieldsReturn> | ||
+ | </ns1:getCustomFieldsResponse> | ||
+ | </SOAP-ENV:Body> | ||
+ | </SOAP-ENV:Envelope> | ||
+ | </code> | ||
Line 78: | Line 144: | ||
^Version ^Change ^ | ^Version ^Change ^ | ||
- | |[[developer:soap-1.3:methods:getcustomfields|1.3]] | Method added in this release | | + | |1.3 | Method added in this release | |