AllSecure Knowledge Base - *IMPORTANT* Guideline to meet Security Standards for OPEN Platform REST API

Please see the below best practices so that you stay up-to-date with the latest Security Standards for the public APIs. According to the API documentation, all the data parameters require to be sent in the request body and not in the URL.

What is the security concern?

Merchant sending API requests with data parameters (including authentication parameters) in URL.

What action the customer must take?

Merchant must send the Access-Token in the Authorization Bearer header. That will replace the use of the authentication parameters. The Access-Token will be taken from Merchant Portal or received from AllSecure. All the other data parameters are expected to go in the HTTPS request body. EntityId will stay as a mandatory parameter to indicate where to action the request.

What AllSecure will do?

Immediately:

AllSecure will allow accepting in the Authorization Bearer header of all requests
AllSecure will continue to allow current authentication mechanism

At deadline time (will be communicated to customers in advance):

AllSecure will disallow accepting requests with data parameters (including authentication parameters) in the URL
AllSecure will disallow accepting requests with access-token not in the Authorization Bearer header

Please find attached a couple of examples on how the requests look today and how they will change. This is not a comprehensive list of all OPP REST API requests supported but should give you a feeling about how to best tackle the integration API changes.

How it is today?

How it should be tomorrow?

SecurePay Integration Guide

1. Prepare the checkout

Checkout request with data parameters in URL

Checkout request with data parameters in the request body

	curl -X POST https://test.oppwa.com/v1/checkouts? \
	authentication.userId=8a8294174b7ecb28014b9699220015cc \
	&authentication.password=sy6KJsT8 \
	&authentication.entityId=8a8294174b7ecb28014b9699220015ca \
	&amount=101.00 \
	&currency=EUR \
	&paymentType=DB

	curl -X POST https://test.oppwa.com/v1/checkouts \
	-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
	-d "entityId=8a8294174b7ecb28014b9699220015ca" \
	-d "amount=92.00" \
	-d "currency=EUR" \
	-d "paymentType=DB"

2. Create the payment form - no change

3. Get the payment status

	curl -X GET https://test.oppwa.com/v1/checkouts/{id}/payment \
	authentication.userId=8a8294174b7ecb28014b9699220015cc \
	&authentication.password=sy6KJsT8 \
	&authentication.entityId=8a8294174b7ecb28014b9699220015ca

	curl -X GET https://test.oppwa.com/v1/checkouts/{id}/payment \
	-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
	-d "entityId=8a8294174b7ecb28014b9699220015ca"

Server-to-server synchronous workflow

Send an Initial Payment

Payment request with data parameters in URL

Payment request with data parameters in the request body

	url -X POST https://test.oppwa.com/v1/payments? \
	authentication.userId=8a8294174b7ecb28014b9699220015cc \
	&authentication.password=sy6KJsT8 \
	&authentication.entityId=8a8294174b7ecb28014b9699220015ca \
	&amount=101.00 \
	&currency=EUR \
	&paymentType=DB \
	&paymentBrand=VISA \
	&card.number=4200000000000000 \
	&card.holder=Niki Lauda \
	&card.expiryMonth=12 \
	&card.expiryYear=2020 \
	&card.cvv=123

	curl -X POST https://test.oppwa.com/v1/payments \
	-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
	-d "entityId=8a8294174b7ecb28014b9699220015ca" \
	-d "amount=101.00" \
	-d "currency=EUR" \
	-d "paymentType=DB" \
	-d "paymentBrand=VISA" \
	-d "card.number=4200000000000000" \
	-d "card.holder=Niki Lauda" \
	-d "card.expiryMonth=12" \
	-d "card.expiryYear=2020" \
	-d "card.cvv=123"

Server-to-server asinhrone transakcije

1. Send an Initial Payment

Payment request with data parameters in the URL

Payment request with data parameters in the request body

	curl -X POST https://test.oppwa.com/v1/payments? \
	authentication.userId=8a8294174b7ecb28014b9699220015cc \
	&authentication.password=sy6KJsT8 \
	&authentication.entityId=8a8294174b7ecb28014b9699220015ca \
	&amount=101.00 \
	&currency=EUR \
	&paymentBrand=PAYPAL \
	&paymentType=PA \
	&shopperResultUrl=https://allsecure.docs.oppwa.com/tutorials/server-to-server

	curl -X POST https://test.oppwa.com/v1/payments \
	-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
	-d "entityId=8a8294174b7ecb28014b9699220015ca" \
	-d "amount=101.00" \
	-d "currency=EUR" \
	-d "paymentBrand=PAYPAL" \
	-d "paymentType=PA" \
	-d "shopperResultUrl=https://allsecure.docs.oppwa.com/tutorials/server-to-server"

2. Redirect the shopper - no change

3. Get the payment status

Get payment status request with data parameters in URL

