Convenience Store / Pay-easy / Online Banking

With our Convenience Store, Pay-easy, and Online Banking payment method, customers can pay from various nationwide institutions in Japan. These include a wide variety of convenience stores, ATMs, banks capable of internet banking, and post offices.

This payment method is highly convenient for your customers: 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 Lawson, Mini Stop, Seico Mart, and Family Mart.

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 owners 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 given 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 Convenience 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:

  1. Create a source object using the Source API.
  2. Create a charge object passing the ID of the created source as the source parameter.

1. Create a source object using the source api

To create a charge for Convenience 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 maximum of 49999 JPY
currency string (required) Currently only JPY is supported
type string (required) The string econtext
name string (required) A maximum of 10 characters of alphanumeric, hiragana, katakana, or kanji. This may appear on convenience store kiosks or receipts depending on the 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 $OMISE_PUBLIC_KEY: \
  -d "amount=150" \
  -d "currency=jpy" \
  -d "type=econtext" \
  -d "name=イワツキユウコ" \
  -d "email=iwatsuki.yuko@email.com" \
  -d "phone_number=01234567891"

{
  "object": "source",
  "id": "src_test_5gkfpxxy24vd2dn5mqm",
  "livemode": false,
  "location": "/sources/src_test_5gkfpxxy24vd2dn5mqm",
  "type": "econtext",
  "flow": "offline",
  "amount": 150,
  "currency": "jpy",
  "created": "2019-07-15T04:33:12Z",
  "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) Custom description for charge. Value can be searched in the dashboard.
amount integer (required) A positive integer between 150 and a maximum of 49999 JPY
currency string (required) The string JPY
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 stored in the variable $SOURCE_ID:

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

{
  "object": "charge",
  "id": "chrg_test_5gkfpy0uwl28njm7ea3",
  "livemode": false,
  "location": "/charges/chrg_test_5gkfpy0uwl28njm7ea3",
  "amount": 150,
  "currency": "jpy",
  "funding_amount": 150,
  "funding_currency": "jpy",
  "description": "Charge for order 3947",
  "metadata": {},
  "status": "pending",
  "capture": true,
  "authorized": false,
  "schedule": null,
  "reversed": false,
  "reversed_at": null,
  "expires_at": "2019-08-14T04:33:13Z",
  "expired": false,
  "expired_at": null,
  "voided": false,
  "paid": false,
  "paid_at": null,
  "transaction": null,
  "refunded": 0,
  "refunds": {
    "object": "list",
    "from": "1970-01-01T00:00:00Z",
    "to": "2019-07-15T04:33:13Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": "chronological",
    "location": "/charges/chrg_test_5gkfpy0uwl28njm7ea3/refunds",
    "data": []
  },
  "return_uri": null,
  "failure_code": null,
  "failure_message": null,
  "card": null,
  "customer": null,
  "ip": null,
  "dispute": null,
  "created": "2019-07-15T04:33:13Z",
  "source": {
    "object": "source",
    "id": "src_test_5gkfpxt0e31wjtstuz8",
    "livemode": false,
    "location": "/sources/src_test_5gkfpxt0e31wjtstuz8",
    "references": {
      "payment_code": "589566",
      "expires_at": "2019-08-14T04:33:13Z"
    },
    "type": "econtext",
    "flow": "offline",
    "amount": 150,
    "currency": "jpy",
    "name": "イワツキユウコ",
    "email": "iwatsuki.yuko@email.com",
    "phone_number": "01234567891",
    "created": "2019-07-15T04:33:12Z"
  },
  "disputable": false,
  "capturable": false,
  "reversible": false,
  "refundable": false,
  "reference": "oflp_test_5gkfpy0zv86l8s36jnt",
  "authorize_uri": "https://pay.omise.co/offlines/econtext/instructions/oflp_test_5gkfpy0zv86l8s36jnt"
}

JSON Response explanation

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

Authorize URI

The URI your merchant should provide to the customer is in the authorize_uri field. The URI 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 URI 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, and 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, 2019 in Japan, the parameter would be: "expires_at=2019-07-01T15:00:00Z"

For example from the above step 2.

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

{
  "object": "charge",
  "id": "chrg_test_5gkfpy5q3h4ku3r922w",
  "livemode": false,
  "location": "/charges/chrg_test_5gkfpy5q3h4ku3r922w",
  "amount": 150,
  "currency": "jpy",
  "funding_amount": 150,
  "funding_currency": "jpy",
  "description": "Charge for order 3947",
  "metadata": {},
  "status": "expired",
  "capture": true,
  "authorized": false,
  "schedule": null,
  "reversed": false,
  "reversed_at": null,
  "expires_at": "2019-07-01T15:00:00Z",
  "expired": true,
  "expired_at": "2019-07-01T15:00:00Z",
  "voided": false,
  "paid": false,
  "paid_at": null,
  "transaction": null,
  "refunded": 0,
  "refunds": {
    "object": "list",
    "from": "1970-01-01T00:00:00Z",
    "to": "2019-07-15T04:33:14Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": "chronological",
    "location": "/charges/chrg_test_5gkfpy5q3h4ku3r922w/refunds",
    "data": []
  },
  "return_uri": null,
  "failure_code": null,
  "failure_message": null,
  "card": null,
  "customer": null,
  "ip": null,
  "dispute": null,
  "created": "2019-07-15T04:33:13Z",
  "source": {
    "object": "source",
    "id": "src_test_5gkfpxvfpwv0sdhuwmm",
    "livemode": false,
    "location": "/sources/src_test_5gkfpxvfpwv0sdhuwmm",
    "references": {
      "payment_code": "494816",
      "expires_at": "2019-07-01T15:00:00Z"
    },
    "type": "econtext",
    "flow": "offline",
    "amount": 150,
    "currency": "jpy",
    "name": "イワツキユウコ",
    "email": "iwatsuki.yuko@email.com",
    "phone_number": "01234567891",
    "created": "2019-07-15T04:33:12Z"
  },
  "disputable": false,
  "capturable": false,
  "reversible": false,
  "refundable": false,
  "reference": "oflp_test_5gkfpy5vjn4rpcnf2fu",
  "authorize_uri": "https://pay.omise.co/offlines/econtext/instructions/oflp_test_5gkfpy5vjn4rpcnf2fu"
}

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