{"openapi":"3.1.0","info":{"title":"Apa API","version":"1.0.0-draft","description":"Draft public contract for Apa non-custodial crypto payments. Apa provides payment links, hosted checkout sessions, route quotes, payments and signed webhooks. Funds settle to merchant-controlled payout wallets."},"servers":[{"url":"https://apa.app/v1"}],"tags":[{"name":"Auth"},{"name":"Payout wallets"},{"name":"Checkout sessions"},{"name":"Payment links"},{"name":"Routes"},{"name":"Payments"},{"name":"Webhooks"}],"security":[{"bearerAuth":[]}],"paths":{"/auth/email/start":{"post":{"tags":["Auth"],"summary":"Send email login code","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["expires_in","sent"],"properties":{"expires_in":{"type":"integer","example":600},"sent":{"type":"boolean"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/auth/email/verify":{"post":{"tags":["Auth"],"summary":"Verify email login code","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","code"],"properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","minLength":6,"maxLength":6}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["session_token"],"properties":{"session_token":{"type":"string"}}}}}},"401":{"description":"Invalid or expired code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/auth/nonce":{"post":{"tags":["Auth"],"summary":"Create wallet sign-in nonce","description":"Wallet login is scoped to the signed EVM or Solana wallet.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"string"},"network":{"type":"string","enum":["ethereum","solana"],"default":"ethereum"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["nonce","expires_in"],"properties":{"nonce":{"type":"string"},"expires_in":{"type":"integer","example":300}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/auth/verify":{"post":{"tags":["Auth"],"summary":"Verify wallet signature","description":"The connected wallet becomes the account's only payout wallet.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","signature"],"properties":{"address":{"type":"string"},"network":{"type":"string","enum":["ethereum","solana"],"default":"ethereum"},"signature":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["session_token","payout_wallet_id"],"properties":{"session_token":{"type":"string"},"payout_wallet_id":{"type":"string"}}}}}},"400":{"description":"Invalid signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/payout-wallets":{"post":{"tags":["Payout wallets"],"summary":"Create payout wallet","description":"Creates a saved payout wallet. Checkout sessions and payment links reference this id; live payment requests do not pass arbitrary raw payout addresses.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutWalletCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutWallet"}}}},"400":{"description":"Invalid payout wallet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Payout wallets"],"summary":"List payout wallets","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutWalletList"}}}}}}},"/payout-wallets/{id}":{"get":{"tags":["Payout wallets"],"summary":"Retrieve payout wallet","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutWallet"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/checkout/sessions":{"post":{"tags":["Checkout sessions"],"summary":"Create checkout session","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"400":{"description":"Invalid checkout session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/checkout/sessions/{id}":{"get":{"tags":["Checkout sessions"],"summary":"Retrieve checkout session","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/payment-links":{"post":{"tags":["Payment links"],"summary":"Create payment link","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"description":"Invalid payment link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Payment links"],"summary":"List payment links","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkList"}}}}}}},"/payment-links/{id}":{"get":{"tags":["Payment links"],"summary":"Retrieve payment link","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/payment-links/{id}/disable":{"post":{"tags":["Payment links"],"summary":"Disable payment link","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/payment-links/{id}/enable":{"post":{"tags":["Payment links"],"summary":"Enable payment link","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/routes/quote":{"get":{"tags":["Routes"],"summary":"Quote direct or routed payment","parameters":[{"name":"pay_asset","in":"query","required":true,"schema":{"type":"string"}},{"name":"pay_network","in":"query","required":true,"schema":{"type":"string"}},{"name":"payout_wallet_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"amount","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteQuote"}}}},"400":{"description":"Invalid route","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/payments":{"get":{"tags":["Payments"],"summary":"List payments","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/PaymentStatus"}},{"name":"route","in":"query","schema":{"enum":["direct","routed"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"starting_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentList"}}}}}}},"/payments/{id}":{"get":{"tags":["Payments"],"summary":"Retrieve payment","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/payments/{id}/refund":{"post":{"tags":["Payments"],"summary":"Record merchant-sent refund","description":"Apa is non-custodial and cannot reverse confirmed crypto payments. This endpoint records a refund the merchant sent from their own wallet.","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRecord"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/webhook-endpoints":{"post":{"tags":["Webhooks"],"summary":"Create webhook endpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Invalid endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}}}}},"/webhook-endpoints/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete webhook endpoint","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["id","deleted"],"properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/webhooks/test":{"post":{"tags":["Webhooks"],"summary":"Send test webhook event","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["endpoint_id","event"],"properties":{"endpoint_id":{"type":"string"},"event":{"$ref":"#/components/schemas/WebhookEventType"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["delivered","response_code"],"properties":{"delivered":{"type":"boolean"},"response_code":{"type":"integer"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"Id":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Safely retry POST requests. Stored for 24 hours."}},"schemas":{"AssetLabel":{"type":"string","enum":["ETH on Ethereum","SOL on Solana","USDC on Solana","ETH on Base","USDC on Base","USDC on Ethereum","USDT on Ethereum","USDT on Solana","BTC on Bitcoin","BNB on BNB Chain","POL on Polygon","ETH on Arbitrum","AVAX on Avalanche","TRX on Tron","USDT on Tron","USDC on Polygon","USDC on Arbitrum"]},"ReceiveAssetLabel":{"type":"string","enum":["USDC on Solana","USDC on Base","USDC on Ethereum","USDC on Polygon","USDC on Arbitrum","USDT on Ethereum","ETH on Ethereum","SOL on Solana"]},"PaymentStatus":{"type":"string","enum":["created","pending","routing","settling","paid","failed","expired","refund_required","refunded"]},"WebhookEventType":{"type":"string","enum":["payment.created","payment.pending","payment.routing","payment.settling","payment.paid","payment.failed","payment.expired","payment.refund_required","payment.refunded"]},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"param":{"type":["string","null"]}}}}},"PayoutWalletCreate":{"type":"object","required":["asset","network","address"],"properties":{"asset":{"type":"string","example":"USDC"},"network":{"type":"string","example":"solana"},"address":{"type":"string"},"label":{"type":"string"}}},"PayoutWallet":{"type":"object","required":["id","asset","network","address","is_default"],"properties":{"id":{"type":"string","example":"pp_123"},"asset":{"type":"string","example":"USDC"},"network":{"type":"string","example":"solana"},"address":{"type":"string"},"label":{"type":["string","null"]},"is_default":{"type":"boolean"}}},"PayoutWalletList":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PayoutWallet"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"CheckoutSessionCreate":{"type":"object","required":["payout_wallet_id","amount","currency"],"properties":{"payout_wallet_id":{"type":"string"},"amount":{"type":"string","example":"100.00"},"currency":{"type":"string","enum":["USD","EUR","AED"]},"order_id":{"type":"string"},"description":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"accepted_assets":{"type":"array","items":{"type":"string"}},"accepted_assets_mode":{"type":"string","enum":["all_supported","custom"],"default":"all_supported"},"expires_in":{"type":"integer"},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"}}},"CheckoutSession":{"type":"object","required":["id","object","status","amount","currency","payout_wallet_id","payment_link_id","checkout_url","created_at"],"properties":{"id":{"type":"string","example":"cs_123"},"object":{"type":"string","const":"checkout_session"},"status":{"$ref":"#/components/schemas/PaymentStatus"},"amount":{"type":"string"},"currency":{"type":"string"},"payout_wallet_id":{"type":"string"},"payment_link_id":{"type":["string","null"],"example":"pl_123"},"order_id":{"type":["string","null"]},"description":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"line_items":{"type":["array","null"],"items":{"$ref":"#/components/schemas/LineItem"}},"accepted_assets":{"type":"array","items":{"type":"string"}},"reference":{"type":"string"},"deposit_addresses":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutDepositAddress"}},"checkout_url":{"type":"string","format":"uri"},"payment":{"type":["string","null"]},"success_url":{"type":["string","null"],"format":"uri"},"cancel_url":{"type":["string","null"],"format":"uri"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"}}},"PaymentLinkCreate":{"type":"object","required":["payout_wallet_id","amount","currency","description"],"properties":{"payout_wallet_id":{"type":"string"},"amount":{"type":"string"},"currency":{"type":"string","enum":["USD","EUR","AED"]},"description":{"type":"string"},"order_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"}}},"PaymentLink":{"type":"object","required":["id","url","description","amount","currency","payout_wallet_id","receive_asset","receive_network","status","payments","created_at"],"properties":{"id":{"type":"string","example":"pl_123"},"url":{"type":"string","format":"uri"},"description":{"type":"string"},"amount":{"type":"string","example":"25.00"},"currency":{"type":"string","enum":["USD","EUR","AED"]},"payout_wallet_id":{"type":"string","example":"pp_123"},"receive_asset":{"type":"string","example":"USDC"},"receive_network":{"type":"string","example":"solana"},"status":{"type":"string","enum":["active","disabled"]},"payments":{"type":"integer","minimum":0},"order_id":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"success_url":{"type":["string","null"],"format":"uri"},"cancel_url":{"type":["string","null"],"format":"uri"},"created_at":{"type":"string","format":"date-time"}}},"PaymentLinkList":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLink"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"RouteQuote":{"type":"object","required":["type","fee_pct","expected_output","expires_in"],"properties":{"type":{"type":"string","enum":["direct","routed"]},"fee_pct":{"type":"number","enum":[0,1.5]},"expected_output":{"type":"string"},"expires_in":{"type":"integer"}}},"Payment":{"type":"object","required":["id","object","status","route","amount","payout_wallet_id","payment_link_id","apa_fee"],"properties":{"id":{"type":"string","example":"pay_8fK2mQ"},"object":{"type":"string","const":"payment"},"status":{"$ref":"#/components/schemas/PaymentStatus"},"route":{"type":"string","enum":["direct","routed"]},"amount":{"type":"string"},"pay_asset":{"type":"string"},"pay_network":{"type":"string"},"order_id":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"payout_wallet_id":{"type":"string"},"payment_link_id":{"type":["string","null"],"example":"pl_123"},"session":{"type":["string","null"]},"expected_output":{"type":["string","null"]},"actual_output":{"type":["string","null"]},"net_settlement":{"type":"string"},"apa_fee":{"type":"string"},"tx_hashes":{"type":"array","items":{"type":"string"}},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"PaymentList":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Pagination":{"type":"object","required":["cursor","has_more"],"properties":{"cursor":{"type":["string","null"]},"has_more":{"type":"boolean"},"total":{"type":"integer","minimum":0}}},"RefundRecord":{"type":"object","properties":{"amount":{"type":"string"},"address":{"type":"string"},"reason":{"type":"string","maxLength":280}}},"WebhookEndpointCreate":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}}}},"WebhookEndpoint":{"type":"object","required":["id","url","events","status"],"properties":{"id":{"type":"string","example":"we_123"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"secret":{"type":"string","description":"Shown once on creation."},"status":{"type":"string","enum":["active","disabled"]}}},"WebhookEndpointList":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"LineItem":{"type":"object","required":["name","quantity","amount"],"properties":{"name":{"type":"string"},"quantity":{"type":"integer"},"amount":{"type":"string"}}},"CheckoutDepositAddress":{"type":"object","required":["asset","network","address","kind"],"properties":{"asset":{"type":"string","example":"USDC"},"network":{"type":"string","example":"solana"},"address":{"type":"string"},"kind":{"type":"string","enum":["direct","routed"]},"reference":{"type":["string","null"]}}}}},"x-apa-facts":{"custody":"non-custodial","directFeePercent":0,"routedFeePercent":1.5,"settlement":"merchant-controlled payout wallet"}}