Convenience Store / Pay-easy / Online Banking [Beta]

With Convenience store, Pay-easy, and Online Banking, customers can pay from various institutions nationwide in Japan such as: a wide variety of Convenience stores, ATMs, Internet banking capable banks, post office, etc.

This payment method is highly convenient for your customers because there are many payment locations, it is possible for your customers to pay 24 hours a day, and your customers can even pay from home.

Omise currently supports payments at Circle K/Sunkus, Lawson, Mini Stop, Seico Mart, and Family Mart. These stores are available across Japan.

Note

- This payment method is only available for merchants with a Japan-registered Omise account.

- Convenience store, Pay-easy, and Online Banking payment is supported on API version 2017-11-02 onwards.

- Individual business owner can not use Convenience store, Pay-easy, and Online Banking payments.

The payment flow

At checkout, after entering shipping details and confirming the order, the customer selects their preferred payment method such as Offline payment methods, Cash payment methods etc.

The customer is required to enter their name, email address and telephone number, and are provided with a link (provided by Omise) to the various payment methods such as Convenience store, Pay-easy, and Online Banking.

To ensure that the customer is provided with accurate instructions, and the correct QR code, we ask that you use the link we provide.

Convenience Store payment flow

Once the online flow is complete the customer will need to pay at a Convenence store, Pay-easy or Online Banking from the link provided to complete the transaction.

Convenience Store payment flow

After the customer makes the payment, Omise will recieve a confirmation message and update your records to show that the transaction has been completed.

Creating a charge by using Payment Source

There are 2 steps to when creating a charge. Step 1 is to create a source object using the source api. Step 2 is to create a charge object passing the source parameter with the id value using the charge api.

1. Create a source object using the source api.

To create a charge for Convenence store, Pay-easy or Online Banking, you are first required to create a source object using the payment source API. See the code sample below.

Source fields
Name Type Attribute
amount integer (required) A positive integer between 150 and a maximim of 50000 JPY
currency string (required) currently only JPY is supported
type string (required) econtext
name string (required) A maximum of 10 characters of alphanumeric, hiragana, katakana, or kanji. This may appear on Convinence store kiosks or reciepts depending on payment method
email string (required) A minimum of 6 and maximum of 50 characters in length
phone_number integer (required) A minimum of 10 and maximum of 11 digits in length
Source creation example
curl https://api.omise.co/sources \
  -X POST \
  -u skey_test_59rnqoboimgxvjk894d: \
  -d "amount=150" \
  -d "currency=jpy" \
  -d "type=econtext" \
  -d "name=イワツキユウコ" \
  -d "email=iwatsuki.yuko@email.com" \
  -d "phone_number=01234567891" 

Please note that the charge amount for Convenence store, Pay-easy and Online Banking payments should be between JPY 150 and JPY 49999.

JSON Response

{
  "object": "source",
  "id": "src_5babhlfyw8g7smtk44u",
  "livemode": true,
  "location": "/sources/src_5babhlfyw8g7smtk44u",
  "type": "econtext",
  "flow": "offline",
  "amount": 150,
  "currency": "jpy",
  "name": "イワツキユウコ",
  "email": "iwatsuki.yuko@email.com",
  "phone_number": "01234567891"
}

When creating the source object, you can use either the secret key or the public key.

The id attribute is included in the results returned.

2. Create a charge object passing a source parameter with id value by using the charge api.

Upon a successful completion of a source object from step 1 above a Charge can be created using the charge API

Charge fields
Name Type Attribute
description string (optional) A custom description for the charge. This value can be searched for in your dashboard.
amount integer (required) A positive integer between 150 and a maximim of 50000 JPY
currency string (required) currently only JPY is supported
source string (required) the id from the source object returned after successful completion of step 1
expires_at string (optional) An ISO 8601 date format (example: YYYY-MM-DD:HH:MM). See Payment Expiration Date below for more details
Charge creation example

