Introduce credential, initiator and series[]

source/index.html.md

@@ -333,64 +333,78 @@ Depending on card scheme and merchant category, the name on the card might be
 necessary for approval of credits. It may be provided through the optional
 parameter `card[name]`.
 
-## Recurring payments
+## Series of transactions
 
-Recurring payments enable you to repeatedly charge cardholders without providing
-CSC or other means of cardholder authentication for subsequent payments.
+A cardholder must explicitly agree when subscribing to something, and will
+thereby give the merchant permission to subsequently withdraw money. Clearhaus
+support two type of subscription billing:
 
-### Subscription concept
+* Recurring: Transactions processed at predetermined, regular intervals not
+    exceeding 1 year; e.g. a monthly subscription for a magazine.
+* UCOF (Unscheduled Credential on File): Transactions that does not occur on
+    predetermined, regular intervals; e.g. a car sharing subscription billed
+    weekly but only for weeks when the service is used.
 
-Many PSPs have a subscription concept for supporting recurring payments.
-The first approved authorization is the initial recurring authorization (also
-known as "first in series"), all later authorizations are called subsequent
-authorizations. Clearhaus supports subscriptions in the form of recurring
-payments.
+The amount may vary among transactions in a series, but may not exceed the
+authentication amount of the first-in-series authorization.
+There may be an agreed end of the series.
 
 ### Repeatedly reserve money
 
-A recurring payment is made by making an authorization and setting `recurring`
-parameter to `true`. The first recurring payment for a given card could be made
-this way (notice that the amount may be zero):
+A first-in-series payment is made by making an authorization and marking it as a
+`recurring` or `unscheduled` series. For instance, a first-in-series recurring
+payment could be made this way:
 
 ````shell
 curl -X POST \
   https://gateway.test.clearhaus.com/authorizations \
   -u <your-api-key>:  \
   -d "amount=2050"    \
   -d "currency=EUR"   \
-  -d "recurring=true" \
+  -d "series[type]=recurring"     \
   -d "card[pan]=4111111111111111" \
   -d "card[expire_month]=06"      \
-  -d "card[expire_year]=2022"     \
+  -d "card[expire_year]=2026"     \
   -d "card[csc]=123"              \
-  --data-urlencode "card[pares]=<some-pares-value>" \
+  --data-urlencode "card[3dsecure][v2][rreq]=<some-rreq-value>" \
   -H "Signature: <signing-api-key> RS256-hex <signature>"
 ````
 
 Example response (snippet):
 
 ````json
 {
-    "id": "e3e9d215-6efc-4c0e-b3d7-2226057c6de8",
-    "status": {
-        "code": 20000
-    },
-    "processed_at": "2018-07-09T12:58:56+00:00",
-    "recurring": true
+    "id": "1b722683-92ad-4c6b-85da-e119d550670d",
+    "status": { "code": 20000 }
 }
 ````
 
-This should be followed by a capture except when the amount is `0`.
+This should be followed by a capture.
 
