Server-to-Server Registration Tokens

Standalone tokenization

The merchant collects card data from shopper and initiates the registration tokenization. No payment request/flow involved. A registration token is synchronously provisioned and returned to the merchant. The registration token can then be used in subsequent payments.

How it works

1. Create the token

Perform a server-to-server POST request with the required customer data, but excluding paymentType. The response to a successful request is an id that should be stored and used in subsequent payments.

Sample request:

curl https://test.prtpe.com/v1/registrations \
 -d "entityId=8a82941851252e930151341fd7e81794" \
 -d "paymentBrand=VISA" \
 -d "card.number=4242424318862572" \
 -d "card.expiryMonth=12" \
 -d "card.expiryYear=2026" \
 -d "card.holder=John Smith" \
 -d "card.cvv=123" \
 -d "testMode=EXTERNAL" \
 -H "Authorization: Bearer OGE4Mjk0MTg1MTI1MmU5MzAxNTEzNDFmZDdmZTE3OTh8bW5RUGZyTkE5bg=="

2. Send payment using the token

Perform a server-to-server POST request over the registration token retrieved in the previous step.
Alternatively, use one-click payment to authorize the payment with a selected stored registration token.

Sample request:

curl https://test.prtpe.com/v1/registrations/{id}/payments \
 -d "entityId=8a82941851252e930151341fd7e81794" \
 -d "paymentBrand=VISA" \
 -d "paymentType=DB" \
 -d "amount=17.99" \
 -d "currency=EUR" \
 -d "testMode=EXTERNAL" \
 -d "standingInstruction.type=RECURRING" \
 -d "standingInstruction.mode=INITIAL" \
 -d "standingInstruction.source=CIT" \
 -d "threeDSecure.eci=05" \
 -d "threeDSecure.authenticationStatus=Y" \
 -d "threeDSecure.version=2.2.0" \
 -d "threeDSecure.dsTransactionId=c75f23af-9454-43f6-ba17-130ed529507e" \
 -d "threeDSecure.acsTransactionId=2c42c553-176f-4f08-af6c-f9364ecbd0e8" \
 -d "threeDSecure.verificationId=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=" \
 -d "threeDSecure.amount=19.99" \
 -d "threeDSecure.currency=EUR" \
 -d "threeDSecure.flow=challenge" \
 -H "Authorization: Bearer OGE4Mjk0MTg1MTI1MmU5MzAxNTEzNDFmZDdmZTE3OTh8bW5RUGZyTkE5bg=="

Tokenization during payment

The merchant collects card data from shopper and initiates the registration tokenization along an account verification (zero amount auth) or initial purchase. A registration token is synchronously provisioned and returned to the merchant once payment is complete. The registration token can then be used in subsequent payments.

How it works

1. Create the token during payment

Perform a server-to-server POST request with createRegistration=true and all required payment and customer data, including payment type, amount and currency. The response to a successful request is a registrationId that should be stored and used in subsequent payments.

Sample request:

curl https://test.prtpe.com/v1/payments \
 -d "entityId=8a82941851252e930151341fd7e81794" \
 -d "paymentBrand=VISA" \
 -d "card.number=4242424240282675" \
 -d "card.expiryMonth=12" \
 -d "card.expiryYear=2026" \
 -d "card.holder=John Smith" \
 -d "card.cvv=123" \
 -d "paymentType=DB" \
 -d "amount=15.99" \
 -d "currency=EUR" \
 -d "createRegistration=true" \
 -d "testMode=EXTERNAL" \
 -d "standingInstruction.type=RECURRING" \
 -d "standingInstruction.mode=INITIAL" \
 -d "standingInstruction.source=CIT" \
 -d "threeDSecure.eci=05" \
 -d "threeDSecure.authenticationStatus=Y" \
 -d "threeDSecure.version=2.2.0" \
 -d "threeDSecure.dsTransactionId=c75f23af-9454-43f6-ba17-130ed529507e" \
 -d "threeDSecure.acsTransactionId=2c42c553-176f-4f08-af6c-f9364ecbd0e8" \
 -d "threeDSecure.verificationId=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=" \
 -d "threeDSecure.amount=19.99" \
 -d "threeDSecure.currency=EUR" \
 -d "threeDSecure.flow=challenge" \
 -H "Authorization: Bearer OGE4Mjk0MTg1MTI1MmU5MzAxNTEzNDFmZDdmZTE3OTh8bW5RUGZyTkE5bg=="

One-click payment

Speed up of the checkout process by re-using the raw card data a shopper entered previously. When the shopper returns on the merchant’s website an unscheduled one-click purchase with one of the saved registration tokens is performed. The cardholder initiated (CIT) payment is authorized with the real card data.

How it works

1. Authenticate the customer

You will need to authenticate the shopper against your records to obtain the respective registration tokens associated with the shopper's account. To prepare showing the one-click payment form you should retrieve the additional stored token data points that should enable the shopper checking out with the desired stored card:

• registration token identifier
• account brand
• last four digits of account number
• expiry date (if applicable)

2. Show the checkout form

Once you were able to retrieve the stored token information, you should offer them as options to shopper for checkout. We recommend offering normal payment methods alongside your One-Click payment page.

