> ## Documentation Index
> Fetch the complete documentation index at: https://docs.singapay.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Transaction

> Cancels a card transaction — voids it when not yet settled, refunds it when already settled.



## OpenAPI

````yaml https://payment-b2b.singapay.id/api/docs/merchant-api.json patch /api/v2.0/card/{account_id}/cancel/{id}
openapi: 3.1.0
info:
  title: Singa Merchant API
  description: >-
    OpenAPI specification for the merchant/partner HTTP API. All routes below
    are additionally protected by `ip.whitelisted.merchant` — the caller IP must
    be registered for the credential or merchant. Obtain a JWT using `POST
    /api/v1.0/access-token/b2b` (Basic auth) or `POST
    /api/v1.1/access-token/b2b` (X-Signature) before calling secured endpoints.
  version: 1.0.0
servers:
  - url: https://sandbox-payment-b2b.singapay.id
    description: >-
      API host. Paths include `/api` prefix (see `RouteServiceProvider`).
      Replace scheme/host with your environment.
security: []
tags:
  - name: Security
    description: >-
      Merchant authentication (`OauthMerchantTokenController`). **v1.1** B2B
      token uses `X-CLIENT-ID`, `X-PARTNER-ID`, and `X-Signature` (no Basic
      auth). Secured routes also require the issued Bearer JWT plus
      `X-PARTNER-ID`.
  - name: Accounts
    description: >-
      Account management (`routes/merchantApiRoute.php`, `v1.0`). Path parameter
      `{id}` is always the account ULID.
  - name: Balance Inquiry
    description: >-
      Merchant and per-account balance inquiry (`BalanceController`, `v1.0`).
      Path `account_id` is the account ULID.
  - name: Statements
    description: >-
      Per-account statement list and detail
      (`AccountController::accountStatements`, `accountStatementDetail`, prefix
      `v1.0/statements`). Flugger responses; detail path param `{statement_id}`
      maps to `statements.transaction_id`.
  - name: Payment Link
    description: >-
      Payment link CRUD and payment-method catalog (`PaymentLinkApiController`,
      prefix `v1.0/payment-link-manage`). `account_id` is ULID;
      `payment_link_id` is numeric `payment_links.id`.
  - name: Payment Link History
    description: >-
      Payment link transaction/history listing and detail
      (`PaymentLinkApiController`, prefix `v1.0/payment-link-histories`).
      `history_id` is numeric `payment_link_histories.id`.
  - name: Virtual Account
    description: >-
      Native VA CRUD (`VirtualAccountController`, prefix
      `v1.0/virtual-accounts`). `account_id` and `virtual_account_id` are ULIDs.
  - name: VA Transaction
    description: >-
      VA money-in transaction listing and detail (`VirtualAccountController`,
      prefix `v1.0/va-transactions`).
  - name: QRIS (Money In)
    description: >-
      MPM dynamic QRIS list, show, and generate (`QrisMpmDynamicApiController`,
      prefix `v1.0/qris-dynamic`).
  - name: QRIS (Money Out)
    description: >-
      Issuer MPM decode/inquiry, payment credit (money out), and transaction
      status (`QrisIssuerMpmController`, `QrisApiV2Controller::checkStatus`,
      prefix `v2.0/qris`). Related list/detail: `GET
      /api/v2.0/qris/transaction/...`.
  - name: E-Wallet (Money In)
    description: >-
      E-Wallet Native checkout and transactions (`EwalletNativeApiController`,
      `EwalletNativeTransactionApiController`, `EwalletNativeV2ApiController`).
      Paths include `v1.0/ewallet-native`, `v1.0/ewallet-native-transactions`,
      and `v2.0/ewallet-native`.
  - name: E-Wallet (Money Out)
    description: >-
      E-wallet disbursement / top-up to beneficiary wallets
      (`EWalletTopUpController`, prefix `v2.0/ewallet`). Responses use the
      custom **`MerchantV2ApiEnvelope`** with **`MerchantV2ResponseCode`**
      (SP000–SP020).
  - name: Card (Money In)
    description: >-
      One-time card payment, cancel, and inquiry
      (`CardPaymentMerchantApiController`, prefix `v2.0/card`).
  - name: Subscription (Recurring)
    description: >-
      Credit-card recurring subscription plans (`SubscriptionPlanApiController`,
      prefix `v2.0/recurring`). Plan `{id}` is UUID (`sub_plans.id`).
  - name: Direct Debit
    description: >-
      Direct Debit — bind a customer bank account once via hosted webview, then
      charge it host-to-host (`DirectDebitMerchantController`, prefix
      `v2.0/direct-debit`). Binding `{binding_id}` and transaction
      `{transaction_id}` are UUIDs. Responses use the
      **`MerchantV2ApiEnvelope`** with both standard SP000–SP020 codes and
      Direct-Debit-specific codes (`SP_DD_*`). The `/charge` endpoint is
      additionally protected by **`X-Signature`** + **`X-Timestamp`**
      (`verify.signature-internal`); see operation parameters for the signing
      scheme.
  - name: Account Transfer
    description: >-
      Move funds between sub-accounts within the same merchant
      (`AnotherAccountApiController`, prefix `v1.0/account-transfer`). The
      transfer endpoint requires request signature headers
      (`verify.signature-internal`). Both accounts must belong to the
      authenticated merchant and be accessible to the credential.
  - name: Disbursement (Money Out)
    description: >-
      Bank disbursement (`DisbursementController` **v1.0**,
      `DisbursementV2Controller` **v2.0**). **v1.0**
      list/show/fee/beneficiary/transfer use Flugg envelopes; v1 inquiry-status
      uses the **custom v2 envelope** (`MerchantV2ApiEnvelope`, codes
      **SP000–SP020**). **v2.0** check-beneficiary, transfer, and inquiry-status
      use the same custom envelope — see component schema
      **`MerchantV2ResponseCode`** for the full response code table.
  - name: Cardless Withdrawal
    description: >-
      Cardless withdrawal API for initiating ATM cash withdrawals without a
      physical card. Supports creating withdrawals with OTP generation, listing
      transaction history, viewing transaction details, canceling pending
      withdrawals, and deleting canceled records. All endpoints use the
      `v1.0/cardless-withdrawals` route prefix and the standard success/error
      response envelope. Path parameter `{id}` refers to the `transaction_id`
      (platform-assigned business identifier).
