API

How to use the API – Big Picture

Before you begin, make sure you have done the following:

• Obtain API access URL, username, password and secret key for accessing API
• Depending on the language you plan to use you might want to generate communication classes and methods (ATS API is exposed as WSDL web service, so there are tools for many languages which can be used to automatically generate code for consuming it – to get WSDL simply append "?wsdl" to API access URL)

Before using any API calls you need to generate some security-related parameters which are used by Nautilus to verify that request is indeed coming from you (and not, for example, from a proxy server between you and Nautilus). More details about this can be found in the chapter about Security.

As a very first step you should register a card product, which will define settling and billing behavior for all cards associated with it – use AddCardProduct call for this.

After registering a card product you usually want to register cards associated with it – use AddCard call for this. Make sure to include the Reference parameter, because Nautilus will later always send the same reference to you together with other card data, making it easier to pair cards from transaction data with cards in your system. Technically speaking, it is not mandatory to register card with Nautilus using AddCard, but if you don’t do that, Nautilus will not know of any special billing and settling rules your card uses and it will in turn blindly trust payment processor data (and, of course, it will not be able to pass you the card reference, so you will have to do manual lookup using payment processor’s token).

If you ever need some data field that Nautilus transaction feed does not include, but the raw payment processor data does, you can use GetRawTransaction to request the raw processor data for a given transaction. Also, in case your system ever fails to process a transaction, or for whatever reason you want to receive data about the same transaction again, you can force Nautilus to resend the data using PushTransaction.

API Security

In order to ensure security and to be certain that each API call indeed originated from you, even if 3rd party proxy services are used, ATS uses two parameters for authenticating each API request:

• ApiToken
• SecurityToken

ApiToken is generated by ATS on your behalf. To obtain the ApiToken, you need to authenticate yourself by providing the assigned username and password to GenerateApiToken method. Each time, a unique ApiToken is returned by ATS, and each ApiToken can be used only once – ie. for each API call you first need to generate an ApiToken.

SecurityToken is generated by you as SHA256 hash of a string which is the concatenation of the ApiToken and the secret key (which you should receive from AraxaTech). This way, the secret key is never transmitted in clear text from you to ATS, and one SecurityToken cannot be used twice, since the ApiToken is constantly changing. This way 3rd party proxy services (or somebody else spying on the traffic between ATS and you) cannot impersonate you.

Example

Card Products

Card products are convenient objects that are used to group together all cards of the same behavior. This means that all cards that bill and settle in the same way should be associated with the same card product. Creating card product also gives you the way to quickly and easily modify behavior of all cards associated with it.

About Billing and Settling Currencies

When it comes to cards (and card products) it is important to understand how all different currencies play together. In general, for each transaction there are 3 currencies at play: original (transaction) currency, (cardholder) billing currency, settling (or reconciliation) currency.

Original (or transaction) currency is the currency merchant wanted for the product or service delivered to cardholder, that currency data is transmitted to you from a merchant place.

Billing (or cardholder billing) currency is the currency the cardholder will pay in for an item purchased. This currency is configured during BIN setup with the card scheme that is supporting the card (for example VISA or MasterCard). Card scheme adds data about this currency to a transaction.

Settling currency is the currency that the issuer will use to pay to card scheme in order to clear a transaction that cardholder made. This currency is also configured during BIN setup. Often this currency is identical to billing currency, but in general case it does not have to be. The card scheme adds data about this currency to the transaction.

AddCard

Use this method to add a card to ATS, so ATS can properly associate it with correct billing and settling setup, and it can properly map it with payment processor’s token.

AddCardProduct

This API call is used to create a new card product. It is convenient to pass ID of card product on your side as Reference parameter (ATS will later return the same reference, so you don’t need to do mapping with ATS IDs). The important thing to note is that the card product name needs to be unique.

AddTokenToCard

Use this API call to associate additional tokens with the existing card. Additional tokens can belong to a different payment processor from the one on which the card was initially created.

GenerateApiToken

This API call is used to generate an ApiToken. A unique value is returned after each call to GenerateApiToken. This value should be used only for one API call. You use ApiToken to generate SecurityToken as explained above.

GetCard

Use this method to get data about the specific card.

GetCardProduct

Use this method to get data about the specific card product.

GetRawTransaction

Use this method to pull raw transaction data, as it was passed to Nautilus by the payment processor.

ModifyCard

This method is used to modify a card reference or association with a card product. Note that this method cannot disassociate a card from one payment processor token and associate it with the other.

ModifyCardProduct

Use this API call to modify settings for an existing card product. Note that you need ProductId as returned by AddCardProduct.

You can pass nulls for values that you don’t want to change (but be careful that if you change BillingCurrencies settings then you also must specify new DefaultBillingCurrency, and analogous for Settling currencies and DefaultSettlingCurrency).

PushTransaction

Use this method to force ATS to push some transaction data to you again.

Status Codes

These are possible values for Status as returned by various API calls.