Web services

From Complete Cyclos documentation wiki
Jump to: navigation, search

This page is for Cyclos 3.7. Interfaces have changed slightly since 3.6.1


Cyclos offers several web services, targeted for integration with external applications, using Apache CXF.

Configuring Web service clients

In order to use web services, there are some concepts which should be understood in Cyclos and some configurations to be done. It is always needed to register a web service client through the Settings > Service clients menu. The client contains the following configuration:

  • Address: IP address, IP address range (in form 200.10.3.[1-50]) or or hostname (to allow dynamic ip resolution). This will be used to identify the client machine. As production servers normally use HTTPS, this is a strong mechanism to identify clients.
  • Username / password: Using an http user / password is possible, but not much for security issues (it's not possible to forge IP addresses in HTTPS), but to identify multiple clients in a same IP machine. For those who feel better using them, it's very easy to setup. When set, client requests should pass the user / password using HTTP BASIC authentication (which is sent plain, but again, HTTPS should be used, making this a strong method).
  • Channel: Channel is not needed for the most simple web services - search advertisements and members. Other operations need a channel. From the built-in channels present in Cyclos, only WebShop may be used. Also, custom channels may be used. Channels hold important configuration, like how to identify users (internally called user principal) - which may be username, card number or any of them and how to authenticate users - login password, transaction password, pin or card security code.
  • Member: Clients restricted to a member will enforce that requests from that client will be always related to the given member: payments may be only from that member or to that member (authenticating the payer with his credentials), account information only for that member's account and so on.
  • Permissions: Here, depending on the selected channels, there will be permissions for that service client.

Writing client applications

Here are some general guidelines on how to write client applications to access web services in Cyclos. Take a look at the code samples section for some examples.

Java client

It is very easy to create Java clients for web services, since Apache CXF allows creating transparent proxies using Java interfaces, similar to RMI.
In order to create the client, there are several required library files (jars). The first one is located at <cyclos download dir>/ws/cyclos_xxx_ws_client.jar, and is available on the main distribution package. Others dependencies are also required on runtime. They are available in <cyclos download dir>/web/WEB-INF/lib. They are:

  • commons-lang-xxx.jar
  • cxf-xxx.jar
  • jaxb-impl-xxx.jar
  • wsdl4j-xxx.jar
  • xml-resolver-xxx.jar
  • XmlSchema-xxx.jar

The client application should use the CyclosWebServicesClientFactory class, which may be instantiated with the cyclos root url as constructor argument or it may be set through setter method. Also, when the Service Client registered in Cyclos uses an username / password, they can be set either as constructor arguments or setter methods. Then, it provides two ways to retrieve service interface proxies:

  • getAccessWebService(), getAccountWebService(), getAdWebService(), getFieldWebService(), getMemberWebService(), getPaymentWebService(), getWebShopWebService(): return proxies for specific web services
  • proxyFor(Class): Given a web service interface, the result is a proxy for it

The CyclosWebServicesClientFactory should be instantiated only once and reused between calls. It is thread safe.

Clients in other languages

Many web sites are written in other languages, such as PHP, Ruby, Python, .NET... Those languages often provide a SOAP library. The problem is that some of them don't generate compatible XML with the specification, and some interoperability problems may arise. However PHP, which is the most widely used language for dynamic sites, have a native SOAP client since version 5, which plays well with Cyclos. All WSDLs use the document style for calls, and all methods results have a single element named 'return'.

Code samples

Here are some code samples for web service clients:

Perform payment (java)
Random advertisements (php)
Complete advertisements search form / result (php)
WebShop payment (php)


Available web services

There are several web services in cyclos. A list can be seen at the address: <cyclos root url>/services.

Every method may raise specific fault codes. However, the following codes may be raised by several methods:

  • application-offline: There's an administrative task which may set the application offline. If so, when attempting to perform any web services operation, this fault will be raised.
  • secure-access-required: When HTTPS is used, all web services access should also be done by HTTPS. Any attempt to use a non-secure (HTTP) access will raise this fault.
  • unauthorized-access: Attempt to invoke a web service without a corresponding web service client registered in Cyclos, or the client is trying to invoke a method it doesn't have permission for.
  • unexpected-error: An unexpected error was generated.


Payment

Payment web service allows external applications to generate payments under Cyclos. A typical use case would be a POS (Point-Of-Sale) application installed in a member's office or a website from the organization itself that uses Cyclos as a backend and generates the payments directly.

To perform payments through this web service, a channel should be registered in Cyclos, granted to member groups and members should choose to participate in this channel. It's possible to set by group the default selected channels for new members also.

The most generally used method is doPayment(PaymentParameters), which performs a single payment directly. When the client is restricted to a member, the payment is either from an arbitrary member (with his credentials) to the restricted member, or from the restricted member to other members. The former is the common case for integrating with existing payment systems. When the client is not restricted, then both from and to member should be passed, and no credential is used. A variation of this method is doBulkPayment(List<PaymentParameters>). This method perform several payments in the given sequence, under the same transaction (they are all guaranteed to succeed or fail atomically).

Another possible operation is a payment request. To do this, the registered channel in Cyclos needs to set the URL for a payment request web service, which is a web service implementing the PaymentRequestWebService interface provided in <cyclos mail download dir>/ws/cyclos_xxx_external_ws.jar. Then. a request may be sent using requestPaymentConfirmation(RequestPaymentParameters). A member may then confirm in another channel, which should then invoke confirmPayment(ConfirmPaymentParameters). This is a more advanced feature, and requires other web services to be implemented apart from Cyclos.

Available operations:

doPayment: Performs a single payment, returning the payment status. For clients restricted to a member, one of fromMember or toMember (or setting the toSystem flag) should be passed, with the other one assumed as the restricted member. In this case, when fromMember is used, his credentials should also be informed.

  • Input parameters:
    • fromMemberPrincipalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member performing the payment. Defaults to the channel's default.
    • fromMember (string): The principal (according to the fromMemberPrincipalType) of the member performing the payment. Optional: when the restricted to member and not specified will assume the restricted member). When not restricted, is required unless fromSystem is set to true.
    • fromSystem (boolean): Only used when performing payment from a system account by a client which is not restricted to a member.
    • toMemberPrincipalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member receiving the payment. Defaults to the channel's default.
    • toMember (string): The principal (according to the toMemberPrincipalType) of the member receiving the payment. Optional: when the restricted to member and not specified will assume the restricted member). When not restricted, is required unless toSystem is set to true.
    • toSystem (boolean): Only used when performing payment to a system account by a client which is not restricted to a member.
    • amount (decimal): The payment amount. Required.
    • currency: Either the currency symbol or identifier. When not set, uses the default account's currency for the actual member.
    • credentials (string): The payer member credentials. Required when the client is restricted to a member, otherwise optional (depends on client configuration).
    • description (string): The generated payment description. Optional, defaulting to the payment type description.
    • transferTypeId (integer): The payment type identifier. Optional, defaulting to the first payment type enabled to the given currency (or default if not specified) which is enabled to the service client's channel.
    • fromMemberFieldsToReturn (string): This field is optional and can appear any number of times. Specify in this field an internal member custom field name to retrieve it's value. If the resulting custom field has an empty value, it will not appear in the result. If the requested custom field doesn't belong to the fromMember, the entire operation will fail.
    • toMemberFieldsToReturn (string): This field is optional and can appear any number of times. Specify in this field an internal member custom field name to retrieve it's value. If the resulting custom field has an empty value, it will not appear in the result. If the requested custom field doesn't belong to the toMember, the entire operation will fail.
    • traceNumber: A (unique) client identifier that will be associated to the payment (useful if we want reverse it)
    • customValues (list of fieldValue): The custom field values for this payment. Each fieldValue contains the field internal name and the value.
  • Result:
    • status (enumerated): The payment status. May be one of:
      • PROCESSED: The payment was successfully processed
      • PENDING_AUTHORIZATION: The payment was created, but is awaiting authorization
      • INVALID_CREDENTIALS: Invalid credential was entered
      • BLOCKED_CREDENTIALS: The credential were blocked for exceeding allowed tries
      • INVALID_CHANNEL: The payment was being performed from a channel the member doesn't have access
      • INVALID_PARAMETERS: One or more parameters were invalid
      • NOT_ENOUGH_CREDITS: The payment couldn't be performed, because there was not enough amount on the source account
      • MAX_DAILY_AMOUNT_EXCEEDED: The payment couldn't be performed, because the maximum amount today has been exceeded
      • RECEIVER_UPPER_CREDIT_LIMIT_REACHED: The payment couldn't be performed, because the destination account would surpass it's upper credit limit
      • UNKNOWN_ERROR: Any other unexpected error will fall in this category
      • NOT_PERFORMED: In a bulk action, when a payment result in error, all next payments will have this status
    • transfer (AccountHistoryTransferVO): Contains data about the generated payment

