CM Payments 2 (new api)

Let op testen via localhost/development kan niet.

CM Payments account

Voordat je kunt beginnen met het testen/gebruiken van de CM Payments 2 module, heb je een account nodig van CM.

Je krijgt, voor het gebruik van de API hierbij de volgende gegevens:

• API Swagger url   Bijv.: https://gateway.acceptance.cmpayments.nl/api/v1/docs/
• Client Id
• Client Secret  

Configuratie

De volgende 3 configuratie-stappen zijn nodig om de CM Payments 2 module te kunnen gebruiken in een scenario in TriplEforms:

• Project.tfProject -> CM Payments 2 module toevoegen aan TriplEforms-editor
• Licentie -> CM Payments 2 module licenseren voor het TriplEforms-project
• Web.config -> CM Payments 2 module basis-configuratie

Project.tfProject

De module dient te worden geïnstalleerd in het TriplEforms-project door het volgende toe te voegen aan het Project.TfProject-bestand. Dit kan op 2 manieren:

Via de TriplEforms-editor

• Dubbelklik in de Solution Explorer in de TriplEforms-editor op Project.
• Maak een nieuwe module aan onder het kopje Modules en noem deze "CM Payments 2":
  

Vul daarna de volgende gegevens in:

Handmatig

<ef:module id="CM Payments 2" type="usercontrol" url="~/CmPayments/CmPayments2.ascx" progressWeight="10">
 <ef:description>The CM Payments 2 user control.</ef:description>
 <ef:parameters>
  <ef:parameter name="PaymentUrl" mandatory="false" description="The base url for the CM Payments 2 api. Defaults to the url configured in the web.config." />
  <ef:parameter name="ClientId" mandatory="false" description="The client id that was provided by CM to identify this 'shop'. Defaults to the client id in the web.config." />
  <ef:parameter name="ClientSecret" mandatory="false" description="The client secret that was provided by CM to confirm the identify of the client id of this 'shop'. Defaults to the client secret in the web.config." />
  <ef:parameter name="ExpiresIn" mandatory="false" description="The number of hours the checkout transaction expipres in. Defaults to the ExpiresIn in the web.config." />
  <ef:parameter name="Reference" mandatory="true" description="The order identifier from the client." />
  <ef:parameter name="MerchantOrderReference" mandatory="true" description="The unique identifier, as known by the merchant." />
  <ef:parameter name="Description" mandatory="true" description="A description of the underlying value or reason of the payment." />
  <ef:parameter name="Amount" mandatory="true" description="The amount in minor units, e.g. in cents." />
  <ef:parameter name="Currency" mandatory="false" description="The order currency as ISO 4217 Alpha 3. Defaults to &quot;EUR&quot;." />
  <ef:parameter name="GivenName" mandatory="true" description="The given name (first name) of the consumer." />
  <ef:parameter name="MiddleName" mandatory="false" description="The middle name of the consumer." />
  <ef:parameter name="FamilyName" mandatory="true" description="The family name (last name) of the consumer." />
  <ef:parameter name="Gender" mandatory="false" description="The optional gender of the consumer: m or f (or leave blank)." />
  <ef:parameter name="Email" mandatory="true" description="The email address of the consumer." />
  <ef:parameter name="Language" mandatory="false" description="The language of the shopper as ISO 639-1 Alpha 2. Defaults to &quot;nl&quot;" />
  <ef:parameter name="CertificateThumbprint" mandatory="false" description="The thumbprint of the certificate used to ensure mTLS with CM. Defaults to the thumbprint set in the web.config." />
 </ef:parameters>
 <ef:results>
  <ef:result name="PaymentStatus" description="The status of the payment: Success, Expired, Cancelled, or Failed." />
  <ef:result name="TransactionId" description="The transaction id that CM Payments identifies this order with." />
  <ef:result name="Error" description="The error text when an error occurs." />
  <ef:result name="StatusCode" description="The optional status code when an error occurs." />
  <ef:result name="TransactionDetails" description="The transaction details." />
 </ef:results>
