Subscriptions with Credit Card Payments

The following section describes how to order a new subscription, and at the same time register a credit card with the subscription. It is assumed that the details of ordering a new subscription using invoice payments have been read and understood. Refer to the subscription section for the specifics.

In terms of API communication the entire process comprises 4 or 5 steps depending on the provider. In addition is the redirection of the customer to the provider terminal.

1. OrderSubscription with paymentflow enabled

2. StartPayment

3. UpdatePayment (only required with DIBS/ePay as provider)

4. CompletePayment

5. CompleteSubscription

(1) Order Subscription

The first step is for the integrating party (web shop or similar) to initiate a subscription order with all the information related to a new subscription. The important part here is to indicate that the order should participate in a payment flow, in this case the registration of the credit card information. This can be achieved by setting the option ParticipateInOnlinePaymentFlow to true in the request of the OrderSubscription method.

Enabling the payment flow tells the system that something needs to be completed before the order can be imported and completed. If something fails during the process the order will remain unfinished and will not end up as a new subscription. This reduces the amount of cleanup that any web client or other integrating party needs to do in case of errors, and it hopefully also reduces strain on the back office personal.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://tech.infosoft.no/schemas/2011/10" xmlns:ns1="http://tech.infosoft.no/schemas/2012/08" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:inf="http://schemas.datacontract.org/2004/07/Infosoft.Webservices.DTO">
 <soapenv:Header/>
 <soapenv:Body>
    <ns:OrderSubscriptionRequest>
       <ns:AddressParameters>
          <ns:CountryCode>NO</ns:CountryCode>
          <ns:HouseNumber>42</ns:HouseNumber>
          <ns:Streetname>TestingRoad</ns:Streetname>
          <ns:ZipCode>0667</ns:ZipCode>
       </ns:AddressParameters>
       <ns:CustomerParameters>
          <ns:EmailAddress>john.doe@invalidaddress.tld</ns:EmailAddress>
          <ns:Firstname>John</ns:Firstname>
          <ns:Lastname>Doe</ns:Lastname>
       </ns:CustomerParameters>

       <!-- IMPORTANT PART: This will make sure we participate in a credit card payment flow -->
       <ns:ParticipateInOnlinePaymentFlow>true</ns:ParticipateInOnlinePaymentFlow>
       <!-- END IMPORT PART -->
       <ns:SubscriptionParameters>
          <ns:NumberOfCopies>1</ns:NumberOfCopies>
          <ns:ProductCode>T1</ns:ProductCode>
          <ns:StartCode>ST</ns:StartCode>
          <ns:StartDate>2099-12-12</ns:StartDate>
          <ns:TermCode>01</ns:TermCode>
          <ns:TitleCode>IS</ns:TitleCode>
       </ns:SubscriptionParameters>
    </ns:OrderSubscriptionRequest>
 </soapenv:Body>
</soapenv:Envelope>

(2) Start Payment

The second step follows immediately after step 1, and the purpose of this request is to initialise the payment in the InfoSystems and at the provider. Specifically a record will be created that indicates a payment process has been started, and for some providers a similar initialisation request will be made to establish a new process.

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://tech.infosoft.no/schemas/2012/08">
    <soapenv:Header/>
    <soapenv:Body>
      <ns:StartPaymentRequest>
       <ns:PaymentSetupCode>IS</ns:PaymentSetupCode>
       <ns:Price>42000</ns:Price>
       <ns:CurrencyCode>NOK</ns:CurrencyCode>
       <ns:TaxPercent>0</ns:TaxPercent>
       <ns:ProductDescription>A two-phased payment</ns:ProductDescription>
       <ns:ExternalOrderId>TWO-PHASED</ns:ExternalOrderId>
       <ns:ReturnUrl>http://google.com</ns:ReturnUrl>
       <ns:CancelUrl>http://bing.com</ns:CancelUrl>
       <ns:ClientIpAddress>127.0.0.1</ns:ClientIpAddress>
       <ns:CultureName>nb-NO</ns:CultureName>
       <ns:PaymentFlow>TwoPhased</ns:PaymentFlow>
       <ns:PaymentOrderType>Subscription</ns:PaymentOrderType>
      </ns:StartPaymentRequest>
    </soapenv:Body>