There is a code sample for performing POS payments in a Java client: Web services/POS Payment.

doBulkPayment: Performs several payments, returning a payment status for each input parameter. Has the same input parameter as doPayment(), but in a collection. The result is also a collection, one for each input. It's guaranteed that the size of the result collection is the same as the inputs. Also, if one payment fails, there will be no attempts to perform next payments, they will all have NOT_PERFORMED as status. It is also possible that a payment fails some static validation. If this happens, the payments which fail will have a corresponding status, and the others will be NOT_PERFORMED (even previous ones). So, a possible way to check whether all payments were performed is to check the last status. If it is PROCESSED or PENDING_AUTHORIZATION, it means the bulk was successful.

  • Fault codes:
    • currently-unavailable: It was not possible to acquire required locks. The client should attempt the same operation again


simulatePayment: Simulates a payment. The input parameters are the same as doPayment(), but the result is only the payment status. No payment is actually performed.


requestPaymentConfirmation: Starts a payment request. The destination member should, using another (or the same) channel, accept this request and a payment is generated.

  • Parameters:
    • fromMemberPrincipalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member performing the payment. Defaults to the channel's default.
    • fromMember (string): The principal (according to the fromMemberPrincipalType) of the member performing the payment. Required.
    • toMemberPrincipalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member receiving the payment. Defaults to the channel's default.
    • toMember (string): The principal (according to the toMemberPrincipalType) of the member receiving the payment. Ignored when restricted to a member (assuming that member), required otherwise.
    • destinationChannel (string): The channel that a member is supposed to receive the payment request. It should be the internal name of a channel which supports payment requests, as explained above. Optional, defaulting to the current web service client's channel.
    • amount (decimal): The payment amount. Required.
    • currency: Either the currency symbol or identifier. When not set, uses the default account's currency for the actual member.
    • description (string): The generated payment description. Optional, defaulting to the payment type description.
  • Result:
    • requestStatus (enumerated): The status for the request itself. May be:
      • SUCCESS: The payment request was delivered to the member.
      • INVALID_MEMBER: The member which should receive the request is invalid for the operation.
      • SYSTEM_OFFLINE: The channel's backend is offline.
      • UNKNOWN_ERROR: There was an unknown error while sending the request.
    • paymentStatus (enumerated): The status of a payment simulation. Since accepting the request may involve costs (for example: SMS), a payment simulation is done. Only if the payment would be successfully processed, the request is sent. For possible values, see the doPayment operation.
    • ticket (string): The ticket used to accept the request by the member.


