Wiki source code of Payment API Client

Last modified by Thomas Warren on 2020/01/23 13:42

7.1	1	## Prerequisites
3.1	2
7.1	3	---
3.1	4
7.1	5	* Java 11
	6	* VueJS
	7	* Maven
	8	* Postgres
3.1	9
7.2	10	## GitHub
	11	---
	12
7.4	13	* [Payment Api Client](https://github.com/PayEx/vas-payment-api-client)
7.2	14
7.3	15	## Swagger documentation
	16
	17	---
	18
	19	* [Payment API Swagger](https://stage-evc.payex.com/payment-api/swagger-ui.html)
	20
7.1	21	## Project setup
3.1	22
7.1	23	---
3.1	24
7.1	25	vas-payment-api-client
6.1	26	├─┬ backend → backend module with Spring Boot code
	27	│ ├── src
	28	│ └── pom.xml
	29	├─┬ frontend → frontend module with Vue.js code
	30	│ ├── src
	31	│ └── pom.xml
7.1	32	└── pom.xml → Maven parent pom managing both modules
3.1	33
7.1	34	## Security
3.1	35
7.1	36	---
3.1	37
7.1	38	<details>
	39	<summary>Oauth2:</summary>
3.1	40
7.1	41	VasPublicPaymentApi requires an OAuth2 access token for interaction.
	42	This application automatically handles token fetching and refreshing by using [Spring Security](https://docs.spring.io/spring-security-oauth2-boot/docs/current/reference/htmlsingle/#boot-features-security-custom-user-info-client).
	43	Configuration values are set in [application.yml](https://github.com/PayEx/vas-payment-api-client/blob/master/backend/src/main/resources/application.yml):
3.1	44
7.1	45	```yaml
6.1	46	# "XXX" Should be replaced by value provided by PayEx
	47	# CLIENT_ID/CLIENT_SECRET/VAS_AUTH_SERVER_URL can also be set in docker-compose.yml as environment variables if running with docker
	48	# The application will see if environment variables are present, if not fall back to "XXX" values.
	49	vas-payment-api:
	50	oauth2:
	51	client:
	52	grantType: client_credentials
	53	clientId: "${CLIENT_ID}:XXX"
	54	clientSecret: "${CLIENT_SECRET}:XXX"
	55	accessTokenUri: "${VAS_AUTH_SERVER_URL}:XXX"
7.1	56	scope: publicapi
	57
	58	```
3.1	59
7.1	60	And the implementation of these are located in [Oauth2RestTemplateConfiguration.java](https://github.com/PayEx/vas-payment-api-client/blob/master/backend/src/main/java/com/payex/vas/demo/config/security/Oauth2RestTemplateConfiguration.java):
3.1	61
7.1	62	```java
6.1	63	public class Oauth2RestTemplateConfiguration {
7.1	64	//...
6.1	65	@Bean
	66	@ConfigurationProperties("vas-payment-api.oauth2.client")
	67	protected ClientCredentialsResourceDetails oAuthDetails() {
	68	return new ClientCredentialsResourceDetails();
7.1	69	}
3.1	70
7.1	71	@Bean
6.1	72	protected RestTemplate restTemplate() {
	73	var restTemplate = new OAuth2RestTemplate(oAuthDetails());
7.1	74	restTemplate.setInterceptors(ImmutableList.of(externalRequestInterceptor()));
6.1	75	restTemplate.setRequestFactory(httpRequestFactory());
	76	return restTemplate;
	77	}
7.1	78	//...
6.1	79	}
	80	```
7.1	81	</details>
3.1	82
7.1	83	<details>
3.1	84
7.1	85	<summary>HMAC:</summary>
3.1	86
7.1	87	The API also requires HMAC authentication to be present in a request.
	88	In this client the HMAC value is automatically calculated by [HmacSignatureBuilder.java](https://github.com/PayEx/vas-payment-api-client/blob/master/backend/src/main/java/com/payex/vas/demo/config/security/HmacSignatureBuilder.java) and added to all outgoing requests in [ExternalRequestInterceptor.java](https://github.com/PayEx/vas-payment-api-client/blob/master/backend/src/main/java/com/payex/vas/demo/config/ExternalRequestInterceptor.java)
3.1	89
7.1	90	HMAC is implemented using SHA-512 secure hash algorithm.
3.1	91
7.1	92	Expected `Hmac` header format is:
3.1	93
7.1	94	```text
	95	HmacSHA512 <user>:<nonce>:<digest>
	96	```
3.1	97
7.1	98	where `digest` is a Base64 formatted HMAC SHA512 digest of the following string:
3.1	99
7.1	100	```text
6.1	101	METHOD\n
	102	RESOURCE\n
	103	USER\
	104	NONCE\n
	105	DATE\n
	106	PAYLOAD\n
7.1	107	```
3.1	108
7.1	109	`METHOD` (mandatory) the requested method (in upper case) `RESOURCE` (mandatory) the path to desired resource (without hostname and any query parameters)
	110	`NONSE` (mandatory) a unique value for each request ([UUID](https://tools.ietf.org/rfc/rfc4122.txt)) `DATE`(optional) same as `Transmission-Time` if provided as seperate header. Uses [ISO8601 standard](https://en.wikipedia.org/wiki/ISO_8601) `PAYLOAD` (optional) body of request
3.1	111
7.1	112	Example request:
3.1	113
7.1	114	```bash
6.1	115	curl -X POST \
7.1	116	https://stage-evc.payex.com/payment-api/api/payments/payment-account/balance \
6.1	117	-H 'Accept: /' \
	118	-H 'Agreement-Merchant-Id: XXX' \
	119	-H 'Authorization: Bearer XXX' \
	120	-H 'Hmac: HmacSHA512 user:21a0213e-30eb-85ab-b355-a310d31af30e:oY5Q5Rf1anCz7DRm3GyWR0dvJDnhl/psylfnNCn6FA0NOrQS3L0fvyUsQ1IQ9gQPeLUt9J3IM2zwoSfZpDgRJA==' \
	121	-H 'Transmission-Time: 2019-06-18T09:19:15.208257Z' \
	122	-H 'Session-Id: e0447bd2-ab64-b456-b17b-da274bb8428e' \
	123	-d '{
	124	"accountIdentifier": {
	125	"accountKey": "7013369000000000000",
	126	"cvc": "123",
	127	"expiryDate": "2019-12-31",
	128	"instrument": "GC"
	129	}
	130	}'
7.1	131	```
3.1	132
7.1	133	In this example `USER` is user and `SECRET` is secret.
3.1	134
7.1	135	The plain string to `digest` would then be:
3.1	136
7.1	137	```text
6.1	138	POST
	139	/payment-api/api/payments/payment-account/balance
	140	user
	141	21a0213e-30eb-85ab-b355-a310d31af30e
	142	2019-06-18T09:19:15.208257Z
	143	{
	144	"accountIdentifier": {
	145	"accountKey": "7013360000000000000",
	146	"cvc": "123",
	147	"expiryDate": "2020-12-31",
	148	"instrument": "CC"
	149	}
	150	}
7.1	151	```
3.1	152
7.1	153	The plain `digest` string is then hashed with `HmacSHA512` algorithm and the `SECRET`. Finally we Base64 encode the hashed value. This is the final `digest` to be provided in the `Hmac` header.
3.1	154
7.1	155	Final `Hmac` header value:
3.1	156
7.1	157	```text
6.1	158	HmacSHA512 user:21a0213e-30eb-85ab-b355-a310d31af30e:oY5Q5Rf1anCz7DRm3GyWR0dvJDnhl/psylfnNCn6FA0NOrQS3L0fvyUsQ1IQ9gQPeLUt9J3IM2zwoSfZpDgRJA==
7.1	159	```
3.1	160
7.1	161	#### Postman example script
3.1	162
7.1	163	In pre-request script copy/paste the following snippet:
3.1	164
7.1	165	```javascript
3.1	166
7.1	167	var user = 'user';
6.1	168	var secret = 'secret';
	169	var transmissionTime = (new Date()).toISOString();
7.1	170	var sessionId = guid();
3.1	171
7.1	172	var hmac = generateHMAC(user, secret, transmissionTime);
	173	console.log('hmac: ' + hmac);
3.1	174
7.1	175	//Set header values
6.1	176	pm.request.headers.add({key: 'Hmac', value: hmac });
	177	pm.request.headers.add({key: 'Transmission-Time', value: transmissionTime });
7.1	178	pm.request.headers.add({key: 'Session-Id', value: sessionId });
3.1	179
7.1	180	function generateHMAC(user, secret, transmissionTime) {
3.1	181
7.1	182	var algorithm = "HmacSHA512";
6.1	183	var separator = ":";
	184	var method = request.method.toUpperCase();
7.1	185	var nonce = generateNonce(); //UUID
6.1	186	var date = transmissionTime;
7.1	187
	188	var uri_path = replaceRequestEnv(request.url.trim()).trim().replace(new RegExp('^https?://[^/]+/'), '/'); // strip hostname
	189	uri_path = uri_path.split("?")[0]; //Remove query paramters
6.1	190	var payload = _.isEmpty(request.data) ? "" : request.data;
	191	var macData = method + '\n'
	192	+ uri_path + '\n'
	193	+ user + '\n'
	194	+ nonce + '\n'
	195	+ date + '\n'
7.1	196	+ payload + '\n';
3.1	197
7.1	198	macData = replaceRequestEnv(macData);
	199	console.log('data to mac: ' + macData);
3.1	200
7.1	201	var hash = CryptoJS.HmacSHA512(macData, secret);
6.1	202	var digest = CryptoJS.enc.Base64.stringify(hash);
	203	return algorithm + " " + user + separator + nonce + separator + digest;
7.1	204	}
3.1	205
7.1	206	function replaceRequestEnv(input) { //manually set environments to they are populated before hashing
	207	return input.replace(/{{([^)]+)}}/g, function (str, key) {
6.1	208	var value = pm.environment.get(key);
	209	return value === null ? pm.varables.get(key) : value;
	210	});
7.1	211	}
3.1	212
7.1	213	function generateNonce() {
6.1	214	return guid();
7.1	215	}
3.1	216
7.1	217	function guid() {
6.1	218	function s4() {
	219	return Math.floor((1 + Math.random()) * 0x10000)
	220	.toString(16)
	221	.substring(1);
7.1	222	}
3.1	223
7.1	224	return s4() + s4() + '-' + s4() + '-' + s4() + '-' +
6.1	225	s4() + '-' + s4() + s4() + s4();
7.1	226	}
3.1	227
7.1	228	```
	229	</details>
3.1	230
7.1	231	### Security documentation
3.1	232
7.1	233	---
3.1	234
7.1	235	* [OAuth2](https://oauth.net/2/)
	236	* [Client Credentials](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/)
	237	* [The RESTful CookBook: HMAC](http://restcookbook.com/Basics/loggingin/)
	238	* [HMAC - Wikipedia](https://en.wikipedia.org/wiki/HMAC)
3.1	239
7.1	240	## First App run
3.1	241
7.1	242	---
3.1	243
7.1	244	NB! The application expects a PostgreSQL server to be running on localhost with a username `test` and password `test` to exist.
	245	This can automatically be configured if PostgreSQL server is started in docker with environment variables `POSTGRES_USER=test` and `POSTGRES_PASSWORD=test` are set (See [docker-compose.yml](https://github.com/PayEx/vas-payment-api-client/blob/master/docker-compose.yml)).
3.1	246
7.1	247	Inside the root directory, do a:
3.1	248
7.1	249	```bash
6.1	250	mvn clean install
7.1	251	```
3.1	252
7.1	253	Run the Spring Boot App:
3.1	254
7.1	255	```bash
	256	mvn --projects backend spring-boot:run
	257	```
3.1	258
7.1	259	Now go to <http://localhost:8080/> and have a look at your new client.
3.1	260
7.1	261	## Testing application
3.1	262
7.1	263	---
3.1	264
7.1	265	1. Add a new card with provided details from PayEx.
	266	1. Click on newly added Card
	267	1. Click on "initiate payment" to create a new transaction
3.1	268
7.1	269	## Build docker image:
3.1	270
7.1	271	---
3.1	272
7.1	273	```bash
	274	mvn --projects backend clean compile jib:dockerBuild
	275	```
3.1	276
7.1	277	## Deploy to local docker:
3.1	278
7.1	279	---
3.1	280
7.1	281	```bash
6.1	282	docker-compose up -d
7.1	283	```

Applications

More applications

Tips

You can click on the arrows next to the breadcrumb elements to quickly navigate to sibling and children pages.

Need help?

If you need help with XWiki you can contact:

Wiki source code of Payment API Client

Applications

Navigation

Tips

Need help?