Get payment status request with data parameters in the request body

	curl -X GET https://test.oppwa.com/v1/payments/{id} \
	authentication.userId=8a8294174b7ecb28014b9699220015cc \
	&authentication.password=sy6KJsT8 \
	&authentication.entityId=8a8294174b7ecb28014b9699220015ca

	curl -X GET https://test.oppwa.com/v1/checkouts/{id}/payment \
	-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
	-d "entityId=8a8294174b7ecb28014b9699220015ca"

Server-to-server tokenization

Store the data as stand-alone

Registration request with data parameters in URL

Registration request with data parameters in the request body

	curl -X POST https://test.oppwa.com/v1/registrations? \
	authentication.userId=8a8294174b7ecb28014b9699220015cc \
	&authentication.password=sy6KJsT8 \
	&authentication.entityId=8a8294174b7ecb28014b9699220015ca \
	&paymentBrand=VISA \
	&card.number=4200000000000000 \
	&card.holder=Niki Lauda \
	&card.expiryMonth=12 \
	&card.expiryYear=2020 \
	&card.cvv=123

	curl -X POST https://test.oppwa.com/v1/registration \
	-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
	-d "entityId=8a8294174b7ecb28014b9699220015ca" \
	-d "paymentBrand=VISA" \
	-d "card.number=4200000000000000" \
	-d "card.holder=Niki Lauda" \
	-d "card.expiryMonth=12" \
	-d "card.expiryYear=2020" \
	-d "card.cvv=123"

Back-office payments

Refund a payment (capture, reversal would be similar)

Refund a payment with data parameters in URL

Refund a payment with data parameters in the request body

	curl -X POST https://test.oppwa.com/v1/payments? \
	authentication.userId=8a8294174b7ecb28014b9699220015cc \
	&authentication.entityId=8a8294174b7ecb28014b9699220015ca \
	&authentication.password=sy6KJsT8 \
	&amount=10.00 \
	&currency=EUR \
	&paymentType=RF

	curl -X POST https://test.oppwa.com/v1/payments \
	-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
	-d "entityId=8a8294174b7ecb28014b9699220015ca" \
	-d "amount=10.00" \
	-d "currency=EUR" \
	-d "paymentType=RF"

Recurring payments guide

Sending the initial Payment

Initial payment request with data parameters in URL

Initial payment request with data parameters in the request body

	curl -X POST https://test.oppwa.com/v1/payments \
	authentication.userId=8a8294174b7ecb28014b9699220015cc \
	&authentication.password=sy6KJsT8 \
	&authentication.entityId=8a8294174b7ecb28014b9699220015ca \
	&amount=92.00 \
	&currency=EUR \
	&paymentBrand=VISA \
	&paymentType=DB \
	&card.number=4200000000000000 \
	&card.holder=Niki Lauda \
	&card.expiryMonth=05 \
	&card.expiryYear=2020 \
	&card.cvv=123 \
	&recurringType=INITIAL \
	&createRegistration=true

	curl -X POST https://test.oppwa.com/v1/payments \
	-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
	-d "entityId=8a8294174b7ecb28014b9699220015ca" \
	-d "amount=92.00" \
	-d "currency=EUR" \
	-d "paymentBrand=VISA" \
	-d "paymentType=DB" \
	-d "card.number=4200000000000000" \
	-d "card.holder=Niki Lauda" \
	-d "card.expiryMonth=05" \
	-d "card.expiryYear=2020" \
	-d "card.cvv=123" \
	-d "recurringType=INITIAL" \
	-d "createRegistration=true"

Sending a repeated payment

Repeated payment request with data parameters in URL

Repeated payment request with data parameters in the request bod

	curl -X POST https://test.oppwa.com/v1/registrations/{id}/payments \
	authentication.userId=8a8294174b7ecb28014b9699220015cc \
	&authentication.password=sy6KJsT8 \
	&authentication.entityId=8a8294174b7ecb28014b9699220015ca \
	&amount=92.00 \
	&currency=EUR \
	&paymentType=PA \
	&recurringType=REPEATED

	curl -X POST https://test.oppwa.com/v1/payments \
	-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
	-d "entityId=8a8294174b7ecb28014b9699220015ca" \
	-d "amount=92.00" \
	-d "currency=EUR" \
	-d "paymentType=PA" \
	-d "recurringType=REPEATED"

Transaction Reports

Transaction Search Using paymentId

Transaction search using authentication data parameters in URL

Transaction search with authentication details in header

	curl -X GET https://test.oppwa.com/v1/query/{id}? \
	authentication.userId=8a8294174b7ecb28014b9699220015cc \
	&authentication.password=sy6KJsT8 \
	&authentication.entityId=8a8294174b7ecb28014b9699220015ca

	curl -X GET https://test.oppwa.com/v1/query/{id}/payment? \
	entityId=8a8294174b7ecb28014b9699220015ca \
	-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="