confirmPayment: Used to confirm a payment request, and should have a matching requestPaymentConfirmation previous invocation.

  • Parameters:
    • ticket (string): The same ticket returned from the requestPaymentConfirmation invocation. Required.
    • credentials (string): The credentials of the member performing the payment. Required.
  • Result: The same as the doPayment operation.


expireTicket: Then the user will not confirm the payment, a ticket expiration may be sent immediately using this method. Anyway, payment which are not confirmed within 1 hour are expired.

  • Parameters:
    • ticket (string): The ticket to expire. Required.
  • Result: A boolean flag indicating whether the ticket was really expired.


chargeback: Used to chargeback a processed (confirmed) payment a member has received.

  • Parameters:
    • transferId (integer): The identifier of the transfer being charged back
  • Result: An object containing the following properties:
  • status (enum): The result of the chargeback operation. May be:
    • SUCCESS: The chargeback / reverse was successful.
    • INVALID_PARAMETERS: Either the given transfer id or amount are invalid.
    • TRANSFER_NOT_FOUND: The transfer to chargedback / reverse was not found (e.g it had never entered to the system)
    • TRANSFER_CANNOT_BE_CHARGEDBACK: The transfer cannot be charged back / reversed. Normally it's because the maximum allowed time for chargeback / reverse has already passed.
    • TRANSFER_ALREADY_CHARGEDBACK: The given transfer was already charged back / reversed
  • originalTransfer (transfer): Contains details of the original transfer (only if status is SUCCESS or TRANSFER_ALREADY_CHARGEDBACK). For more details, check out the model data details.
  • chargebackTransfer (transfer): Contains details of the chargeback / reverse transfer (only if status is SUCCESS or TRANSFER_ALREADY_CHARGEDBACK). For more details, check out the model data details.


doBulkChargeback: Performs several chargebacks, returning a chargeback status for each identifier. Receives a collection of internal identifiers, of payments to be charged back. The result is also a collection, one for each input. It's guaranteed that the size of the result collection is the same as the inputs. Also, if one chargeback fails, there will be no attempts to perform next chargebacks, they will all have NOT_PERFORMED as status. It is also possible that a chargeback fails some static validation. If this happens, failed chargebacks will have a corresponding status, and the others will be NOT_PERFORMED (even previous ones). So, a possible way to check whether all chargebacks were performed is to check the last status. If it is SUCCESS, it means the bulk was successful.

  • Fault codes:
    • currently-unavailable: It was not possible to acquire required locks. The client should attempt the same operation again


reverse: Used to reverse a payment a member has received but there isn't a confirmation of the payment (if it was processed or not). The third party software that generates the payment can pass a unique number (tracenumber) with the payment. This number can be used to charge back a payment without having to search for the paymentID. The difference is that with a conventional chargeback the third party software needs to get the ID of the payment through a search in Cyclos. This is not necesary with a reverse, as tracenumber is generated by the third party software. The chargeback can be done directly without a search for the transaction.

  • Parameters:
    • traceNumber (string): A (unique) client identifier used to search for the transfer being reversed
  • Result: Same as chargeback operation.

doBulkReverse: Performs several reverses, returning a chargeback status for each identifier. Receives a collection of internal identifiers, of payments to be reversed. The result is also a collection, one for each input. It's guaranteed that the size of the result collection is the same as the inputs. Also, if one reverse fails, there will be no attempts to perform next reverses, they will all have NOT_PERFORMED as status. It is also possible that a reverse fails some static validation. If this happens, failed reverser will have a corresponding status, and the others will be NOT_PERFORMED (even previous ones). So, a possible way to check whether all reverser were performed is to check the last status. If it is SUCCESS, it means the bulk was successful.

  • Fault codes:
    • currently-unavailable: It was not possible to acquire required locks. The client should attempt the same operation again


WebShop

External web shops may allow their customers to pay with Cyclos units, and need tickets to do so. The tickets provide a secure mechanism where the web shop can define the transaction data and initiate the payment but does not have access to member authentication data and payment confirmation. In order to do this, both the shop client and the shop itself must have a Cyclos account.

The following flow would be applied for the client member to pay to the web shop member:

  1. The member client selects on the web shop to pay with Cyclos units;
  2. The web shop requests the Cyclos server to create a ticket, passing the transaction information, together with a return url;
  3. The web shop redirects the client into the Cyclos external payment page, passing as parameter the ticket id (<root>/do/webshop/payment?ticket=<ticket id>);
  4. The client types his username and password and confirms the payment;
  5. The Cyclos server validates the payment, and redirects the user back into the specified return url;
  6. The web shops queries Cyclos about that ticket id, and validates the response, and completes the transaction.

It is very important that the web shop validates the ticket, because the client may cancel the payment or do anything, at all.

Normally, each web shop would be registered as a Service Client in Cyclos under Settings > Service Clients. It is a good practice to restrict this client to the member who owns the web shop, so that all payments performed are guaranteed to go to that member.

Available operations:

  • generate: The generate operation returns the generated ticket identifier (String), and takes as argument an object, named params, containing the following parameters:
    • toUsername or toSystem: If the payment is targeted to a specific user (normally on web shops), then toUsername should be specified, containing the member login name. Otherwise, when the payment should be to system (for example, on a organization shop), then toSystem should be set to true. Required.
    • amount: The payment amount. If not specified, then the client member will be prompted. Althrough not required, the web shop will normally set, to force the amount to be correct.
    • currency: Either the currency symbol or identifier. When not set, uses the default account's currency for the actual member.
    • description: The payment description. If not set, will be the payment type description.
    • clientAddress: The IP address of the web shop client. Required.
    • returnUrl: The HTTP(s) URL where the user will be redirected to after completing the payment. Required.
  • get: Loads a specific ticket, getting the ticket identifier as parameter (the same returned from the generate operation), named ticket, and returns a ticket object.

