Skip to content

Home

Jump to bottom
Hayato Tomoda edited this page Apr 6, 2026 · 29 revisions

Version 2.1.0

New Features

Granular Refund Webhook Events

Refund outcomes are now delivered via two separate webhook events, replacing the single CHARGE_REFUND event:

  • EVENT_TYPE_REFUND_SUCCEEDED — fired when a refund completes successfully
  • EVENT_TYPE_REFUND_FAILED — fired when a refund fails
message = Jamm::Webhook.parse(json_hash)

case message.event_type
when Jamm::OpenAPI::EventType::REFUND_SUCCEEDED     👈️👈️👈️
  refund = message.refund
  puts refund.refund_id         # "rfd-..."
  puts refund.amount_refunded
  puts refund.jamm_fee
  puts refund.consumption_tax   # 10% of Jamm fee
  puts refund.original_transaction_fee_waived  # true for same-day cancel
  puts refund.processed_at

when Jamm::OpenAPI::EventType::REFUND_FAILED         👈️👈️👈️
  error = message.refund&.error
  puts error.code               # Jamm error code
  puts error.message            # human-readable description
end

New RefundInfo Model

Refund webhook payloads now include a nested refund object (Jamm::OpenAPI::RefundInfo) with detailed refund information:

Field Type Description
refund_id String Refund identifier (rfd-* format)
amount_refunded Integer Refund amount
jamm_fee Integer Jamm fee charged for this refund
consumption_tax Integer 10% of Jamm fee
original_transaction_fee_waived Boolean true for same-day cancellation
error ChargeError Error details (on failure only)
processed_at String Processing timestamp

New ChargeError Model

A new Jamm::OpenAPI::ChargeError model provides structured error details for failed refunds:

error = message.refund&.error
error.code      # Jamm error code string
error.message   # human-readable description

New ChargeMessage Fields

The webhook ChargeMessage payload now includes additional fields for refund events:

Field Type Description
jamm_fee Integer Jamm fee for this refund
consumption_tax Integer 10% of Jamm fee
original_transaction_jamm_fee String "waived" or "not_waived"
refund_id String External refund identifier (rfd-*)
refund RefundInfo Nested refund details object

New Charge Status: REFUNDED

A new ChargeMessageStatus::REFUNDED (STATUS_REFUNDED) value has been added to indicate that a charge has been fully refunded.

Breaking Changes

Webhook event type renamed: CHARGE_REFUND → REFUND_SUCCEEDED / REFUND_FAILED

The CHARGE_REFUND event type has been removed and replaced with two granular events. Update your webhook handler:

# BEFORE (2.0.0)
when Jamm::OpenAPI::EventType::CHARGE_REFUND

# AFTER (2.1.0)
when Jamm::OpenAPI::EventType::REFUND_SUCCEEDED     👈️👈️👈️
  # handle successful refund
when Jamm::OpenAPI::EventType::REFUND_FAILED         👈️👈️👈️
  # handle failed refund

Version 2.0.0

New Features

Platform Mode

The SDK now supports Platform Mode, allowing platformers to call the Jamm API on behalf of their merchants.

Configure platform mode during initialization:

Jamm.configure(
    client_id: '<your client id>',
    client_secret: '<your client secret>',
    env: 'production',
    platform: true,                         👈️👈️👈️
)

Once configured, all API methods accept an optional merchant: parameter to specify which merchant to act on behalf of:

# Payment on behalf of a merchant
Jamm::Payment.on_session(
    merchant: 'mer-12345',                  👈️👈️👈️
    buyer: Jamm::OpenAPI::Buyer.new(
        email: 'foo@example.com',
        name: 'Yamada Taro',
    ),
    charge: Jamm::OpenAPI::InitialCharge.new(
        price: 1000,
        description: 'Test payment',
    ),
    redirect: Jamm::OpenAPI::URL.new(
        success_url: 'https://jamm-pay.jp/success',
        failure_url: 'https://jamm-pay.jp/fail',
    )
)

# Customer management on behalf of a merchant
Jamm::Customer.get('cus-12345', merchant: 'mer-12345')
Jamm::Customer.create(buyer: buyer, merchant: 'mer-12345')
Jamm::Customer.update('cus-12345', params, merchant: 'mer-12345')
Jamm::Customer.delete('cus-12345', merchant: 'mer-12345')

The merchant: parameter is available on all modules: Payment, Customer, Healthcheck.

Refund Support

A new Jamm::Payment.refund method is now available. If the same-day cancellation window has not passed, the charge is cancelled directly. Otherwise, a bank transfer refund request is created. The final result is delivered via webhook (charge_refund).

request = Jamm::OpenAPI::RefundRequest.new(
    charge: 'chg-12345',
)

