Using the Smartpay API

Once you have a Smartpay token for a consumer, you need to create an order using that token when you want to charge the consumer via the Smartpay API. Both the token and the consumer who owns the token must be active.

Create an order using a token

When your are ready to charge the consumer, create an order by calling the create an order API endpoint.

Note, payment authorization is not done at a 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. Please check the order status before fulfilling the order.

Please note that every request will create a new order and charge the consumer for it. Please take a look at API idempotency to avoid accidentally double charging the consumer.

For the full argument list please see the create an order API endpoint. The following fields are mandatory:

amount: The amount intended to be collected through this order. A positive integer in the smallest currency unit.
currency: Three-letter ISO currency code, in uppercase. Must be a supported currency.
customerInfo: Customer Information, the details provided here may be used during authorization. The more information you send, the better the authorization rate we can provide.
items: The line items the customer ordered.
shippingInfo: Shipping Information for the order.
token: The unique identifier for the token to be used when creating this order.

curl --request POST \
     --url https://api.smartpay.co/v1/orders \
     --header 'Authorization: Basic sk_test_cok3psbYJpZZX9x3yboLIH' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "amount": 1500,
     "currency": "JPY",
     "customerInfo": {
          "accountAge": 30,
          "address": {
               "line1": "虎ノ門1-17-1",
               "line2": "虎ノ門ヒルズビジネスタワー 15階",
               "line3": "string",
               "line4": "string",
               "line5": "string",
               "subLocality": "string",
               "locality": "港区",
               "administrativeArea": "東京都",
               "postalCode": "105-6415",
               "country": "JP"
          },
          "dateOfBirth": "2022-10-06",
          "emailAddress": "[email protected]",
          "firstName": "John",
          "firstNameKana": "ジョン",
          "lastName": "Doe",
          "lastNameKana": "ドエ",
          "legalGender": "male",
          "phoneNumber": "+818000000000",
          "reference": "my_customer_reference"
     },
     "items": [
          {
               "amount": 1000,
               "brand": "FARVALUE",
               "currency": "JPY",
               "description": "ニット セーター",
               "gtin": "682141169930",
               "images": [
                    "https://mystore.jp/images/image.png"
               ],
               "label": "string",
               "name": "セーター",
               "priceDescription": "string",
               "productDescription": "string",
               "quantity": 0,
               "reference": "string",
               "url": "https://mystore.jp/my-product/",
               "kind": "product"
          }
     ],
     "reference": "my_merchant_order_reference",
     "shippingInfo": {
          "address": {
               "line1": "虎ノ門1-17-1",
               "line2": "虎ノ門ヒルズビジネスタワー 15階",
               "line3": "string",
               "line4": "string",
               "line5": "string",
               "subLocality": "string",
               "locality": "港区",
               "administrativeArea": "東京都",
               "postalCode": "105-6415",
               "country": "JP"
          },
          "addressType": "home",
          "carrierName": "yamato",
          "reference": "1234-5678-9123",
          "feeAmount": 500,
          "feeCurrency": "JPY"
     },
     "token": "paytok_test_zAo001ZRfyjz1F4rMyYPnL"
}
'

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

$payment = $api->createOrder([
  'amount' => 1500,
  'currency' => 'JPY',
  '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'
  ],
  'items' => [
    [
      'amount' => 1000,
      'brand' => 'FARVALUE',
      'currency' => 'JPY',
      'description' => 'ニット セーター',
      'gtin' => '682141169930',
      'images' => [
        'https://mystore.jp/images/image.png'
      ],
      'name' => 'セーター',
      'quantity' => 1,
      'reference' => 'my_merchant_product_reference',
      'url' => 'https://mystore.jp/my-product/'
    ]
  ],
  'locale' => 'ja',
  'reference' => 'my_merchant_order_reference',
  'shippingInfo' => [
    'address' => [
      'line1' => '虎ノ門1-17-1',
      'line2' => '虎ノ門ヒルズビジネスタワー 15階',
      'locality' => '港区',
      'administrativeArea' => '東京都',
      'postalCode' => '105-6415',
      'country' => 'JP',
    ],
    'feeAmount' => 500,
    'feeCurrency' => 'JPY',
  ],
  'token' => 'paytok_test_zAo001ZRfyjz1F4rMyYPnL'
]);

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

session = Smartpay::Api.create_order({
  amount: 1500,
  currency: 'JPY',
  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',
  },
  items: [
    {
      amount: 1000,
      brand: 'FARVALUE',
      currency: 'JPY',
      description: 'ニット セーター',
      gtin: '682141169930',
      images: [
        'https://mystore.jp/images/image.png'
      ],
      label: null,
      metadata: {},
      name: 'セーター',
      priceDescription: null,
      priceMetadata: {},
      productDescription: null,
      productMetadata: {},
      quantity: 1,
      reference: 'my_merchant_product_reference',
      url: 'https://mystore.jp/my-product/'
    }
  ],
  reference: 'my_merchant_order_reference',
  shippingInfo: {
    address: {
      line1: '虎ノ門1-17-1',
      line2: '虎ノ門ヒルズビジネスタワー 15階',
      locality: '港区',
      administrativeArea: '東京都',
      postalCode: '105-6415',
      country: 'JP',
    },
    feeAmount: 500,
    feeCurrency: 'JPY',
  },
  token: 'paytok_test_zAo001ZRfyjz1F4rMyYPnL',
})

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_order({
    "amount": 1500,
    "currency": "JPY",
    "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",
    },
    "items": [
        {
             "amount": 1000,
             "brand": "FARVALUE",
             "currency": "JPY",
             "description": "ニット セーター",
             "gtin": "682141169930",
             "images": [
                  "https://mystore.jp/images/image.png"
             ],
             "label": null,
             "metadata": {},
             "name": "セーター",
             "priceDescription": null,
             "priceMetadata": {},
             "productDescription": null,
             "productMetadata": {},
             "quantity": 1,
             "reference": "my_merchant_product_reference",
             "url": "https://mystore.jp/my-product/"
        }
    ],
    "reference": "my_merchant_order_reference",
    "shippingInfo": {
        "address": {
            "line1": "虎ノ門1-17-1",
            "line2": "虎ノ門ヒルズビジネスタワー 15階",
            "locality": "港区",
            "administrativeArea": "東京都",
            "postalCode": "105-6415",
            "country": "JP",
          },
        "feeAmount": 500,
        "feeCurrency": "JPY",
    },
    "token": "paytok_test_zAo001ZRfyjz1F4rMyYPnL",
})

When the order is created, Smartpay underwrites the transaction and depending on the result your order will be successful or declined.

Succeeded order

If the order was approved by Smartpay, the returned order will be in succeeded state if you are using automatic capture (default) or requires_capture state if you are using manual capture (specifying captureMethod = manual in the create order request). You can proceed with fulfilling the order.

Rejected order

In the case the order is declined by Smartpay, because for example the consumer account or the token is not active anymore, the returned order will be in rejected state. Please contact the consumer to ask for an alternative payment method.