</ef:module>`

Licentie

De CM Payments-module is beschermd middels een licentiecategorie in de TriplEforms license.

Deze is (alleen door Kodision medewerkers!!) aan te zetten middels de TriplEforms LicenseTool.

Web.config

In de web.config van de betreffende website (TemplateProject of TemplateMijnOmgeving) dient de CM Payments 2 module te worden ingesteld:

<configuration>
 <kodision.tripleforms...>
  <cmPayments2 paymentUrl="..." clientId="..." clientSecret="..." expiresIn="..." certificateThumbprint="..." />
 </kodision.tripleforms>
</configuration>

mTLS in de CM Payments 2 module

De 'nieuwe' CM api heeft al mogelijkheid mTLS te activeren voor alle requests. mTLS staat voor mutual TLS en is een extra beveiliging stap om betalingsverkeer veiliger te maken. Het soort certificaat wat gebruikt moet worden is afhankelijk van de situatie:

Wij als sturen partij sturen ons publieke deel mee met requests naar CM. CM integreert dit publieke deel in het CM payments account wat gebruikt wordt door de sturende partij (wij, andere klant, etc). Dit moet in overleg gebeuren met CM, het kan over de mail geregeld worden.

Let op

Installeer de CA in de trusted root en het client ceritifcaat wat je meestuurt in de personal local store. Vergeet niet de rechten op de private key, geef de application pool hier rechten op.

Module gebruiken in een scenario

Sleep hiervoor de CM Payments 2 module vanuit de Toolbox onder de categorie Modules naar het scenario, en bewerk de eigenschappen.

Eigenschappen module

Onderstaand popup-dialoog wordt getoond. Het schermpje kan geresized worden als niet alle Parameters gezien kunnen worden.

Parameters

Dit zijn parameters die nodig zijn voor de werking van de CM Payments-module.

Result parameters

Hiermee kunnen result parameters worden gemapt naar een TriplEforms variabele zodat ze bij scenario-flow of in een formulier verder gebruikt kunnen worden.

Webhooks

CM ondersteunt webhooks. Dit zijn asynchrone callbacks (via een url) die door CM worden aangeroepen zodra een bepaalde status is bereikt.

Events

Op dit moment is er een event:

De webhook url kan worden ingesteld via de betreffende parameter. Dit moet een absolute url zijn (incl. domein) die vanuit CM aan te roepen is (i.e. geen localhost en geen relatieve url), bijv. 

PurchaseId op url

Er wordt door de module automatisch een querystring-parameter genaamd "purchaseId" toegevoegd aan de url met daarin de waarde van de MerchantOrderReference-parameter. Hiermee kan worden geïdentificeerd voor welke transactie het event is aangeroepen.

Bijv. "https://localhost/NonInteractive/scNonInteractive.aspx?purchaseId=order123"

LET OP: Deze querystring parameter "purchaseId" dient dus NIET handmatig te worden opgenomen in de webhook event url in de parameters!

Snelheid (rate) van aanroepen event

CM beschrijft het volgende omtrent de snelheid (rate) van het aanroepen van events:

Webhooks enable receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

TransactionDetails

Het TransactionDetails-object is een object met daarin gegevens over de (poging tot) betaling, zoals de ingestelde waardes en de status van de transactie.

LET OP dat in de tabel hieronder TF variabele-namen worden getoond, maar dat het woord TransactionDetails moet worden vervangen door de variabelenaam die is ingevuld bij de Result parameters van de module.

Flow

De flow vanuit de CM Payments 2 module kan worden gestuurd via voornamelijk de PaymentStatus-variabele, die altijd door de module wordt geretourneerd met 1 van de waardes "Success", "Expired", "Cancelled" of "Failure".

LET OP: naast de PaymentStatus en de StatusCode kan gebruik gemaakt worden van alle waardes in de TransactionDetails.

Zie hiervoor het hoofdstuk TransactionDetails hierboven.

Success

De status Success geeft aan dat de betaling is gelukt.

In het TransactionDetails-object kunnen de details worden verwerkt in vervolgstappen (opsturen naar KIM, of maken document) of vervolgformulieren.

Expired

De status Expired geeft aan dat de betaling is verlopen en niet is geaccepteerd door CM Payments 2. Dit komt voornamelijk doordat de betaler te lang heeft gedaan over de betaling. De ExpiresAt-DateTime wordt bepaald door de huidige datum/tijd + het aantal uren dat in ExpiresIn in de web.config of de parameters is ingesteld. Standaard is 4 uur.

Cancelled

De status Cancelled geeft aan dat de gebruiker de betaling heeft geannuleerd. Let op dat als een betaling mislukt is dit niet terugkomt vanuit CM: de betaler wordt na een mislukte betaling eerst teruggeleid naar een CM-pagina waar de betaler op 'Ga terug' kan klikken, wat de Cancelled-status veroorzaakt in het formulier.

In dit geval is het mogelijk om de flow terug naar de CM Payments 2 Module te laten gaan (evt. via een tussenformulier), zodat de gebruiker nogmaals de betaling kan proberen te doen.

Failed

De status Failed geeft aan dat er in de module of in de CM Payments 2 API een fout is opgetreden. Ook wordt er een Error-melding teruggegeven.

Als het gaat om een fout in de CM Payments API dan wordt de StatusCode gezet. Zie de mogelijke waardes in de CM Payments 2 Swagger API documentatie .

In dit geval is het mogelijk om de flow terug naar de CM Payments 2 Module te laten gaan (evt. via een tussenformulier of via aanpassing van parameter-settings), zodat de gebruiker nogmaals de betaling kan proberen te doen.

SSL Offloading

Als de TriplEforms applicatie draait op een omgeving waar een load balancer met SSL offloading actief is moet je de volgende appSetting (web.config) gebruiken om betalingen goed te laten verlopen.

<add key="publicOriginCM" value="--ENTER-APPLICATION-ROOT-URL-WITH-SCHEMA-HERE---" />