<aside> 🚧 Please note this is an early release and there may be some variance in names and terminology between these guides and the API reference. Please don’t hesitate to reach out to the RubyPay technical team for assistance or clarification. Thank you for your patience and understanding.

</aside>

Introduction

RubyPay uses the leading, PCI DSS compliant tokenisation tools to securely store tokenised payment methods. No sensitive data is collected by or stored on RubyPay infrastructure. Not only does storing payment methods in this way reduce risk to end customers, but it also provides a powerful way of improving end customer experience, as well as increasing the ability for RubyPay to detect fraudulent or malicious behaviour.

Any payment method (i.e. Credit/Debit card, bank account, crypto wallet etc) is tokenised in this way.

Retrieving payment methods

Getting a list of existing payment methods for a customer can be done via the tokens endpoint, or included in the full get Customer endpoint:

List tokens for customer

Get customer

Payment method storage (tokenisation)

The storage of a payment method is broken into multiple steps, to allow for a more customisable user interface.

The flow for saving a payment method (tokenisation)

Storing a payment method has the following key steps:

1. Initiate the request for a payment method

This may begin in one of 2 ways:

When the customer initiates a payment or disbursement.
At any point that you may want to include payment method management for the customer, for example on their user profile.

To begin the flow, first request a “capturing endpoint”:

Create capturing endpoint

2. Create a callback handler function

The next step requires a callback function that receives the newly created token. The token is then used for a payment, or can optionally be stored against the customers profile for future use.

For example:

function tokenCreationCallbackHandler(token_object){
	const token = token_object.token;
		
	// Store or temporarily hold the token value for storing later, or as a one-off only for the payment flow.
}

3. Embed the capture form

With the returned endpoint and the callback handler function created, the form can be embedded.

It is possible to customise the wording for the capture form button, set by the submitText property of the options object and passed to the SDK function (🚧 more customisation options are in progress).

Using the RubyPay SDK, bring this all together:

<script src="<https://js.test.rubypay.io/v1>"></script>

...

<div id="method-capture-container"></div>

...

const rubyPay = RubyPay('your_publishable_key');

// Customise the form submit button
const options = {
	submitText: "Save Card"
};

// Use .createACHElements() for capturing bank account information
rubyPay.createPCDElements('method-capture-container', token, options, tokenCreationCallbackHandler);

The RubyPay SDK will the load and embed the necessary capture form into your UI, the customer can securely enter their details.

4. (Optional) Store the tokenised payment method

Once the customer has submitted their payment method details, the newly stored token is passed to your callback handler function. If you have included a “Save for later” option in your UI, this would allow the customer to opt in for this.

Alternatively, you may offer the payment method management option as part of a customers profile/management.

Storing the token is via:

Add card token (noting, whilst named “card token”, it handles both card and bank account tokens…🚧).

🚧 Deleting payment methods

This is still a work in progress, however deleting will be enabled through a single API endpoint.