Provider Differences

There are two main provider types, which we will refer to as "server-oriented" and "client-oriented". The server-oriented providers are characterized by having a separate web service call for transaction initialization, while the client-oriented providers treat the actual payment as the initialization. It's unfortunately not possible for the InfoSystems Payment API to completely hide the distinction between the two types, meaning that clients for server-oriented and client-oriented underlying providers are not completely interchangeable.

For server-oriented providers, the underlying flow, i.e. what you would do if you used the provider directly, looks like this:

1. Initialize the transaction
2. Send the end user to the payment window URL
3. Complete the transaction

The majority of the work for a client of a server-oriented payment provider lies in passing the correct values to the initialization method. Completing the payment is just a matter of passing the correct transaction ID.

For client-oriented providers, there is no initialization step:

1. Send the end user to the payment window URL, with the URL containing input parameters
2. Complete the transaction

Here the client needs to build the payment window URL on its own. The InfoSystems Payment API takes care of building the URL based on various input parameters. However, since no transaction exists until after the user has made the payment, an extra step is necessary to update the transaction in the Infosoft database, in the form of the UpdatePayment method.

The InfoSystems Payment API currently supports four providers. The providers break down into the two categories as follows:

• Server-oriented: PayEx, Netaxept
• Client-oriented: DIBS, ePay

The StartPayment method is used at the start of every payment, and it takes a large number of parameters. Not all parameters are used for all underlying providers, and some parameters are required for some providers but optional for others.

For more details on reference keys, refer to the Reference Keys article.

All providers have an ID that uniquely identifies each payment. Whether the ID is globally unique or merely unique for the current merchant varies, but it's always guaranteed to be unique for each merchant. The type of the ID also varies: For some providers it's a simple integer, while for others it may also contain letters or other symbols.

PayEx makes a further distinction between two different IDs. When you start a new transaction, PayEx returns an "order reference", which PayEx calls orderRef. This ID must be used as the input when calling the PayEx equivalent of CompletePayment, which is called simply Complete. When Complete is called successfully, PayEx will return another unique ID, called transactionNumber. All the other PayEx methods that operate on transactions, such as Capture, Cancel and Check, take the transactionNumber as their input, while the orderRef is no longer used for anything.

In the InfoSystems Payment API, these PayEx fields correspond to the fields ProviderOrderReference and ProviderTransactionReference. PayEx is currently the only provider that makes this distinction, so if any other underlying provider is used then the distinction is irrelevant, since the fields will always have the same value. However, it's still the case that the ProviderTransactionReference will only be set after the CompletePayment method has been called.

Another point of difference between the providers is to do with agreements. All the underlying providers have support for agreements, although they all use different terms for them. PayEx calls them "agreements", DIBS refers to them as "tickets", and in ePay they are "subscriptions". For Netaxept, where they are of a slightly different nature, they's called "recurring payments". We will henceforth always refer to them as "agreements".

There are also some significant differences between the providers in terms of how the agreements work behind the scenes. The InfoSystems Payment API abstracts away these differences to a sufficient extent that clients of the API should not need to know about it, but it's still useful to be aware of how the underlying provider works in this regard.

Infosoft has support for deleting (also known as "locking") agreements by way of the LockPaymentAgreement method. However, not all of the underlying providers support deleting/disabling the agreements on their end. Currently, Netaxept is the only provider that doesn't support agreement deletion, but support for this is currently not implemented when DIBS is the underlying provider either. (See below table for details.)

Note that, as the name LockPaymentAgreement suggests, the agreements are not actually deleted from the database. Instead they are marked as locked but kept around in a disabled state, and they will not be used for future automatic payments. Once an agreement has been locked there's no way to "unlock" it.

Note
* DIBS does in fact support this, but only with the delticket method in the old Flexwin API. The new Payment Window API has no corresponding method, and the InfoSystems Payment API only uses the new API.

Some providers support what will henceforth be referred to as "agreement-only payments". An agreement-only payment is a payment that lets the user store their credit card for use for future agreement payments, or alternatively as a verification that the user indeed has a valid credit card, but in either case without performing an actual payment. To invoke agreement-only payments, the Agreement value should be used for the PaymentFlow input parameter. The providers that support it usually provide a special payment window with a different design from the usual one. Of the currently supported providers, only PayEx doesn't support agreement-only payments.

When the Agreement flow is used, and the provider supports agreement-only payments, the price argument will be ignored. The Agreement flow can still be used with providers that don't support agreement-only payments, but a price argument must be given as with normal payments. The most typical approach is to use a "token" price, such as the lowest possible monetary sum for the relevant currency, or some other insignficant amount. Note that the money will never actually be withdrawn from the customer's card by Infosoft when the Agreement flow is used.

While DIBS does support agreement-only payments, and even has a special version of the payment window for the purpose, it's still necessary for there to be a non-zero price argument behind the scenes, presumably because their underlying data model necessitates it. This amount will never be shown to the user, but it will be available on the DIBS admin site, and can be captured manually from there. However, the DIBS payment window will not return the transaction ID, so neither the client nor the Infosoft database will have any knowledge of the transaction. In spite of this, we have defined DIBS as supporting agreement-only payments. DIBS will behave identically to ePay in this regard, except for the "secret" transaction that's created behind the scenes.

Note
When the Agreement PaymentFlow is used with DIBS as the underlying provider, an input amount of 100 is always added by the InfoSystems Payment API, no matter what the price input parameter to StartPayment is.

There are three pieces of information about the credit card used for each payment that are stored in the Infosoft database: A masked version of the card number, the card type (Visa, MasterCard, etc.) and the expiration date. Some providers support automatic retrieval of these details, while others require the client to pass the data to the server based on the values returned from the payment window. This is only applicable to client-oriented providers.

These pieces of information are mainly useful for debugging and customer support, but the expiration date is also used by the system to determine if a payment agreement is still valid. A payment agreement may be invalid even if its expiration date has not been reached, but Infosoft will never even attempt to use a payment agreement that has expired.

Of the currently supported providers, PayEx and Netaxept fully support automatic retrieval of credit card details, so the client does not need to concern itself with any of this when either of these providers is used. ePay almost entirely supports it as well, but there's a single exception. When the Agreement flow is used when ePay is the underlying provider, there's currently no way for Infosoft to automatically retrieve the masked card number from ePay. The masked card number can be retrieved automatically for Instant/TwoPhased payments, but not for agreement-only payments. This means that when the Agreement flow is used and ePay is the underlying provider, the cardno field returned from the payment window should be passed as the CardMask parameter to UpdatePayment.

DIBS has some status functions that can be used to retrieve this information, but they are only implemented in the old Flexwin API. The InfoSystems Payment API only uses the new DIBS Payment Window API when the underlying provider is DIBS, so these status functions are never used. It's therefore always necessary for the client to pass the credit card details to the system using the UpdatePayment method. The values returned from the payment window are called cardTypeName, cardNumberMasked, expMonth and expYear. The expMonth and expYear should be combined into a single field before calling UpdatePayment. The expiration field should be on the form MMYY, e.g. 1113 for November 2013.

Depending on which provider is used, different currency codes are supported. For details on supported currencies, please refer to the provider's own documentation.

In the case of ePay, the InfoSystems Payment API currently only supports a limited subset of the currency codes supported by ePay: http://tech.epay.dk/en/currency-codes. The currencies that are supported when ePay is used are currently the following: NOK, DKK, SEK, GBP, USD, EUR. Please contact Infosoft if you need to use a different currency.

Reference

Other Resources