There is a code sample for performing a WebShop payment in a PHP: Web services/WebShop payment.


Advertisements

Allow searching for advertisements. The organization site might find useful to publish on the institutional web site a list of recent advertisements published on Cyclos, or allow any user to search for advertisements. The advertisements web service allows such operations. The available operations are:

load: Given a numeric identifier named id, returns the details of an advertisement.

fullTextSearch: Searches for advertisements using a full text search technique, which is best suited when the user supplies keywords. The results are ordered by relevance, listing the best results first.

  • Parameters: Takes a single object names params, with the following attributes:
    • currentPage (number): The current query page, starting at zero. Defaults to 0.
    • pageSize (number): The number of records per page. Defaults to 10.
    • keywords (string): A text to search within the advertisement title or description, as well as member details.
    • status (enum): The advertisement publication status. May be ACTIVE, PERMANENT, SCHEDULED or EXPIRED. Defaults to ACTIVE.
    • categoryId (number): The internal identifier for the advertisement category.
    • since (timePeriod): The maximum time period since the ad publication date.
    • tradeType (enumeration): The advertisement trade type. May be OFFER (for ads offering a product / service), SEARCH (for ads searching for a product / service) or BOTH.
    • adFields (list of fieldValue): The advertisement custom field values. When searching for an enumerated field, the value must be the possible value id.
    • memberFields (list of fieldValue): The publisher custom field values. When searching for an enumerated field, the value must be the possible value id.
    • memberId (number): The publisher's identifier.
    • memberGroupIds (array of number): The publisher's group, allowing multiple groups to be specified.
    • memberGroupFilterIds (array of number): The publisher's group filter, allowing multiple group filters to be specified.
    • withImagesOnly (boolean): If set to true, only return ads with at least one image. Defaults to false
    • showAdFields (boolean): If set to true, return the advertisement custom field values. Defaults to false
    • showMemberFields (boolean): If set to true, return the publisher custom field values. Defaults to false
  • Result: A page of ads, containing the following attributes:
    • currentPage (integer): The current page in the search.
    • totalCount (integer): The total number of advertisements (not only those returned in the page).
    • ads (array of ad): Contains the details for each advertisement. For more details, refer to the model data details
  • Fault codes:
    • query-parse-error: When the given keywords contains an invalid expression

A complete example in PHP of how to search advertisements is available: Web_services/Advertisements search.

search: Searches for advertisements without the full text search technique, and is best suited when the user does not supply a search phrase. Examples would be the last published advertisements, or n random advertisements. The input is an object very similar to the one for fullTextSearch, but has an additional option, randomOrder, which when set to true wull return the advertisements randomly ordered.

A simple example in PHP, listing a few random advertisements is available: Web_services/Random_advertisements.

  • loadCategory: Given a numeric identifier named id, returns a category.
  • listCategories: Takes no arguments, and returns an array of leaf categories (categories with no children).
  • listCategoryTree: Takes no arguments, and returns an array of detailed categories (along with their children, allowing the navigation as a tree).


Members

Allow searching for members, and retrieving data from a given member. Also allows member registration and manipulation of profile fields. The following operations are available:


load: Given a numeric identifier named id, returns a member.


fullTextSearch: Searches for members using a full text search technique, which is best suited when the user supplies keywords. The results are ordered by relevance, listing the best results first.

  • Parameters: Takes a single object named params with the following attributes:
    • currentPage (number): The current query page, starting at zero. Defaults to 0.
    • pageSize (number): The number of records per page. Defaults to 10.
    • keywords (string): Keywords to search.
    • email (string): The email to search.
    • groupIds (array of numbers): An array of group identifiers.
    • groupFilterIds (array of numbers): An array of group filter identifiers.
    • fields (list of fieldValues): The custom field values for the member. Each fieldValue contains the field internal name and the value. When searching for an enumerated field, the value must be the possible value id.
    • showCustomFields (boolean): Indicates if the custom fields will be retrieved together with each member. Defaults to false.
    • showImages (boolean): Indicates if the images information will be retrieved together with each member. Defaults to false.
  • Result: A page of members, containing the following attributes:
    • currentPage (integer): The current page in the search.
    • totalCount (integer): The total number of members (not only those returned in the page).
    • ads (array of member): Contains the details for each member. For more details, refer to the model data details
  • Fault codes:
    • query-parse-error: When the given keywords contains an invalid expression


search: Searches for members, returning a page of members.

  • Parameters: Takes a single object named params, which have almost all attributes as the one for fullTextSearch (except for keywords), and have the following additional ones:
    • username (string): A text to search within the login name.
    • name (string): A text to search within the name.
    • randomOrder (boolean): When set to true, the result order will be scrambled.


registerMember: Registers a new member.

  • Parameters: Takes a single object named params with the following attributes:
    • groupId (number): The identifier of the group the member will participate. Defaults to the first available group, as set on the web service client. If specified, must be one of the available groups.
    • username (string): The member user name. Will only be used when the user name is not generated, required otherwise.
    • name (string): The member full name. Required.
    • email (string): The member e-mail. Required.
    • loginPassword (string): The login password. Required.
    • fields (list of registrationFieldValues): The custom field values for the member. Each fieldValue contains the field internal name and the value. Optionally, the 'hidden' flag can be set. For enumerated fields, the value must be the possible value id.
  • Result: An object containing the given parameters
    • awaitingEmailValidation (boolean): When e-mail validation is required, the actual member is not created until the mail is validated. So, the other fields will be null if this property is true.
    • id (number): The generated member id
    • username (string): Returns the username, which could be generated, depending on the cyclos configuration.


