DEPOT | Merchant Connection Specification

1. Overview

This is the specification for connecting a merchant's website (frontend) to our PSP payment system.

It performs transaction registration, redirect to the payment page, and receiving payment results (Webhook) via APIs.

2. Connection flow diagram

3. Connection specification details

3.1. Payment API

The following three are mainly "required".

Endpoint [Production] https://api.poitouch.com/v1/payments Method: POST

Endpoint [Sandbox] https://api.sandbox.poitouch.com/v1/payments
Authentication Bearer token (API access token) Note: Tokens are issued by us. Production and Sandbox tokens are provided separately.
API request See below.

Example API request

{
  "amount": 1200,
  "currency": "jpy",
  "payment_method": "depot",
  "email": "test@example.com"
}

Example response

{
  "success": true,
  "transaction_id": "tx_xxx...",
  "gateway_transaction_id": "tx...",
  "payment_url": "https://poitouch.com/payment/?token=xxx..."
}

Transaction API parameters

Key	Type	Length	Request	Description	Response
amount	int/float	up to 6 digits	● (required)	Payment amount	✓
currency	string	up to 3 chars	● (required)	Currency (jpy)	✓
payment_method	string	up to 20 chars	● (required)	Payment method (depot)	✓
email	string	up to 255 alphanumerics	● (required)	Customer email	✓
customer_id	string	up to 150 alphanumerics	○	Customer ID	✓
product_name	string	alphanumerics, spaces, hyphens, full-width kana, long vowel mark (ー), up to 30 chars	○	Product name (kanji not allowed)	✓
tel	string	10–15 digits	○	User phone number	✓
merchant_order_id	string	—	○	Merchant-side order ID	✓
transaction_id	string	—	-	Transaction ID (issued by PoiTouch)	✓
status	string	—	-	Transaction status (e.g. succeeded)	✓
created_at	string	—	-	Created at (ISO 8601, UTC)	✓
payment_url	string	—	-	Payment page URL (for redirect)	✓

Request column … ● (required) / ○ (optional) / - (response-only)
Response column … "✓" means returned

3.2. Redirect to the payment page

Redirect the end user to the payment_url you received.

3.3. Webhook notification specification

Purpose: Notify the merchant server of the payment result after payment completes
Webhook URL: Configured per merchant (viewable/editable in the admin panel)
Authentication: HMAC-SHA256 signature (using the Webhook secret)

Notification: example Body

{
  "event": "payment.succeeded",
  "transaction_id": "tx_xxx...",
  "status": "succeeded",
  "currency": "jpy",
  "payment_method": "depot",
  "amount": 500,
  "merchant_order_id": "ORDER12345",
  "product_name": "Sweets Assortment",
  "customer_id": "cust0123",
  "email": "xxxxx@gmail.com",
  "tel": "09012355332",
  "amount_refunded": 0,
  "created_at": "2025-06-05T06:15:04.000Z",
  "timestamp": "2025-06-05T07:39:59.333Z"
}

Notification: example Header

{
  "user-agent": "Poitouch-Webhook/1.0",
  "content-type": "application/json",
  "x-forwarded-for": "168.1.1.1",
  "x-forwarded-host": "test.com",
  "x-forwarded-proto": "https",
  "X-poitouch-signature": "xxxxxx",
  "accept-encoding": "gzip"
}

3.4. Webhook retry

If the Webhook cannot be received due to a 5xx error, etc., it is automatically retried several times.

3.5. Payment notification email

If needed, a notification is sent to the merchant's specified email address when payment completes (viewable/editable in the admin panel).

3.6. Payment completion email (sample)

Subject: [Payment Successful] Merchant Name - Transaction ID: tx_xxxx

Dear [Merchant], The payment was processed successfully.

Transaction ID: tx_xxxx… Amount: ¥1,200 Payment method: Card Status: success Product: Red Sneakers

4. Notes

API tokens and Webhook secrets can be regenerated and viewed from the admin panel.
URLs and keys for the test and production environments are managed separately.
Always communicate over HTTPS.

If you need detailed implementation examples (sample code, etc.), please see below.

💻 Node.js 18 sample code

1. Calling the Payment API

const https = require("https");

const postData = JSON.stringify({
  amount: 1000,
  currency: "jpy",
  payment_method: "depot",
  email: "test@example.com",
});

https
  .request(
    "https://api.poitouch.com/v1/payments",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer sk_test_xxxxxxxxxx", // access token
        "Content-Length": postData.length,
      },
    },
    (res) => {
      let data = "";
      res.on("data", (chunk) => (data += chunk));
      res.on("end", () => console.log(JSON.parse(data).payment_url));
    },
  )
  .end(postData);

Sandbox API endpoint: https://api.sandbox.poitouch.com/v1/payments
Production API endpoint: https://api.poitouch.com/v1/payments

2. Webhook receiver server (Node.js 18)

const crypto = require('crypto');
const WEBHOOK_SECRET = 'whsec_xxxxxxxxxxx'; // Webhook secret

function handleWebhook(req, res) {
  // Get the request body
  const body = JSON.stringify(req.body);

  // Verify the signature
  const signature = req.headers['x-poitouch-signature'] || '';
  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(body)
    .digest('hex');

  if (signature === expected) {
    // Valid signature
    console.log('Webhook received:', req.body);
    res.json({ status: 'ok' });
  } else {
    // Invalid signature → 401
    res.status(401).end();
  }
}

module.exports = handleWebhook;

Replace YOUR_WEBHOOK_SECRET with your actual secret.
Sandbox signature: x-poitouch-signature-sandbox / Production signature: x-poitouch-signature
Sandbox user-agent: Poitouch-Webhook-Sandbox/1.0 / Production user-agent: Poitouch-Webhook/1.0

💻 PHP sample code

1. Calling the Payment API (cURL example)

<?php
// Poitouch payment API endpoint and token (set the one issued by Poitouch)
$url = 'https://api.poitouch.com/v1/payments';
$apiToken = 'YOUR_MERCHANT_API_TOKEN'; // API access token

// Payment data
$data = [
  'amount' => 500, // amount
  'currency' => 'jpy', // currency
  'payment_method' => 'depot', // payment method
  'email' => 'test@example.com' // email
];

// Call the API
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'Authorization: ' . 'Bearer ' . $apiToken
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

// Redirect to the payment page
$res = json_decode($response, true);
header('Location: ' . $res['payment_url']);
exit;
?>

Sandbox API endpoint: https://api.sandbox.poitouch.com/v1/payments
Production API endpoint: https://api.poitouch.com/v1/payments

2. Webhook receiver (with signature verification)

<?php
// Webhook secret (set the one issued by Poitouch)
$secret = 'YOUR_WEBHOOK_SECRET'; // Webhook secret

// Get the signature from the header (e.g. using the 'X-Signature' header)
$signature = $_SERVER['HTTP_X_POITOUCH_SIGNATURE'] ?? '';

// Get the raw request body
$body = file_get_contents('php://input');

// Recompute the signature with HMAC-SHA256
$expected = hash_hmac('sha256', $body, $secret);

// Verify the signature
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    echo 'Invalid signature';
    exit;
}

// On success
file_put_contents('/var/www/psp_webhook.log', $body . "\n", FILE_APPEND);
http_response_code(200);
echo 'ok';
?>

Replace YOUR_WEBHOOK_SECRET with your actual secret.
Sandbox signature: x-poitouch-signature-sandbox / Production signature: x-poitouch-signature
Sandbox user-agent: Poitouch-Webhook-Sandbox/1.0 / Production user-agent: Poitouch-Webhook/1.0

DEPOT | Merchant Connection Specification

On this page