Depot Payments

Overview

Depot is a redirect-based e-money payment method. After creating a payment via API, redirect the customer to payment_url to complete the payment.

Requirements

Requirement	Value
Currency	JPY only
Amount	Positive integer (whole yen). Decimal amounts are rejected
Maximum amount	¥100,000 per payment
`payment_method`	Send `"depot"`
`email`	Required
Refund / Void	Not available through the API — contact support
Payment result	Delivered by webhook. You can also confirm it with the Get Payment API (`GET /v1/payments/{id}`)

Field Constraints

Depot validates these fields more strictly than card payments, and it does so late: creating the payment succeeds, and the violation only surfaces when the customer tries to pay on the Depot page. Validate these yourself before calling the API — otherwise the customer is redirected, fills nothing in, and hits an error you cannot explain to them.

Field	Constraint
`customer_id`	Alphanumeric only (no hyphens, underscores, or other symbols), up to 150 characters
`product_name`	Up to 30 characters. Kanji is not supported
`tel`	10–15 digits
`email`	Up to 255 characters

customer_id rejects any character outside [A-Za-z0-9], and the rejection happens at the payment step, not at creation. A value such as cus_12345 is accepted by POST /v1/payments, the customer is redirected, and only then does the payment fail with error 1004. Map your customer identifiers to an alphanumeric value before sending.

customer_id, email, tel and product_name are shown to the customer on the payment page, so send them whenever you have the values.

Payment Flow

Create Payment

Call POST /v1/payments to create a payment and obtain payment_url

Redirect Customer

Redirect customer to payment_url

Customer Completes Payment

Customer completes payment on Depot’s page

Redirect Back

Customer is redirected to the success_url / failure_url / cancel_url you passed on the payment, falling back to the defaults configured in your merchant dashboard

Verify Result

Treat the webhook as the source of truth. Optionally confirm with the Get Payment API

Implementation Example

// 1. Create payment via API
const response = await fetch('https://api.sandbox.zafapay.com/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1000,             // whole yen only — decimals are rejected
    currency: 'jpy',          // Depot settles in JPY
    payment_method: 'depot',
    external_id: 'order12345',
    product_name: 'Premium Plan',
    customer_id: 'cust001',   // alphanumeric only
    email: 'customer@example.com',
    tel: '08000000000',
    success_url: 'https://example.com/checkout/success',
    failure_url: 'https://example.com/checkout/failed',
    cancel_url: 'https://example.com/checkout/cancel'
  })
});

const payment = await response.json();

// 2. Redirect customer to Depot payment page
window.location.href = payment.payment_url;

Webhook Integration

The webhook is the authoritative result of a Depot payment — confirm the payment there rather than relying on the page the customer lands on. Depot webhooks use the same payload as every other payment method: payment_method is "depot", currency is "jpy", and the card fields (card_brand, card_last4, …) are absent. Any metadata you sent when creating the payment is returned unchanged, which makes it a convenient place to carry your own session identifier.

// Webhook handler
app.post('/webhooks/zafapay', express.raw({ type: 'application/json' }), (req, res) => {
  // Sandbox and production sign under different header names — read both,
  // or your sandbox integration fails verification on every callback
  const signature =
    req.headers['x-zafapay-signature'] || req.headers['x-zafapay-signature-sandbox'];

  // Verify against the raw body before trusting anything.
  // See the Webhooks reference for verifyWebhookSignature.
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, transaction_id, external_id, amount, currency } = JSON.parse(req.body);

  if (event === 'payment.succeeded') {
    // Use transaction_id as the idempotency key — webhooks may be delivered more than once
    await markOrderPaid({ transaction_id, external_id, amount, currency });
  }

  res.json({ received: true });
});

For the complete payload and signature verification, see the Webhooks reference. For all request parameters, see API Reference.

Getting Started

Dashboard

Integration

Overview

Requirements

Field Constraints

Payment Flow

Implementation Example

Webhook Integration

​Overview

​Requirements

​Field Constraints

​Payment Flow

​Implementation Example

​Webhook Integration

Overview

Requirements

Field Constraints

Payment Flow

Implementation Example

Webhook Integration