This guide describes how the Payment is done via Click to Pay offering and describes all the Use Cases for the New Users and the Registered Users.
The EMV Secure Remote Commerce (SRC) enable a common consumer e-checkout that promotes simplicity, familiarity, interoperability convenience and trust. Click to Pay is built on EMV standards and it provides the checkout experience that delivers the security, convenience, and control currently offered in the physical world. To provide Click to Pay to our customers, ACI integrated with Secure Remote Commerce Initiator (SRCi) via Mastercard.
To better understand what Click to Pay is, please read the Configuration and Integration Guides.
First, perform a server-to-server POST request to prepare the checkout with the required data, including the order type, amount and currency. The response to a successful request is a JSON string with an id, which is required in the second step to create the payment form.
For a full list of parameters that can be sent in the prepare checkout request, please see the API Reference
Please note that for a HTTP POST request all the parameters are expected to go into the message body and not into the URL.
2. Create the payment form
To create the payment form you just need to add the following lines of HTML/JavaScript to your page and populating the following variables
The checkout's id that you got in the response from step 1
The shopperResultUrl, which is the page on your site where the customer should be redirected to after the payment is processed and the brands that will be available.
View the customization guide for more information on customizing the payment form. Please note if you are using SAQ-A compliant credit card form click Enter button on your keyboard to execute the payment.
Display of multiple card forms is now supported. This feature can be used by merchants for card brand promotion and allows the merchant to group card brands across multiple forms as per the need. To put this feature at work, add any number of <form> tag elements as above. The data-brands attribute of the rendered card forms can be configured as per the merchant need.
A checkout id expires when a payment has been finalized successfully by user, but not later than 30 minutes. Before it expires, it can be used multiple times in order to retrieve a valid payment form. This can occur for example when a user does not finish a payment and reloads the page, or uses the back button of the browser. Therefore you don't have to generate a new checkout ID in such scenarios. However be aware that such cases can generate multiple transactions in the system, for example one (or more) failed and another one successful, based on the same checkout id.
3. Get the payment status
Once the payment has been processed, the customer is redirected to your shopperResultUrl along with a GET parameter resourcePath.
Important: The baseUrl must end in a "/", e.g. "https://eu-test.oppwa.com/".
Then, to get the status of the payment, you should make a GET request to the baseUrl + resourcePath, including your authentication parameters.
Example of a resourcePath:
resourcePath=/v1/checkouts/{checkoutId}/payment
Once a status response is successful the checkout identifier can't be used anymore. In this case the Transaction Reports endpoint can be used to get the transaction status using the payment id.
IMPORTANT: A throttling rule applies for get payment status calls. Per checkout, it is allowed to send two get payment requests in a minute.
We recommend that you verify the following fields from the Payment Status response, by comparing the returned values with expected:
ID(s)
Amount
Currency
Brand
Type
Backoffice operations
COPYandPAY is used to securely accept the payment data. Once the payment data has been processed you can perform refunds or other backoffice operations by following our backoffice operations guide.
The Shopper clicks on the 'Click to Pay' checkbox on the Card widget and completes the Payment. On the click of this checkbox, Click to Pay workflow is triggered. When the payment is confirmed, TF (Token Fetch) is created. TF retrieves the Account Data from the Scheme based on the RIRO Configuration at Administration > Processing > Click to Pay Configuration. It can be Full PAN or DPAN (for Network Tokens).
Once TF is completed, actual payment transaction(PA/DB) is created which goes to the Acquirer.
Shopper enters the Card Details and clicks 'Click to Pay' checkbox on the Card widget
Create the new 'Click to Pay' profile
The Shopper proceeds for the Checkout on the Merchant's website and opts to pay via Credit Card. They will enter their Card details and will agree to register for 'Click to Pay' using the Checkbox on the card widget. The Shopper is then directed to the Scheme's page while doing the payment where they share their information like Name, Address, Contact Number to create their Click to Pay profile. Profile gets created when the payment is completed.
Payment Response
Based on the configuration settings, Scheme returns Email ID, Mobile Number, Address of the Shopper and their masked Account details. If the Dynamic Data type settings indicate that the Scheme returns the Full Card details, then masked Credit card data is retrieved. If the Dynamic Data type settings indicate that the Scheme returns the Token details, then masked Network Token data is retrieved like Token Account Number, Expiry and Cryptogram.
Once the Token Fetch is completed and the account data is retrieved from the Scheme , actual payment is created (PA/DB) which goes to the Acquirer.
Sample request:
Cookie Recognition
The Shopper with an existing account with the Merchant proceeds for the Checkout on the Merchant's website. On selecting the Credit Card as the Payment Option, they get recognized by the Browser Cookies since they are the returning shopper and already registered for Click to Pay. After the successful recognition, the Shopper is presented with the list of Click to Pay- registered cards. They select a card from the list, review and make the payment.
This Use case allows the Shopper to pay without any manual card entry.
The Recognized Shopper is presented with the list of cards registered against their Click to Pay profile.
Returning Shopper gets recognized via Cookies
The Recognized Shopper is presented with the list of cards registered against their Click to Pay profile when they choose to pay via Credit Card. Scheme Library recognizes the Returning Shopper based on the Browser Cookies and present them the list of cards registered against their Click to Pay profile.
Payment Response
Based on the configuration settings, the Scheme returns Email ID, Mobile Number, Address of the Shopper and their masked Account details. If the Dynamic Data type settings indicate that the Scheme returns the Full Card details, then masked Credit card data is retrieved. If the Dynamic Data type settings indicate that the Scheme returns the Token details, then masked Network Token data is retrieved like Token Account Number, Expiry and Cryptogram.
Once the Token Fetch is completed and the account data is retrieved from the Scheme, actual payment is created (PA/DB) which goes to the Acquirer.
Sample request:
Email ID Lookup
The Shopper with an existing account with the Merchant proceeds for the Checkout on the Merchant's website. On selecting the Credit Card as the Payment Option, they can enter their Email ID. If the Shopper is Registered for Click to Pay, an OTP is triggered to their Mobile Number/Email address. After the successful recognition, the Shopper is presented with the list of Click to Pay- registered cards. They select a card from the list, review and make the payment. This Use case allows the Shopper to pay without any manual card entry.
Shopper opts to pay via Credit Card and they enter their Email Address. the Scheme Library gets called to check if that email is enrolled for Click to Pay. If the email address is registered for Click to Pay, Shopper is requested to enter an OTP triggered on their phone/email. Once the authentication is successful, shopper is presented with the list of cards against their registered Click to Pay profile.
Transactions:
1. Email ID lookup
To check if the email provided by the Shopper is registered for Click to Pay, the Scheme Library is called. If the profile is found, OTP authentication is triggered which when successful, returns the Card list registered against that Click to Pay profile.
Payment response
Based on the configuration settings, the Scheme returns Email ID, Mobile Number, Address of the Shopper and their masked Account details. If the Dynamic Data type settings indicate that the Scheme returns the Full Card details, then masked Credit card data is retrieved. If the Dynamic Data type settings indicate that the Scheme returns the Token details, then masked Network Token data is retrieved like Token Account Number, Expiry and Cryptogram.
The response will include a token transaction history, indicating that the network token provisioning process
has started with the card network. Due to a simulated 2-second delay in the test environment, the network token provisioning
request will be in flight, and the payment will continue using the original PAN upon detokenizing the omni token.
The network token fetching is attempted, but the response will indicate that the provisioning request is still in progress.
Sample request:
CIT payment with network token
A shopper returns on the merchant’s website (card is already tokenized). Network token is provisioned and active for payment.
An unscheduled purchase with the saved token is performed. A cardholder initiated (CIT) payment is then authorized with the
active network token if the acquirer supports it.
Send the payment request using the stored merchant token (shopper is present).
Transactions:
1. Send payment initiated by the cardholder
To send a payment initiated by the cardholder, perform a server-to-server POST request using the stored
merchant token with all required payment and customer data, including payment type, amount, and currency.
Payment response
The response will include a token transaction history, indicating that an attempt was made to fetch the network
token from the card network. If no network token is active for payments, the payment authorization will proceed
using the real card data.
When the network token is fetched, the response will also provide the original PAN BIN. This information will be
exposed in the payment response as part of the card.bin parameter. It’s important to note that the
network token BIN is different from the original PAN BIN. This distinction is crucial for post-authorization
issuer BIN management, ensuring that you have the necessary details to handle the transaction accurately.
Sample request:
MIT payment with network token
A merchant initiated (MIT) payment is submitted based on the available card-on-file agreement with the shopper.
Card is already tokenized. Network token is provisioned and active for payment. MIT payment is authorized with the network token
if the acquirer supports it.
Send the payment request using the stored merchant token (shopper is not present).
Transactions:
1. Send payment initiated by the merchant
To send a payment initiated by the merchant, perform a server-to-server POST request using the stored merchant
token with all required payment and customer data, including payment type, amount, and currency.
Payment response
The response will include a token transaction history, indicating that an attempt was made to fetch the network
token from the card network. If no network token is active for payments, the payment authorization will proceed
using the real card data.
When the network token is fetched, the response will also provide the original PAN BIN. This information will
be exposed in the payment response as part of the card.bin parameter. It’s important to note that the
network token BIN is different from the original PAN BIN. This distinction is crucial for post-authorization issuer
BIN management, ensuring that you have the necessary details to handle the transaction accurately.
Sample request:
Payment with your network token
The merchant has its own Token Service Provider (TSP) and wants to submit payments with its existing network token authorization data.
The merchant provides all the required network token data including dynamic cryptographic data when necessary. The payment is authorized
with the network token if the acquirer supports it.
Send the payment request using the network token and cryptographic data as received from your Token Service Provider.
Transactions:
1. Send payment using your network token
To send a payment using your network token, perform a server-to-server POST request with your available network
token and the required payment and customer data, including payment type, amount, and currency.
Using tokenAccount.* data parameters
When provisioning network tokens and obtaining cryptograms through your own Token Service Provider (TSP),
you can pass the network token authorization data points in the request using the tokenAccount.*
data parameters. This ensures that all necessary information is included for the network token authorization.
Sample request:
One-Time Payment
The merchant collects card data from shopper and initiates the one-time payment. 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.
Send the one-time payment request with the collected card data.
Transactions:
1. Send one-time payment
To send a one-time payment, perform a server-to-server POST request with all the required payment and customer
data, including payment type, amount, and currency.
Payment response
The response will include a token transaction history, indicating that an attempt was made to fetch the network
token from the card network. If no network token is active for payments, the payment authorization will proceed
using the real card data.
When the network token is fetched, the response will also provide the original PAN BIN. This information will
be exposed in the payment response as part of the card.bin parameter. It’s important to note that the
network token BIN is different from the original PAN BIN. This distinction is crucial for post-authorization issuer
BIN management, ensuring that you have the necessary details to handle the transaction accurately.
You can switch the content of this page to learn how to use Omni Tokens as merchant tokens alongside
network tokens for payments. Toggle the switch below to see detailed information and update the page
content accordingly.