ON-LINE CARD (sm) Service - Interfaces Description

ON-LINE CARD (sm) Merchant Interfaces

1. Basic Knowledge

More than one separate service with a value-account can be deployed within the same consumer (business) service account, - e.g. a number of web-shops, or a web-shop + some type of value-transfer service with a separate value-account, etc.

If you have two or more web-shops you have isolated order numbers for each shop, or if you want to transfer money from your account, you have one more outgoing transfer numbering space; a 'namespace' is an entity defined by the merchant for each type of operation he can perform.

Therefore, if you are going to request, whether the order #5 has been paid already, you must specify the 'namespace' of order.

“Payment interface” operation (see below) is defined in the context of namespace too, so when you put a form on a site, and user pays for an order, incoming transfer always will contain at least a namespace, and if you specify the order number, it will have this number too. All operations are defined in a context of namespaces.

Merchant is issued a 'namespace id'  during operations configuration wizard execution.

2. Non-webservice actions

Authentication

Merchant can ask an end-user (his client) to authenticate himself with the help of ON-LINE CARD (tm) client application with unique pre-registered cryptographic material. This is a 'phishing-proof' 'two-factor' authentication mechanizm, that was designed and can be used instead of conventional 'log-in/password' authentication.
As a result of authentication Merchant will know that user actually owns an account with a number, and (optionally) can request and retrive user’s profile details if end user permits him to do so during the authentication.

See 'Demo Merchant' web-site for working example.

HTML code (to be placed on Merchant's 'log-in page'):

<form action=https://auth.on-linecard.com/Pay.aspx method=”post”>
<input type=hidden name='MerchantNamespaceId' value='0003-8F63D5F1-C62D-4F74-A477-BEFF2DC80620'>
<input type=submit>
</form>

After clicking a button on Merchant's web-page the user will be prompted to authenticate himself by ON-LINE CARD (tm) client software. Upon approval, client software requests a secutiy token from the Service. This token will be added to the merchant’s site URL (pre-configured on OLC Service site, by Merchant) and will be returned to the browser via POST method as AuthenticateToken parameter.

Later, Merchant web-site software can validate this token on Service server and retrieve user’s personal data via webservice-driven interface CheckAtuthenticate.

Payment Interface

You have to inclide the following HTML code on your 'Check-out' page to request client payment for an order. Please do not forget to enable this type of operation while pre-configuring the Service through administration web-interfaces!

See 'Demo Merchant' web-site for working example.

HTML code must be as follows:

<form action=https://auth.on-linecard.com/Pay.aspx method=”post”>
<input type=hidden name=’DescriptionUser' value='Test payment'>
<input type=hidden name='MerchantNamespaceId' value='0003-8F63D5F1-C62D-4F74-A477-BEFF2DC80620'>
<input type=hidden name='Amount' value='1.5'>
<input type=hidden name='TransferMerchantId' value='10'>
<input type=submit>
</form>

MerchantNamespaceId is a namespace id of your operation. TransferMerchantId, if specified, is the order number, if not, a transfer w/o number will be created by user (donations etc.); if specified, it must be unique within the namespace (Service never commits two transactions with the same order number, for this reason it’s impossible to pay twice for the same order).

DescriptionSystem field can be specified within DescriptionUser - see separate chapter about this extended field.

Merchant pre-configures the URL's, where user will be redirected after successful, unsuccesful and cancelled payments through web-interfaces of the Service.

IMPORTANT: merchant developer shall remember that his system can not know exactly (without additional authentication-related steps) that someone who is accessing a successful payment page is the same person who has commited the payment.

3. Webservice-driven operations

Basic

Access URL: http://webservice.on-linecard.com/Merchant/Primary.asmx

For all interfaces you need to pass SOAP-header with namespace id:

    <MerchantNamespaceHeader xmlns="http://on-linecard.com/Ns/1.0">
      <MerchantNamespaceId>string</MerchantNamespaceId>
    </MerchantNamespaceHeader>

All interfaces must sign MerchantNamespaceHeader, Action, MessageId, Timestamp headers and request body.

Signature algorythms:

SignatureMethod = "http://www.w3.org/2000/09/xmldsig#rsa-sha1"
SignedInfo CanonicalizationMethod =
                   "http://www.w3.org/2001/10/xml-exc-c14n#"
DigestMethod = "http://www.w3.org/2000/09/xmldsig#sha1"

Signature and message body must be encrypted by:

EncryptionMethod = "http://www.w3.org/2001/04/xmlenc#rsa-1_5" or
                    = "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"

session key alg = "http://www.w3.org/2001/04/xmlenc#aes128-cbc" or
                     = "http://www.w3.org/2001/04/xmlenc#aes192-cbc" or
                    = "http://www.w3.org/2001/04/xmlenc#aes256-cbc"

SOAP and XmlSignature / XmlEncryption have been described above.

The clock on Merchant System must be synchronized with UTC; the time on merchant’s service can differ by not more than 15 min from real UTC time.