Show HTML example

<!DOCTYPE HTML>
<html>
  <head>
	<script>
	var wpwlOptions = {
		style: "card"
	}
	</script>
	<script src="https://test.prtpe.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>
	<style>
		body { background-color:white; width:720px; margin:auto;padding:10px;font-size:14px;}
		h2 { margin-top:25px;margin-bottom:10px;padding:5px;width:100%;background-color:#eee;
		border:1px solid #ccc;border-radius:6px;font-size: 16px;font-weight:normal; }
	</style>
  </head>
  <body>
  <h2><input type="radio" checked="checked" /> Checkout with stored payment details</h2>
	<table>
		<tr>
			<td width="100px">Visa</td>
			<td width="200px">xxxx-xxxx-xxxx-1234</td>
			<td width="200px">Dec / 2018</td>
		</tr>
	</table>
	<div><button type="submit" name="pay" class="myButton">Pay now</button></div><br /><br />
  <h2><input type="radio" /> Checkout with new payment method</h2>
	<form action="http://localhost/pay.html">
	  MASTER VISA AMEX CHINAUNIONPAY
	</form>
  </body>
</html>
		

3. Send the payment

When the shopper checks out via one-click form, all you need to do is sending a server-to-server POST request for a new payment over the selected registration token.

Sample request:

curl https://test.prtpe.com/v1/registrations/{id}/payments \
 -d "entityId=8a82941851252e930151341fd7e81794" \
 -d "paymentBrand=VISA" \
 -d "paymentType=DB" \
 -d "amount=18.99" \
 -d "currency=EUR" \
 -d "testMode=EXTERNAL" \
 -d "standingInstruction.type=RECURRING" \
 -d "standingInstruction.mode=INITIAL" \
 -d "standingInstruction.source=CIT" \
 -d "threeDSecure.eci=05" \
 -d "threeDSecure.authenticationStatus=Y" \
 -d "threeDSecure.version=2.2.0" \
 -d "threeDSecure.dsTransactionId=c75f23af-9454-43f6-ba17-130ed529507e" \
 -d "threeDSecure.acsTransactionId=2c42c553-176f-4f08-af6c-f9364ecbd0e8" \
 -d "threeDSecure.verificationId=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=" \
 -d "threeDSecure.amount=19.99" \
 -d "threeDSecure.currency=EUR" \
 -d "threeDSecure.flow=challenge" \
 -H "Authorization: Bearer OGE4Mjk0MTg1MTI1MmU5MzAxNTEzNDFmZDdmZTE3OTh8bW5RUGZyTkE5bg=="

Payment with token

The merchant submits a subsequent payment based on the card-on-file agreement available with the shopper. It can be a cardholder (CIT) or merchant (MIT) initiated payment transaction.

How it works

1. Send payment using the token

Perform a server-to-server POST request over the stored registration token with all required payment and customer data, including payment type, amount and currency.

Sample request:

curl https://test.prtpe.com/v1/registrations/{id}/payments \
 -d "entityId=8a82941851252e930151341fd7e81794" \
 -d "paymentBrand=VISA" \
 -d "paymentType=DB" \
 -d "amount=17.99" \
 -d "currency=EUR" \
 -d "standingInstruction.type=UNSCHEDULED" \
 -d "standingInstruction.mode=REPEATED" \
 -d "standingInstruction.source=MIT" \
 -d "testMode=EXTERNAL" \
 -H "Authorization: Bearer OGE4Mjk0MTg1MTI1MmU5MzAxNTEzNDFmZDdmZTE3OTh8bW5RUGZyTkE5bg=="

Token deletion

The merchant initiates a deletion request on the registration token. The deregistered token cannot be used anymore in subsequent payments.

How it works

1. Deregister stored card data

Perform a server-to-server DELETE request over the stored registration token.

Sample request:

curl -X DELETE "https://test.prtpe.com/v1/registrations/{id}\
?entityId=8a82941851252e930151341fd7e81794" \
 -H "Authorization: Bearer OGE4Mjk0MTg1MTI1MmU5MzAxNTEzNDFmZDdmZTE3OTh8bW5RUGZyTkE5bg=="

Token extension

The merchant has business requirements to keep unused registration tokens alive for a longer period than stipulated by the Data Retention Policy. The default retention period can get extended for up to 24-months. It applies to both card and non-card registration tokens. Examples:

• A card based registration token is generated today with expiry date 1-Feb-Y1. By default, the token is deleted 14 months after card expiration which is 1-Apr-Y2. If there is a good reason to keep the registration token for longer period, the 14 months retention period can be adjusted.
• Same rule applies for a non-card based registration token. However, the token is getting deleted 14 months after the last transaction performed with that registration token.

How it works

1. Extend token retention period

Perform a server-to-server POST request over the stored registration token to extend its retention. No additional parameters are required in the request.

Sample request:

curl https://test.prtpe.com/v1/registrations/{id}/extendlife \
 -d "entityId=8a82941851252e930151341fd7e81794" \
 -H "Authorization: Bearer OGE4Mjk0MTg1MTI1MmU5MzAxNTEzNDFmZDdmZTE3OTh8bW5RUGZyTkE5bg=="