-Subsequent authorizations are made similarly, however, CSC would not be
-included. For 3-D Secure version 1 (see [3-D Secure](#3-d-secure)), PARes would
-not be included. 3-D Secure version 2 has some support for subsequent
-authorizations.
+Subsequent recurring authorizations initiated by the merchant are made
+similarly, however, CSC would not be included, and the previous-in-series is
+referenced, e.g.:
 
-An initial recurring authorization can also be made using the `applepay` and
-`mobilepayonline` payment methods; subsequent recurring payments, however, must
-be made using the `card` payment method using the card details of the initial
-recurring authorization.
+````shell
+curl -X POST \
+  https://gateway.test.clearhaus.com/authorizations \
+  -u <your-api-key>:  \
+  -d "amount=2050"    \
+  -d "currency=EUR"   \
+  -d "series[previous][id]=1b722683-92ad-4c6b-85da-e119d550670d" \
+  -d "card[pan]=4111111111111111" \
+  -d "card[expire_month]=06"      \
+  -d "card[expire_year]=2026"     \
+  -H "Signature: <signing-api-key> RS256-hex <signature>"
+````
+
+A first-in-series authorization can also be made using the `applepay` or
+`mobilepayonline` payment methods; subsequent-in-series authorizations, however,
+must be made using the `card` payment method using the card details of the
+previous-in-series authorization referenced.
+
+Any first-in-series authorization must be made with strong customer
+authentication (SCA) regardless of the authorization amount.
 
 
 ## 3-D Secure
@@ -540,26 +554,123 @@ Exactly one payment method must be used.
   <dd>
     Amount in minor units of given currency (e.g. cents if in Euro).
   </dd>
+
   <dt>currency
     <span class="type">[A-Z]{3}</span>
   </dt>
   <dd>
     <a target="_blank" href="currencies.txt">3-letter currency code</a>. (Some exponents differ from ISO 4217.)
   </dd>
+
+  <dt>credential
+    <span class="type">(<code>storing</code>|<code>using</code>)</span>
+  </dt>
+  <dd>
+    Indicate if the payment credential (e.g. PAN and expiry) will be stored for
+    future use where the payment credential is not provided by the
+    cardholder but collected from (encrypted) storage.
+    <br />
+    <code>storing</code>: The payment credential will be stored; may only be
+    stored if the authorization is approved.
+    <br />
+    <code>using</code>: The payment credential has already been stored and is now
+    being used.
+    <br />
+    Default:
+    <ul>
+      <li><code>using</code>, if <code>initiator</code> is <code>merchant</code>
+      (<code>storing</code> is invalid),</li>
+      <li><code>storing</code>, if the authorization is first-in-series.</li>
+    </ul>
+
+    <div class="type">Optional</code>
+  </dd>
+
+  <dt>initiator
+    <span class="type">(<code>cardholder</code>|<code>merchant</code>)</span>
+  </dt>
+  <dd>
+    The initiator of the authorization. An authorization is initiated by the
+    cardholder if the cardholder decided the transaction should be created.
+    This is regardless of whether stored payment credential is being used.
+    <br />
+    For compliance reasons there should be a previous approved transaction (for
+    the cardholder and the merchant) marked with <code>storing</code> before
+    <code>initiator</code> may be <code>merchant</code>.
+    <br />
+    Default:
+    <ul>
+      <li><code>merchant</code>, if the authorization is
+      subsequent-in-subsequent (<code>cardholder</code> is invalid),</li>
+      <li><code>cardholder</code>, otherwise.</li>
+    </ul>
+
+    <div class="type">Optional</div>
+  </dd>
+
   <dt>ip
     <span class="type">[0-9.a-fA-F:]{3,45}</span>
   </dt>
   <dd>
     Cardholder's IP address. It must be a valid v4 or v6 address.
     <div class="type">Optional<br></div>
   </dd>
-  <dt>recurring
-    <span class="type">(true|false)</span>
+
+  <dt>reference
+    <span class="type">[\x20-\x7E]{1,30}
+      <a target="_blank" href= "http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters">
+        ASCII printable characters
+      </a>
+    </span>
   </dt>
   <dd>
-    Must be <code>true</code> for recurring payments.
+    A reference to an external object, such as an order number.
     <div class="type">Optional</div>
   </dd>
+
+  <dt>
+    series[type]
+    <span class="type">(<code>recurring</code>|<code>unscheduled</code>)</span>
+  </dt>
+  <dd>
+    Indicate the type of series.
+    <br />
+    <code>recurring</code>: A series of transactions where the cardholder has
+    explicitly agreed that the merchant will repeatedly charge the cardholder at
+    regular, predetermined intervals that may not exceed 1 year.
+    <br />
+    <code>unscheduled</code>: A series of transactions where the cardholder has
+    explicitly agreed that the merchant will repeatedly charge the cardholder at
+    unknown times, e.g. based on cardholder usage.
+    <br />
+    Although the amount may vary among transactions in any series, the amount
+    of any subsequent-in-series transaction can not exceed the amount of the
+    authentication of the first-in-series authorization.
+
+    <div class="type">Conditional. Cannot be present if <code>series[previous]</code> is present.</div>
+  </dd>
+
+  <dt>
+    series[previous][id]
+    <span class="type">[:UUIDv4:]</span>
+  </dt>
+  <dd>
+    The Clearhaus authorization ID as a reference to the latest approved
+    authorization in the series.
+    <br />
+    If omitted and <code>series[type]</code> is populated, then the
+    authorization will be a first-in-series.
+    <br />
+    Can be used only with payment method <code>card</code>.
+    <br />
+    If the latest approved authorization in the series was not processed via
+    Clearhaus, after obtaining explicit approval from Clearhaus, you can
+    provide raw scheme values; see
+    <a href="#scheme-reference-to-series">Scheme reference to series</a>.
+
+    <div class="type">Conditional. Cannot be present if <code>series[type]</code> is present.</div>
+  </dd>
+
   <dt>text_on_statement
     <span class="type">[\x20-\x7E]{2,22}
       <a target="_blank" href="http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters">
@@ -572,16 +683,13 @@ Exactly one payment method must be used.
     <div class="type">May not be all digits, all same character, or all sequential characters (e.g. "abc")</div>
     <div class="type">Optional</div>
   </dd>
-  <dt>reference
-    <span class="type">[\x20-\x7E]{1,30}
-      <a target="_blank" href= "http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters">
-        ASCII printable characters
-      </a>
-    </span>
+
+  <!-- deprecated -->
+  <dt><strike>recurring</strike>
+    <span class="type">(true|false)</span>
   </dt>
   <dd>
-    A reference to an external object, such as an order number.
-    <div class="type">Optional</div>
+    Deprecated! Please use <code>series</code>.
   </dd>
 </dl>
 
@@ -798,6 +906,58 @@ Only one 3-D Secure version can be used for a given authorization.
   </dd>
 </dl>
 
+##### Scheme reference to series
+
+If the previous-in-series authorization was made via this API, you should use
+`series[previous][id]` to reference the previous-in-series authorization.
+Otherwise, you must obtain explicit approval from Clearhaus to use the raw
+scheme values grouped in <code>series[previous][mastercard]</code> and
+<code>series[previous][visa]</code>.
+
+The Mastercard specific reference to the series contains the following parts.
+
+<dl class="dl-vertical">
+  <dt>
+    series[previous][mastercard][tid]
+    <span class="type">[A-z0-9]{3}[A-z0-9]{6}[0-9]{4}[ ]{2}</span>
+  </dt>
+  <dd>
+    Trace ID being the concatenation of values
+    Data element 63 subfield 1 (Financial Network Code) (position 1-3),
+    Data element 63 subfield 2 (Banknet Reference Number) (position 4-9),
+    Data element 15 (Date, Settlement) (position 10-13), and
+    two spaces;
+    to be used in Data Element 48, Subfield 63.
+
+    <div class="type">Optional. Cannot be present if <code>series[previous][id]</code> or <code>series[previous][visa]</code> is present.</div>
+  </dd>
+
+  <dt>
+    series[previous][mastercard][tokenized]
+    <span class="type">(true|false)</span>
+  </dt>
+  <dd>
+    Indicate if the series was initiated with a tokenized payment method.
+
+    <div class="type">Conditional. Required if <code>series[previous][mastercard][tid]</code> is present.</div>
+  </dd>
+</dl>
+
+The Visa specific reference to the series has only one part.
+
+<dl class="dl-vertical">
+  <dt>
+    series[previous][visa][tid]
+    <span class="type">[0-9]{15}</span>
+  </dt>
+  <dd>
+    Transaction ID from Field 62.2 of the first (or previous) in series
+    authorization; to be used in Field 125, Usage 2, Dataset ID 03.
+
+    <div class="type">Optional. Cannot be present if <code>series[previous][id]</code> or <code>series[previous][mastercard]</code> is present.</div>
+  </dd>
+</dl>
+
 
 ### Captures
 
@@ -981,6 +1141,11 @@ POST https://gateway.clearhaus.com/credits
   </dd>
 </dl>
 
+<p class="alert alert-info">
+<b>Notice:</b> Implicitly, <code>initiator</code> is <code>merchant</code> and
+<code>credential</code> is <code>used</code>.
+</p>
+
 ### Account
 
 The account resource holds basic merchant account information. Only `HTTP GET`