Here is a code sample for creating a charge using the id value from above src_5babhlfyw8g7smtk44u

curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_59rnqoboimgxvjk894d: \
  -d "description=Charge for order 3947" \
  -d "amount=150" \
  -d "currency=jpy" \
  -d "source=src_5babhlfyw8g7smtk44u" \

An example of JSON response.

 {
  "object": "charge",
  "id": "chrg_5babhz7ufmaxu5wi03y",
  "livemode": true,
  "location": "/charges/chrg_5babhz7ufmaxu5wi03y",
  "amount": 150,
  "currency": "jpy",
  "description": "test multipay charge",
  "metadata": {
  },
  "status": "pending",
  "capture": true,
  "authorized": false,
  "reversed": false,
  "voided": false,
  "paid": false,
  "transaction": null,
  "refunded": 0,
  "refunds": {
    "object": "list",
    "from": "1970-01-01T00:00:00Z",
    "to": "2018-03-16T02:53:39Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": null,
    "location": "/charges/chrg_5babhz7ufmaxu5wi03y/refunds",
    "data": [

    ]
  },
  "return_uri": null,
  "reference": null,
  "authorize_uri": "https://pay.omise.co/offlines/econtext/instructions/oflp_om1s3yqgwaldlnhy6y3",
  "failure_code": null,
  "failure_message": null,
  "card": null,
  "customer": null,
  "ip": null,
  "dispute": null,
  "created": "2018-03-16T02:53:39Z",
  "source": {
    "object": "source",
    "id": "src_5babhlfyw8g7smtk44u",
    "references": {
      "payment_code": "553384",
      "expires_at": "2018-04-15T09:00:00Z"
    },
    "type": "econtext",
    "flow": "offline",
    "amount": 150,
    "currency": "jpy",
    "name": "イワツキユウコ",
    "email": "iwatsuki.yuko@email.com",
    "phone_number": "01234567891"
  },
  "disputable": false,
  "capturable": false,
  "reversible": false,
  "refundable": false
}

JSON Response explanation

The returned JSON response is a charge object and therefore has many fields which may not be relevant to Convenence store, Pay Easy or Online Banking payments. For example these payment methods cannot be voided, refunded, disputed, or reversed.

Authorize Uri

The url your merchant should provide to the customer is in the authorize_uri field. The url will have all the payment methods and instructions needed for customers to make a sucessful payment. If you're currently using our test mode, a sample URL will be provided.

Payment Expiration Date

During the application process a default amount of expiration days from the payment creation is specified on the application form for Convenience Store / Pay-easy / Online Banking. However if another date is preferred then an expiration date can be specified during the charge creation (step 2) by adding an ISO 8601 date in UTC timezone. Japan is 9 hours ahead of UTC thus for a payment to expire midnight on July 1st, 2018 in Japan, the parameter would be: "expires_at=2018-07-01T15:00:00Z"

For example from the above step 2.

curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_59rnqoboimgxvjk894d: \
  -d "description=Charge for order 3947" \
  -d "amount=150" \
  -d "currency=jpy" \
  -d "source=src_5babhlfyw8g7smtk44u" \
  -d "expires_at=2018-07-01T15:00:00Z"

Payment status

You can always check the status of the charge by retrieving the charge as described in Charges API.

  • When both authorized and paid are marked true, the charge has succeeded.
  • When both authorized and paid are marked false, the charge has failed.
    (Detailed explanation on the reason of failure can be found in the Charge object under failure_code and failure_message.)
  • There is no scenario where authorized and paid are marked with differently values.

Failure codes

Code Description
payment_cancelled Payment cancelled by payee.
timeout Payee did not take action within specified period; causing payment to expire.
failed_processing Payment failed due to other reasons.

Webhooks

Rather than relying on the redirect back to the return_uri, we suggest merchants to make use of our Webhook API. Whenever a transaction is completed a webhook is sent to the URL that is specified in the dashboard with the event name charge.complete