Onerway
POST

Subscription payment webhook

View as Markdown
Webhook URL
Use this webhook to receive subscription payment results and link each charge to the related contractId, tokenId, and scenarios value.

Signature coverage

Request signing guide

All payload fields are included in the signature except:

Webhook payload fields

notifyTypestring
Notification type, identifying the webhook business category.
Constraints
Values
Fixed to TXN for subscription payment notifications.
transactionIdstring
Onerway transaction number generated for this subscription payment, used for tracking, queries, and idempotent processing.
Constraints
Rule
This value is a large-ID-style string. Preserve it as a string in JavaScript systems to avoid precision loss.
paymentIdstring
Payment intent ID used to associate this subscription payment flow.
txnTypestring
Transaction operation type represented by this notification.
Allowed values
SALE
Payment transaction.
Constraints
Values
Fixed to SALE for subscription payment notifications.
merchantNostring
Merchant number assigned by Onerway, identifying the merchant account receiving this notification.
merchantTxnIdstring
Merchant-side transaction number used for reconciliation, deduplication, and subscription payment order association.
responseTimestring
Time when Onerway generated this notification result in yyyy-MM-dd HH:mm:ss format.
txnTimestring
Time when this subscription payment transaction occurred or reached this transaction state in yyyy-MM-dd HH:mm:ss format.
txnTimeZonestring
Time zone offset used by txnTime, in ±HH:mm format.
orderAmountstring
Subscription payment amount, expressed in orderCurrency.
Constraints
Rule
Amount values are returned as decimal strings. Avoid binary floating-point arithmetic for money.
orderCurrencystring
Subscription payment currency, as a three-letter ISO 4217 currency code.
statusstring
Processing status of this subscription payment transaction.
Allowed values
S
Successful transaction.
F
Failed transaction.
P
Processing transaction.
paymentStatusstring
Payment-intent-level status for this subscription payment intent.
Allowed values
I
Payment intent initialized.
U
Payment intent pending payment.
P
Payment intent processing.
contractIdstring
Subscription contract number for this payment. Save it for later subscription queries, cancellation, or updates.
Constraints
Rule
This value is a large-ID-style string. Preserve it as a string in JavaScript systems to avoid precision loss.
tokenIdstring
Subscription token. Store it together with contractId; later subscription charges, queries, and cancellation require both values.
Constraints
Rule
This token is only valid for subscription operations. It is not a saved payment method token and cannot be used for subProductType=TOKEN payments.
Consistency
For a card subscription created with subscription.bindCard=true, the saved payment method token is returned in cardTokenId, not in this field. For local payment method subscriptions, the Saved payment method result webhook returns this same value in its tokenId, where it is also the subscription token. Wallet subscriptions receive only this notification.
cardTokenIdstring
Saved payment method token of the card used for this subscription.
Constraints
Consistency
Same value as tokenId in the Saved payment method result webhook; use it to match the two notifications. It is a different token from tokenId in this notification.
Rule
Whether the card was saved is decided by the Saved payment method result webhook: use this token for subProductType=TOKEN payments through Create direct transaction only after that notification returns status=S. Onerway saves the card after this payment succeeds, so a failed payment never produces that notification. The order in which your server receives the two notifications is not guaranteed; process each one idempotently.
ecistring
Electronic Commerce Indicator (ECI), indicating the 3DS authentication state related to the transaction.
cardBinCountrystring
Card BIN country or region, as an ISO 3166-1 alpha-2 two-letter code.
Transaction result reason object, carried as a JSON string in the notification.
signstringSignature field · Excluded from signature
Legacy signature string kept for compatibility. It is computed with only the first enabled key and can mismatch your configured key during key rotation; verify notifications with the X-Rh-Signature header instead.
Constraints
Rule
Exclude sign itself from the canonical string when verifying this webhook.
paymentMethodstringExcluded from signature
Payment method or card brand used by this subscription payment.
walletTypeNamestringExcluded from signature
Wallet type name.
Allowed values
GooglePay
Google Pay wallet.
ApplePay
Apple Pay wallet.
EXPR
Wallet funding source: bank card.
subscriptionManageUrlstring
Subscription management URL that the buyer can use to view and manage the subscription.
subscriptionStatusstring
Current lifecycle status of the subscription contract.
Allowed values
trialing
Trial period before the paid subscription starts.
paymentdue
Payment is due or processing; the subscription contract is not active yet.
active
The subscription is active and all due payments have been paid.
dataStatusstring
Enablement status of the subscription contract.
Allowed values
0
Pending activation.
1
Active.
2
Inactive.
Product list submitted in txnOrderMsg.products of the subscription request, returned as a JSON string.
metaDatastring
Custom data submitted in the request, returned unchanged as the original JSON string.
Constraints
Consistency
If both the top-level metaData and subscription.metaData were submitted, this field returns subscription.metaData.
channelRequestIdstring
Payment channel or processor request identifier, used for channel-side reconciliation or troubleshooting.
scenariosstring
Subscription scenario that triggered this notification, distinguishing lifecycle events across the initial payment, renewals, card replacement, plan changes, cancellation, and expiration.
Allowed values
SUBSCRIPTION_INITIAL
Initial subscription payment, usually collected when the subscription contract is created.
SUBSCRIPTION_RENEWAL
Recurring subscription payment for a later billing cycle, using the saved contractId and tokenId.
SUBSCRIPTION_CARD_REPLACEMENT
Payment method update for an existing subscription, such as replacing an expired or invalid card.
Payment method details object. Card transaction details are under the card child object.

