COPYandPAY Omni Tokens

Tokenization during payment

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

There are two ways to store the raw card details during a payment checkout:

• Merchant-determined tokenization (see below). Add createOmniToken=true in the checkout request.
• Shopper-determined tokenization. Add a checkbox to the COPYandPAY form to let the customer decide whether or not to store the raw card details.

How it works

1. Prepare the checkout

Perform a server-to-server POST request to prepare the checkout with the required payment and customer data, including the order type, amount and currency. The response to a successful request is an id required in the second step to create the payment form.

Sample request:

curl https://eu-test.oppwa.com/v1/checkouts \
 -d "entityId=8ac7a4c79394bdc801939736f1e8064f" \
 -d "testMode=EXTERNAL" \
 -d "createOmniToken=true" \
 -d "amount=31.12" \
 -d "currency=EUR" \
 -d "paymentType=DB" \
 -d "standingInstruction.mode=INITIAL" \
 -d "standingInstruction.source=CIT" \
 -d "standingInstruction.type=UNSCHEDULED" \
 -d "customer.givenName=Smith" \
 -d "customer.ip=192.168.0.0" \
 -d "customer.surname=John" \
 -d "customer.language=DE" \
 -d "customer.email=john.smith@gmail.com" \
 -d "billing.city=MyCity" \
 -d "billing.country=DE" \
 -d "billing.postcode=712121" \
 -d "billing.state=DE" \
 -d "billing.street1=MyStreet" \
 -d "integrity=true" \
 -H "Authorization: Bearer OGFjN2E0Yzc5Mzk0YmRjODAxOTM5NzM2ZjFhNzA2NDF8enlac1lYckc4QXk6bjYzI1NHNng="

2. Create the payment form

Create the payment form by adding the following lines of HTML/JavaScript to your page:

• With the checkout_id received from first step

  <script
  	src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkout_id}"
  	integrity="{integrity}"
  	crossorigin="anonymous">
  </script>
  

• With the shopperResultUrl as the page on your site where the end consumer should be redirected after the payment is complete

  <form action="{shopperResultUrl}" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>

Sample form:

3. Get the payment status

Once the payment request is processed, the customer is redirected to your shopperResultUrl along with a GET parameter resourcePath.

resourcePath=/v1/checkouts/{checkout_id}/payment

Sample request:

curl -G https://eu-test.oppwa.com/v1/checkouts/{id}/payment \
 -d "entityId=8ac7a4c79394bdc801939736f1e8064f" \
 -H "Authorization: Bearer OGFjN2E0Yzc5Mzk0YmRjODAxOTM5NzM2ZjFhNzA2NDF8enlac1lYckc4QXk6bjYzI1NHNng="

Standalone tokenization

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

How it works

1. Prepare the checkout

Perform a server-to-server POST request to prepare the checkout with the required customer data, including createOmniToken=true but excluding paymentType. The response to a successful request is an id required in the second step to create the tokenization form.

Sample request:

curl https://eu-test.oppwa.com/v1/checkouts \
 -d "entityId=8ac7a4c79394bdc801939736f1e8064f" \
 -d "testMode=EXTERNAL" \
 -d "createOmniToken=true" \
 -d "integrity=true" \
 -H "Authorization: Bearer OGFjN2E0Yzc5Mzk0YmRjODAxOTM5NzM2ZjFhNzA2NDF8enlac1lYckc4QXk6bjYzI1NHNng="

2. Create the token form

Create the tokenization form by adding the following lines of HTML/JavaScript to your page:

• With the checkout_id received from first step

  <script
  	src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkout_id}"
  	integrity="{integrity}"
  	crossorigin="anonymous">
  </script>
  

• With the shopperResultUrl as the page on your site where the end consumer should be redirected after the tokenization is complete

  <form action="{shopperResultUrl}" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>

Sample form:

3. Get the token status

Once the tokenization request is processed, the customer is redirected to your shopperResultUrl along with a GET parameter resourcePath.

resourcePath=/v1/checkouts/{checkout_id}/omnitoken

Sample request:

