CM Payments 2 (new api)

TriplEforms 4.3

Gemaakt door Mark Duijkers, Gewijzigd op Fri, 23 Sep 2022 om 01:31 PM op Mark Duijkers

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:



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":
    image.png

Vul daarna de volgende gegevens in:
image.png


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>


AttribuutBeschrijving
paymentUrlDe basis-url voor de CM Payments 2 api die je wilt gebruiken.
De acceptatie-url is de volgende: https://gateway.acceptance.cmpayments.nl 
clientIdHet id van het CM store-account, bijv. bf46acd2af6678f7870faa8ec23ea34450bd7bdf
clientSecretDe secret key die nodig is om de API te mogen gebruiken, bijv. 9eee220a0be7e73ed5312976e6f7ca4b059a9ee0
expiresInOptioneel: Het aantal uur dat een betalingstransactie geldig: binnen deze termijn moet de betaling voltooid zijn. Default waarde is 4 (uur).
certificateThumbprintOptioneel: De thumbprint van het certificaat om voor mTLS te gebruiken. Kijk hier voor meer uitleg.

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.

image.png


Parameters

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


ParameterVerplichtOmschrijving
PaymentUrlNeeHiermee kan de PaymentUrl, zoals die in de Web.config is ingesteld, worden overschreven.
ClientIdNeeHiermee kan de ClientId, zoals die in de Web.config is ingesteld, worden overschreven.
ClientSecretNeeHiermee kan de ClientSecret, zoals die in de Web.config is ingesteld, worden overschreven.
ExpiresInNeeHiermee kan de ExpiresIn, zoals die in de Web.config is ingesteld, worden overschreven. Deze waarde is in uren.
ReferenceJaEen ordernummer of -referentie die de gebruiker te zien krijg.
MerchantOrderReferenceJaEen ordernummer of -referentie die intern door de store wordt gebruikt. Kan gelijk zijn aan de Reference.
DescriptionJaEen (korte) beschrijving voor de order en/of het bedrag dat betaald moet worden.
AmountJaEen bedrag groter dan 0 in minor units van de opgegeven Currency.
Bij "EUR" (Euro) zijn dit Euro-centen: €1,23 wordt dus 123.
CurrencyNeeDe betaaleenheid waarin het bedrag is opgegeven.
Dit dient een geldige ISO 4217 Alpha 3 currency te zijn.
 -> De default is "EUR" (Euro).
EmailJaHet e-mailadres van de betaler.
GivenNameJaDe voornaam van de betaler.
MiddleNameJaDe middelste naam (of tussenvoegsel) van de betaler.
FamilyNameJaDe achternaam van de betaler.
GenderNeeHet optionele geslacht van de betaler. Mogelijke waardes: f of m (of leeg).
LanguageNeeDe gewenste taal voor de betaler.
Dit dient een geldige ISO 639-1 Alpha 2 language te zijn.
 -> De default is "nl" (Nederlands).
CertificateThumbprintNeeDe thumbprint van het certificaat te gebruiken bij mTLS. 
WebHookEvent_FINALSTATUSNeeWebhook-url. Indien gezet wordt deze url aangeroepen door CM wanneer de status niet langer "OPEN" is.


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.

Result parameterOmschrijving
PaymentStatusDe betaalstatus.
Een van de waardes: "Success""Expired""Cancelled" of "Failure".
TransactionIdDit is de unieke sleutel (GUID) waaronder de betalingstransactie bij CM Payments 2 aangemaakt is.
ErrorDe foutmelding als er een error is opgetreden.
StatusCodeEen optionele Html StatusCode als er een error is opgetreden.
Zie voor geldige waardes de CM Payments 2 Swagger documentatie-pagina .
Bij het betalen wordt eerst een POST /authorization/oauth2/token gedaan om toegang te krijgen, gevolgd door een POST /paymentmethods/checkout/v1/transactions, en als laatste een GET /paymentmethods/checkout/v1/transactions na het betalen.
TransactionDetailsDit is een object waarin allerlei gegevens staan over de (gepoogde) betalingstransactie.
Zie de TransactionDetails-tabel hieronder voor de eigenschappen van dit object.


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:

EventParameterOmschrijving
FINALSTATUSWebHookEvent_FINALSTATUSWanneer de status van de transactie zijn eindstatus bereikt; niet langer "OPEN" is.


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.

VariabeleType
TransactionDetailsObject
TransactionDetails.IdString
TransactionDetails.ReferenceString
TransactionDetails.AmountInt
TransactionDetails.CurrencyCurrencyISO 4217 Alpha 3 
TransactionDetails.ConsumerObject
  TransactionDetails.Consumer.GivenNameString
  TransactionDetails.Consumer.MiddleNameString
  TransactionDetails.Consumer.FamilyNameString
  TransactionDetails.Consumer.EmailString
  TransactionDetails.Consumer.GenderEnum ("f""m""")
TransactionDetails.MerchantOrderReferenceString
TransactionDetails.DescriptionString
TransactionDetails.ExpiresAtDateTime
TransactionDetails.LanguageLanguageISO 639-1 Alpha 2 
TransactionDetails.StatusEnum ("OPEN""SUCCESS""CANCELLED""EXPIRED""FAILURE")
TransactionDetails.CreatedAtDateTime


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---" />

Deze setting zorgt ervoor dat de origin url van het request niet op http, maar onder https komt te staan.


Was dit artikel nuttig?

Dat is fantastisch!

Hartelijk dank voor uw beoordeling

Sorry dat we u niet konden helpen

Hartelijk dank voor uw beoordeling

Laat ons weten hoe we dit artikel kunnen verbeteren!

Selecteer tenminste een van de redenen
CAPTCHA-verificatie is vereist.

Feedback verzonden

We stellen uw moeite op prijs en zullen proberen het artikel te verbeteren