🚧

PCI-DSS Warning

If you use this guide to process credit cards, we will likely ask you to submit proof of PCI-DSS compliance. You may be able to lessen the requirement by collecting token information client-side and using Tokens. Have a chat with your Customer Success representative for more details.

The simplest way around this is to integrate with Hosted Page or Hosted Fields.

In this guide we'll show you how to make payments directly through KOMOJU. By directly, we mean that your server sends payment details (e.g. a credit card number) to KOMOJU, and KOMOJU processes it immediately.

Some possible use cases for this style of integration might be:

• You have a fully custom UI for collecting customer payment details, and want to use KOMOJU behind the scenes.
• You have contracts with multiple payment service providers, including KOMOJU, and want to multiplex between them.

When using our API to create payments, you have 2 options. Either you can first create a Session and then "pay" for it, or you can just create a Payment directly. Usually the first method is the most versatile but we'll walk through both methods for completeness.

Method 1: Pay for a Session

This method of creating payments requires at least 2 API calls: one to create a Session object and one to create a Payment.

This recipe shows a complete example. We'll go over the steps in detail here.

Step 1: create a session

Call the Session: Create API with the following attributes:

The resulting Session object can be quite large. The attributes you'll care about depend on how you plan to use the session. In this case, we're just using the session as a carrier for payments, so these are the response attributes of interest:

Step 2: pay for the session

Next, you'll want to call our Session: Pay endpoint.

Step 3: handle the pay result

The response from Session: Pay looks like this:

If status is not "error", then you can always handle this by redirecting your customer to redirect_url.

Here's a detailed breakdown of some different scenarios you might encounter here. When in doubt, just redirect to redirect_url.

If you choose to not redirect to redirect_url in any of these cases, we recommend reading through the Payment Details doc to understand how your specific payment method(s) works.

Step 4: handle return URL and webhook

The return_url you specified when you created your session is where the customer will be sent when they finish submitting their payment information, or when they decide to cancel while on their payment app.

When the customer is redirected to return_url, a query parameter called session_id will be appended. Your back-end should use this session_id to call Session: Show, and check the Session's status.

Here's an example:

In addition to this return_url check, we recommend you set up Webhooks - specifically for payment.captured and payment.authorized. You can use the Payment's external_order_num, metadata, or session attributes to associate it with your order.

---

Method 2: Creating a Payment Directly

Here's how you can create payments without an associated Session.

Step 1: create payment

Call Payment: Create.

See the Payment: Create reference for the full list. Most of the time, the attributes you see here are the only ones you'll need.

Step 2: handle the response

The Payment: Create endpoint returns a Payment object with the following attributes (non-exhaustive):

Here's a breakdown of the different Payment status values you might encounter:

How you handle this depends on your specific use case and which payment method you chose. Advice on handling specific payment methods can be found on the Payment Details page.

Note on handling Konbini / Convenience Store Payments

Konbini payments may have the following fields in the response:

• instructions_url (All Konbini): This contains a URL to a page providing the required payment information as well as detailed instructions on how to perform the payment at the Konbini. It should be served to the end-user for their convenience.
• receipt: This is a payment code that can be used for Konbini purchases.
  • For 7-Eleven, this is deprecated. This field should not be served to the end-user. The end user is required to access the URL served in the instructions_url field to perform payment at the store.
  • For others, this can be provided to end users along with confirmation_code, if available in the response. However, we strongly recommend providing just the URL from instructions_url to the end user, as it contains precise instructions as to how to perform payment at the store.
• confirmation_code: This is available for some Konbini brands and can be used by end users to perform payment at the store, in combination with receipt. However, this is not recommended - like receipt, we recommend providing just the URL from instructions_url to the end-user, as it contains precise instructions as to how to perform payment.

Step 3: webhook

The definitive way to know when a payment has been captured is to listen for payment.captured Webhooks. We recommend putting your order processing logic into your webhook handler for payment.captured or payment.authorized.

Notes on return_url

For direct payments, when the customer redirects to your return_url, KOMOJU adds query parameters to the url. One such query parameter an HMAC that can be checked to verify that the redirect came from KOMOJU.

The HMAC is computed using the final part of the URL: the path and all the query params other than the HMAC itself, signed using your private key. So, for example if the return URL provided at payment creation is:

https://example.com/return

After a payment is completed, we will redirect to the following URL:

https://example.com/return?hmac=examplehmac&param1=a&param2=b

The message is the path + parameters with hmac removed, so in this case:

message = "/return?param1=a&param2=b"

Then you can calculate the HMAC using hmac-sha256 to verify that it matches our HMAC. Example Ruby code below:

OpenSSL::HMAC.hexdigest('sha256', your_private_key, message) => "examplehmac"