Tokenization

Tokenization makes your transactions easier. Once you have created a token, you don’t have to enter all the payment data every time, because the data will be stored with the tokenization. That makes it possible to use the payment data later. The token can be used for recurring transactions.

The Tokenization includes the registration, the use of the stored payment data and then the cancellation of the stored payment data.

Merchant needs to set authentication token in header for each request. To generate authentication token, please refer Auth token API.

Registering the payment data

You have two opportunities to create a token.

Store the data during a payment
Store the data as stand-alone

Customer sign up :

Merchant or Partner can register a customer with Munstartech using this API.

Customer sign up request is send over HTTPS to the merchantServices/api/v1/customerSignup resource using POST method.

Sample Request

Requester::

Language:

curl https://preprod.munstartech.com/merchantServices/api/v1/customerSignup \
curl --header "AuthToken:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjb25tZXJjaGFudDEiLCJyb2xlIjoibWVyY2hhbnQiLCJpc3MiOiJQWiIsImV4cCI6MTUwMTE0NjY0MX0.TFmGGKDUgkktmZQvrUTeox1buH1J6lgBVE3Mcy8OVjA"
	-d "authentication.memberId=11344" \
	-d "authentication.checksum=efac101d0b30bc51771567f9957cec58" \
	-d "customer.givenName=Jon" \
	-d "customer.surname=Doe" \
	-d "customer.sex=male" \
	-d "customer.email=jon.doe@domain.com" \
	-d "customer.phone=1234567890" \
	-d "shipping.country=UK" \
	-d "shipping.postcode=CH5 3LJ" \
	-d "customer.birthDate=19981202"

Sample Response

Requester::

Language:

JSON
XML

{
 "memberId": "11344",
 "customerId": "10279",
 "result": {
  "code": "00007",
  "description": "Cardholder successfully registered"
 },
 "timestamp": "2016-06-27 14:22:39"
}

Data storing during a payment:

While sending a POST request to the /transactionServices/REST/v1/payments endpoint it is possible to store the payment’s data simultaneous to the payment. The POST request you have to send is the createRegistration parameter with a value of true.

For future operations you need the parameter registrationId which you get as an additional response. With this parameter you have access to the stored parameter data later.

Sample Request

Mode:

Brand:

Language:

curl https://preprod.munstartech.com/transactionServices/REST/v1/payments \
curl --header "AuthToken:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjb25tZXJjaGFudDEiLCJyb2xlIjoibWVyY2hhbnQiLCJpc3MiOiJQWiIsImV4cCI6MTUwMTE0NjY0MX0.TFmGGKDUgkktmZQvrUTeox1buH1J6lgBVE3Mcy8OVjA"
	-d "authentication.memberId=11344" \
	-d "authentication.accountId=2967" \
	-d "authentication.checksum=3d1079465e8f3ffef07c086605289df1" \
	-d "authentication.terminalId=1106" \
	-d "merchantTransactionId=Rest Transaction 01" \
	-d "amount=50.00" \
	-d "currency=EUR" \
	-d "shipping.country=UK" \
	-d "shipping.city=Aston" \
	-d "shipping.state=NA" \
	-d "shipping.postcode=CH5 3LJ" \
	-d "shipping.street1=19 Scrimshire Lane" \
	-d "customer.telnocc=+44" \
	-d "customer.phone=07730432996" \
	-d "customer.email=john.doe@xyz.com" \
	-d "customer.givenName=John" \
	-d "customer.surname=Doe" \
	-d "customer.ip=192.168.0.1" \
	-d "customer.birthDate=19890202" \
	-d "card.number= 4000000000000051" \
	-d "card.expiryMonth=07" \
	-d "card.expiryYear=2022" \
	-d "card.cvv=745" \
	-d "paymentBrand=VISA" \
	-d "paymentMode=CC" \
	-d "paymentType=DB" \
	-d "merchantRedirectUrl=https://www.merchantRedirectUrl.com" \
	-d "createRegistration=true" \
	-d "customer.customerId=12345"

Sample Response

Mode :

Brand:

Language:

JSON
XML

{
 "paymentId": "55312",
 "registrationId": "lEboh2679uwnGjqKLS8H63WQBcM5PVv3",
 "paymentType": "DB",
 "paymentBrand": "VISA",
 "paymentMode": "CC",
 "amount": "50.00",
 "currency": "EUR",
 "descriptor": "Payon_EUR",
 "result": {
  "code": "00001",
  "description": "Transaction succeeded"
 },
 "card": {
  "bin": "417666",
  "last4Digits": "1056",
  "holder": "John Doe",
  "expiryMonth": "12",
  "expiryYear": "2018"
 },
 "timestamp": "2018-07-26 13:22:39",
 "merchantTransactionId": "10thOct2016-029751",
 "remark": "Approved",
 "transactionStatus": "Y",
 "tmpl_amount": "50.00",
 "tmpl_currency": "EUR"
}

