• NOTICE: Xfers will be undergoing a prolonged service disruption to its Maybank account from the 25th of May 2017. Here's an update onthe status.

Getting Started With Xfers Direct

Xfers Direct (Tokenize) allows you to control your users' payment experience through our tokenization APIs. 

1. Creating a Bank Transfer Enabled Guest Checkout Flow

Step 1: Create A Charge

See http://docs.xfers.io/#charges

A charge represents item(s) your platform or business is selling to the buyer. Once your platform detects that the user is checking out her shopping cart, you should create a charge on the backend. 
Required fields:

  • user_phone_no (to collect the user's phone number from a form field in your front end)
  • currency
  • order_id
  • redirect (set to false)
Once the charge API call is fired, buyer will receive an OTP (one time password) from Xfers. At Xfers, phone numbers are the identity of the user. Hence we require the OTP of the user in the next step to confirm that they have control over / owns the phone number. 

The response after creating a charge will include a transfer_info attribute containing information about the bank the user should transfer to to pay for the charge. This is used in step 3.

  **Please do not save this bank information in your database for reuse , as the bank information might change from time to time.**

Step 2: Authorize The Charge

The user has to enter the OTP received on your UI. Once she has done that, send the OTP to your backend and call the authorize charge endpoint (See http://docs.xfers.io/#authorize-a-charge).

Step 3: Display The Bank Transfer Information

Using the transfer_info object obtained in step 1, show on your UI the bank account details your customer should transfer to. The bank_unique_amt should be the amount user should transfer to the bank.
Please remind your customer to enter the same phone number in the “Comments/your initials” section when doing the bank transfer. This is how Xfers is able to detect which user the bank transfer is coming from.

And that’s it!

Once the user makes a bank transfer to the account, Xfers will detect it and transfer the money into your platform’s Xfers Wallet/Merchant Account. 

2. Creating a Bank Transfer Enabled Registered User Checkout Flow

Step 1: Getting user_api_token (If you haven't already saved on for this customer)

In order to let the user have a seamless checkout experience, we need to avoid redirecting them to the Xfers page to signup/login.

Here, we will show you how to programmatically sign up/login for the user and get the user's API token.

This step can be done when you are registering a new user for your platform as these are the details (e.g. email and phone number) which Xfers needs to register an account on our database. If you already have existing registered users before integrating Xfers, this step can be done when they are doing a checkout. 

(a) Sign Up / Login

Let the user enter her phone number on your UI. Pass it to your backend and call the http://docs.xfers.io/#signup/login-to-xfers endpoint. Once this endpoint is called, the user will receive an OTP. 

(b) Get User API Token 

Let the user enter the OTP on your UI. Pass it to your backend and call the http://docs.xfers.io/#get-user-api-token 

The response will be as follows:  
{
  "msg": "success",
  "user_api_token": "1DnsZkv3qXwKx4EAdps8AJ8jXCPsxP2sKSygMHTAFLM",
  "sign_up_url" :
"https://sandbox.xfers.io/api/v3/account_registration?phone_no=%2B6597288608&token=4014d3e9f0600f78dbfabd86036de7b008f70c52"
  }

Step 2: Create a charge 

See http://docs.xfers.io/#charges

A charge represents item(s) your platform or business is selling to the buyer. Once your platform detects that the user is checking out her shopping cart, you should create a charge on the backend. 
Required fields:

  • user_phone_no (taken from Step 1)
  • currency
  • order_id
  • redirect (set to false)
  • No OTP is needed here, unlike Guest checkout for I-banking.

    The response after creating a charge will include a transfer_info attribute containing information about the bank the user should transfer to to pay for the charge. This is used in step 3.

*Please do not save this bank information in your database for reuse, as the bank information might change from time to time.

Step 3: Display the bank transfer information 

This is same as Guest checkout - Bank transfer.

*Since this is a registered Xfers user, he/she might have sufficient money in his/her wallet. In that case, Xfers will just deduct from his/her wallet and the returned status would be “paid” or “completed”. No transfer_info will be displayed.

3. Creating a Credit Card Enabled Guest Checkout Flow

Step 1: Create a charge 

See http://docs.xfers.io/#charges

A charge represents item(s) your platform is selling to the buyer. Once your platform detects that the user is checking out her shopping cart, you should create a charge on the backend. 
This step has some differences to Guest checkout by Bank Transfer - you do not need to pass in the user_phone_no param, and no OTP is needed. Of course, no bank transfer information is returned in the response too.
Required fields:

  • user_phone_no (to collect the user's phone number from a form field in your front end)
  • currency
  • order_id
  • redirect (set to false)
  • card_only (set to true)
Since the customer phone number is not passed to Xfers, you would not be able to reuse the credit card again as Xfers does not know which customer it belongs to. See Registered User checkout - Credit Card if you would like to save credit card details.

So how would the customer details be displayed on you Xfers Dashboard? Assuming your email is [email protected], we would show [email protected] (just appending a +credit_card_guest to your email).

Step 2: Get Customer's Credit Card Details And Tokenize It 

Refer to https://github.com/Xfers/xfers.js

There are three steps.
A) Include xfers.js in your HTML file and create your own credit card form.
B) Initialize xfers.js by doing Xfers.init();  
C) You pass in an object with the attributes number, exp-month, exp-year and cvc into the Xfers.createToken function. The response is of the following format:
The response is of the following format
{
  "first6": "424242",
"last4": "4242",
  "credit_card_token": "tok_197O8gB8MXWbQJDjPMILsIr6"
}

Step 3: Pay for the charge with the credit card token 

Use charge_card_guest endpoint (http://docs.xfers.io/#charge-guest-card) to charge this credit card for guest user. This can be done on the client side and does not need API key authentication.
You would need the charge id from step 1 (put it in the txn_id field), the credit_card_token, first6 and last4 from step 2.

4. Creating a Credit Card Enabled Registered User Checkout Flow

Step 1: Getting user_api_token (If you haven't already saved on for this customer)

In order to let the user have a seamless checkout experience, we need to avoid redirecting them to the Xfers page to signup/login.

Here, we will show you how to programmatically sign up/login for the user and get the user's API token.

This step can be done when you are registering a new user for your platform as these are the details (e.g. email and phone number) which Xfers needs to register an account on our database. If you already have existing registered users before integrating Xfers, this step can be done when they are doing a checkout. 

(a) Sign Up / Login

Let the user enter her phone number on your UI. Pass it to your backend and call the http://docs.xfers.io/#signup/login-to-xfers endpoint. Once this endpoint is called, the user will receive an OTP. 

(b) Get User API Token 

Let the user enter the OTP on your UI. Pass it to your backend and call the http://docs.xfers.io/#get-user-api-token 

The response will be as follows:  
{
  "msg": "success",
  "user_api_token": "1DnsZkv3qXwKx4EAdps8AJ8jXCPsxP2sKSygMHTAFLM",
  "sign_up_url" :
"https://sandbox.xfers.io/api/v3/account_registration?phone_no=%2B6597288608&token=4014d3e9f0600f78dbfabd86036de7b008f70c52"
  }

Step 2: Create a charge 

See http://docs.xfers.io/#charges

A charge represents item(s) your platform or business is selling to the buyer. Once your platform detects that the user is checking out her shopping cart, you should create a charge on the backend. 
Required fields:

  • user_phone_no (taken from Step 1)
  • currency
  • order_id
  • redirect (set to false)
  • card_only (set to true)

Step 3: Selecting a card to use

There are two options. 

(a) Use an existing card 

Call http://docs.xfers.io/#list-cards on your backend to fetch cards this customer has already added to your platform. Display this information on your front-end.
If the user wants to change her default card, pass the card_id she selected to your backend and call http://docs.xfers.io/#set-default-card. If not, just go to Step 4 to pay for the charge.
(b) Add a new card

Should the customer want to add a new card: 

Scenario 1: You need to get Customer’s Credit Card Details and tokenize it

This is same as Guest checkout - Credit Card.

Scenario 2: Add the Credit Card Token to the Customer

Call http://docs.xfers.io/#add-a-card once your server receives the credit card token, first6 and last4 from step 3. Also include user_api_token of your customer.

Scenario 3: Set this card as default

See http://docs.xfers.io/#set-default-card 

Step 4: Pay for the charge 

In your backend, call http://docs.xfers.io/#charge-existing-card, passing in the id of the created charge in Step 1.
Because this charge is already linked to a particular customer (remember you passed in the user_api_token when creating the charge), Xfers will automatically use the default card of the customer and pay for the charge.

5. Receiving callback notifications (optional)

If notify_url is passed in when creating a charge, Xfers will send a POST request to that URL on success/failure/expiration of the charge.

Please acknowledge the callback by providing a HTTP 200 status.

Success - Charge is successfully paid for by the user and money is transferred to your platform’s Xfers Wallet.
Failure - User has cancelled the charge
Expiration - Charge has expired (default 48 hours. Can set it using the hrs_to_expirations param when creating a charge)