curl -G https://eu-test.oppwa.com/v1/checkouts/{id}/omnitoken \
 -d "entityId=8ac7a4c79394bdc801939736f1e8064f" \
 -H "Authorization: Bearer OGFjN2E0Yzc5Mzk0YmRjODAxOTM5NzM2ZjFhNzA2NDF8enlac1lYckc4QXk6bjYzI1NHNng="

4. Send payment using the token

Perform a server-to-server POST request over the omni token retrieved in the previous step.
Alternatively, use one-click checkout to authorize the payment with a selected stored omni token. Before proceeding with the payment based on the omniToken, a detokenization occurs to ensure the necessary card details are available for the transaction.

Sample request:

curl https://eu-test.oppwa.com/v1/omnitokens/{id}/payments \
 -d "entityId=8ac7a4c79394bdc801939736f1e8064f" \
 -d "paymentBrand=VISA" \
 -d "paymentType=DB" \
 -d "amount=17.99" \
 -d "currency=EUR" \
 -d "standingInstruction.type=UNSCHEDULED" \
 -d "standingInstruction.mode=INITIAL" \
 -d "standingInstruction.source=CIT" \
 -d "testMode=EXTERNAL" \
 -H "Authorization: Bearer OGFjN2E0Yzc5Mzk0YmRjODAxOTM5NzM2ZjFhNzA2NDF8enlac1lYckc4QXk6bjYzI1NHNng="

One-click checkout

Speed up of the checkout process by re-using the raw card data a shopper entered previously. A shopper returns on the merchant’s website (card is already omni tokenized). An unscheduled one-click purchase with one of the saved omni tokens is performed. A cardholder initiated (CIT) payment is authorized with the real card data as retrieved from the Token Vault for the omni token.

How it works

1. Prepare the checkout

Perform a server-to-server POST request to prepare the checkout with the required payment data, including the omni token IDs. The stored card on files should be sent in the omniToken[n].id parameter, where n is a sequence number from zero, incrementing for each of the customer's omni token IDs. The response to a successful request is an id required in the second step to create the one-click payment form.

Sample request:

curl https://eu-test.oppwa.com/v1/checkouts \
 -d "entityId=8ac7a4c79394bdc801939736f1e8064f" \
 -d "testMode=EXTERNAL" \
 -d "omniTokens[0].id=4242422722377457" \
 -d "omniTokens[1].id=5555555389278796" \
 -d "omniTokens[2].id=349360734671451" \
 -d "amount=31.13" \
 -d "currency=EUR" \
 -d "paymentType=DB" \
 -d "standingInstruction.mode=REPEATED" \
 -d "standingInstruction.source=CIT" \
 -d "standingInstruction.type=UNSCHEDULED" \
 -d "integrity=true" \
 -H "Authorization: Bearer OGFjN2E0Yzc5Mzk0YmRjODAxOTM5NzM2ZjFhNzA2NDF8enlac1lYckc4QXk6bjYzI1NHNng="

2. Create the payment form

Create the payment form by adding the following lines of HTML/JavaScript to your page:

• With the checkout_id received from first step

  <script
  	src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkout_id}"
  	integrity="{integrity}"
  	crossorigin="anonymous">
  </script>
  

• With the shopperResultUrl as the page on your site where the end consumer should be redirected after the payment is complete

  <form action="{shopperResultUrl}" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>

When COPYandPAY builds the payment form to display stored cards, a detokenization process is performed for each available stored card or omniToken using the Token Vault. This process retrieves essential card details such as the last four digits, expiry date, and holder name (if available). The detokenization operation will now appear as a separate transaction in the system, identified by the DT paymentType.

Sample form:

3. Get the payment status

Once the payment request is processed, the customer is redirected to your shopperResultUrl along with a GET parameter resourcePath.

resourcePath=/v1/checkouts/{checkout_id}/payment

Sample request:

curl -G https://eu-test.oppwa.com/v1/checkouts/{id}/payment \
 -d "entityId=8ac7a4c79394bdc801939736f1e8064f" \
 -H "Authorization: Bearer OGFjN2E0Yzc5Mzk0YmRjODAxOTM5NzM2ZjFhNzA2NDF8enlac1lYckc4QXk6bjYzI1NHNng="