Data storing as stand-alone:

Your second option for a registration is a stand-alone request to /transactionServices/REST/v1/registrations endpoint. What means that you directly receive a registration object in the ID field.

Sample Request

Mode:

Brand:

Language:

curl https://preprod.munstartech.com/transactionServices/REST/v1/registrations \
curl --header "AuthToken:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjb25tZXJjaGFudDEiLCJyb2xlIjoibWVyY2hhbnQiLCJpc3MiOiJQWiIsImV4cCI6MTUwMTE0NjY0MX0.TFmGGKDUgkktmZQvrUTeox1buH1J6lgBVE3Mcy8OVjA"
	-d "authentication.memberId=11344" \
	-d "authentication.checksum=14d66a100d669fa054514fae7ac5f7d0" \
	-d "shipping.language=ENG" \
	-d "shipping.country=UK" \
	-d "shipping.city=Aston" \
	-d "shipping.state=NA" \
	-d "shipping.postcode=CH5 3LJ" \
	-d "shipping.street1=19 Scrimshire Lane" \
	-d "customer.telnocc=+44" \
	-d "customer.phone=07730432996" \
	-d "customer.email=john.d@xyz.com" \
	-d "shipping.givenName=John" \
	-d "shipping.surname=veer" \
	-d "customer.ip=192.168.0.1" \
	-d "customer.birthDate=19890202" \
	-d "card.number=4000000000000051" \
	-d "card.expiryMonth=07" \
	-d "card.expiryYear=2022" \
	-d "card.cvv=745" \
	-d "paymentBrand=VISA" \
	-d "paymentMode=CC" \
	-d "customer.customerId=10014" \
	-d "createRegistration=true"

Sample Response

Mode :

Brand:

Language:

JSON
XML

{
 "registrationId": "kGuadVKOymeTYkuAYoxon2vKUzu88Po1",
 "memberId": "11344",
 "paymentBrand": "VISA",
 "paymentMode": "CC",
 "result": {
  "code": "00002",
  "description": "Registration successful"
 },
 "timestamp": "2018-07-24 19:24:19"
}

Payments using the stored payment data:

When the customer has just registered his data but didn’t send the payment on the same time. In this case you can store the data as stand-alone, so you send the payment directly to the /transactionServices/REST/v1/paywithtoken/{id} endpoint.

Sample Request

Language:

Sample Response

Language:

JSON
XML

{
 "paymentId": "34463",
 "paymentType": "PA",
 "result": {
  "code": "00001",
  "description": "Transaction succeeded"
 },
 "timestamp": "2016-06-27 15:05:25"
}

Use stored payment data for Recurring Payments

If you want to use the stored payment data for recurring payments, you need to add the parameter recurringType to your requests.

There are two different values for the payment request which depend on if it’s an initial or a subsequent payment request.

Use the value INITIAL for an initial payment
Use the value REPEATED for a subsequent payment.

If you are in need of a more detailed explanation, please check the Recurring tutorial.

Get Installment With Token

To get the list of Installment values, the request to be sent over /transactionServices/REST/v1/getInstallmentWithToken/{id} endpoint, where token has to be sent in place of {id} in the URL.

Sample Request

Language:

curl https://preprod.munstartech.com/transactionServices/REST/v1/getInstallmentWithToken/{id} \
curl --header "AuthToken:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjb25tZXJjaGFudDEiLCJyb2xlIjoibWVyY2hhbnQiLCJpc3MiOiJQWiIsImV4cCI6MTUwMTE0NjY0MX0.TFmGGKDUgkktmZQvrUTeox1buH1J6lgBVE3Mcy8OVjA"
	-d "authentication.memberId=11344" \
	-d "authentication.checksum=6LkB101d0b30bc51771567f9957cec58"

Sample Response

Language:

JSON
XML

{
 "registrationId": "ECctbYC5rprluSdQvsmRsSHS1v80f0u2",
 "card": {
  "bin": "444433",
  "last4Digits": "1111",
  "lastFourDigits": "1111"
 },
 "installment": "3,4"
}

Delete the Stored Data

Sometimes it’s necessary to delete the stored registration. Therefore send the paymentType with value DL to /transactionServices/REST/v1/paywithtoken/{id} endpoint. Use the HTTP POST method against the registrationId.

Sample Request

Language:

curl https://preprod.munstartech.com/transactionServices/REST/v1/paywithtoken/{id}\
-d authentication.memberId=11344\
-d authentication.accountId=2967\
-d authentication.checksum=3d1079465e8f3ffef07c086605289df1\
-d authentication.terminalId=1106\
-d paymentType=DL"