updateMember: Updates fields of an specific member. Fields which are not passed won't be used to update values.

  • Parameters: Takes a single object named params with the following attributes:
    • id (number): The member identified. Optional, as either it or a principal should be passed.
    • principalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member. Defaults to the channel's default.
    • principal (string): The principal (according to the principalType) of the member. Optional, as either it or the id should be passed.
    • name (string): The new member name. Optional.
    • email (string): The new member e-mail. Optional.
    • fields (list of registrationFieldValues): The custom field values for the member. Each fieldValue contains the field internal name and the value. For enumerated fields, the value must be the possible value id. Only fields specified will be updated.
  • Result: There is no explicit result


listManagedGroups: Lists the groups managed by the current web service client.

  • Parameters: There are no parameters
  • Result: A collection of groups (see the #Model_data_details for more details)


Custom Fields

Since Cyclos allows registering arbitrary fields for members, advertisements and other entities, it also offers this web service to get data about those fields. The following operations are provided:

memberFieldsForMemberSearch: Takes no arguments, and returns an array of member custom fields that may be used to search for members.

memberFieldsForAdSearch: Takes no arguments, and returns an array of member custom fields that may be used to search for advertisements.

memberFields: Takes a group id (optional, defaulting to the first managed group), and returns an array of member custom fields related to that group.

adFieldsForAdSearch: Takes no arguments, and returns an array of advertisement custom fields that may be used to search for advertisements.

possibleValuesForMemberField: Takes an argument named name that is a member custom field internal name, and returns a list of possible values.

possibleValuesForAdField: Takes an argument named name that is an advertisement custom field internal name, and returns a list of possible values.

possibleValuesForAdFieldGivenParent: Takes an argument named name that is an advertisement custom field internal name, and returns a list of possible values for the given parent id.

possibleValuesForMemberFieldGivenParent: Takes an argument named name that is a member custom field internal name, and returns a list of possible values for the given parent id.

paymentFields: Takes a transfer type id and returns an array of member custom fields related to that transfer type.

possibleValuesForPaymentFields: Returns an array of possible values for the given custom field name configured in the given transfer type.

  • name: The name of the payment custom field
  • transferTypeId: The transfer type id

allMemberFields: Takes no arguments and returns an array of all the member custom fields.

allAdFields: Takes no arguments and returns an array of all the advertisement custom fields.


Info texts

An administrator can register 'info texts' in Cyclos. Info texts can consist of a word, or a combination of words and they contain a 'respond text'. It can be used for various channels. For example in the case of SMS users send an SMS to the organization number with a operation command and info text key and Cyclos will return a message with the corresponding respond text. The info text feature also supports a title and rich text. This means it can be used as well by websites to retrieve and publish information that is maintained in Cyclos.

The available operations are:

loadByAlias: Given an alias, returns the matching info text

loadById: Given a numeric identifier, returns the matching info text

search: Searches for info texts according to the given parameters.

  • Parameters: Takes a single object names params, with the following attributes:
    • currentPage (number): The current query page, starting at zero. Defaults to 0.
    • pageSize (number): The number of records per page. Defaults to 10.
    • keywords (string): A text to search within the info text content. Note that this is not a full text keyword, but a regular 'contains' operand.
    • alias (string): An alias for the search.
    • withBodyOnly (boolean): If set to true, only return info texts which contains a body.
  • Result: A page of ads, containing the following attributes:
    • currentPage (integer): The current page in the search.
    • totalCount (integer): The total number of advertisements (not only those returned in the page).
    • infoTexts (array of infoText): Contains the details for each info text. For more details, refer to the model data details


Access

It is possible to check via an external channel for pin and channel access data of members. The operations in this service only works for web service clients which are not restricted to a member. Here are the available operations:

checkCredentials: Checks whether the given credentials, associated with the channel this web service client is related, are correct for the given member.

  • Parameters:
    • principalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member. Defaults to the channel's default.
    • principal (string): The principal (according to the principalType) of the member. Required.
    • credentials (string): The credentials to check. Depending on the channel configuration, may be the login password, transaction password, pin or card security code.
  • Result: One of the give status codes:
    • VALID: the given credentials are valid
    • INVALID: the given credentials are invalid
    • BLOCKED: the given credentials were blocked by exceeding the invalid attempts


isChannelEnabledForMember: Checks whether the given member allows access to the given channel.

    • principalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member. Defaults to the channel's default.
    • principal (string): The principal (according to the principalType) of the member. Required.
  • Result: A boolean flag indicating whether the given channel is enabled for the member.
  • Fault codes:
    • member-not-found: If the given principal did not match any member


changeCredentials: Changes the credential associated with the web service's channel. Only login password and pin are supported.

  • Parameters:
    • principalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member. Defaults to the channel's default.
    • principal (string): The principal (according to the principalType) of the member. Required.
    • oldCredentials (string): The current credentials. Required.
    • newCredentials (string): The new credentials. Required.
  • Result: One of the give status codes:
    • SUCCESS: The credentials were successfully changed.
    • MEMBER_NOT_FOUND: The member was not found.
    • INVALID_CREDENTIALS: Invalid current credentials are invalid.
    • BLOCKED_CREDENTIALS: The credentials are blocked by exceeding attempts.
    • INVALID_CHARACTERS: The given credentials contains invalid characters (like it was supposed to be numeric and a non-numeric credential was informed).
    • TOO_SIMPLE: The given credentials are too simple, according to the member's group policy.
    • CREDENTIALS_ALREADY_USED: The given credentials were already used in past.


Account

This web service allows retrieving information for a member account. When the client is restricted to a member, will only be able to see account information for that member. The available operations are:

getMemberAccounts: Returns which accounts a member have.

  • Parameters: A single object named param, with the given fields:
    • principalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member. Defaults to the channel's default.
    • principal (string): The principal (according to the principalType) of the member. Required when not restricted to a member.
  • Result: A list of memberAccount. For more details, check out the model data details.


searchAccountHistory: Returns both the status (balances, limits...) and account history (credits and debits) for a given member account.

  • Parameters: A single object containing the following attributes:
    • currentPage (number): The current query page, starting at zero. Defaults to 0.
    • pageSize (number): The number of records per page. Defaults to 10. If set to 0 will return the account status only.
    • principalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member. Defaults to the channel's default.
    • principal (string): The principal (according to the principalType) of the member. If null when not restricted to a member assume a system account.
    • credentials (string): The credentials of the member. Only required if the service client is not restricted to a member and set to require credentials.
    • accountTypeId (integer): The account type internal identifier. When null or zero is passed, first the currency is considered, returning an account of that currency, or, if it was not set, the default account type is assumed.
    • currency (string): The currency (either symbol or id) of the member account. Optional. Ignored when accountTypeId is passed.
    • relatedMemberPrincipalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member. Defaults to the channel's default.
    • relatedMember (string): The principal (according to relatedMemberPrincipalType) for the payment related member. Optional.
    • beginDate (date): The begin date for payments. Optional.
    • endDate (date): The end date for payments. Optional.
    • fields (list of fieldValue): A list containing payment custom fields. Optional.
    • reverseOrder (boolean): If true then sort the transaction list in order descendent according to the date.
  • Result: A page of transfers, containing the following attributes:
    • accountStatus (accountStatus): An object containing the account balance, available balance and so on. For more details, refer to the model data details
    • currentPage (integer): The current page in the search.
    • totalCount (integer): The total number of transfers (not only those returned in the page).
    • transfers (array of transfer): Contains the details for each transfer. For more details, refer to the model data details
  • Fault codes:
    • invalid-parameters: If the principal is null and the client is not restricted to a member.
    • member-not-found: If the given principal did not match any member
    • invalid-channel: If the member did not enabled the access to the service client's channel.
    • invalid-credentials: If the given credentials are invalid
    • blocked-credentials: If the given credentials are blocked by exceeding the maximum tries


loadTransfer: Returns a single transfer, given it's identifier, or null when not found.

  • Parameters:
    • principalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member. Defaults to the channel's default.
    • principal (string): The principal (according to the principalType) of the member. Required when not restricted to a member.
    • credentials (string): The credentials of the member. Only required if the service client is not restricted to a member and set to require credentials.
    • transferId (number): The transfer identifier. Required.
  • Result: A transfer object. For more details, refer to the model data details
  • Fault codes:
    • member-not-found: If the given principal did not match any member
    • invalid-channel: If the member did not enabled the access to the service client's channel.
    • invalid-credentials: If the given credentials are invalid
    • blocked-credentials: If the given credentials are blocked by exceeding the maximum tries


searchTransferTypes: Gets the available transfer types (or payment types) for the given parameters.

  • Parameters: A single object containing the following attributes:
    • currency (string): Either the symbol or internal identifier for a currency. Optional.
    • fromMemberPrincipalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member performing the payment. Defaults to the channel's default.
    • fromMember (string): The principal (according to the fromMemberPrincipalType) of the member performing the payment. Optional: when the restricted to member and not specified will assume the restricted member). Required if not restricted to a member.
    • toMemberPrincipalType (string): The principal type (USER, CARD, EMAIL or a custom field internal name) of the member receiving the payment. Defaults to the channel's default.
    • toMember (string): The principal (according to the toMemberPrincipalType) of the member receiving the payment. When restricted to a member, if both fromMember and toMember are null then toMember is set as the restricted member. Required if not restricted to a member.
    • toSystem (boolean): When set to true, instead of returning payment types to a member, return payment types to a system account.
    • fromSystem (boolean): When set to true, instead of returning payment types from a member, return payment types from a system account.
    • fromAccountTypeId (number): The identifier of the origin account type. Optional
    • toAccountTypeId (number): The identifier of the destination account type. Optional
  • Result: A list of transfers types objects. For more details, refer to the model data details
  • Fault codes:
    • invalid-parameters: If the fromSystem flag is false and the fromMember is null or the toSystem flag is false and the toMember is null.
    • unauthorized-access: If the client is restricted to a member and both fromMember and toMember aren't the retricted member.


