> ## Documentation Index > Fetch the complete documentation index at: https://docs.halliday.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Return funds to owner or retry payment > Request a withdrawal to return funds back to the owner or to a requoted processing address. This endpoint should be used when a payment cannot be completed and funds need to be returned. ## OpenAPI ````yaml /public/openapi.yaml post /payments/withdraw openapi: 3.1.0 info: title: Halliday API V2 description: > API V2 for Halliday's payment infrastructure, supporting onramps, swaps, and offramps. This API provides a unified interface for cryptocurrency payments, allowing developers to: - Quote payments across multiple providers - Execute payments with onramps, swaps, and offramps - Track payment status and history ## Authentication API key authentication is required for all endpoints. version: 2.0.0 contact: name: Contact Halliday url: https://halliday.xyz email: support@halliday.xyz servers: - url: https://v2.prod.halliday.xyz description: Base domain security: - ApiKeyAuth: [] tags: - name: Chains description: Blockchain network information and configuration - name: Assets description: Asset information, discovery, and supported asset pairs - name: Payments description: >- Core payment operations including quotes, confirmation, and status tracking - name: Webhooks description: > Register HTTPS endpoints to receive signed notifications when a workflow reaches a terminal state, instead of polling for status. You subscribe to one or more event types per webhook. | Event type | Fires when a workflow's status becomes | | --- | --- | | `WORKFLOW_COMPLETED` | `COMPLETE` | | `WORKFLOW_FAILED` | `FAILED` | All management endpoints live under `/orgs/webhooks` and authenticate with a secret API key (passed as a bearer token) that has webhook access. Publishable keys cannot manage webhooks. **Integration checklist** - Receiver is a public HTTPS endpoint (no private IPs). - Save the `signing_secret` when you create the webhook — it is shown only once. - Verify `X-Halliday-Signature` against the raw body, accepting any of its comma-separated signatures. - Respond `2xx` quickly and do the real work afterward. - Skip deliveries whose `id` you have already handled. paths: /payments/withdraw: post: tags: - Payments summary: Return funds to owner or retry payment description: > Request a withdrawal to return funds back to the owner or to a requoted processing address. This endpoint should be used when a payment cannot be completed and funds need to be returned. operationId: withdrawPayment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WithdrawPaymentAuthorizationRequest' responses: '200': description: Withdrawal initiated successfully content: application/json: schema: $ref: '#/components/schemas/WithdrawPaymentAuthorizationResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - kind: other message: Missing field 'token_amounts'. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - kind: other message: Invalid or missing API key '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - kind: other message: You are not authorized to withdraw funds from this payment '404': description: Payment not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - kind: other message: Payment 'pay_def456' not found components: schemas: WithdrawPaymentAuthorizationRequest: type: object required: - payment_id - token_amounts - recipient_address properties: payment_id: type: string description: ID of the payment to withdraw token_amounts: type: array items: $ref: '#/components/schemas/TokenAmount' description: >- List of token amounts to withdraw back to the owner or to a requoted processing address recipient_address: type: string description: >- On-chain address to withdraw the funds to. The assets will go to the address on the same chain the assets are on. withdraw_account: type: string enum: - INTENT - SPW default: SPW description: Type of account to withdraw from. WithdrawPaymentAuthorizationResponse: type: object required: - type - signature_type - payment_id - withdraw_authorization - state_token properties: signature_type: type: string enum: - EIP712 - EIP191 description: Signature type required for the withdrawal authorization. payment_id: type: string description: ID of the withdrawal transaction withdraw_authorization: type: string description: > Authorization data to sign. For EIP712, this is a JSON string to parse and pass to signTypedData. For EIP191, pass this string directly to signMessage. state_token: type: string description: Opaque state token to pass back when confirming the withdrawal. ErrorResponse: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/Issue' description: Error response for known errors TokenAmount: type: object required: - token - amount properties: token: $ref: '#/components/schemas/Token' amount: type: string description: >- Amount of the token to withdraw, represented as a string to preserve precision Issue: oneOf: - $ref: '#/components/schemas/AmountIssue' - $ref: '#/components/schemas/AmountDownstreamIssue' - $ref: '#/components/schemas/FundingIssue' - $ref: '#/components/schemas/OwnerIssue' - $ref: '#/components/schemas/GeolocationIssue' - $ref: '#/components/schemas/ProviderIssue' - $ref: '#/components/schemas/PayinMethodIssue' - $ref: '#/components/schemas/OtherIssue' - $ref: '#/components/schemas/UnknownIssue' discriminator: propertyName: kind Token: type: string description: Token identifier in the format "chain:address" pattern: ^[a-z]+:0x[a-fA-F0-9]+$ example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 AmountIssue: type: object required: - kind - asset - given - limits - source - message - reason properties: kind: type: string enum: - amount asset: $ref: '#/components/schemas/Asset' given: $ref: '#/components/schemas/Amount' limits: $ref: '#/components/schemas/Limits' downstream_limits: $ref: '#/components/schemas/Limits' source: type: string message: type: string reason: type: string enum: - TOO_LOW - TOO_HIGH - NO_VALID_AMOUNT - UNKNOWN AmountDownstreamIssue: type: object required: - kind - asset - given - limits - source - message - reason properties: kind: type: string enum: - amount-downstream asset: $ref: '#/components/schemas/Asset' given: $ref: '#/components/schemas/Amount' limits: $ref: '#/components/schemas/Limits' downstream_limits: $ref: '#/components/schemas/Limits' source: type: string message: type: string reason: type: string enum: - TOO_LOW - TOO_HIGH - NO_VALID_AMOUNT - UNKNOWN FundingIssue: type: object required: - kind - token - balance properties: kind: type: string enum: - funding token: $ref: '#/components/schemas/Token' balance: type: string description: Current token balance at the funding address. OwnerIssue: type: object required: - kind - message - mitigation properties: kind: type: string enum: - owner message: type: string mitigation: type: string enum: - change - verify GeolocationIssue: type: object required: - kind - message properties: kind: type: string enum: - geolocation message: type: string ProviderIssue: type: object required: - kind - message properties: kind: type: string enum: - provider message: type: string PayinMethodIssue: type: object required: - kind - message properties: kind: type: string enum: - payin_method message: type: string OtherIssue: type: object required: - kind - message properties: kind: type: string enum: - other message: type: string UnknownIssue: type: object required: - kind - message properties: kind: type: string enum: - unknown message: type: string Asset: type: string description: >- Identifier in the token format ("chain:address") or fiat currency code ("USD") example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 Amount: type: string description: A decimal amount string. Limits: type: object properties: min: type: string description: Minimum amount as a decimal string. max: type: string description: Maximum amount as a decimal string. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY ````