Convenience Store [Beta]

Convenience store payments (or also known as Konbini) is a local cash-based payment method widely used in Japan. Omise currently supports payments at Seven Eleven, 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.

- For users with a live account, you will be required to review Terms & Conditions before using the live API.

The payment flow

At checkout, after entering shipping details and confirming the order, the customer selects their preferred payment method. To pay at a convenience store, select the option Convenience Store.

Convenience Store payment flow

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 outlets: Convenience Store payment flow

The payment procedure varies across outlets. To ensure that the customer is provided with accurate instructions, and the correct QR code, we ask that you use the link we provide.

Creating a charge by using Payment Source

To create a charge for convenience store payments, you are first required to create a source object using the Source API. See the code sample below.

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 conveninence store 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. To create a charge, pass the id as the source parameter in the Charge API. The id src_5babhlfyw8g7smtk44u is used in the example.

Payment expiration settings

To set an expiration date for the charge, include the expiry_date parameter with your request. Use the ISO 8601 Date and time format. In cases where the expiry_date is not included, either your account's default valid days will be used in calculating the expiry date of the charge, or the Omise default of 7 days will be used.
The default valid days for your account is included in the application forms for Convenince Store payments. Your account's valid days can be changed by contacting our support team.

When setting an expiry_date, please be consider the following;

  • Charges at Seven Eleven can only be made valid for a maximum of 60 days
  • It is recommended to set the expiry_date within 365 days
  • A time of “00:00” can be ambiguous, therefore the system will use “23:59" by default
  • If no time of expiry is specified then the time will be set to “23:59" by default
  • If no time zone is specified the system will use JST by default

The example below shows a charge created with an expiry_date and source included.

curl https://api.omise.co/charges \
 -X POST \
 -u skey_test_59rnqoboimgxvjk894d: \
 -d "description=Your description here" \
 -d "amount=150" \
 -d "currency=jpy" \
 -d "expiry_date=2018-04-15T09:00:00Z" \
 -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 Convenience Store Payments. For example Convenience Store payments 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 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