POS

New in Cyclos 3.6 is the function to manage POS devices. These devices have an identifier in Cyclos, and can be assigned to members and managed from the main Cyclos interface. The physical POS devices may either be smart enough to access Cyclos directly using this web service or through a gateway, with that gateway communicating with Cyclos with this web service.

Unless returned as status (like on receivePayment and makePayment), operations that uses the POS pin might raise the following fault codes:

  • unauthorized-access:
    • When the pos or posPin is empty or not specified.
  • unexpected-error:
    • Unexpected number format
    • Empty required numeric fields

Operations might return as status:

  • INVALID_CREDENTIALS: The given POS pin is invalid
  • BLOCKED_CREDENTIALS: The given POS pin has been blocked by exceeding attempts

The available operations are:

getInitializationData: Should be invoked on POS initialization. Returns several important data and configuration parameters for the POS operation.

  • Parameters:
    • posId (string): the POS device identifier. Required.
    • posPin (string): The PIN of this pos device. Required.
  • Result: An object containing the following properties:
    • owner (member): Contains details (id, name, username) of the POS owner. For more details, check out the model data details.
    • principalTypes: Contains a list of which principal types is expected for the POS channel. For principal type details, check out the model data details.
    • accountTypes (array of detailedAccountType): Contains the available accounts types, together with the available payment types from each account. For more details, check out the model data details.
    • transactionNumber (object): When transaction number is enabled in Cyclos, contains the prefix, the pad length and the suffix used to generate transaction numbers. See the local settings manual page for more details. When transaction number is disabled, this property contains a null value.
    • decimalDigits: Indicates the number of decimal digits (precision) for amounts.
    • maxSchedulingPayments (integer): The maximum number of installments for scheduled payments.
    • numberOfCopies (integer): The number of printed copies for receipts
    • resultPageSize (integer): The number of records which will be returned in searches (currently only used in searchAccountHistory method).
    • allowMakePayment (boolean): Checks whether this pos device can be used to perform payments from the POS owner to other members.