Sample Response

Language:

JSON
XML

{
 "registrationId": "kGuadVKOymeTYkuAYoxon2vKUzu88Po1",
 "result": {
  "code": "00003",
  "description": "Registration successfully deleted"
 },
 "timestamp": "2016-06-27 13:41:18"
}

The list of registration IDs

To get the list of registration IDs which registred against the customer.

The customer.customerId parameters has to be send if customer specific are details required with a POST request over HTTPS to the /transactionServices/REST/v1/getCardsAndAccounts .

Sample Request

Requester::

Language:

curl https://preprod.munstartech.com/transactionServices/REST/v1/getCardsAndAccounts \
curl --header "AuthToken:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjb25tZXJjaGFudDEiLCJyb2xlIjoibWVyY2hhbnQiLCJpc3MiOiJQWiIsImV4cCI6MTUwMTE0NjY0MX0.TFmGGKDUgkktmZQvrUTeox1buH1J6lgBVE3Mcy8OVjA"
	-d "authentication.memberId=11344" \
	-d "authentication.checksum=6LkB101d0b30bc51771567f9957cec58"

Sample Response

Requester::

Language:

JSON
XML

{
 "memberId": "11344",
 "customerId": "10179",
 "result": {
  "code": "0008",
  "description": "Your request processed successfully"
 },
 "cards": {
  "card": [
   {
    "registrationId": "rIGEIU5l5S7EAeiJ5O6bKU6Z9sARPx0q",
    "registrationStatus": "Y",
    "cardType": "VISA",
    "bin": "411111",
    "last4Digits": "1111",
    "expiryMonth": "03",
    "expiryYear": "2018"
   },
   {
    "registrationId": "mJYNJpbWgcmgsALMSiwXOSM9sqs2YcfK",
    "registrationStatus": "Y",
    "cardType": "VISA",
    "bin": "400000",
    "last4Digits": "0002",
    "expiryMonth": "12",
    "expiryYear": "2017"
   }
  ]
 },
 "bankaccounts": {
  "bankaccount": {
   "registrationId": "qcZCmDMTn19EVaRoRaoQ1UFDDjJx3OaP",
   "registrationStatus": "Y",
   "iban": "******************7890",
   "bic": "MARKDEF1100"
  }
 }
}

Hashing Rule

Munstartech is supporting MD5 Cryptographic Hash for the authenticity of payment request send to the server.

Below is the description of fields use for generating checksum:

memberId <Merchant ID as shared by Munstartech>
secureKey <Secure Key that can be generated through Munstartech's dashboard>
merchantTransactionId <Unique transaction ID provided by merchant>
amount <Amount of transaction>
cardNumber/bic <Card number or bic through which you want to register>
amount <Amount of transactions>
customerId <Customer's ID generated against the card or account>
givenName <First name of a Merchant>
surname <Last name of a Merchant>
partner's secureKey <Partner secure key that can be generated through Munstartech's dashboard >
merchant's secureKey <Merchant secure key that can be generated through Munstartech's dashboard >
registrationId <Generated after Card Registration>

How to generate Checksum?

A checksum has to be calculated with following combination & need to be send along with the authentication parameters in each server-to-server request:

Store the data during a payment:
<memberId>|<secureKey>|<merchantTransactionId>|<amount>

Store the data as stand-alone:
<memberId>|<secureKey>|<cardNumber>/<bic>

Using the stored payment data:
<memberId>|<secureKey>|<registrationId>|<amount>

Deleting the stored payment data:
<memberId>|<secureKey>|<registrationId>

Customer registration by Merchant:
<merchantId>|<Merchant's secureKey>|<givenName>|<surname>|<email>

Customer registration by Partner:
<partnerId>|<Partner's secureKey>|<givenName>|<surname>|<email>

Getting list of cards and accounts by Merchant:
<merchantId>|<Merchant's secureKey>

Getting list of cards and accounts by Partner:
<partnerId>|<Partner's secureKey>

Getting list of Installment with Token:
<memberid>|<secureKey>|<registrationId>

The Secure key varies, If the request is come from Partner then it must contain the Partner's secure key otherwise it will consider the Merchant's key.

Sample Code

Language:

import java.security.MessageDigest
def generateMD5Checksum() {
String values= "11344|secureKey|hcZRVi0AGc2jFZ82WNo1Ncs0oOYCdRvQ|50.00";
MessageDigest digest = MessageDigest.getInstance(MD5)
digest.update(values.bytes);
new BigInteger(1, digest.digest()).toString(16).padLeft(32, '0')
}