paths:
  /api/v2.0/card/{account_id}/cancel/{id}:
    patch:
      tags:
        - Card (Money In)
      summary: Cancel Transaction
      description: >-
        Cancels a card transaction — voids it when not yet settled, refunds it
        when already settled.
      operationId: cardMerchantCancel
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            description: Account ULID
            type: string
        - name: id
          in: path
          required: true
          schema:
            description: Transaction lookup key
            type: string
      responses:
        '200':
          description: >-
            **SP000** Successfully — transaction voided or refunded (see
            `data.cancel_type`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardCancelSuccessResponse'
        '400':
          description: >-
            **SP012** cannot cancel in current status, or **SP001** provider
            cancel failure.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CardErrorBadRequestResponse'
                  - $ref: '#/components/schemas/CardErrorTransactionFailureResponse'
        '403':
          description: Access denied to this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardErrorAccessDeniedResponse'
        '404':
          description: >-
            **SP020** Merchant Account Not Found, or **SP009** Transaction Not
            Found.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CardErrorAccountNotFoundResponse'
                  - $ref: '#/components/schemas/CardErrorTransactionNotFoundResponse'
        '500':
          description: '**SP002** General Failure — unexpected error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardErrorGeneralFailureResponse'
      security:
        - BearerAuth: []
          PartnerId: []
components:
  schemas:
    CardCancelSuccessResponse:
      description: >-
        Merchant v2 envelope returned on a successful cancel (`SP000`, HTTP
        200).
      required:
        - response_code
        - response_message
        - data
      properties:
        response_code:
          $ref: '#/components/schemas/MerchantV2ResponseCode'
        response_message:
          $ref: '#/components/schemas/MerchantV2ResponseMessage'
        data:
          $ref: '#/components/schemas/CardCancelData'
      type: object
      example:
        response_code: SP000
        response_message: Successfully
        data:
          transaction_id: '101222025010112000099887766'
          reference_no: INV-2024-0012
          status: success
          cancel_type: void
    CardErrorBadRequestResponse:
      description: >-
        Merchant v2 envelope for validation or bad-request failures (`SP012`,
        HTTP 400). Validation failures include `data.errors` keyed by field
        name.
      required:
        - response_code
        - response_message
      properties:
        response_code:
          description: Business response code.
          type: string
          example: SP012
        response_message:
          description: Human-readable message.
          type: string
          example: Bad Request
        data:
          description: Validation context. Present on input validation failures.
          properties:
            errors:
              description: Field-level validation messages.
              type: object
              example:
                amount:
                  - The amount must be at least 10000.
              additionalProperties: true
          type:
            - object
            - 'null'
      type: object
      example:
        response_code: SP012
        response_message: The amount field is required.
        data:
          errors:
            amount:
              - The amount field is required.
    CardErrorTransactionFailureResponse:
      description: >-
        Merchant v2 envelope when the provider declines or the transaction
        cannot be processed (`SP001`, HTTP 400). `data.status` reflects the
        resulting transaction state.
      required:
        - response_code
        - response_message
      properties:
        response_code:
          description: Business response code.
          type: string
          example: SP001
        response_message:
          description: Provider error message.
          type: string
          example: Transaction Failure
        data:
          properties:
            transaction_id:
              type: string
              example: '101222025010112000099887766'
            reference_no:
              type: string
              example: INV-2024-0012
            status:
              type: string
              example: failed
          type:
            - object
            - 'null'
      type: object
      example:
        response_code: SP001
        response_message: Card declined by issuer
        data:
          transaction_id: '101222025010112000099887766'
          reference_no: INV-2024-0012
          status: failed
    CardErrorAccessDeniedResponse:
      description: >-
        Merchant v2 envelope when the authenticated merchant is not allowed to
        access this account (HTTP 403). Returned by the controller with a
        numeric `403` response code.
      required:
        - response_code
        - response_message
      properties:
        response_code:
          description: HTTP-aligned access-denied code.
          type: integer
          example: 403
        response_message:
          description: Human-readable message.
          type: string
          example: Access denied to this account.
        data:
          type:
            - object
            - 'null'
          example: null
      type: object
      example:
        response_code: 403
        response_message: Access denied to this account.
        data: null
    CardErrorAccountNotFoundResponse:
      description: >-
        Merchant v2 envelope when the `{account_id}` does not belong to the
        authenticated merchant (`SP020`, HTTP 404).
      required:
        - response_code
        - response_message
      properties:
        response_code:
          description: Business response code.
          type: string
          example: SP020
        response_message:
          description: Human-readable message.
          type: string
          example: Merchant Account Not Found
        data:
          type:
            - object
            - 'null'
          example: null
      type: object
      example:
        response_code: SP020
        response_message: Merchant Account Not Found
        data: null
    CardErrorTransactionNotFoundResponse:
      description: >-
        Merchant v2 envelope when the referenced transaction does not exist for
        this account (`SP009`, HTTP 404).
      required:
        - response_code
        - response_message
      properties:
        response_code:
          description: Business response code.
          type: string
          example: SP009
        response_message:
          description: Human-readable message.
          type: string
          example: Transaction Not Found
        data:
          type:
            - object
            - 'null'
          example: null
      type: object
      example:
        response_code: SP009
        response_message: Transaction not found
        data: null
    CardErrorGeneralFailureResponse:
      description: >-
        Merchant v2 envelope for unexpected server-side failures (`SP002`, HTTP
        500).
      required:
        - response_code
        - response_message
      properties:
        response_code:
          description: Business response code.
          type: string
          example: SP002
        response_message:
          description: Human-readable message.
          type: string
          example: An unexpected error occurred
        data:
          type:
            - object
            - 'null'
          example: null
      type: object
      example:
        response_code: SP002
        response_message: An unexpected error occurred
        data: null
    MerchantV2ResponseCode:
      description: SingaPay custom business response code.
      type: string
      example: SP000
    MerchantV2ResponseMessage:
      description: Human-readable label paired with `response_code`.
      type: string
      example: Successfully
    CardCancelData:
      description: >-
        Payload returned on a successful cancel. `cancel_type` is `void` for a
        not-yet-settled transaction or `refund` for a settled one.
      properties:
        transaction_id:
          description: SingaPay card transaction identifier.
          type: string
          example: '101222025010112000099887766'
        reference_no:
          description: Merchant reference for the transaction.
          type: string
          example: INV-2024-0012
        status:
          description: Cancel outcome.
          type: string
          example: success
        cancel_type:
          description: Cancellation type applied by the provider.
          type: string
          enum:
            - void
            - refund
          example: void
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      description: >-
        JWT issued by `POST /api/v1.1/access-token/b2b`. Send `Authorization:
        Bearer <token>`.
      bearerFormat: JWT
      scheme: bearer
    PartnerId:
      type: apiKey
      description: Merchant API key (`Credential.api_key`). Required on every request.
      name: X-PARTNER-ID
      in: header

````