Creating a token

1. Initiate token creation

Create a checkout session from your server by calling the create a checkout session endpoint using the token payload. The call returns the created checkout session and token along with their IDs and the url you need to redirect the shopper to.
Securely store the returned token.id in your system as it will be required to create orders and manage the token (eg. disable or delete) in the future.

Creating the checkout session needs to happen from your server. It requires your secret API key. This prevents malicious users from tampering with the request.

For the full argument list please see the create a checkout session API endpoint. The following fields are specific to tokens:

mode: set to token to specify the checkout session will be used to create a token.
Note that the call does not require you to send the order amount and the items purchased. The token is not restricted for a specific amount and you will need to specify the items and amount when creating the order using the token.

curl --request POST \
     --url https://api.smartpay.co/v1/checkout-sessions \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic sk_test_abcdef12345678' \
     --header 'Content-Type: application/json' \
     --data '
{
     "cancelUrl": "https://mystore.jp/cancel",
     "customerInfo": {
          "accountAge": 30,
          "address": {
               "line1": "虎ノ門1-17-1",
               "line2": "虎ノ門ヒルズビジネスタワー 15階",
               "locality": "港区",
               "administrativeArea": "東京都",
               "postalCode": "105-6415",
               "country": "JP"
          },
          "dateOfBirth": "2019-08-24",
          "emailAddress": "[email protected]",
          "firstName": "John",
          "firstNameKana": "ドエ",
          "lastName": "Doe",
          "lastNameKana": "ドエ",
          "legalGender": "male",
          "phoneNumber": "+818000000000",
          "reference": "string"
     },
     "locale": "ja",
     "mode": "token",
     "reference": "my_merchant_token_reference",
     "successUrl": "https://mystore.jp/success",
     "tokenType": "recurring"
}
'

$api = new \Smartpay\Api(getenv('SECRET_KEY'), getenv('PUBLIC_KEY'));

$checkoutSession = $api->checkoutSession([
  'cancelUrl' => 'https://mystore.jp/cancel',
  'customerInfo' => [
    'accountAge' => 30,
    'address' => [
      'line1' => '虎ノ門1-17-1',
      'line2' => '虎ノ門ヒルズビジネスタワー 15階',
      'locality' => '港区',
      'administrativeArea' => '東京都',
      'postalCode' => '105-6415',
      'country' => 'JP'
    ],
    'dateOfBirth' => '2019-08-24',
    'emailAddress' => '[email protected]',
    'firstName' => 'John',
    'firstNameKana' => 'ドエ',
    'lastName' => 'Doe',
    'lastNameKana' => 'ドエ',
    'legalGender' => 'male',
    'phoneNumber' => '+818000000000',
    'reference' => 'string'
  ],
  'locale' => 'ja',
  'mode' => 'token',
  'reference' => 'my_merchant_token_reference',
  'successUrl' => 'https://mystore.jp/success',
  'tokenType' => 'recurring'
]);

Smartpay.configure do |config|
  config.public_key = ENV['PUBLIC_KEY']
  config.secret_key = ENV['SECRET_KEY']
end

session = Smartpay::Api.create_checkout_session({
  cancelUrl: 'https://mystore.jp/cancel',
  customerInfo: {
    accountAge: 30,
    address: {
      line1: '虎ノ門1-17-1',
      line2: '虎ノ門ヒルズビジネスタワー 15階',
      locality: '港区',
      administrativeArea: '東京都',
      postalCode: '105-6415',
      country: 'JP',
    },
    dateOfBirth: '1985-06-30',
    email: '[email protected]',
    firstName: '田中',
    lastName: '太郎',
    firstNameKana: 'たなか',
    lastNameKana: 'たろう',
    legalGender: 'male',
    phoneNumber: '+818000000000',
    reference: 'my_merchant_consumer_reference',
  },
  locale: 'ja',
  mode: 'token',
  reference: 'my_merchant_token_reference',
  successUrl: 'https://mystore.jp/success',
  tokenType: 'recurring',
})

SECRET_KEY = os.environ.get('SECRET_KEY', '<YOUR_SECRET_KEY>')
PUBLIC_KEY = os.environ.get('PUBLIC_KEY', '<YOUR_PUBLIC_KEY>')

smartpay = Smartpay(SECRET_KEY, public_key=PUBLIC_KEY)

session = smartpay.create_checkout_session({
    "cancelUrl": "https://mystore.jp/cancel",
    "customerInfo": {
        "accountAge": 30,
        "address": {
          "line1": "虎ノ門1-17-1",
          "line2": "虎ノ門ヒルズビジネスタワー 15階",
          "locality": "港区",
          "administrativeArea": "東京都",
          "postalCode": "105-6415",
          "country": "JP",
        },
        "dateOfBirth": "1985-06-30",
        "email": "[email protected]",
        "firstName": "田中",
        "lastName": "太郎",
        "firstNameKana": "たなか",
        "lastNameKana": "たろう",
        "legalGender": "male",
        "phoneNumber": "+818000000000",
        "reference": "my_merchant_consumer_reference",
    },
    "locale": "ja",
    "mode": "token",
    "reference": "my_merchant_order_reference",
    "successUrl": "https://mystore.jp/success",
    "tokenType": "recurring",
})

2. Redirect the shopper to the Smartpay Checkout

Use the url returned by the create checkout session call to redirect the shopper to the Smartpay Checkout.

3. Shopper completes the Smartpay Checkout

Once the shopper completes Smartpay Checkout, they are returned to your website.

If the shopper clicks confirm, Smartpay will activate the token and the shopper is redirected to success URL provided by you.
If the shopper cancels, the shopper is redirected to the cancel URL provided by you.

Active token

If the checkout was completed successfully by the shopper, they are redirected to the success URL configured in the checkout session. Present the shopper with a confirmation page. You can move ahead with using the token to create orders.

You can list tokens, disable / enable them and delete them. For further details please see our guide on token management.

Canceled tokens

If the shopper cancels the checkout session they are redirected to the cancel URL configured in the checkout session. Present an appropriate message to the shopper and ask them to select an alternative payment method.

Good to know

Payment authorization is not done at the time of token creation. Payment authorization is done when you create an order using the token. This means that even though the token was authorized successfully, it may still be rejected when an order is processed using the token.
A token does not expire, so please disable or delete the token that is no longer needed.
A consumer can have multiple tokens with the same merchant.