receivePayment: The member which is the POS owner receives a payment from another member.

  • Parameters: A single object containing the following attributes:
    • posId (string): The POS device identifier. Required.
    • amount (decimal): The payment amount. Required.
    • transferTypeId (integer): The identifier of the payment type. Available transfer types are obtained by the getInitializationData() method. Required.
    • fromMemberPrincipal (string): The principal (username or card number, depending on the channel configuration) of the member performing the payment.
    • fromMemberCredentials (string): The credentials (login password, transaction password, pin or card security code, depending on the channel configuration) of the member performing the payment.
    • fromMemberPrincipalType (string): The principal type of the member performing the payment. For principal type details, check out the model data details.
  • Result: The same object returned by the #Payment web service's doPayment() method.
    • INVALID_CREDENTIALS: The given fromMemberCredentials is invalid

makePayment: The member which is the POS owner performs a payment to another member. May only be used if the POS device is configured to allow making payments.

  • Parameters: A single object containing the following attributes:
    • posId (string): The POS device identifier. Required.
    • amount (decimal): The payment amount. Required.
    • transferTypeId (integer): The identifier of the payment type. Available transfer types are obtained by the getInitializationData() method. Required.
    • toMemberPrincipal (string): The principal (username or card number, depending on the channel configuration) of the member receiving the payment.
    • posPin (string): The PIN of this pos device. Required.
    • toMemberPrincipalType (string): The principal type of the member receiving the payment. For principal type details, check out the model data details.
  • Result: The same object returned by the #Payment web service's doPayment() method.


chargeback: Allows 'undoing' a payment received by the POS owner.

  • Parameters: A single object containing the following attributes:
    • posId (string): The POS device identifier. Required.
    • posPin (string): The PIN of this pos device. Required.
    • transferId (integer): The internal identifier of the transfer which will be charged back. Required.
    • amount (decimal): The payment amount. Used to double check that the payment is actually correct. Required.
  • Result: The same object returned by the #Payment web service's chargeback() method.

getAccountStatus: Returns an account's status, like balance, reserved amount and available balance.

  • Parameters: A single object containing the following attributes:
    • posId (string): The POS device identifier. Required.
    • posPin (string): The PIN of this pos device. Required.
    • accountTypeId (integer): The identifier of account type to get the status. Required.
  • Result: An accountStatus. For more details, check out the model data details.


searchAccountHistory: Returns the account history (credits and debits) for a given member account.

  • Parameters: A single object containing the following attributes:
    • posId (string): The POS device identifier. Required.
    • posPin (string): The PIN of this pos device. Required.
    • currentPage (number): The current query page, starting at zero. Defaults to 0.
    • accountTypeId (integer): The account type internal identifier. Required.
  • Result: A page of transfers, containing the following attributes:
    • currentPage (integer): The current page in the search.
    • totalCount (integer): The total number of transfers (not only those returned in the page).
    • transfers (list of transfer): Contains the details for each transfer. For more details, refer to the model data details


Model data details

Many of the web services operations works with model data. The following elements are available (with their properties):

transfer

  • id (number): The internal identifier
  • transferType (transferType): The payment type
  • date (date): The creation / submission date
  • formattedDate (string): The creation / submission date, formatted according to the Cyclos settings
  • processDate (date): The processing / accepting date
  • formattedProcessDate (string): The processing / accepting date, formatted according to the Cyclos settings
  • amount (decimal): The payment amount
  • formattedAmount (string): The payment amount, formatted according to the Cyclos settings
  • member (member): The member which received / performed the payment, when the payment was to / from a member
  • systemAccountName: The system account name, when the payment was to / from system
  • transactionNumber (string): The generated transaction number
  • description (string): The transfer description

accountStatus

  • balance (decimal): The raw account balance
  • formattedBalance (string): The raw account balance, formatted according to the Cyclos settings
  • availableBalance (decimal): The available balance
  • formattedAvailableBalance (string): The available balance, formatted according to the Cyclos settings
  • reservedAmount (decimal): The amount which is currently reserved
  • formattedReservedAmount (string): The amount which is currently reserved, formatted according to the Cyclos settings
  • creditLimit (decimal): The maximum negative balance this account may reach, represented as a positive number
  • formattedCreditLimit (string): The maximum negative balance this account may reach, formatted according to the Cyclos settings
  • upperCreditLimit (decimal): The maximum positive balance this account may reach, or null when unlimited
  • formattedUpperCreditLimit (string): The maximum positive balance this account may reach, formatted according to the Cyclos settings

accountType

  • name (string): The transfer type name
  • currency (currency): Contains this account type's currency

detailedAccountType

  • name (string): The transfer type name
  • currency (currency): Contains this account type's currency
  • default (boolean): Indicates whether this is the default account type
  • transferTypes (array of transferType): Contains the possible transfer types which may be used to perform payments from this account type

