Tokenizing a Payment Method

The Redirect and Modal payment methods are configured per system and do not allow a customer to make automatic payments. To save the details of the customer payment method, a customer first needs to make a purchase, pay an order or add a new payment method in UX1 for Customers.

Creating a token during checkout

In a nutshell, a token is created when Billing receives the ADD_NEW_METHOD array in the Callback method response. A token is created and the data received in that array are associated with it. Beside the predefined parameters, the ADD_NEW_METHOD array may contain custom parameters introduced by the plug-in implementer criteria. Data associated with the token will be sent to the plugin when a payment using that token starts (for details, see Auth, Capture and Sell methods input parameters).

Note: The presence of the ADD_NEW_METHOD array causes a new token to be created regardless of the Callback response status. The plugin implementer needs to take this into consideration when using the ADD_NEW_METHOD array.

As the ADD_NEW_METHOD array is related to the Callback method response, it does not depend on the payment flow (that is, Redirect or Modal). The general flow of storing a token is depicted on the following diagram:

A browser calls the Billing Redirect (return_url) or Notify (notify_url) URL.
Billing calls the Callback method in the plugin passing the parameters received in the request.
The plugin completes transactions with the payment gateway. It also detects that a token must be created.
The plugin responds with the transaction status, details, and the ADD_NEW_METHOD array (for details, see Callback).
Billing detects the ADD_NEW_METHOD array and creates a new payment method (a token).
Billing completes the transaction and updates the Payment and Order status and details.
Billing responds to the customer:
- Redirect Flow: The customer is redirected back to CloudBlue Commerce.
- Modal Flow: Billing responds with the transaction status and additional data.

To summarize:

Billing creates a token when the Callback method response contains the ADD_NEW_METHOD array.
The data to be saved together with the token is defined at the payment plug-in level (that is, the Callback method implementation) and also depends on the payment gateway protocol.
If the payment gateway also returns its own payment method ID, it could be passed to the external_id parameter of the ADD_NEW_METHOD array. This parameter is saved to the Billing database and can be used to search for the payment method when synchronizing the payment method status from the payment gateway system to Billing.
The plugin may add the initial_status parameter in the ADD_NEW_METHOD array (valid values are the OK or PENDING status). Customers can only pay with those payment methods that have the OK status. Payment methods in the PENDING status cannot be used for payments until the status is changed to OK.

Creating a token by manually adding a new Payment Method

The UX1 for Customers allows a customer to create a new Payment Method without buying anything. To do so, the Add New Payment Method button (UX1 for Customers > Account > Payment Methods) is used.

However, this button is active when there is at least one active plugin that:

supports the Redirect or Modal flow. In other words, implements the Redirect or GoModal methods,
implements the Sell or Auth methods, and
implements the Void or Refund methods.

When a new payment method is created using this approach, Billing creates a "Pre-authorization Charge" document and attempts to pay it using the selected plugin. The amount can be configured for each currency supported by the plugin (Provider Control Panel > Billing > Settings > Payment Processing > Payment Gateways > Plugin > Features)

After the plugin confirms the payment, Billing creates a new Payment Method and calls the Void (or Refund) method in order to void the "Pre-authorization Charge" document.

Creating a token with the Redirect flow

A customer clicks the Add New Payment Method button.
- UX1 displays a list of plugins to the customer.
- The customer selects the Payment Method type.
The customer clicks Continue.
A browser sends the preauthorize-payment-method request to Billing.
Billing creates the "Preauthorization Charge" document (DocType is DT_CHECK).
Billing calls the Redirect method in the target plugin.
The plugin processes the redirect request.
The plugin responds with the REDIRECT status and parameters, which includes the URL to redirect the customer to (for details, refer to the Redirect method description).
Billing returns the preauthorization response data from the plugin.
The browser redirects to the payment gateway URL received in the Redirect method response. In that HTTP request, parameters received from the plugin will be sent to the payment gateway. Those parameters include the callbackURL¹.
The customer fills out a payment form with the desired payment method and data in the gateway payment page.
The payment gateway processes the payment request.
The payment gateway sends a callback request to the customer using the provided callbackURL.
The browser calls Billing using the callbackURL received from the payment gateway.
Billing calls the Callback method in the plugin passing the parameters received in the request.
The plugin completes transactions with the payment gateway. It also detects that a token must be created.
The plugin responds with the transaction status, details, and ADD_NEW_METHOD array (for details, refer to the Callback method description).
Billing detects the ADD_NEW_METHOD array and creates a new payment method (a token).
Billing completes the transaction and updates the Payment and Order status and details.
Billing detects that DocType is DT_CHECK and schedules an asynchronous call to the plug-in Void or Refund method².
Billing redirects the customer back to CloudBlue Commerce.

¹Billing provides three callback URLs: return_url, return_url_ok , and return_url_fail. Billing sends those URLs in the Environment array when calling the Redirect and Callback methods.

²Billing checks whether the plugin supports the Void method. If not, Billing checks the refund type and tries to call theRefund, RefundPartial, or RefundCredit method.

Creating a token with the Modal flow

A customer clicks the Add New Payment Method button
- UX1 displays a list of plugins.
- The customer selects the Payment Method type.
The customer clicks Continue.
The browser sends the preauthorize-payment-method request to Billing.
Billing creates the "Preauthorization Charge" document (DocType is DT_CHECK).
Billing calls the GoModal method.
The plugin processes the GoModal request.
The plugin responds with the MODAL status and parameters (for details, refer to the GoModal method description).
Billing returns the GoModal method response back to the browser.
The browser renders the modal form based on the parameters received from the GoModal method (for details, refer to Rendering the Modal Form).
The customer fills out a form and submits it.
The browser sends data to the payment gateway through the HTTP POST request.
The payment gateway processes the payment request.
The payment gateway responds with the transaction data.
The browser calls the Billing notify URL (notify_url) with the payment transaction data received in the payment gateway payment response.
Billing calls the plug-in Callback method, passing the data received in the request.
The plugin processes the Callback request.
The plugin responds with the transaction status, details, and ADD_NEW_METHOD array (for details, refer to the Callback method description).
Billing detects the ADD_NEW_METHOD array and creates a new payment method (a token).
Billing completes the transaction and updates the Payment and Order status and details.
Billing detects that DocType is DT_CHECK and schedules an asynchronous call to the plug-in Void or Refund method.
The browser receives the transaction status and additional data.