Transaction Groups Migration

We are committed to providing our users with the most efficient and reliable payment processing solutions and strive to stay up-to-date with the latest industry trends and advancements. As the payment industry evolves, we recognize the need to adapt our APIs to support new payment methods, such as MobilePay. Our brand-new APIs that revolve around transaction groups instead of single transactions impact your payment processing. This guide explains the necessary changes and essential information related to this migration.

📘

You only need to migrate if you wish to process MobilePay

You currently only need to migrate from the transactionId to the transactionGroupsId flows if you wish to process MobilePay. Please get in touch if you are unsure if this change is required or not. You will still have the option to continue using your currently implemented transactionId flows alongside the new transactionGroupId flows.

Why is this migration needed, and what will change?

Some MobilePay services may perform multiple authorization attempts instead of the traditional one authorization per transaction approach. This change can impact how our APIs interact with your environments. You must know the few API changes if you wish to introduce MobilePay to your available payment methods.

The main changes are listed below:

• The URL of our APIs will change. Instead of calling the transactions APIs, you will call the transactionGroups APIs.
• The init response will contain a transactionGroupId and not a transactionId anymore. This will newly have the format UUID.
• The transactionGroupId will remain active for 60 minutes, and not the usual 30 minutes of a transactionId.
• For MobilePay transactions and in some cases only, the transaction group will contain more than one transactionId.
• Only one successful authorization can exist in one transaction group.
• Our settle, cancel, and credit API will only be available for successful authorizations. It will hence only be applied on the last transaction available in the transaction group.
• Our webhook will contain a transactionGroupId and the usual transaction information related to the last authorization attempt.

Changes related to our URLs

The changes below are related to the part appended after the environment URL. The first part of our production and sandbox URLs will remain the same than the transactionId URLs.

Changes related to the API response body

As discussed in the overview, the response we send back to your systems should be almost the same as with the transactionId flows. The main difference is that you will get a transactionGroupId instead of the usual transactionId. The format will be UUID and not a numeric value anymore. You will also get back a transactionGroupStatus in our status response.

{
	"transactionGroupId": "ecb1d7b1-cab0-0001-0000-0187c327ea15"
}

{
	"acquirerAuthorizationCode": "164516",
	"card": {
		"masked": "540400xxxxxx0001"
	},
	"transactionGroupId": "ecb1d7b1-cab0-0001-0000-0187c32cf70a"
}

{
	"merchantId": "{merchantId}",
	"type": "payment",
	"status": "authorized",
	"currency": "CHF",
	"refno": "my-reference-1234",
	"paymentMethod": "ECA",
	"detail": {
		"authorize": {
			"amount": 10,
			"acquirerAuthorizationCode": "164948"
		}
	},
	"card": {
		"masked": "540400xxxxxx0001",
		"expiryMonth": "06",
		"expiryYear": "25",
		"info": {
			"brand": "MCI",
			"type": "credit",
			"usage": "consumer",
			"country": "CH",
			"issuer": "DATATRANS"
		}
	},
	"history": [
		{
			"action": "authorize",
			"amount": 10,
			"source": "api",
			"date": "202X-04-27T14:49:47Z",
			"success": true,
			"ip": "127.0.0.1"
		}
	],
	"transactionGroupId": "ecb1d7b1-cab0-0001-0000-0187c3311b26",
	"transactionGroupStatus": "SUCCESSFUL"
}

Changes related to our payment forms (Redirect Lightbox)

The payment page URL that you have to redirect your users to will newly require a new id instead of the transactionId. The exact URL can be retrieved from the header Location passed in our init response.

https://pay.sandbox.datatrans.com/upp/v1/start/{redirectId}

Changes related to our webhook

Our webhook will only be called upon a successful authorization (success, error) and after the timeout of a transactionGroupId occurs (cancel). Similar to the status API, the body will contain a transactionGroupId and the transactionGroupStatus.

{
  "merchantId" : "1100012345",
  "type" : "payment",
  "status" : "authorized",
  "currency" : "CHF",
  "refno" : "Pre-5019603176",
  "paymentMethod" : "ECA",
  "detail" : {
    "authorize" : {
      "amount" : 100,
      "acquirerAuthorizationCode" : "165633"
    }
  },
  "language" : "en",
  "card" : {
    "masked" : "540400xxxxxx0001",
    "expiryMonth" : "06",
    "expiryYear" : "25",
    "info" : {
      "brand" : "MCI",
      "type" : "credit",
      "usage" : "consumer",
      "country" : "CH",
      "issuer" : "DATATRANS"
    },
    "3D" : {
      "authenticationResponse" : "Y"
    }
  },
  "history" : [ {
    "action" : "init",
    "amount" : 100,
    "source" : "api",
    "date" : "202X-04-27T14:56:19Z",
    "success" : true
  }, {
    "action" : "authorize",
    "amount" : 100,
    "source" : "redirect",
    "date" : "202X-04-27T14:56:33Z",
    "success" : true,
    "ip" : "12.12.12.12"
  } ],
  "transactionGroupId" : "ecb1d7b1-cab0-0001-0000-0187c3370a4e",
  "transactionGroupStatus" : "SUCCESSFUL"
}

Questions?

Any questions? Get in touch with us! We are happy to answer any questions related to this migration.