---
title: "Update transaction status to trigger async fee payment or currency conversion"
method: PUT
path: "/api/v1/merchants/{merchantId}/transactions/{transactionId}/status"
tags: ["Transactions"]
---

# Update transaction status to trigger async fee payment or currency conversion

`PUT /api/v1/merchants/{merchantId}/transactions/{transactionId}/status`

## Request

- Base URL: `https://core.quidkey.com`
- URL: `https://core.quidkey.com/api/v1/merchants/{merchantId}/transactions/{transactionId}/status`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/banqzinc/apis/quidkey-api/docs/api/v1/merchants/:merchantId/transactions/:transactionId/status/put.ts> (a function with typed inputs; its response is checked against the schema)

Update transaction status to trigger async fee payment or currency conversion

## Path parameters

- `merchantId` string, uuid, required: The unique identifier of the merchant
- `transactionId` string, uuid, required: The unique identifier of the transaction

## Request body

- TransactionUpdateStatusInput
  - `status` union, required: New status for the transaction. Use RECEIVED to activate a PENDING refund. Use CANCELLED to cancel a PENDING refund.
    - 'received'
    - 'fee_paid'
    - 'converted'
    - 'completed'
    - 'cancelled'

## Response `200`

Success

- TransactionUpdateStatusResponse
  - `success` boolean, required
  - `data` object, required
    - `id` string, required
    - `transaction_number` string, required
    - `amount` number, required: Transaction amount in decimal format
    - `currency` object, required
      - `code` string, required: ISO 4217 currency code
      - `symbol` string, required: Currency symbol
      - `name` string, required: Currency name
      - `minor_unit` number, required: Number of decimal places
    - `transaction_type` 'payment' | 'refund' | 'reversal', required
    - `status` 'pending' | 'received' | 'fee_paid' | 'converted' | 'completed' | 'failed' | 'cancelled' | 'error' | 'unknown', required
    - `status_message` string, nullable, required
    - `cross_border` boolean, required
    - `deposit_country` string, required
    - `payout_country` string, required
    - `payout_currency` object, nullable, required
      - `code` string, required: ISO 4217 currency code
      - `symbol` string, required: Currency symbol
      - `name` string, required: Currency name
      - `minor_unit` number, required: Number of decimal places
    - `exchange_rate` number, nullable, required: FX rate applied for cross-border conversion
    - `converted_amount` number, nullable, required: Amount in payout currency after FX conversion
    - `payout_at` string, date-time, nullable, required: When the payout settled
    - `payout_batch_id` string, uuid, nullable, required: ID of the payout batch this transaction belongs to
    - `test` boolean, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `settled_at` string, date-time, nullable, required
    - `payment_request` object, nullable, required
      - `id` string, uuid, required
      - `order_id` string, required: Merchant order ID
      - `merchant` object, nullable, required
        - `id` string, uuid, required
        - `partner` object, nullable, required
          - `id` string, uuid, required
      - `customer` object, nullable, required
        - `id` string, uuid, required
        - `name` string, required
        - `email` string, required
      - `payment_token` string, required: Payment token
      - `authorization_agreement_record_id` string, uuid, nullable, required: AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).
    - `destination_account` string, nullable, required
    - `destination_account_type` string, nullable, required
    - `remittance_information` string, nullable, required
    - `payment_scheme` string, nullable, required
    - `platform` 'shopify' | 'woocommerce' | 'embedded' | 'payment_link', nullable, required
    - `problems` object[]
      - `code` string, required: Error code identifying the problem
      - `message` string, required: Human-readable description of the problem
      - `label` string, required: Display label for the problem
      - `is_resolvable` boolean, required: Whether the problem can be resolved by providing additional data
    - `target_status` union
      - 'pending'
      - 'received'
      - 'fee_paid'
      - 'converted'
      - 'completed'
      - 'failed'
      - 'cancelled'
      - 'error'
      - 'unknown'
    - `refund_status` union, required: Current refund status for payment transactions
      - 'refunding'
      - 'refunding_stuck'
      - 'refunding_failed'
      - 'partially_refunded'
      - 'fully_refunded'
    - `can_refund` boolean, required: Whether a refund can be initiated for this transaction
    - `related_transaction` object, nullable, required
      - `id` string, uuid, required
      - `transaction_number` string, required
    - `provider_status_events` object[], required
      - `id` string, uuid, required
      - `source` 'webhook' | 'polling' | 'finalization' | 'admin', required
      - `provider_name` string, required
      - `provider_status` string, required
      - `processing_status` 'received' | 'processed' | 'ignored' | 'failed' | 'conflict' | 'stale', required
      - `provider_updated_at` string, date-time, nullable, required
      - `created_at` string, date-time, required
      - `observed_at` string, date-time, required
      - `signature_valid` boolean, required
      - `event_id` string
      - `event_type` string
      - `processing_error` string
      - `provider_request_id` string
    - `merchant_webhook_deliveries` object[], required
      - `id` string, uuid, required
      - `payment_provider_status_id` string, uuid, nullable, required: Optional ID of the PaymentProviderStatus event that triggered this delivery
      - `webhook_url` string, required: The URL the webhook was sent to
      - `platform` 'embedded' | 'shopify' | 'woocommerce', required: Platform type
      - `event_type` string, required: Event type sent
      - `status` 'delivered' | 'failed', required: Delivery status
      - `response_status_code` number, nullable, required: HTTP response status code from merchant endpoint
      - `error_message` string: Error message if delivery failed
      - `duration_ms` number, nullable, required: Request duration in milliseconds
      - `created_at` string, date-time, required
    - `fees` object, required
      - `total` number, required: Total fees in decimal format
      - `currency` object, required
        - `code` string, required: ISO 4217 currency code
        - `symbol` string, required: Currency symbol
        - `name` string, required: Currency name
        - `minor_unit` number, required: Number of decimal places
      - `items` object[], required
        - `id` string, uuid, required
        - `amount` number, required: Fee amount in decimal format
        - `currency` object, required
          - `code` string, required: ISO 4217 currency code
          - `symbol` string, required: Currency symbol
          - `name` string, required: Currency name
          - `minor_unit` number, required: Number of decimal places
        - `fee_type` string, required
        - `rate_type` string, required
        - `rate_value` string, required
        - `rate_unit` string, required
        - `rate_base` string, required
        - `notes` string, nullable, required
        - `settlement_status` string, required
        - `invoice_id` string, uuid, nullable, required
        - `settled_at` string, date-time, nullable, required
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
    - `refunds` object[]: Refund transactions with full details including fees (only present for payment transactions with refunds)
      - `id` string, required
      - `transaction_number` string, required
      - `amount` number, required: Transaction amount in decimal format
      - `currency` object, required
        - `code` string, required: ISO 4217 currency code
        - `symbol` string, required: Currency symbol
        - `name` string, required: Currency name
        - `minor_unit` number, required: Number of decimal places
      - `transaction_type` 'payment' | 'refund' | 'reversal', required
      - `status` 'pending' | 'received' | 'fee_paid' | 'converted' | 'completed' | 'failed' | 'cancelled' | 'error' | 'unknown', required
      - `status_message` string, nullable, required
      - `cross_border` boolean, required
      - `deposit_country` string, required
      - `payout_country` string, required
      - `payout_currency` object, nullable, required
        - `code` string, required: ISO 4217 currency code
        - `symbol` string, required: Currency symbol
        - `name` string, required: Currency name
        - `minor_unit` number, required: Number of decimal places
      - `exchange_rate` number, nullable, required: FX rate applied for cross-border conversion
      - `converted_amount` number, nullable, required: Amount in payout currency after FX conversion
      - `payout_at` string, date-time, nullable, required: When the payout settled
      - `payout_batch_id` string, uuid, nullable, required: ID of the payout batch this transaction belongs to
      - `test` boolean, nullable, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `settled_at` string, date-time, nullable, required
      - `payment_request` object, nullable, required
        - `id` string, uuid, required
        - `order_id` string, required: Merchant order ID
        - `merchant` object, nullable, required
          - `id` string, uuid, required
          - `partner` object, nullable, required
            - `id` string, uuid, required
        - `customer` object, nullable, required
          - `id` string, uuid, required
          - `name` string, required
          - `email` string, required
        - `payment_token` string, required: Payment token
        - `authorization_agreement_record_id` string, uuid, nullable, required: AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).
      - `destination_account` string, nullable, required
      - `destination_account_type` string, nullable, required
      - `remittance_information` string, nullable, required
      - `payment_scheme` string, nullable, required
      - `platform` 'shopify' | 'woocommerce' | 'embedded' | 'payment_link', nullable, required
      - `problems` object[]
        - `code` string, required: Error code identifying the problem
        - `message` string, required: Human-readable description of the problem
        - `label` string, required: Display label for the problem
        - `is_resolvable` boolean, required: Whether the problem can be resolved by providing additional data
      - `target_status` union
        - 'pending'
        - 'received'
        - 'fee_paid'
        - 'converted'
        - 'completed'
        - 'failed'
        - 'cancelled'
        - 'error'
        - 'unknown'
      - `refund_status` union, required: Current refund status for payment transactions
        - 'refunding'
        - 'refunding_stuck'
        - 'refunding_failed'
        - 'partially_refunded'
        - 'fully_refunded'
      - `can_refund` boolean, required: Whether a refund can be initiated for this transaction
      - `related_transaction` object, nullable, required
        - `id` string, uuid, required
        - `transaction_number` string, required
      - `provider_status_events` object[], required
        - `id` string, uuid, required
        - `source` 'webhook' | 'polling' | 'finalization' | 'admin', required
        - `provider_name` string, required
        - `provider_status` string, required
        - `processing_status` 'received' | 'processed' | 'ignored' | 'failed' | 'conflict' | 'stale', required
        - `provider_updated_at` string, date-time, nullable, required
        - `created_at` string, date-time, required
        - `observed_at` string, date-time, required
        - `signature_valid` boolean, required
        - `event_id` string
        - `event_type` string
        - `processing_error` string
        - `provider_request_id` string
      - `merchant_webhook_deliveries` object[], required
        - `id` string, uuid, required
        - `payment_provider_status_id` string, uuid, nullable, required: Optional ID of the PaymentProviderStatus event that triggered this delivery
        - `webhook_url` string, required: The URL the webhook was sent to
        - `platform` 'embedded' | 'shopify' | 'woocommerce', required: Platform type
        - `event_type` string, required: Event type sent
        - `status` 'delivered' | 'failed', required: Delivery status
        - `response_status_code` number, nullable, required: HTTP response status code from merchant endpoint
        - `error_message` string: Error message if delivery failed
        - `duration_ms` number, nullable, required: Request duration in milliseconds
        - `created_at` string, date-time, required
      - `fees` object, required
        - `total` number, required: Total fees in decimal format
        - `currency` object, required
          - `code` string, required: ISO 4217 currency code
          - `symbol` string, required: Currency symbol
          - `name` string, required: Currency name
          - `minor_unit` number, required: Number of decimal places
        - `items` object[], required
          - `id` string, uuid, required
          - `amount` number, required: Fee amount in decimal format
          - `currency` object, required
            - `code` string, required: ISO 4217 currency code
            - `symbol` string, required: Currency symbol
            - `name` string, required: Currency name
            - `minor_unit` number, required: Number of decimal places
          - `fee_type` string, required
          - `rate_type` string, required
          - `rate_value` string, required
          - `rate_unit` string, required
          - `rate_base` string, required
          - `notes` string, nullable, required
          - `settlement_status` string, required
          - `invoice_id` string, uuid, nullable, required
          - `settled_at` string, date-time, nullable, required
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
    - `reversals` object[]: Reversal transactions with full details (only present for payment transactions with reversals)
      - `id` string, required
      - `transaction_number` string, required
      - `amount` number, required: Transaction amount in decimal format
      - `currency` object, required
        - `code` string, required: ISO 4217 currency code
        - `symbol` string, required: Currency symbol
        - `name` string, required: Currency name
        - `minor_unit` number, required: Number of decimal places
      - `transaction_type` 'payment' | 'refund' | 'reversal', required
      - `status` 'pending' | 'received' | 'fee_paid' | 'converted' | 'completed' | 'failed' | 'cancelled' | 'error' | 'unknown', required
      - `status_message` string, nullable, required
      - `cross_border` boolean, required
      - `deposit_country` string, required
      - `payout_country` string, required
      - `payout_currency` object, nullable, required
        - `code` string, required: ISO 4217 currency code
        - `symbol` string, required: Currency symbol
        - `name` string, required: Currency name
        - `minor_unit` number, required: Number of decimal places
      - `exchange_rate` number, nullable, required: FX rate applied for cross-border conversion
      - `converted_amount` number, nullable, required: Amount in payout currency after FX conversion
      - `payout_at` string, date-time, nullable, required: When the payout settled
      - `payout_batch_id` string, uuid, nullable, required: ID of the payout batch this transaction belongs to
      - `test` boolean, nullable, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `settled_at` string, date-time, nullable, required
      - `payment_request` object, nullable, required
        - `id` string, uuid, required
        - `order_id` string, required: Merchant order ID
        - `merchant` object, nullable, required
          - `id` string, uuid, required
          - `partner` object, nullable, required
            - `id` string, uuid, required
        - `customer` object, nullable, required
          - `id` string, uuid, required
          - `name` string, required
          - `email` string, required
        - `payment_token` string, required: Payment token
        - `authorization_agreement_record_id` string, uuid, nullable, required: AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).
      - `destination_account` string, nullable, required
      - `destination_account_type` string, nullable, required
      - `remittance_information` string, nullable, required
      - `payment_scheme` string, nullable, required
      - `platform` 'shopify' | 'woocommerce' | 'embedded' | 'payment_link', nullable, required
      - `problems` object[]
        - `code` string, required: Error code identifying the problem
        - `message` string, required: Human-readable description of the problem
        - `label` string, required: Display label for the problem
        - `is_resolvable` boolean, required: Whether the problem can be resolved by providing additional data
      - `target_status` union
        - 'pending'
        - 'received'
        - 'fee_paid'
        - 'converted'
        - 'completed'
        - 'failed'
        - 'cancelled'
        - 'error'
        - 'unknown'
      - `refund_status` union, required: Current refund status for payment transactions
        - 'refunding'
        - 'refunding_stuck'
        - 'refunding_failed'
        - 'partially_refunded'
        - 'fully_refunded'
      - `can_refund` boolean, required: Whether a refund can be initiated for this transaction
      - `related_transaction` object, nullable, required
        - `id` string, uuid, required
        - `transaction_number` string, required
      - `provider_status_events` object[], required
        - `id` string, uuid, required
        - `source` 'webhook' | 'polling' | 'finalization' | 'admin', required
        - `provider_name` string, required
        - `provider_status` string, required
        - `processing_status` 'received' | 'processed' | 'ignored' | 'failed' | 'conflict' | 'stale', required
        - `provider_updated_at` string, date-time, nullable, required
        - `created_at` string, date-time, required
        - `observed_at` string, date-time, required
        - `signature_valid` boolean, required
        - `event_id` string
        - `event_type` string
        - `processing_error` string
        - `provider_request_id` string
      - `merchant_webhook_deliveries` object[], required
        - `id` string, uuid, required
        - `payment_provider_status_id` string, uuid, nullable, required: Optional ID of the PaymentProviderStatus event that triggered this delivery
        - `webhook_url` string, required: The URL the webhook was sent to
        - `platform` 'embedded' | 'shopify' | 'woocommerce', required: Platform type
        - `event_type` string, required: Event type sent
        - `status` 'delivered' | 'failed', required: Delivery status
        - `response_status_code` number, nullable, required: HTTP response status code from merchant endpoint
        - `error_message` string: Error message if delivery failed
        - `duration_ms` number, nullable, required: Request duration in milliseconds
        - `created_at` string, date-time, required
      - `fees` object, required
        - `total` number, required: Total fees in decimal format
        - `currency` object, required
          - `code` string, required: ISO 4217 currency code
          - `symbol` string, required: Currency symbol
          - `name` string, required: Currency name
          - `minor_unit` number, required: Number of decimal places
        - `items` object[], required
          - `id` string, uuid, required
          - `amount` number, required: Fee amount in decimal format
          - `currency` object, required
            - `code` string, required: ISO 4217 currency code
            - `symbol` string, required: Currency symbol
            - `name` string, required: Currency name
            - `minor_unit` number, required: Number of decimal places
          - `fee_type` string, required
          - `rate_type` string, required
          - `rate_value` string, required
          - `rate_unit` string, required
          - `rate_base` string, required
          - `notes` string, nullable, required
          - `settlement_status` string, required
          - `invoice_id` string, uuid, nullable, required
          - `settled_at` string, date-time, nullable, required
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found

## Changes

- **2026-06-17** `b372e7d5563d`: 1 info
  - endpoint added
- **2025-11-02** `919eb7a392aa`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/banqzinc/apis/quidkey-api/changes/api/v1/merchants/:merchantId/transactions/:transactionId/status/put.md)

---

[API](https://skmtc.dev/banqzinc/apis/quidkey-api.md) - [All operations](https://skmtc.dev/banqzinc/apis/quidkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/banqzinc/apis/quidkey-api/revisions/f86d2bdbcb08?raw)