Jamm::Payment.refund(request)

# Platform mode
Jamm::Payment.refund(request, merchant: 'mer-12345')

Charge Status Enum

A new ChargeStatus enum has been added with the following values:

  • CHARGE_STATUS_SUCCESS
  • CHARGE_STATUS_FAILURE
  • CHARGE_STATUS_WAITING_EKYC
  • CHARGE_STATUS_BLOCKING
  • CHARGE_STATUS_CANCELLED
  • CHARGE_STATUS_REFUNDED
  • CHARGE_STATUS_PENDING

Breaking Changes

Jamm.configure signature change

Jamm.configure now accepts an optional platform: keyword argument. Existing calls without platform: will continue to work (defaults to false), but the SDK now sets Jamm.mode internally. This is not a breaking change for existing merchant integrations.

Webhook event type renamed: CHARGE_CANCEL → CHARGE_REFUND

The CHARGE_CANCEL event type has been renamed to CHARGE_REFUND. If you are matching on webhook event types, update your code:

# BEFORE (1.x)
when Jamm::OpenAPI::EventType::CHARGE_CANCEL

# AFTER (2.0.0)
when Jamm::OpenAPI::EventType::CHARGE_REFUND        👈️👈️👈️

Deleted Features

Jamm::Charge module removed

The Jamm::Charge module, deprecated since v1.4.0, has been permanently removed. All deprecated methods are no longer available:

  • Jamm::Charge.create_with_redirect → use Jamm::Payment.on_session
  • Jamm::Charge.create_without_redirect → use Jamm::Payment.off_session
  • Jamm::Charge.get → use Jamm::Payment.get
  • Jamm::Charge.list → use Jamm::Payment.list

Version 1.7.0

New Features

On Session Payment now supports one-time payment mode.

Jamm::Payment.on_session(
    one_time: true,                     👈️👈️👈️
    buyer: Jamm::OpenAPI::Buyer.new(
        email: 'foo@example.com',
        name: 'Yamada Taro',
        force_kyc: true,
        katakana_last_name: 'ヤマダ',
        katakana_first_name: 'タロウ',
        address: 'Tokyo, Minato-ku 1-2-3',
        birth_date: '2000-01-23',
        gender: 'male',
        metadata: {},
    ),
    charge: Jamm::OpenAPI::InitialCharge.new(
        price: 1000,
        description: 'Test payment',
        metadata: {},
    ),
    redirect: Jamm::OpenAPI::URL.new(
        success_url: 'https://jamm-pay.jp/success',
        failure_url: 'https://jamm-pay.jp/fail',
    )
)

Version 1.6.0

Improvements

customer.update() methods now supports updating customer (buyer) email and phone number.

Jamm::Customer.update('cus-12345', {
    email: 'new-email-address@example.com',
    phone: '09012345678',
})

Please check out Customer Update Parameters for more information.

Version 1.5.0

New Features

Added a new link_initiated field to the Jamm::Customer.get response that indicates whether a payment link associated with this customer has been clicked or initialized.

Please check Customer object for more information.

Minor Changes

Optional Redirect Links

Redirect links are now optional. If a redirect link is provided, the user will be redirected, otherwise they will remain on the same page.

# On Session Payment with redirect object.
Jamm::Payment.on_session(
    buyer: Jamm::OpenAPI::Buyer.new(
        email: 'foo@example.com',
        name: 'Yamada Taro',
        force_kyc: true,
        katakana_last_name: 'ヤマダ',
        katakana_first_name: 'タロウ',
        address: 'Tokyo, Minato-ku 1-2-3',
        birth_date: '2000-01-23',
        gender: 'male',
        metadata: {},
    ),
    charge: Jamm::OpenAPI::InitialCharge.new(
        price: 1000,
        description: 'Test payment',
        metadata: {},
    ),
    # Only set this object when merchant wants to redirect
    # user back after completing payment approval.
    redirect: Jamm::OpenAPI::URL.new(               👈️👈️👈️
        success_url: 'https://jamm-pay.jp/success',
        failure_url: 'https://jamm-pay.jp/fail',
    )
)

# On Session Payment without redirect object.
Jamm::Payment.on_session(
    buyer: Jamm::OpenAPI::Buyer.new(
        email: 'foo@example.com',
        name: 'Yamada Taro',
        force_kyc: true,
        katakana_last_name: 'ヤマダ',
        katakana_first_name: 'タロウ',
        address: 'Tokyo, Minato-ku 1-2-3',
        birth_date: '2000-01-23',
        gender: 'male',
        metadata: {},
    ),
    charge: Jamm::OpenAPI::InitialCharge.new(
        price: 1000,
        description: 'Test payment',
        metadata: {},
    ),
    # Omit redirect object when merchant does not need to
    # bring user back to website after payment approval.
)

