SecurePay Network Tokens

Last updated:April 5th, 2024

SecurePay allows you to securely collect card data from shoppers and initiate provisioning of a network token with the respective card network. While the network token is being provisioned, you are immediately receiving a registration token to store it for future usage e.g. recurring payments, one-click payments.

To better understand network tokens in eCommerce and inStore, please read Tokenization Guide.
To know which acquirers do support network tokens, please reach out to your Customer Success Manager.

Use cases

Standalone tokenization

Provision a network token to be used later in payments.

Select

Tokenization during payment

Provision a network token during the initial payment or account verification.

Select

One-click checkout

Authorize cardholder initiated payment with selected token.

Select

Standalone tokenization

The merchant collects card data from shopper via widget 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. In the background, a network token is being provisioned by the card network with Issuer involved in the token approval process to make it active for payments.

How it works

Without 3D Secure
With 3D Secure and Fraud

Prepare the checkout

Send the request parameters server-to-server to prepare the registration form.

Create the registration form

Display the registration form on your checkout page. Shopper submits the card information.

Network token provisioning for the collected card data is automatically triggered with card network.

Get the registration status

Find out if the registration token was successful.

OPTIONAL

Send the payment using the token

Send the payment using the stored registration token.

Transactions:

1. Prepare the checkout

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

Sample request:

2. Create the registration form

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

With the checkoutId received from first step

<script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}/registration"></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 registration status

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

resourcePath=/v1/checkouts/{checkoutId}/registration

A token transaction history is provided in the response to let you know that the network token provisioning kicked-off with the card network. The provisioning request takes time with issuer involved in the token approval process. The network token will be fetched with the subsequent payment attempt.

"transactions":[
  {
	"reason":"tokenization",
	"transactionId":"<UUID>",
	"clearingInstituteName":"TokenVault",
	"paymentType":"TK",
	"result":{
	  "code":"000.000.000",
	  "description":"Transaction succeeded"
	}
  }
]

The network token BIN (Bank Identification Number) is different than the original PAN (Primary Account Number) BIN. However, the original PAN BIN is provided in the response to help you with a better post-authorization real issuer BIN management.

"card":{
  "bin":"<bin>",
  "last4Digits":"<last4>",
  "holder":"<holder>",
  "expiryMonth":"<month>",
  "expiryYear":"<year>"
}

Sample request:

4. Send payment using the registration

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

A token transaction history is provided in the response to tell you that the network token is attempted to be fetched from the card network. The payment authorization continues with real card data if no network token is yet active for payments.

"transactions":[
  {
	"reason":"tokenization",
	"transactionId":"<UUID>",
	"clearingInstituteName":"TokenVault",
	"paymentType":"TF",
	"result":{
	  "code":"000.000.000",
	  "description":"Transaction succeeded"
	}
  }	
]

Sample request:

Prepare the checkout

Send the request parameters server-to-server to prepare the registration form.

Create the registration form

Display the registration form on your checkout page. Shopper submits the card information.

Network token provisioning for the collected card data is automatically triggered with card network.

Get the registration status

Find out if the registration token was successful.

OPTIONAL

Send payment using the registration

Send payment using stored registration token.

Transactions:

1. Prepare the checkout

Sample request:

2. Create the registration form

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

With the checkoutId received from first step

<script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}/registration"></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 registration status

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

resourcePath=/v1/checkouts/{checkoutId}/registration

"transactions":[
  {
	"reason":"tokenization",
	"transactionId":"<UUID>",
	"clearingInstituteName":"TokenVault",
	"paymentType":"TK",
	"result":{
	  "code":"000.000.000",
	  "description":"Transaction succeeded"
	}
  }
]

"card":{
  "bin":"<bin>",
  "last4Digits":"<last4>",
  "holder":"<holder>",
  "expiryMonth":"<month>",
  "expiryYear":"<year>"
}

Sample request:

4. Send payment using the registration

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

"transactions":[
  {
	"reason":"tokenization",
	"transactionId":"<UUID>",
	"clearingInstituteName":"TokenVault",
	"paymentType":"TF",
	"result":{
	  "code":"000.000.000",
	  "description":"Transaction succeeded"
	}
  }	
]

"card":{
  "bin":"<bin>",
  "last4Digits":"<last4>",
  "holder":"<holder>",
  "expiryMonth":"<month>",
  "expiryYear":"<year>"
}

Sample request:

Tokenization during payment

The merchant collects card data from shopper via widget and initiates tokenization along an account verification (zero amount auth) or initial purchase. A registration token is synchronously provisioned and returned to the merchant once the payment is complete. The registration token can then be used in subsequent payments. In the background, a network token is being provisioned by the card network with Issuer involved in the token approval process. The payment is authorized with real card data or with the network token if available and active.

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

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

How it works

Without 3D Secure
With 3D Secure and Fraud

Prepare the checkout

Send the request parameters server-to-server to prepare the payment form.

Create the payment form

Display the payment form on your checkout page. Shopper submits the card and payment information.

Network token provisioning for the collected card data is automatically triggered with card network.

Payment authorization is performed with network token, if provisioned and active, or otherwise, with real card data.

Get the payment status

Find out if the payment and registration were successful.

Transactions:

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:

2. Create the payment form

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

With the checkoutId received from first step

<script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></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/{checkoutId}/payment

A token transaction history is provided in the response to let you know that the network token provisioning kicked-off with the card network. The network token is then attempted to be fetched before the payment authorization beggins. The payment authorization continues with real card data if no network token is yet active for payments.

