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

# Finalize Cross-chain Withdrawal

> Have Chipi's relayer deliver a recorded withdrawal on the destination chain

```bash cURL theme={null}
curl -X POST "https://api.chipipay.com/v1/transactions/finalize-cross-chain-withdrawal" \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "x-api-key: pk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "burnTxHash": "0x07d61890..." }'
```

```json 200 Response theme={null}
{
  "burnTxHash": "0x07d61890...",
  "status": "COMPLETE",
  "destTxHash": "0x9c1e...",
  "sponsoredByChipi": true,
  "verifiedOnChain": true
}
```

```json 409 Not confirmed yet theme={null}
{
  "statusCode": 409,
  "message": "Burn 0x07d61890... is not confirmed on Starknet yet; retry"
}
```

The relayer waits for Circle's attestation, runs `receiveMessage` on the destination chain paying its gas, and, when Chipi sponsors the fee, pays the recipient back the fee Circle took, both read from the attested message. The call can take minutes. Retry freely: a finished withdrawal comes back `COMPLETE`, and the Starknet burn is never lost.


## OpenAPI

````yaml POST /transactions/finalize-cross-chain-withdrawal
openapi: 3.1.0
info:
  title: Chipi Pay API
  description: >-
    REST API for creating self-custodial wallets, executing gasless
    transactions, and purchasing services on Starknet.
  version: 14.0.0
  license:
    name: MIT
servers:
  - url: https://api.chipipay.com/v1
security:
  - bearerAuth: []
    apiKeyAuth: []
tags:
  - name: Wallets
    description: Create and manage self-custodial Starknet wallets
  - name: Transactions
    description: Record and query blockchain transactions
  - name: SKUs
    description: Browse available services for purchase
  - name: SKU Purchases
    description: Purchase services using blockchain payments
  - name: Exchanges
    description: Currency conversion rates
  - name: Cross-chain
    description: >-
      USDC in and out of a Chipi wallet through Circle's CCTP V2 (Base and other
      EVM chains, Solana)
paths:
  /transactions/finalize-cross-chain-withdrawal:
    post:
      tags:
        - Cross-chain
      summary: Finalize Cross-chain Withdrawal
      description: >-
        Ask Chipi's relayer to deliver a recorded withdrawal on the destination
        chain (receiveMessage, gas paid by Chipi). It waits for Circle's
        attestation, so the call can take minutes. A row still carrying the
        client's values is verified against the burn first. Retryable: a
        finished withdrawal comes back COMPLETE, the burn is never lost.
      operationId: finalizeCrossChainWithdrawal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinalizeCrossChainWithdrawalBody'
      responses:
        '200':
          description: Withdrawal COMPLETE with destTxHash
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossChainWithdrawal'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Withdrawal not found for this API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The burn is not confirmed on Starknet yet; retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    FinalizeCrossChainWithdrawalBody:
      type: object
      properties:
        burnTxHash:
          type: string
      required:
        - burnTxHash
    CrossChainWithdrawal:
      type: object
      properties:
        burnTxHash:
          type: string
        destChain:
          type: string
        destDomain:
          type: integer
        recipient:
          type: string
        recipientOwner:
          type: string
          nullable: true
        amount:
          type: string
          description: Human USDC
        status:
          type: string
          enum:
            - PENDING
            - COMPLETE
            - FAILED
        destTxHash:
          type: string
          nullable: true
          description: The destination receiveMessage transaction, once COMPLETE
        failureReason:
          type: string
          nullable: true
        sponsoredByChipi:
          type: boolean
        feeBps:
          type: number
          nullable: true
        finality:
          type: string
          nullable: true
        verifiedOnChain:
          type: boolean
          description: >-
            Whether amount, destDomain and recipient were read from the burn's
            own DepositForBurn event
      required:
        - burnTxHash
        - destChain
        - destDomain
        - recipient
        - amount
        - status
        - sponsoredByChipi
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
      required:
        - error
        - message
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized — invalid or missing API key / bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded (100 requests/minute per API key)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token — use your secret key (sk_prod_xxx) for server-side calls,
        or the user's JWT for client-side calls
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Chipi public API key (pk_xxx)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.