**Last updated**: 17 November 2025 | [**Change log**](/products/apms/changelog/)

# Konbini

The Konbini and Pay-easy payment method is a collection of payment types that customers in Japan can use to shop online.

Note
Make yourself familiar with our [API Principles](/products/reference/api-principles) to ensure a resilient integration.

details
summary
Product Overview
Your customers can complete their payment with one of the following:

- Offline cash payment at a convenience store (Konbini)
- Offline cash/electronic payment at an ATM (Pay-easy)
- Online electronic payment by internet banking (Pay-easy)


### Feature summary

| Payment type | Country | Currencies | Recurring | Reversals | Partial Reversals | Disputes |
|  --- | --- | --- | --- | --- | --- | --- |
| E-Cash | Japan | JPY | ❌ | ❌ | ❌ | ❌ |


- Minimum Transaction Value: 100 JPY
- Maximum Transaction Values:
The maximum amount for a single transaction depends on what payment option the customer chooses. The default limits are:
  - 299.000 JPY at a convenience store
  - 99.000 JPY at an ATM with cash
  - 999.999 JPY at an ATM with a cash card or with internet banking
In addition Internet banks may set their own limits.


## Set your headers

Setting your headers is an important part of an API request. The headers represent the meta-data associated with your API request.


```
Authorization: {your_credentials}
Content-Type: application/json
WP-Api-Version: 2023-06-01
```

| Header | Description |
|  --- | --- |
| `Authorization` | We use the `Authorization` header to identify and authenticate you within Access Worldpay. You **must** use the `Authorization` header for any request you send to our APM API. |
| `Content-Type` | We require the `Content-Type` header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`. |
| `WP-Api-Version` | We use the `WP-Api-Version` header to identify which version of our APM API you are using. You **must** use the `WP-Api-Version` header for any request you send to our API. |


If you're using both the `Content-Type` and `WP-Api-Version` headers, they must match.

Note
Replace `{your_credentials}` with your base64-encoded Basic Auth username and password. To get your Access Worldpay credentials contact your Implementation Manager.

## Take a payment

#### Example request

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant":
    {
        "entity": "default"
    },
    "instruction":
    {
        "narrative":
        {
            "line1": "Mind Palace Ltd"
        },
        "value":
        {
            "amount": 50,
            "currency": "JPY"
        },
        "paymentInstrument":
        {
            "type": "konbini",
            "country": "JP",  
            "lastName": "姓",
            "telephoneNumber": "1234567890",
            "shopperEmailAddress": "email@example.com",
            "pendingURL": "https://example.com/pending"
        }
    }
}
### Parameters

| Parameter | Required? | Description | Data type | Length |
|  --- | --- | --- | --- | --- |
| `merchant` | ✅ | An object that contains information about the merchant. | Object | N/A |
| `merchant.entity` | ✅ | Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for Authentication and Queries.Contact your Implementation Manager for more details. | String | Must be between 1 and 32 characters. |
| `transactionReference` | ✅ | A unique reference generated by you that is used to identify a payment throughout its lifecycle. See [transaction reference format](/products/reference/formatting#transaction-reference-format). | String | Must be between 1 to 64 characters. |
| `instruction` | ✅ | An object that contains all the information related to the payment. | Object | N/A |
| `instruction.narrative` | ✅ | An object that helps your customers better identify you on their statement. | Object | See our [formatting rules](/products/reference/formatting#narrative-format) |
| `instruction.narrative.line1` | ✅ | The first line of the narrative which appears on your customer's statement (If a character is not supported it is replaced with a space.).See [narrative `line1` format](/products/reference/formatting#narrative-line1) for more details. | Object | 24 |
| `instruction.value` | ✅ | An object that contains information about the payment transaction. | Object | N/A |
| `instruction.value.amount` | ✅ | The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2,50. You can find the relevant exponent in our [currency table](/products/reference/supported-countries-currencies#iso-currency-codes). | Integer | N/A |
| `instruction.value.currency` | ✅ | The payment currency. Refer to the individual APM page for supported currencies. | Integer | 3 |
| `instruction.paymentInstrument` | ✅ | An object that contains information about the payment method. | Object | N/A |
| `instruction.paymentInstrument.type` | ✅ | The payment type and details. It defines which alternative payment method you wish to use. Value is "konbini". | Object | N/A |
| `paymentInstrument.country` | ✅ | The country of your customer. Follows [alpha 2 ISO 3166-1](/products/reference/supported-countries-currencies#iso-country-codes) standard. | Object | 2 |
| `paymentInstrument.shopperEmailAddress` | ✅ | Your customer's email address. | String | N/A |
| `paymentInstrument.lastName` | ✅ | Your customer's last name. | String | 0-10 |
| `paymentInstrument.telephoneNumber` | ✅ | Your customer's telephone number. | String | 10-11 |
| `instruction.paymentInstrument.pendingURL` | ✅ | When we receive the payment result for a pending payment transaction, we redirect your customer to that pending URL. | String | N/A |


## Response

#### Successful request response

* an HTTP code `201`
* an `id` which is unique to the payment - we recommend storing the "id" as this can be used to manage the payment later
* a `url` to redirect your customer to the APM provider to complete the payment
* an link to query the payment status


### Example Response

{
    "paymentId": "nFxASqw-LV9HE_rr1mMONJmqBDeXmnv5dzt9IxAXgXbfpu0O_8mOnTpFSIM9gnTSygCKQgvlwQdUbu5rExIpJA_5Uq2LEGXXAanycRpxfDPNA-E70zIWdnaMb2gJhC8AIhbOkM6xDiVNu90YCXo2snTzi_k1sEOQnKIAJNTW3Qc",
    "lastEvent": "pending",
    "_links": {
        "self": {
            "href": "https://access.worldpay-bsh.securedataplatform.com/apmPayments/nFxASqw-LV9HE_rr1mMONJmqBDeXmnv5dzt9IxAXgXbfpu0O_8mOnTpFSIM9gnTSygCKQgvlwQdUbu5rExIpJA_5Uq2LEGXXAanycRpxfDPNA-E70zIWdnaMb2gJhC8AIhbOkM6xDiVNu90YCXo2snTzi_k1sEOQnKIAJNTW3Qc"
        }
    },
    "_actions": {},
    "url": "https://payments.worldpay-bsh.securedataplatform.com/app/hpp/integration/wpg/corporate?OrderKey="
}
Note
In case of an error, you can get further information in our [error reference](/products/reference/worldpay-error-responses).

**Next Steps**

[Manage your Konbini payment](/products/apms/20230601/manage)