Version 1.4.0

We are deprecating some methods from older versions. You will see deprecation warning when those methods are called, and we will remove them entirely from our backend in future versions. Once it's removed from our backend, all method calls will return HTTP error.

Please follow our migration guide in below to transition to our latest methods.

Deprecating Methods

  • Jamm::Charge::create_with_redirect
  • Jamm::Charge::create_without_redirect
  • Jamm::Charge::get
  • Jamm::Charge::list

Migration Guide

Jamm::Charge::create_with_redirect

This method was supposed to provide Payment Link to bring customer to Jamm application to confirm and approve their payment. Ruby SDK 1.4.0 start to provide such functionality through Jamm::Payment.on_session method.

If you are creating Payment Link for new customer, you should have buyer object attached. The input structure is exactly the same, just swap the method call.

# DEPRECATING
Jamm::Charge.create_with_redirect(
    buyer: Jamm::OpenAPI::Buyer.new(
        email: 'foo@example.com',
        name: 'Yamada Taro',
        force_kyc: true,
        katakana_last_name: 'ヤマダ',
        katakana_first_name: 'タロウ',
        address: 'Tokyo, Minato-ku 1-2-3',
        birth_date: '2000-01-23',
        gender: 'male',
        metadata: {},
    ),
    charge: Jamm::OpenAPI::InitialCharge.new(
        price: 1000,
        description: 'Test payment',
        metadata: {},
    ),
    redirect: Jamm::OpenAPI::URL.new(
        success_url: 'https://jamm-pay.jp/success',
        failure_url: 'https://jamm-pay.jp/fail'
    )
)

# NEW
Jamm::Payment.on_session(               👈️👈️👈️
    buyer: Jamm::OpenAPI::Buyer.new(
        email: 'foo@example.com',
        name: 'Yamada Taro',
        force_kyc: true,
        katakana_last_name: 'ヤマダ',
        katakana_first_name: 'タロウ',
        address: 'Tokyo, Minato-ku 1-2-3',
        birth_date: '2000-01-23',
        gender: 'male',
        metadata: {},
    ),
    charge: Jamm::OpenAPI::InitialCharge.new(
        price: 1000,
        description: 'Test payment',
        metadata: {},
    ),
    redirect: Jamm::OpenAPI::URL.new(
        success_url: 'https://jamm-pay.jp/success',
        failure_url: 'https://jamm-pay.jp/fail',
    )
)

If you are creating Payment Link for the existing customer, you should have customer object attached. The input structure is exactly the same, just swap the method call.

# DEPRECATING
Jamm::Charge.create_with_redirect(
    customer: 'cus-12345',
    charge: Jamm::OpenAPI::InitialCharge.new(
        price: 1000,
        description: 'Test payment',
        metadata: {},
    ),
    redirect: Jamm::OpenAPI::URL.new(
        success_url: 'https://jamm-pay.jp/success',
        failure_url: 'https://jamm-pay.jp/fail',
    )
)

# NEW
Jamm::Payment.on_session(               👈️👈️👈️
    customer: 'cus-12345',
    charge: Jamm::OpenAPI::InitialCharge.new(
        price: 1000,
        description: 'Test payment',
        metadata: {},
    ),
    redirect: Jamm::OpenAPI::URL.new(
        success_url: 'https://jamm-pay.jp/success',
        failure_url: 'https://jamm-pay.jp/fail'
    )
)

Jamm::Charge::create_without_redirect

This method was supposed to immediately withdraw money from the existing customer's bank account.

Ruby SDK 1.4.0 start to provide such functionality through Jamm::Payment.off_session method.

# DEPRECATING
Jamm::Charge.create_without_redirect(
    customer: 'cus-12345',
    charge: Jamm::OpenAPI::InitialCharge.new(
        price: 1000,
        description: 'Test payment',
        metadata: {},
    )
)

# NEW
Jamm::Payment.off_session(               👈️👈️👈️
    customer: 'cus-12345',
    charge: Jamm::OpenAPI::InitialCharge.new(
        price: 1000,
        description: 'Test payment',
        metadata: {},
    )
)

Jamm::Charge::get

# DEPRECATING
Jamm::Charge.get('chg-12345')

# NEW
Jamm::Payment.get('chg-12345')           👈️👈️👈️

Jamm::Charge::list

# DEPRECATING
Jamm::Charge.list(
  customer: 'cus-12345',
)

# NEW
Jamm::Payment.list(                       👈️👈️👈️
  customer: 'cus-12345',
)

Clone this wiki locally