</soapenv:Envelope>

The output from this requests include an order reference, and an URL that the customer should be redirected to. The order reference is used in the remainder of the process to update and complete it, as well as querying for information at a later time. Consider storing it for later use.

(3) Update Payment (Required for DIBS and ePay)

Once the customer is returned from the provider terminal, the payment can be updated with details that were not available upon initialisation, this can be achieved with the UpdatePayment method. Due to the way DIBS/ePay works, it is not possible to directly query for all the required information, instead the information is returned once the user has been redirect back to the shop, after inputting the credit card information.

Note

When using DIBS/ePay this step is REQUIRED, for all other providers it is optional and can be ignored. DIBS is special in that they have no support for getting important information like the credit card mask without communication with the browser, so consider keeping this information for the last step of the process. ePay have support for getting important information, but the agreement reference is needed for this an the only way to get it is via brower communication.

  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://tech.infosoft.no/schemas/2012/08">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:UpdatePaymentRequest>
          <ns:OrderReference>42</ns:OrderReference>
           <ns:ProviderOrderReference>ABCDEFGHIJKLMNO</ns:ProviderOrderReference>
           <ns:AgreementReference>12345678911</ns:AgreementReference>
           <ns:PaymentMethod>VISA</ns:PaymentMethod>
           <ns:CardMask>****-****-****-1234</ns:CardMask>
           <ns:CardExpiration>1337</ns:CardExpiration>
      </ns:UpdatePaymentRequest>
   </soapenv:Body>
</soapenv:Envelope>

(4) Complete Payment

CompletePayment serves the purpose of reserving (or withdrawing) the required amount on the customers bank account. In two-phased mode the amount is reserved, and in instant mode it is also captured immediately. In addition the payment process is marked as reserved (or completed) awaiting futher processing and association with a subscription.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://tech.infosoft.no/schemas/2012/08">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:CompletePaymentRequest>
         <ns:OrderReference>42</ns:OrderReference>
      </ns:CompletePaymentRequest>
   </soapenv:Body>
</soapenv:Envelope>

(5) Complete Subscription

Once the payment has been completed, the only remaining thing is to connect the subscription order and the payment using the CompleteSubscription method The important part here is to connect the order id, from the inital subscription order in step 1 with the payment order reference from step 2.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://tech.infosoft.no/schemas/2011/10">
  <soapenv:Header/>
  <soapenv:Body>
    <ns:CompleteSubscriptionRequest>
        <ns:OrderId>12345678</ns:OrderId>
        <ns:TitleCode>IS</ns:TitleCode>
        <ns:PaymentOrderReference>42</ns:PaymentOrderReference>
    </ns:CompleteSubscriptionRequest>
  </soapenv:Body>
</soapenv:Envelope>

Note

Important: If for some reason things fails here, and TwoPhased mode is used, the amount is reserved on the customer credit card but no subscription has been created, and it should possibly be reported somewhere. Critical: If for some reason things fails here, and Instant mode is used, the amount HAS BEEN TRANSFERED, but no subscription has been created. I.e. the customer has paid but received no product. This is bad and should be handled with care.

In addition to the subscription payment flow detailed above, it's possible for users to perform standalone payments using the methods PerformInvoicePayment and PerformBalancePayment. For more details on these methods, see Standalone Subscription Payments.

In case the user presses the cancel button, he or she is normally redirected back to the given cancel Url.
You should call the CancelPayment method if you want to cancellation to be reflected immediately in the backend. However it is not a requirement.

Note
Important: If you cancel a payment that has been completed, but has yet to be captured, it corresponds to the user not having paid and the reservation is cancelled - so only call cancel when the user has pressed cancel/abort.

Other Resources