Webhook example

{
  "notifyType": "TXN",
  "transactionId": "replace_with_card_sale_transaction_id",
  "paymentId": "replace_with_card_sale_payment_id",
  "txnType": "SALE",
  "merchantNo": "replace_with_merchant_no",
  "merchantTxnId": "replace_with_merchant_subscription_reference",
  "responseTime": "2026-01-15 10:10:02",
  "txnTime": "2026-01-15 10:10:00",
  "txnTimeZone": "+08:00",
  "orderAmount": "7.00",
  "orderCurrency": "USD",
  "status": "S",
  "paymentStatus": "S",
  "contractId": "replace_with_subscription_contract_id",
  "tokenId": "replace_with_subscription_token",
  "cardTokenId": "replace_with_saved_card_token",
  "eci": "05",
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "replace_with_sha256_signature",
  "paymentMethod": "VISA",
  "subscriptionManageUrl": "https://developers.onerway.com/example-subscription-manage",
  "subscriptionStatus": "active",
  "dataStatus": "1",
  "products": "[{\"currency\":\"USD\",\"name\":\"Example weekly plan\",\"num\":\"1\",\"price\":\"7.00\",\"type\":\"\"}]",
  "metaData": "{\"plan\":\"weekly\"}",
  "channelRequestId": "replace_with_card_sale_channel_request_id",
  "scenarios": "SUBSCRIPTION_INITIAL",
  "paymentMethodDetails": "{\"card\":{\"checks\":{\"addressCheck\":null,\"postalCodeCheck\":null,\"cardholderNameCheck\":null,\"avsResultRawCode\":null,\"threeDSecureResult\":{\"version\":\"UNKNOWN\",\"authenticationFlow\":\"CHALLENGE\",\"chargebackLiability\":\"UNKNOWN\",\"transStatus\":null,\"transStatusReason\":null,\"veresEnrolled\":null,\"eci\":\"05\",\"cvvResult\":null,\"avsFullResult\":null,\"cavvResult\":\"replace_with_cavv\"}},\"holderName\":\"Example Cardholder\",\"year\":\"2028\",\"month\":\"05\",\"cardType\":null,\"productCategory\":null,\"issuer\":\"Example Issuer\",\"cardBinCountry\":\"US\",\"authorizationCode\":null,\"cardNumber\":\"400000******0002\"}}"
}

Acknowledgement

Return HTTP 200 with the received transactionId as the raw response body after the subscription payment webhook is received and accepted.

Response body example

HTTP 200
Use a text/plain response whose body is the transactionId from the received webhook payload.
replace_with_transaction_id

Payment result webhook

Receive ordinary payment result notifications for successful, failed, timed-out, or canceled payment flows.

Authorization, capture, and void webhook

Receive pre-authorization creation, capture, and void notifications and associate them through the same payment intent.