"transactions":[
  {
	"reason":"tokenization",
	"transactionId":"<UUID>",
	"clearingInstituteName":"TokenVault",
	"paymentType":"TK",
	"result":{
	  "code":"000.000.000",
	  "description":"Transaction succeeded"
	}
  },
  {
	"reason":"tokenization",
	"transactionId":"<UUID>",
	"clearingInstituteName":"TokenVault",
	"paymentType":"TF",
	"result":{
	  "code":"800.900.303",
	  "description":"No token created"
	}
  }	
]

"card":{
  "bin":"<bin>",
  "last4Digits":"<last4>",
  "holder":"<holder>",
  "expiryMonth":"<month>",
  "expiryYear":"<year>"
}

Sample request:

Prepare the checkout

Send the request parameters server-to-server to prepare the payment form.

Create the payment form

Display the payment form on your checkout page. Shopper submits the card and payment information.

Network token provisioning for the collected card data is automatically triggered with card network.

Payment authorization is performed with network token, if provisioned and active, or otherwise, with real card data.

Get the payment status

Find out if the payment and registration were successful.

Transactions:

1. Prepare the checkout

Sample request:

2. Create the payment form

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

With the checkoutId received from first step

<script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></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/{checkoutId}/payment

A token transaction history is provided in the response to let you know that the network token provisioning kicked-off with the card network. The network token is then attempted to be fetched before the 3D Secure authentication and payment authorization beggins. If no network token is yet active then both the 3D Secure authentication and payment authorization continue with real card data.

"transactions":[
  {
	"reason":"tokenization",
	"transactionId":"<UUID>",
	"clearingInstituteName":"TokenVault",
	"paymentType":"TK",
	"result":{
	  "code":"000.000.000",
	  "description":"Transaction succeeded"
	}
  },
  {
	"reason":"tokenization",
	"transactionId":"<UUID>",
	"clearingInstituteName":"TokenVault",
	"paymentType":"TF",
	"result":{
	  "code":"800.900.303",
	  "description":"No token created"
	}
  }	
]

"card":{
  "bin":"<bin>",
  "last4Digits":"<last4>",
  "holder":"<holder>",
  "expiryMonth":"<month>",
  "expiryYear":"<year>"
}

Sample request:

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 tokenized). Network token is provisioned and active for payment. An unscheduled one-click purchase with one of the saved registration tokens is performed. A cardholder initiated (CIT) payment is authorized with the active network token.

How it works

Without 3D Secure
With 3D Secure and Fraud

Prepare the checkout

Send the request parameters server-to-server to prepare the payment form.

Create the payment form

Display the one-click checkout payment form. Shopper selects the tokenized card and submits the payment information.

Payment authorization is performed with network token, if provisioned and active, or otherwise, with real card data.

Get the payment status

Find out if the payment with the network token was successful.

Transactions:

1. Prepare the checkout

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

Sample request:

2. Create the payment form

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

With the checkoutId received from first step

<script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></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 SecurePay builds up the payment form it automatically fetches the registrations data from the server and displays the pre-filled widgets to the shopper.

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/{checkoutId}/payment

"transactions":[
  {
	"reason":"tokenization",
	"transactionId":"<UUID>",
	"clearingInstituteName":"TokenVault",
	"paymentType":"TF",
	"result":{
	  "code":"000.000.000",
	  "description":"Transaction succeeded"
	}
  }	
]

"card":{
  "bin":"<bin>",
  "last4Digits":"<last4>",
  "holder":"<holder>",
  "expiryMonth":"<month>",
  "expiryYear":"<year>"
}

Sample request:

Prepare the checkout

Send the request parameters server-to-server to prepare the payment form.

Create the payment form

Display the one-click checkout payment form. Shopper selects the tokenized card and submits the payment information.

Payment authorization is performed with network token, if provisioned and active, or otherwise, with real card data.

Get the payment status

Find out if the payment with the network token was successful.

Transactions:

1. Prepare the checkout

Sample request:

2. Create the payment form

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

With the checkoutId received from first step

<script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></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 SecurePay builds up the payment form it automatically fetches the registrations data from the server and displays the pre-filled widgets to the shopper.

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/{checkoutId}/payment

A token transaction history is provided in the response to let you know that the network token is attempted to be fetched from the card network. If no network token is yet active then both the 3D Secure authentication and payment authorization continue with real card data.

"transactions":[
  {
	"reason":"tokenization",
	"transactionId":"<UUID>",
	"clearingInstituteName":"TokenVault",
	"paymentType":"TF",
	"result":{
	  "code":"000.000.000",
	  "description":"Transaction succeeded"
	}
  }	
]

"card":{
  "bin":"<bin>",
  "last4Digits":"<last4>",
  "holder":"<holder>",
  "expiryMonth":"<month>",
  "expiryYear":"<year>"
}

Sample request:

SecurePay Network Tokens

Last updated:April 5th, 2024

Use cases

Standalone tokenization

Tokenization during payment

One-click checkout

Standalone tokenization

How it works

1. Prepare the checkout

2. Create the registration form

3. Get the registration status

4. Send payment using the registration

1. Prepare the checkout

2. Create the registration form

3. Get the registration status

4. Send payment using the registration

Tokenization during payment

How it works

1. Prepare the checkout

2. Create the payment form

3. Get the payment status

1. Prepare the checkout

2. Create the payment form

3. Get the payment status

One-click checkout

How it works

1. Prepare the checkout

2. Create the payment form

3. Get the payment status

1. Prepare the checkout

2. Create the payment form

3. Get the payment status

See also