Paidy Checkout
Paidy Checkout provides a secure and streamlined process that works for all payments and across all major desktop browsers and mobile devices. With just a few clicks, your consumers can quickly and conveniently check out. And, best of all, Paidy Checkout works within your existing checkout page, so you do not have to worry about session management, redirects, or lost sales.
How does it work
Paidy Checkout comprises two components:
- Checkout JS: a JavaScript library that passes the data required for creating a payment or token to Paidy.
- Checkout app: the application displayed on your website. The Checkout app guides the consumer through the checkout process and prompts them for any required information.
- When a consumer checks out with Paidy Checkout, your frontend passes the data to the Checkout JS script and the Checkout app starts.
- The consumer enters their mobile number and email address in the Checkout app, which is sent to Paidy.
- Paidy sends a 4-digit authentication code to this mobile number via SMS.
- The consumer enters the authentication code in the Checkout app. The app may prompt the consumer for additional information. (Paidy offers multiple payment options to consumers and depending on the payment options they select, they may be prompted for more information.)
- Paidy processes the request and executes your JavaScript callback function to return the result to your frontend.
- Save the payment ID or token ID to your backend. This ID is very important.
- If you also want to receive the result directly to your backend, you need to implement Webhooks. The use of Webhooks is optional, but recommended. Once you have Webhooks set up, you will receive notifications for successful payment and token requests.
- Paidy sends a confirmation email and SMS to the consumer.
If a new token was created, you can use the API to create a payment using this token. When a new payment was created, you can use the API to capture and manage the payment.
Secure communication
TLS is an industry standard protocol for encrypting network communications and providing end-to-end security over the Internet. Paidy Checkout supports TLS version 1.2 and higher.
Integrating Paidy Checkout for payments
To integrate Paidy Checkout for payments:
- Update the checkout page template
- Verify the payment data
- Configure the Checkout app (optional step)
Update the checkout page template
Sometimes Japanese characters sent in the JSON can be garbled and replaced with random characters (such as a question mark or a box). To ensure that the text in the JSON is transmitted correctly and displayed correctly at Paidy’s user interfaces, make sure it is UTF-8 encoded.
STEP 1: Embed the Checkout JS script in the checkout page template. Example:
<script type="text/javascript" src="https://apps.paidy.com/"></script>
STEP 2: Log in to the Merchant Dashboard and make a note of your public key. The Merchant Dashboard lists your keys for both the test and live (production) environments. Make sure to use the correct public key.
STEP 3: Add the following fields to the checkout page template. This is your merchant configuration.
-
PARAMETER
DESCRIPTION
-
api_key
string
REQUIRED
Public key. This is the most important attribute as it identifies your account when communicating with Paidy.
-
logo_url
string
optional
URL to a merchant logo that can be displayed in the Checkout app header.
-
closed
function
optional
Callback function that is executed when Paidy has finished processing the request. For payments, this callback will contain the result of the authorization, i.e., whether it was successful, failed, or the consumer closed Paidy Checkout before completing the checkout process. While the callback function is not required, we strongly recommend you use it.
-
metadata
object
optional
Merchant-defined data about the payment object. This field is a key-value map, limited to 20 keys. The metadata field can be set in the merchant configuration and in the payload data. If it is set in both places, the values set in the payload will overwrite the values set in the merchant configuration.
STEP 4: Add the following fields to the checkout page template. This is the payload data.
-
PARAMETER
DESCRIPTION
-
amount
double
REQUIRED
Total payment amount, including tax, shipping, and excluding any discounts.
-
currency
string
REQUIRED
ISO 4217 currency code for this order; set to JPY.
-
store_name
string
optional
Name of the store. This is displayed in the Checkout app header, at MyPaidy, and the Merchant Dashboard.
-
buyer
object
REQUIRED
buyer object containing details about the buyer.
-
buyer_data
object
REQUIRED
buyer_data object containing details about the consumer’s purchasing history at your store.
-
order
object
REQUIRED
order object containing details about the items being purchased.
-
shipping_address
object
REQUIRED
shipping_address object containing the address to which the goods are being shipped.
It is very important to send the full address — from the prefecture to the apartment number. If the full address is not provided, the request may fail.
If the consumer is shipping the order to multiple addresses, provide the other addresses in the additional_shipping_addresses array in the buyer_data object. -
description
string
optional
Description for the payment.
-
metadata
object
optional
Merchant-defined data about the object. This field is a key-value map, limited to 20 keys. The metadata field can be set in the merchant configuration and in the payload data. If it is set in both places, the values set in the payload will overwrite the values set in the merchant configuration.
Buyer object:
-
PARAMETER
DESCRIPTION
-
email
string
optional
Consumer's email address. If this field is included in the payload, it will be pre-filled in the Paidy Checkout app when it launches. If this field are not included in the payload, the consumer must enter them during checkout.
-
name1
string
REQUIRED
Consumer's name in kanji. Family name and first name must be separated by a space, e.g., 山田 太郎. The space can be a Unicode U+0020 space or a U+3000 ideographic space.
-
name2
string
optional
Consumer's name in katakana. Family name and first name must be separated by a space, e.g., ヤマダ タロウ. The space can be a Unicode U+0020 space or a U+3000 ideographic space.
-
phone
string
optional
Consumer's phone number, e.g., 09011112222. This should be a Japanese mobile phone where the consumer can receive text messages.
If this field is included in the payload, it will be pre-filled in the Paidy Checkout app when it launches. If this field are not included in the payload, the consumer must enter them during checkout. -
dob
string
optional
Consumer's date of birth; format is YYYY-MM-DD.
Buyer data object:
-
PARAMETER
DESCRIPTION
-
user_id
string
optional
Consumer's user ID at your online store.
-
age
integer
REQUIRED
Time in days since the consumer opened the account with you.
If the age is not known, then this field can be omitted, but the account_registration_date should be sent in the payload. -
age_platform
integer
optional
Time in days since the consumer opened an account with the parent organization for your store.
-
account_registration
_datestring
optional
Date the consumer registered their account. The format of this field is YYYY-MM-DD.
If the account_registration_date is not known, then this field can be omitted, but the age should be sent in the payload. -
days_since_first
_transactioninteger
optional
Time in days since the consumer's first transaction, excluding canceled, rejected, or refunded transactions. Also excluding Paidy payments.
-
ltv
double
REQUIRED
Lifetime value. The total amount (in JPY) the consumer has ordered, excluding canceled, rejected, or refunded transactions. Also excluding Paidy payments.
-
order_count
integer
REQUIRED
Number of orders the consumer has made at your store since creating an account, excluding canceled, rejected, or refunded transactions. Also excluding Paidy payments.
-
last_order_amount
double
REQUIRED
Amount (in JPY) of the last order, excluding canceled, rejected, or refunded transactions. Also excluding Paidy payments.
-
last_order_at
integer
REQUIRED
Time in days since the last order, excluding canceled, rejected, or refunded transactions. Also excluding Paidy payments.
If the last_order_at is not known, then this field can be omitted, but the last_order_date should be sent in the payload. -
last_order_date
string
optional
Date on which the consumer made their last purchase, excluding canceled, rejected, or refunded transactions. Also excluding Paidy payments. The format of this field is YYYY-MM-DD.
If the last_order_date is not known, then this field can be omitted, but the last_order_at should be sent in the payload. -
order_amount
_last3monthsinteger
optional
Amount the consumer spent in the last 3 months, excluding canceled, rejected, or refunded transactions. Also excluding Paidy payments.
-
order_count
_last3monthsinteger
optional
Number of orders the consumer placed in the last 3 months, excluding canceled, rejected, or refunded transactions. Also excluding Paidy payments.
-
additional_shipping
_addressesarray
optional
If the consumer's order is being shipped to multiple addresses, there will be one object in the additional_shipping_addresses array for each shipping address.
Each object will contain the following fields: line1, line2, city, state, zip. (See the shipping address object for details about these fields.) -
billing_address
object
optional
Consumer's billing address (i.e., residence). This object contains the following fields: line1, line2, city, state, zip. (See the shipping address object for details about these fields.)
-
delivery_locn_type
string
optional
Type of location where the goods will be delivered. Set to one of the following values:
"home": Receive at home.
"office": Receive at office.
"shop": Pickup in-store.
"combini": Pickup at convenience store.
"locker": Pickup at delivery locker service.
"post_office": Pickup at post office.
"delivery_center": Pickup at delivery center.
"forwarding_shipment_service": Use a forwarding shipment service.
"gift": Send as a gift.
"not_primary_home": Receive at a home address other than the address registered with your site. -
gender
string
optional
Gender of the consumer. For example: "Male" or "Female"
-
subscription_counter
integer
optional
For subscriptions, a counter showing the total number of times a subscription has been purchased, using any payment method (including Paidy). Set to "1" for the first time a subscription is purchased and increment by 1 for each additional purchase. Do not include subscriptions that were cancelled or refunded.
-
previous_payment
_methodsobject
optional
Object that contains the following fields: credit_card_used, cash_on_delivery_used, convenience_store_prepayment_used, carrier_payment_used, bank_transfer_used, rakuten_pay_used, line_pay_used, amazon_pay_used, np_postpay_used, other_postpay_used
All fields are of type Boolean. If a payment method was used, set the value for that field to true; if a payment method was not used, set its value to false; if a payment is not available at your store, you may omit it or set it to null. -
number_of_points
integer
optional
Number of points the consumer has accumulated (prior to this order).
-
order_item_categories
array
optional
Categories of items being purchased, as a comma-separated list.
Order object:
-
PARAMETER
DESCRIPTION
-
items
object
REQUIRED
Array of items objects representing all of the items in the order. If you want to offer consumers a discount, use this object to create a “discount order item”, with the unit_price set to the negative value of the discount.
-
order_ref
string
optional
Merchant-defined order ID or reference.
-
shipping
double
optional
Total shipping charges for the order.
-
tax
double
optional
Total tax charged on the order.
Items object:
-
PARAMETER
DESCRIPTION
-
id
string
optional
Merchant-defined product identifier. This field is optional, but if sent, it will be displayed at the Merchant Dashboard and MyPaidy.
-
quantity
integer
REQUIRED
Quantity of the item added to the order.
-
title
string
optional
Title of the order item (or discount/coupon). This field is optional, but we recommend sending it as part of the payload. If sent, it is shown at both the Merchant Dashboard and MyPaidy to identify the order item. If not sent, only the quantity and unit price will be displayed for the order item.
-
unit_price
double
REQUIRED
Price per unit for the item. If the order item is a discount or coupon, make sure the unit_price is set to a negative value, so that it will be subtracted from the total amount for the order.
-
description
string
optional
Description of the item. Currently, this is not displayed at the Merchant Dashboard or MyPaidy.
Shipping address object:
-
PARAMETER
DESCRIPTION
-
line1
string
optional
For Japanese addresses: building name, apartment number.
-
line2
string
optional
For Japanese addresses: district, land number, land number extension.
-
city
string
optional
Name of city, municipality, or village.
-
state
string
optional
Prefecture
-
zip
string
REQUIRED
Postal code; format is NNN-NNNN.
NOTE! This field is required. Each of the other fields in the address object are optional, but in addition to the zip field, at least one of the other fields must be populated. If two fields are not provided in the address, the request will fail.
Also remember, if you are splitting the address into two fields (zip and another field), you must provide the full address in that second field or the request may fail.
It is very important to send the full address, from the prefecture to the apartment number. If all of the information is not provided, the request may fail. Additionally, we recommend sending the address information formatted into the following set of fields, i.e., with the address separated field by field.
Paidy Checkout example
<html>
<body>
<button id="paidy-checkout-button" onclick="paidyPay()">ペイディでお支払い</button>
<script type="text/javascript" src="https://apps.paidy.com/"></script>
<script type="text/javascript">
var config = {
"api_key": "pk_0000_000000000000000",
"logo_url": "http://www.paidy.com/images/logo.png",
"closed": function(callbackData) {
/*
Data returned in the callback:
callbackData.id,
callbackData.amount,
callbackData.currency,
callbackData.created_at,
callbackData.status
*/
}
};
var paidyHandler = Paidy.configure(config);
function paidyPay() {
var payload = {
"amount": 10000,
"currency" : "JPY",
"store_name": "Paidy sample store",
"buyer": {
"email": "successful.payment@paidy.com",
"name1": "山田 太郎",
"name2": "ヤマダ タロウ",
"phone" : "08000000001",
"dob": "1990-10-25"
},
"buyer_data": {
"user_id": "yamada_taro",
"age": 29,
"age_platform": 50,
"days_since_first_transaction": 29,
"ltv": 250000,
"order_count": 1000,
"last_order_amount": 20000,
"last_order_at": 20,
"order_amount_last3months": 15000,
"order_count__last3months": 5,
"additional_shipping_addresses": [{
"line1": "AZABUビル 2F",
"line2": "東麻布2-10-1",
"city": "港区",
"state": "東京都",
"zip": "106-0023"
}],
"billing_address": {
"line1": "AXISビル 10F",
"line2": "六本木4-22-1",
"city": "港区",
"state": "東京都",
"zip": "106-2004"
},
"delivery_locn_type": "office",
"gender": "Male",
"subscription_counter": 2,
"previous_payment_methods": {
"credit_card_used": false,
"cash_on_delivery_used": true,
"convenience_store_prepayment_used": true,
"carrier_payment_used": false,
"bank_transfer_used": false,
"rakuten_pay_used": true,
"line_pay_used": false,
"amazon_pay_used": false,
"np_postpay_used": false,
"other_postpay_used": false
},
"number_of_points": 8023,
"order_item_categories": ["sunglasses", "contact lenses"]
},
"order": {
"items": [
{
"id":"PDI001",
"quantity":1,
"title":"スニーカー",
"unit_price":10000,
"description":" "
}
],
"order_ref": "88e021674",
"shipping": 0,
"tax": 0
},
"shipping_address": {
"line1": "AXISビル 10F",
"line2": "六本木4-22-1",
"city": "港区",
"state": "東京都",
"zip": "106-2004"
},
"description" : "Sample store"
};
paidyHandler.launch(payload);
};
</script>
</body>
</html>
Result data
Upon completion, Paidy executes your JavaScript callback function. For payment requests that were either successfully authorized or failed the authorization process, we return all of the following fields in the callback.
-
PARAMETER
DESCRIPTION
-
amount
double
Total payment amount.
-
currency
string
ISO 4217 currency code for this order. Set to JPY.
-
created_at
string
Date and time the payment was created, in UTC, and displayed in ISO 8601 format.
-
id
string
Unique ID for the payment. All Paidy payment IDs begin with pay_.
-
status
string
Status of the request, either AUTHORIZED for a successful authorization or REJECTED for a failed authorization.
If the consumer closes Paidy Checkout before the checkout process was complete, we only return one field in the callback: status with the value set to "closed".
This should not be confused with the CLOSED payment status. A payment in the Merchant Dashboard can have a status of CLOSED which means the payment was either successfully completed or canceled by the merchant. When "closed" is returned in the callback, the consumer has closed Paidy Checkout before the checkout completed, so a Paidy payment does not exist.
Verify the payment data
For payments created using Paidy Checkout, Paidy requires that you verify the data by sending a request from your backend using your secret API key. This is an important security measure that must not be skipped!
When a payment is authorized, Paidy Checkout will execute your JavaScript callback function to return the payment ID. Before saving the payment ID, the payment must be verified to ensure that the data in the browser was not tampered with when it was transmitted from your frontend to Paidy.
The required verification flow is:
- Send the payment ID returned in the callback function to your backend.
- Send a GET request from your backend to the
/payments/{id}endpoint, where {id} is the payment ID. If the request is successful, we will return the full payment object. - Verify that the value in the amount field (in the payment object) is the same as the value that was sent in the authorize request.
- If both are the same, the payment is valid and you can store the payment object to your database.
Configure the Checkout app
The Checkout app displays the Paidy logo in the header, but you can configure the app to display your own logo. To do this:
- Update logo_url in the merchant configuration on the checkout page template (see step 3).
- Make sure your logo is installed in the same domain as the page that is using Paidy Checkout.
The recommended image size is 184px X 184px. The recommended image formats are .png, .jpg, and .gif.
Integrating Paidy Checkout for tokens
To integrate Paidy Checkout for tokens:
- Update the checkout page template
- Configure the Checkout app (optional step)
Update the checkout page template
Sometimes Japanese characters sent in the JSON can be garbled and replaced with random characters (such as a question mark or a box). To ensure that the text in the JSON is transmitted correctly and displayed correctly at Paidy’s user interfaces, make sure it is UTF-8 encoded.
STEP 1: Embed the Checkout JS script in the checkout page template. Example:
<script type="text/javascript" src="https://apps.paidy.com/"></script>
STEP 2: Log in to the Merchant Dashboard and make a note of your public key. The Merchant Dashboard lists your keys for both the test and live (production) environments. Make sure to use the correct public key.
STEP 3: Add the following fields to the checkout page template. This is your merchant configuration.
-
PARAMETER
DESCRIPTION
-
api_key
string
REQUIRED
Public key. This is the most important attribute as it identifies your account when communicating with Paidy.
-
logo_url
string
optional
URL to a merchant logo that can be displayed in the Checkout app header.
-
on_close
function
optional
Callback function that is executed when the Checkout app closes. The on_close function is executed if the token is successfully created, or if the consumer closes Paidy Checkout before completing the checkout process. While this callback function is not required, we strongly recommend you use it.
-
closed
function
optional
Callback function that is executed when the Checkout app closes. The closed callback only executes if the token is successfully created. Because of this, we recommend you use the on_close callback instead, which executes both for successful token creation and when the consumer closes Paidy Checkout early.
-
metadata
object
optional
Merchant-defined data about the token object. This field is a key-value map, limited to 20 keys. The metadata field can be set in the merchant configuration and in the payload data. If it is set in both places, the values set in the payload will overwrite the values set in the merchant configuration.
-
token
object
optional
This is the object with the token-related configuration fields. If this is present, Paidy will use the "create token" flow to process the request; if it is not present, Paidy will use the "create payment" flow to process the request.
Token object:
-
PARAMETER
DESCRIPTION
-
wallet_id
string
optional
Wallet ID. Large-scale merchants who have multiple sub-merchants or act as a service provider for other merchants can use this field to identify the sub-merchants. Do not send an empty string for this field; either set the value or do not send this field in the token object. If this field is not sent, Paidy will set the value to "default".
-
type
string
REQUIRED
Token type. Set to “recurring”.
-
description
string
optional
Merchant-defined description for the token.
STEP 4: Add the following fields to the checkout page template. This is the payload data.
-
PARAMETER
DESCRIPTION
-
store_name
string
optional
Name of the store. This is displayed in the Checkout app header, at MyPaidy, and the Merchant Dashboard.
-
buyer
object
REQUIRED
Buyer object containing the consumer’s name, email address, and mobile number.
-
description
string
optional
Description for the payment.
-
metadata
object
optional
Merchant-defined data about the object. This field is a key-value map, limited to 20 keys. The metadata field can be set in the merchant configuration and in the payload data. If it is set in both places, the values set in the payload will overwrite the values set in the merchant configuration.
Buyer object:
-
PARAMETER
DESCRIPTION
-
email
string
optional
Consumer's email address. If this field is included in the payload, it will be pre-filled in the Paidy Checkout app when it launches. If this field are not included in the payload, the consumer must enter them during checkout.
-
name1
string
REQUIRED
Consumer's name in kanji. Family name and first name must be separated by a space, e.g., 山田 太郎. The space can be a Unicode U+0020 space or a U+3000 ideographic space.
-
name2
string
optional
Consumer's name in katakana. Family name and first name must be separated by a space, e.g., ヤマダ タロウ. The space can be a Unicode U+0020 space or a U+3000 ideographic space.
-
phone
string
optional
Consumer's phone number, e.g., 09011112222. This should be a Japanese mobile phone where the consumer can receive text messages.
If this field is included in the payload, it will be pre-filled in the Paidy Checkout app when it launches. If this field are not included in the payload, the consumer must enter them during checkout.
Paidy Checkout example
<html>
<body>
<button id="paidy-checkout-button" onclick="paidyPay()">Paidyでお支払い</button>
<script type="text/javascript" src="https://apps.paidy.com/"></script>
<script type="text/javascript">
var config = {
"api_key": "pk_0000_000000000000000",
"logo_url": "http://www.paidy.com/images/logo.png",
"on_close": function(callbackData) {
/*
Data returned in the callback:
callbackData.id,
callbackData.created_at,
callbackData.status
*/
},
"token": {
"wallet_id": "default",
"type": "recurring",
}
};
var paidyHandler = Paidy.configure(config);
function paidyPay() {
var payload = {
"store_name": "Paidy sample store",
"buyer": {
"email": "successful.payment@paidy.com",
"name1": "山田 太郎",
"name2": "ヤマダ タロウ",
"phone" : "08000000001"
}
};
paidyHandler.launch(payload);
};
</script>
</body>
</html>
Result data
Upon completion, Paidy executes your JavaScript callback function. We will return the following fields in the callback.
-
PARAMETER
DESCRIPTION
-
id
string
Unique ID for the token. All Paidy tokens begin with tok_.
-
created_at
string
Data and time the token was created, in UTC, and displayed in ISO 8601 format.
-
status
string
Status of the token creation. The value will be either ACTIVE for successfully created tokens, or CLOSED if the consumer closed Paidy Checkout before completing the checkout process. If CLOSED, status will be the only field that we return in the callback.
Configure the Checkout app
The Checkout app displays the Paidy logo in the header, but you can configure the app to display your own logo. To do this:
- Update logo_url in the merchant configuration on the checkout page template (see step 3).
- Make sure your logo is installed in the same domain as the page that is using Paidy Checkout.
The recommended image size is 184px X 184px. The recommended image formats are .png, .jpg, and .gif.
Supported browsers
As part of our development process, we test against all major browsers and across different versions of browsers. However, we do not support browsers that are no longer receiving security updates. If you have an issue with Paidy Checkout on a specific browser, please contact us so we can improve its support.
-
WEB BROWSERS & VERSIONS
-
Recommended
Latest versions of Microsoft Edge, Chrome, Safari, and Firefox.
-
Supported
Microsoft Edge, Chrome and Safari on all platforms for three years from version release.
Firefox on desktop platforms for three years from version release. (Note, we respond to bug reports, but do not proactively test the latest version of Firefox on Android or iOS.)
We also test across different mobile platforms.
-
PLATFORM VERSIONS
-
Recommended
iOS 12 and above
Android 7 and above -
Supported
iOS 12 and above
Android 7 and above
Troubleshooting
-
ERROR
POSSIBLE CAUSE & SOLUTION
-
ERROR
Paidy configuration JSON is missing required parameters
Incomplete or missing configuration object. Make sure the configuration object passed to Paidy.configure() is well-formed and contains all of the required keys and values.
-
/payments
503 Service unavailable or connection refused
The payments service is not running or the configuration points to the wrong server or port. Check your configuration.
-
/payments
401 Unauthorized
Incorrect public key provided. Log in to the Merchant Dashboard and verify the value of your public key. Then, verify you are using the correct public key in the merchant configuration.