# Authorization, capture, and void webhook

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

```yaml
openapi: 3.1.0
info:
  title: Authorization, capture, and void webhook
  version: 1.0.0
  description: Receive pre-authorization creation, capture, and void notifications
    and associate them through the same payment intent.
webhooks:
  authorization.capture:
    post:
      summary: Authorization, capture, and void webhook
      description: Receive pre-authorization creation, capture, and void notifications
        and associate them through the same payment intent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                notifyType:
                  type: string
                  description: Notification type, identifying the webhook business category.
                  x-onerway-constraints:
                    - kind: values
                      text: Fixed to `TXN` for authorization, capture, and void notifications.
                  x-onerway-signature-participation: included
                transactionId:
                  type: string
                  description: Onerway transaction number generated for this authorization,
                    capture, or void operation, used for tracking, queries, and
                    idempotent processing.
                  x-onerway-constraints:
                    - kind: rule
                      text: This value is a large-ID-style string. Preserve it as a string in
                        JavaScript systems to avoid precision loss.
                    - kind: consistency
                      text: In the same authorization lifecycle, `AUTH`, `CAPTURE`, and `VOID` are
                        related but separate transaction operations, and their
                        `transactionId` values are different.
                  x-onerway-signature-participation: included
                paymentId:
                  type: string
                  description: Payment intent ID used to associate the original pre-authorization
                    and its later capture or void operation.
                  x-onerway-constraints:
                    - kind: rule
                      text: This value is a large-ID-style string. Preserve it as a string in
                        JavaScript systems to avoid precision loss.
                    - kind: consistency
                      text: Authorization, capture, and void operations under the same
                        pre-authorization lifecycle can be associated through
                        the same `paymentId`.
                  x-onerway-signature-participation: included
                txnType:
                  type: string
                  description: Transaction operation type, indicating whether this notification is
                    for pre-authorization creation, capture, or void.
                  enum:
                    - AUTH
                    - CAPTURE
                    - VOID
                  x-enum-descriptions:
                    AUTH: Pre-authorization creation. Funds are authorized first; use `status` and
                      `paymentStatus` to determine the authorization state.
                    CAPTURE: Pre-authorization capture. Captures an already authorized amount.
                    VOID: Pre-authorization void. Releases the authorized amount without capturing
                      it.
                  x-onerway-signature-participation: included
                merchantNo:
                  type: string
                  description: Merchant number assigned by Onerway, identifying the merchant
                    account receiving this notification.
                  x-onerway-signature-participation: included
                merchantTxnId:
                  type: string
                  description: Merchant transaction number used for reconciliation and order
                    association.
                  x-onerway-constraints:
                    - kind: rule
                      text: Capture notifications may echo the merchant transaction number of the
                        original pre-authorization order. `VOID` notifications
                        can return the merchant transaction number from the void
                        request. Use `transactionId` to deduplicate operation
                        notifications. Associate lifecycle records with
                        `paymentId`, `transactionId`, and transaction query
                        results.
                  x-onerway-signature-participation: included
                responseTime:
                  type: string
                  description: Time when Onerway generated this notification result in `yyyy-MM-dd
                    HH:mm:ss` format.
                  x-onerway-signature-participation: included
                txnTime:
                  type: string
                  description: Time when this authorization, capture, or void transaction occurred
                    in `yyyy-MM-dd HH:mm:ss` format.
                  x-onerway-signature-participation: included
                txnTimeZone:
                  type: string
                  description: Time zone offset used by `txnTime`, in `±HH:mm` format.
                  x-onerway-signature-participation: included
                orderAmount:
                  type: string
                  description: Original pre-authorization order amount. In capture or void
                    notifications, this represents the associated original
                    authorization amount.
                  x-onerway-constraints:
                    - kind: rule
                      text: Amount values are returned as decimal strings. Avoid binary floating-point
                        arithmetic for money.
                  x-onerway-signature-participation: included
                orderCurrency:
                  type: string
                  description: Original pre-authorization order currency, as a three-letter [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                    currency code.
                  x-onerway-signature-participation: included
                status:
                  type: string
                  description: Current processing status of this authorization, capture, or void
                    operation.
                  enum:
                    - S
                    - F
                    - P
                    - R
                    - N
                    - I
                    - U
                  x-enum-descriptions:
                    S: Successful transaction.
                    F: Failed transaction.
                    P: Processing transaction.
                    R: Redirect required.
                    N: Canceled transaction. The transaction was closed because it was not paid
                      within its validity window — for example, the checkout
                      session timed out.
                    I: Under review or approval.
                    U: Waiting for payment.
                  x-onerway-constraints:
                    - kind: consistency
                      text: This field represents the result of the current operation. Do not confuse
                        it with the payment-intent-level `paymentStatus`.
                  x-onerway-signature-participation: included
                paymentStatus:
                  type: string
                  description: Payment-intent-level status representing the current state of the
                    pre-authorization lifecycle.
                  enum:
                    - A
                    - O
                    - S
                    - N
                  x-enum-descriptions:
                    A: Payment intent is authorized and waiting for a later action, such as capture.
                    O: Payment intent remains open and can be retried.
                    S: Payment intent succeeded.
                    N: Payment intent is closed.
                  x-onerway-constraints:
                    - kind: rule
                      text: After a successful `AUTH`, this field can return `A`; when `AUTH` fails
                        but the payment intent remains retryable it can return
                        `O`; after a successful `CAPTURE` it can return `S`;
                        after a successful `VOID` it returns `N` (closed).
                  x-onerway-signature-participation: included
                eci:
                  type:
                    - string
                    - "null"
                  description: Electronic Commerce Indicator (ECI), indicating the 3DS
                    authentication state related to the transaction.
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Has a value when card or 3DS transactions return ECI; it can be omitted when
                        absent.
                      zh: 卡交易或 3DS 交易返回 ECI 时有值；未返回时可能不返回。
                  x-onerway-signature-participation: included
                cardBinCountry:
                  type:
                    - string
                    - "null"
                  description: Card BIN country or region, as an [ISO 3166-1
                    alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
                    two-letter code.
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Has a value when this is a card transaction and the card BIN country or
                        region can be identified.
                      zh: 卡交易且可识别卡 BIN 所属国家 / 地区时有值。
                  x-onerway-signature-participation: included
                reason:
                  type: string
                  description: Transaction result reason object, carried as a JSON string in the
                    notification.
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      respCode:
                        type: string
                        description: Result code. `20000` means success; other values are error codes.
                      respMsg:
                        type: string
                        description: Human-readable message for the result code.
                  x-onerway-format: json_string
                  x-onerway-signature-participation: included
                periodValue:
                  type:
                    - string
                    - "null"
                  description: Installment period count.
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Has a value for installment transactions; it may be an empty string or
                        omitted when not applicable.
                      zh: 分期交易返回期数时有值；不适用或未返回期数时可能为空字符串或不返回。
                  x-onerway-signature-participation: excluded
                sign:
                  type: string
                  description: 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.
                  x-onerway-constraints:
                    - kind: rule
                      text: Exclude `sign` itself from the canonical string when verifying this
                        webhook.
                  x-onerway-signature-participation: signature-field
                paymentMethod:
                  type: string
                  description: Payment method or card brand used by this authorization, capture,
                    or void.
                  x-onerway-signature-participation: excluded
                channelRequestId:
                  type: string
                  description: Payment channel or processor request identifier, used for
                    channel-side reconciliation or troubleshooting.
                  x-onerway-signature-participation: included
                paymentMethodDetails:
                  type: string
                  description: Payment method details object. Card transaction details are under
                    the `card` child object.
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      card:
                        type: object
                        properties:
                          checks:
                            type:
                              - object
                              - "null"
                            properties:
                              addressCheck:
                                type:
                                  - string
                                  - "null"
                                description: AVS street-address check result.
                                enum:
                                  - pass
                                  - fail
                                  - unavailable
                                  - unchecked
                                  - notProvided
                                  - unsupported
                                  - null
                                x-enum-descriptions:
                                  pass: The information submitted for verification matches issuer records.
                                  fail: The information submitted for verification does not match issuer records.
                                  unavailable: The issuer does not support this verification.
                                  unchecked: Verification was not performed.
                                  notProvided: The information required for this verification was not provided.
                                  unsupported: AVS is not supported for this transaction.
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Has a value when AVS street-address verification was performed.
                                    zh: 执行 AVS 街道地址校验时有值。
                              postalCodeCheck:
                                type:
                                  - string
                                  - "null"
                                description: AVS postal-code check result.
                                enum:
                                  - pass
                                  - fail
                                  - unavailable
                                  - unchecked
                                  - notProvided
                                  - unsupported
                                  - null
                                x-enum-descriptions:
                                  pass: The information submitted for verification matches issuer records.
                                  fail: The information submitted for verification does not match issuer records.
                                  unavailable: The issuer does not support this verification.
                                  unchecked: Verification was not performed.
                                  notProvided: The information required for this verification was not provided.
                                  unsupported: AVS is not supported for this transaction.
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Has a value when AVS postal-code verification was performed.
                                    zh: 执行 AVS 邮编校验时有值。
                              cardholderNameCheck:
                                type:
                                  - string
                                  - "null"
                                description: American Express AVS result indicating whether the cardholder name
                                  matches issuer records.
                                enum:
                                  - pass
                                  - fail
                                  - unavailable
                                  - unchecked
                                  - notProvided
                                  - unsupported
                                  - null
                                x-enum-descriptions:
                                  pass: The information submitted for verification matches issuer records.
                                  fail: The information submitted for verification does not match issuer records.
                                  unavailable: The issuer does not support this verification.
                                  unchecked: Verification was not performed.
                                  notProvided: The information required for this verification was not provided.
                                  unsupported: AVS is not supported for this transaction.
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Returns the result when American Express cardholder name verification is
                                      performed, or `null` if it is not
                                      performed.
                                    zh: 执行 American Express 持卡人姓名验证时返回验证结果；未执行时返回 `null`。
                              avsResultRawCode:
                                type:
                                  - string
                                  - "null"
                                description: Raw AVS result code returned by the card network.
                                enum:
                                  - N
                                  - S
                                  - U
                                  - R
                                  - W
                                  - Z
                                  - X
                                  - Y
                                  - M
                                  - F
                                  - D
                                  - A
                                  - B
                                  - P
                                  - G
                                  - I
                                  - C
                                  - FD
                                  - NP
                                  - null
                                x-enum-descriptions:
                                  N: Postal code and street address both do not match.
                                  S: AVS is not supported.
                                  U: Verification service unavailable.
                                  R: System unable to perform verification.
                                  W: Nine-digit postal code matches; address does not match.
                                  Z: Five-digit postal code matches; address does not match.
                                  X: Nine-digit postal code and address both match.
                                  Y: Five-digit postal code and address both match.
                                  M: Address and postal code match for an international transaction.
                                  F: Address and postal code match for a United Kingdom transaction.
                                  D: Address and postal code match for an international transaction.
                                  A: Address matches; postal code does not match.
                                  B: Address matches; postal code was not verified.
                                  P: Postal code matches; address was not verified.
                                  G: Non-US AVS participant.
                                  I: International address was not verified.
                                  C: Address and postal code were not verified for a non-US Visa card.
                                  FD: AVS verification unavailable in Onerway.
                                  NP: Address and postal code were not provided.
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Has a value when the card network or Onerway returns a raw AVS result code.
                                    zh: 卡组织或 Onerway 返回原始 AVS 结果码时有值。
                              threeDSecureResult:
                                type:
                                  - object
                                  - "null"
                                properties:
                                  version:
                                    type: string
                                    description: 3D Secure protocol version.
                                  authenticationFlow:
                                    type:
                                      - string
                                      - "null"
                                    description: 3DS authentication flow type.
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the 3DS authentication flow can be identified.
                                        zh: 可识别 3DS 认证流程时有值。
                                  chargebackLiability:
                                    type: string
                                    description: 3DS chargeback liability party.
                                  transStatus:
                                    type:
                                      - string
                                      - "null"
                                    description: 3DS authentication result.
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when ACS returns an authentication status.
                                        zh: ACS 返回认证状态时有值。
                                  transStatusReason:
                                    type:
                                      - string
                                      - "null"
                                    description: Detailed reason for the 3DS authentication status.
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the authentication status includes a detailed reason.
                                        zh: 需要补充说明 3DS 认证状态时有值。
                                  veresEnrolled:
                                    type:
                                      - string
                                      - "null"
                                    description: 3DS enrollment result.
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the 3DS enrollment result is returned.
                                        zh: 3DS enrollment 结果返回时有值。
                                  eci:
                                    type:
                                      - string
                                      - "null"
                                    description: Electronic Commerce Indicator (ECI).
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the 3DS result returns ECI.
                                        zh: 3DS 结果返回 ECI 时有值。
                                  cvvResult:
                                    type:
                                      - string
                                      - "null"
                                    description: CVV security-code check result.
                                    enum:
                                      - M
                                      - N
                                      - P
                                      - S
                                      - U
                                      - I
                                      - null
                                    x-enum-descriptions:
                                      M: CVV matched issuer records.
                                      N: CVV did not match issuer records.
                                      P: CVV processing error.
                                      S: CVV was not provided.
                                      U: Verification service unavailable or unknown.
                                      I: CVV format invalid.
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the CVV check result is returned.
                                        zh: CVV 校验结果返回时有值。
                                  avsFullResult:
                                    type:
                                      - string
                                      - "null"
                                    description: AVS full address verification result.
                                    enum:
                                      - Y
                                      - N
                                      - A
                                      - Z
                                      - U
                                      - null
                                    x-enum-descriptions:
                                      Y: Postal code and street address both match.
                                      N: Postal code and street address both do not match.
                                      A: Street address matches; postal code does not match.
                                      Z: Postal code matches; street address does not match.
                                      U: Address verification service unavailable.
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the AVS full-result value is returned.
                                        zh: AVS 综合校验结果返回时有值。
                                  cavvResult:
                                    type:
                                      - string
                                      - "null"
                                    description: CAVV cryptogram returned by 3DS authentication.
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when 3DS authentication returns CAVV.
                                        zh: 3DS 认证返回 CAVV 时有值。
                                description: 3D Secure verification result.
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Has a value when 3DS verification results are returned; it is `null` when
                                      absent.
                                    zh: 返回 3DS 验证结果时有值；未返回时为 `null`。
                            description: Verification check results, including AVS and 3DS results.
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Can contain AVS or 3DS verification results in `AUTH` notifications.
                                  `CAPTURE` or `VOID` notifications may return
                                  `null`.
                                zh: "`AUTH` 通知中可能返回 AVS / 3DS 验证结果；`CAPTURE` 或 `VOID` 通知可能返回 `null`。"
                          holderName:
                            type:
                              - string
                              - "null"
                            description: Cardholder name.
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Can be returned in `AUTH` notifications; `CAPTURE` or `VOID` notifications
                                  may return `null`.
                                zh: "`AUTH` 通知可返回持卡人姓名；`CAPTURE` 或 `VOID` 通知可能为 `null`。"
                          year:
                            type:
                              - string
                              - "null"
                            description: Card expiry year, four digits.
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when card expiry year is returned; `CAPTURE` or `VOID`
                                  notifications may return `null`.
                                zh: 返回卡有效期时有值；`CAPTURE` 或 `VOID` 通知可能为 `null`。
                          month:
                            type:
                              - string
                              - "null"
                            description: Card expiry month, two digits (`01`-`12`).
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when card expiry month is returned; `CAPTURE` or `VOID`
                                  notifications may return `null`.
                                zh: 返回卡有效期时有值；`CAPTURE` 或 `VOID` 通知可能为 `null`。
                          cardType:
                            type:
                              - string
                              - "null"
                            description: Card brand or card network.
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when the card network returns the card brand; `VOID`
                                  notifications may return `null`.
                                zh: 卡组织返回卡类型时有值；`VOID` 通知可能为 `null`。
                          productCategory:
                            type:
                              - string
                              - "null"
                            description: Card product category.
                            enum:
                              - D
                              - P
                              - C
                              - H
                              - R
                              - N
                              - null
                            x-enum-descriptions:
                              D: Debit
                              P: Prepaid
                              C: Credit
                              H: Charge Card
                              R: Deferred Debit
                              N: Unknown
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when the card network returns the product category; `VOID`
                                  notifications may return `null`.
                                zh: 卡组织返回卡产品类别时有值；`VOID` 通知可能为 `null`。
                          issuer:
                            type:
                              - string
                              - "null"
                            description: Issuer name.
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when the issuer can be identified; `CAPTURE` or `VOID`
                                  notifications may return `null`.
                                zh: 可识别发卡行时有值；`CAPTURE` 或 `VOID` 通知可能为 `null`。
                          cardBinCountry:
                            type:
                              - string
                              - "null"
                            description: Card BIN country or region.
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when the card BIN country or region can be identified.
                                zh: 可识别卡 BIN 所属国家 / 地区时有值。
                          authorizationCode:
                            type:
                              - string
                              - "null"
                            description: Issuer or acquiring-side authorization code, used for
                              reconciliation and dispute handling.
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when an authorization code is returned, including in successful
                                  `VOID` notifications. `AUTH` failure or
                                  `CAPTURE` notifications may return `null`.
                                zh: 返回授权码时有值，成功的 `VOID` 通知也可返回授权码；`AUTH` 失败或 `CAPTURE` 通知可能为 `null`。
                          cardNumber:
                            type: string
                            description: Masked card number, keeping only the first 6 and last 4 digits.
                        description: Card payment method details.
                  x-onerway-format: json_string
                  x-onerway-signature-participation: included
            examples:
              authorization_succeeded:
                summary: Authorization succeeded
                value:
                  notifyType: TXN
                  transactionId: replace_with_authorization_transaction_id
                  paymentId: replace_with_payment_id
                  txnType: AUTH
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_transaction_id
                  responseTime: 2026-05-01 03:08:19
                  txnTime: 2026-05-01 03:05:45
                  txnTimeZone: +08:00
                  orderAmount: "79.97"
                  orderCurrency: USD
                  status: S
                  paymentStatus: A
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: MASTERCARD
                  channelRequestId: replace_with_channel_request_id
                  paymentMethodDetails: '{"card":{"checks":null,"cardType":"MASTERCARD","cardNumber":"512345******0008"}}'
              capture_succeeded:
                summary: Capture succeeded
                value:
                  notifyType: TXN
                  transactionId: replace_with_capture_transaction_id
                  paymentId: replace_with_payment_id
                  txnType: CAPTURE
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_transaction_id
                  responseTime: 2026-05-01 03:10:19
                  txnTime: 2026-05-01 03:10:12
                  txnTimeZone: +08:00
                  orderAmount: "79.97"
                  orderCurrency: USD
                  status: S
                  paymentStatus: S
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: MASTERCARD
                  channelRequestId: replace_with_channel_request_id
                  paymentMethodDetails: '{"card":{"checks":null,"cardNumber":"512345******0008"}}'
              void_succeeded:
                summary: Authorization void succeeded
                value:
                  notifyType: TXN
                  transactionId: replace_with_void_transaction_id
                  paymentId: replace_with_payment_id
                  txnType: VOID
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_void_merchant_transaction_id
                  responseTime: 2026-05-01 21:34:43
                  txnTime: 2026-05-01 15:33:51
                  txnTimeZone: +08:00
                  orderAmount: "0.01"
                  orderCurrency: USD
                  status: S
                  paymentStatus: N
                  cardBinCountry: HK
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_signature
                  paymentMethod: VISA
                  channelRequestId: replace_with_channel_request_id
                  paymentMethodDetails: '{"card":{"checks":null,"holderName":null,"year":null,"month":null,"cardType":null,"productCategory":null,"issuer":null,"cardBinCountry":"HK","authorizationCode":"example_authorization_code","cardNumber":"example_masked_card_number"}}'
      responses:
        "200":
          description: Return HTTP 200 with the received `transactionId` as the raw
            response body after the authorization, capture, or void webhook is
            received and accepted.
          content:
            text/plain:
              schema:
                type: string
              examples:
                return_transaction_id:
                  summary: Return transactionId
                  description: Use a `text/plain` response whose body is the `transactionId` from
                    the received webhook payload.
                  value: replace_with_transaction_id
```