transferType

  • name (string): The transfer type name
  • from (accountType): The origin account type
  • to (accountType): The destination account type

currency

  • symbol (string): The currency symbol
  • name (string): The currency name
  • pattern (string): A string containing #amount#, which should be replaced by the actual amount. For example: "$U #amount" would be replaced by "$U 0.00".

ticket

  • ticket (string): The ticket identifier
  • fromMember (member): The member that paid the transaction
  • toMember (member): The member that received the transaction (when was to a member)
  • toSystem (boolean): Indicates it the payment was to system
  • amount (number): The payment amount
  • description (string): The payment description
  • ok (boolean): Indicates if the payment was successfully completed
  • cancelled (boolean): Indicates if the payment was cancelled by the member
  • pending (boolean): Indicates if the payment wasn't completed yet
  • expired (boolean): Indicates if the payment wasn't completed within an hour
  • awaitingAuthorization (boolean): Indicates if the payment is awaiting authorization in Cyclos
  • formattedAmount (string): The payment amount, formatted according to the Cyclos settings
  • creationDate (date): The date the ticket was created
  • formattedCreationDate (string): The date the ticket was created, formatted according to the Cyclos settings
  • clientAddress (string): The client member IP address
  • memberAddress (string): The web shop IP address
  • returnUrl (string): The informed return url

ad

  • id (number): The internal identifier
  • category (adCategory): The advertisement category
  • searching (boolean): Indicates if the member is demanding a product / service (when true) or offering (when false)
  • title (string): The title
  • description (string): The description
  • html (boolean): Indicates if the description is html (true) or plain text (false)
  • owner (member): The member that published the advertisement
  • price (number): The price
  • formattedPrice (string): The price, formatted according to Cyclos settings
  • permanent (boolean): Indicates if the advertisement is permanent (like yellow pages) or not (a specific offering)
  • publicationStart (date): The date the advertisement was published
  • formattedPublicationStart (string): The date the advertisement was published, formatted according to Cyclos settings
  • publicationEnd (date): The date the advertisement expires
  • formattedPublicationEnd (string): The date the advertisement expires, formatted according to Cyclos settings
  • fields (list of fieldValue): The advertisement custom field values. May or may not be present, depending on how this object was retrieved.
  • images (array of image): An array of advertisement images

adCategory

  • id (number): The internal identifier
  • name (string): The full category name, in the form "Parent: Child"

detailedAdCategory

  • id (number): The internal identifier
  • name (string): The category name
  • fullName (string): The full category name, in the form "Parent: Child"
  • level (number): The level of nesting this category has, starting with 1
  • countOffer (number): The number of active advertisements being offered on this category
  • countSearch (number): The number of active advertisements being searched on this category
  • children (array of detailedAdCategory): The categories that are children of this category

group

  • id (number): The internal identifier
  • name (string): The group name

member

  • id (number): The internal identifier
  • groupId (number): The group identifier
  • name (string): The member name
  • username (string): The login name
  • email (string): The member e-mail
  • fields (list of fieldValue). The member custom field values. May or may not be present, depending on how this object was retrieved.
  • images (array of image): An array of member images. May or may not be present, depending on how this object was retrieved.

field

  • id (number): The internal identifier
  • internalName (string): The internal name
  • displayName (string): The display name
  • type (enumeration): The field data type. May be: STRING, ENUMERATED, INTEGER, FLOAT, DATE or BOOLEAN
  • enumerated (boolean): Indicates if the field is enumerated, that means, accepts only specific values. Will be true when type is ENUMERATED
  • required: Boolean flag indicating whether the field is required
  • mask: The mask used for inputting / formatting field values. Only makes sense if type is STRING.
  • parentFieldId: Number containing the numeric identifier of this field's parent field. Only makes sense if type is ENUMERATED.
  • possibleValues: A list of possibleValue containing all the possible values. It only applies when the field has type ENUMERATED.
  • control: The form control used to input values for that custom field. May be one of the following: TEXT, TEXTAREA, RICH_EDITOR, SELECT, RADIO or CHECKBOX
  • maxLength: The field maximum length.
  • minLength: The field minimum length.

possibleValue

  • id (number): The internal identifier
  • value (string): The display value
  • parentId (number): The internal identifier of the parent possible value

image

  • id (number): The internal identifier
  • thumbnailUrl (string): The url for the image thumbnail
  • fullUrl (string): The url for the full image
  • caption (string): A descriptive caption
  • lastModified (date): The date of last modification

page

  • currentPage (number): The current page on the search
  • totalCount (number): The total number of results
  • [ads / members]: If is an ad page, the ads will contain an array of ads. If a member page, an array of members

fieldValue

  • internalName (string): The custom field internal name
  • fieldId (number): The custom field id
  • displayName (string): The custom field display name
  • value (any): The custom field value
  • possibleValueId (number): The custom field possible value id

registrationFieldValue

  • internalName (string): The custom field internal name
  • fieldId (number): The custom field id
  • displayName (string): The custom field display name
  • value (any): The custom field value
  • possibleValueId (number): The custom field possible value id
  • hidden (boolean): Indicates whether the given field is hidden from others

timePeriod

  • number (number): The period numeric value
  • field (enumeration): The period field. May be: DAYS, WEEKS or MONTHS

principalType

  • USER: The login name is used
  • CARD: The card number is used
  • EMAIL: The e-mail is used
  • CUSTOM_FIELD: The specific custom field is used

infoText

  • subject (string): The info text subject
  • body (string): The info text body. Normally not used in case of SMS messages
  • validFrom (date) The date which defines when the info text validity begins
  • validTo (date) The date which defines when the info text validity ends