{"openapi":"3.1.1","info":{"title":"Paymegate Merchant API","version":"1.0.0","description":"Create card and crypto orders, manage network-specific payout wallets, and reconcile payments with tenant-isolated server APIs. Keep API keys on your server."},"servers":[{"url":"https://www.paymegate.com/api","description":"Merchant API"}],"tags":[{"name":"Configuration"},{"name":"Products"},{"name":"Orders"},{"name":"Payments"},{"name":"Transactions"},{"name":"Webhook deliveries"}],"paths":{"/v1/wallet":{"get":{"tags":["Configuration"],"operationId":"getApiWallet","summary":"Get card and crypto payout-wallet configuration","description":"Returns the EVM payout wallet, optional network-specific crypto wallets, the includeCrypto switch, and per-order EVM override status. Provider credentials are never returned.","security":[{"MerchantApiKey":[]}],"responses":{"200":{"description":"Current payout-wallet configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWalletEnvelope"}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"$ref":"#/components/responses/Forbidden"}}},"put":{"tags":["Configuration"],"operationId":"updateApiWallet","summary":"Configure card and crypto payout wallets","description":"Requires a live API key. Existing orders keep their snapshotted receiving wallet and checkout session. Crypto assets shown at checkout are the intersection of Paymegate-supported assets and payout networks configured by the merchant.","security":[{"MerchantApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWalletUpdateRequest"},"example":{"payoutWallet":"0x2222222222222222222222222222222222222222","cryptoWallets":{"btc":"1BoatSLRHtKNngkdXEeobR76b53LETtpyT","trc20":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8"},"orderWalletOverrideEnabled":true}}}},"responses":{"200":{"description":"Updated payout-wallet configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWalletEnvelope"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/webhook":{"get":{"tags":["Configuration"],"operationId":"getApiWebhook","summary":"Get the merchant webhook URL","description":"Returns the authenticated merchant's single outbound webhook configuration. Signing secrets and digests are never returned by this operation.","security":[{"MerchantApiKey":[]}],"x-required-scope":"api:read","responses":{"200":{"description":"Current webhook configuration","including an explicit unconfigured state.":null,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWebhookEnvelope"}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"$ref":"#/components/responses/Forbidden"}}},"put":{"tags":["Configuration"],"operationId":"updateApiWebhook","summary":"Create or replace the merchant webhook URL","description":"Requires a live API key with webhooks:write. The operation preserves the current signing secret and subscribed events, and reactivates a disabled endpoint when replacing its URL. On first configuration only, signingSecret is returned once and cannot be recovered later.","security":[{"MerchantApiKey":[]}],"x-required-scope":"webhooks:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiWebhookUpdateRequest"},"example":{"url":"https://merchant.example/webhooks/paymegate"}}}},"responses":{"200":{"description":"Created or updated webhook configuration. signingSecret is present only when the endpoint is configured for the first time.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiWebhookEnvelope"},{"$ref":"#/components/schemas/ApiWebhookCreatedEnvelope"}]}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/payment-methods":{"get":{"tags":["Payments"],"operationId":"listPaymentMethods","summary":"List active payment methods and their minimums","description":"Returns concrete active card, bank, wallet, and crypto method keys with their minimums without filtering by an entered amount. The crypto key is included when crypto checkout is enabled for the merchant. The special all and legacy hosted sentinels are never returned to API-key clients. The upstream provider-status catalogue is cached in memory for one hour, and concurrent cache misses share one provider request.","security":[{"MerchantApiKey":[]}],"parameters":[{"name":"forceFetch","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When true","bypasses and refreshes the one-hour provider-status cache. Concurrent refreshes still share one provider request.":null}],"responses":{"200":{"description":"Active provider-status methods with minimum amount and currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderStatusMethodListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/ProviderUnavailable"}}}},"/v1/checkout/products/{productUUID}":{"get":{"tags":["Products"],"operationId":"getPublicProductCheckout","summary":"Get an active product checkout","description":"Public, unauthenticated product projection used by the hosted checkout page. It exposes only display, price, and accepted-method fields. Archived products and products owned by suspended merchants return 404.","security":[],"parameters":[{"$ref":"#/components/parameters/ProductUUID"}],"responses":{"200":{"description":"Public product checkout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCheckoutProductEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/checkout/products/{productUUID}/orders":{"post":{"tags":["Products","Orders"],"operationId":"createPublicProductOrder","summary":"Create an order from an active product","description":"Public checkout operation called after the buyer enters contact information and chooses one concrete payment method. The server resolves the merchant and snapshots product metadata, description, and image. Amount and currency may be provided together only when the product has allowPriceOverride enabled.","security":[],"parameters":[{"$ref":"#/components/parameters/ProductUUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProductOrderRequest"},"example":{"customer":{"email":"customer@example.com","fullName":"Example Customer"},"paymentMethodKey":"stripe","amount":"35.00","currency":"USD"}}}},"responses":{"201":{"description":"UNPAID order created; navigate the browser to redirectUrl.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProductOrderCreatedEnvelope"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"403":{"description":"The customer is blocked from starting payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/products":{"post":{"tags":["Products"],"operationId":"createProduct","summary":"Create a reusable order template","description":"Creates a tenant-scoped catalog product. Future orders snapshot the product UUID, name, and image, so later product edits never rewrite financial history.","security":[{"MerchantApiKey":[]}],"x-required-scope":"products:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductRequest"}}}},"responses":{"201":{"description":"Product created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEnvelope"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"get":{"tags":["Products"],"operationId":"listProducts","summary":"List catalog products","security":[{"MerchantApiKey":[]}],"x-required-scope":"products:read","parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageToken"}],"responses":{"200":{"description":"Newest-updated product page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPageEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/products/bulk":{"post":{"tags":["Products"],"operationId":"bulkCreateProducts","summary":"Atomically create multiple products","description":"Creates 1 to 50 products in one all-or-nothing write. UUIDs are generated by Paymegate. A failed item prevents every product in the request from being stored.","security":[{"MerchantApiKey":[]}],"x-required-scope":"products:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCreateProductsRequest"}}}},"responses":{"201":{"description":"Every product was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCreateProductsEnvelope"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"description":"Request body exceeds the 5.25 MB bulk limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Products"],"operationId":"bulkUpsertProducts","summary":"Atomically insert or replace multiple products","description":"Upserts 1 to 50 products by productUUID in one all-or-nothing write. Existing products preserve createdAt; request values replace their editable product fields, including the orderTemplate amount and currency defaults. Set allowPriceOverride to true when later product orders may override amount and currency together.","security":[{"MerchantApiKey":[]}],"x-required-scope":"products:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpsertProductsRequest"}}}},"responses":{"200":{"description":"Every product was inserted or updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpsertProductsEnvelope"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"description":"Request body exceeds the 5.25 MB bulk limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/bulk/status":{"patch":{"tags":["Products"],"operationId":"bulkSetProductStatus","summary":"Atomically disable or re-enable products","description":"Sets active for 1 to 100 unique product UUIDs. Every UUID must exist for the authenticated merchant or no product is changed.","security":[{"MerchantApiKey":[]}],"x-required-scope":"products:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkProductStatusRequest"},"example":{"productUUIDs":["8bc96020-f910-4e20-8e84-b7af5f13d101"],"active":false}}}},"responses":{"200":{"description":"Every product now has the requested active state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkProductStatusEnvelope"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/products/{productUUID}":{"get":{"tags":["Products"],"operationId":"getProduct","summary":"Get one catalog product","security":[{"MerchantApiKey":[]}],"x-required-scope":"products:read","parameters":[{"$ref":"#/components/parameters/ProductUUID"}],"responses":{"200":{"description":"Product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Products"],"operationId":"updateProduct","summary":"Edit, archive, or restore a product","description":"Set active to false to archive the product. Archived products remain available for historical order display but cannot initialize new orders.","security":[{"MerchantApiKey":[]}],"x-required-scope":"products:write","parameters":[{"$ref":"#/components/parameters/ProductUUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductRequest"}}}},"responses":{"200":{"description":"Updated product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductEnvelope"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/orders":{"post":{"tags":["Orders"],"operationId":"createOrder","summary":"Initialize an unpaid order","description":"Every request creates a new UNPAID order and one private order-scoped checkout session in CREATED state, or READY for a crypto-only order. This endpoint does not call PayMeGate, fetch live provider status, provision a wallet, or create a provider checkout session; syntactically valid provider keys are stored and live availability plus card, bank, or wallet provisioning are verified only when the buyer enters `/payment/process/{orderUUID}`. Provide amount, currency, and paymentMethodsKeys for an ad-hoc order, or provide productUUID to load an active product template. With a product, optional paymentMethodsKeys must be a subset of the product methods. Amount and currency may be overridden together only when that product has allowPriceOverride enabled. Product description and image remain authoritative. `externalId` is stored directly; order metadata merges over product metadata. Correlation fields round-trip in the response and later `order.paid` webhook. Private provider URLs and credentials are never returned. Test API keys cannot call this live route.","security":[{"MerchantApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"},"examples":{"allAvailableMethods":{"summary":"Card, wallet, bank, and crypto methods available to this merchant","value":{"externalId":"invoice_2026_0042","amount":"20.00","currency":"USD","paymentMethodsKeys":["*"],"customer":{"email":"customer@example.com","fullName":"Example Customer"},"metadata":{"cartId":"cart_42","workspaceId":"workspace_7"}}},"cryptoOnly":{"summary":"Hosted crypto checkout","value":{"amount":"20.00","currency":"USD","paymentMethodsKeys":["crypto"],"customer":{"email":"customer@example.com","fullName":"Example Customer"},"metadata":{"cartId":"cart_123"}}},"productReference":{"summary":"Create from a reusable product template","value":{"productUUID":"8bc96020-f910-4e20-8e84-b7af5f13d101","customer":{"email":"customer@example.com","fullName":"Example Customer"},"externalId":"invoice_2026_0042","metadata":{"seat":"owner"}}},"productPriceOverride":{"summary":"Override an override-enabled product's price and narrow its methods","value":{"productUUID":"8bc96020-f910-4e20-8e84-b7af5f13d101","amount":"24.50","currency":"EUR","paymentMethodsKeys":["crypto"],"customer":{"email":"customer@example.com","fullName":"Example Customer"},"externalId":"invoice_2026_0042","metadata":{"seat":"owner"}}}}}}},"responses":{"201":{"description":"Order initialized with a platform-owned checkoutUrl; provider provisioning is deferred until payment processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderEnvelope"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"description":"The API key cannot create orders","wallet overrides are disabled":null,"or the merchant has blocked this customer.":null,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/orders/{orderUUID}/cancel":{"post":{"tags":["Orders"],"operationId":"cancelOrder","summary":"Cancel an unpaid order","description":"Atomically changes an UNPAID order to CANCELLED only before provider provisioning or a payment attempt has begun, abandons its active checkout session, removes the amount from pending statistics, and records cancellation statistics. No transaction is created. Requires Firebase dashboard authentication or a live API key with orders:manage.","security":[{"MerchantApiKey":[]}],"x-required-scope":"orders:manage","parameters":[{"$ref":"#/components/parameters/OrderUUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelOrderRequest"},"example":{"reason":"Customer requested cancellation"}}}},"responses":{"200":{"description":"Order cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedOrderEnvelope"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"API key lacks orders:manage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/orders/{orderUUID}/refunds":{"post":{"tags":["Orders","Transactions"],"operationId":"refundOrder","summary":"Record a full or partial refund","description":"Records an externally executed refund against a provider-settled paid transaction. Omit amount to refund the entire remaining refundable balance, or provide amount for a partial refund. The update to the order, transaction, append-only refund record, notification, and statistics is atomic. Historical gross volume remains unchanged and the recorded refund is subtracted from net revenue. This operation does not contact PayMeGate or transfer funds; execute the monetary refund through the original provider or an external process first. Forced-paid orders have no transaction and cannot use this operation.","security":[{"MerchantApiKey":[]}],"x-required-scope":"orders:manage","parameters":[{"$ref":"#/components/parameters/OrderUUID"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundOrderRequest"},"examples":{"full":{"summary":"Refund all remaining value","value":{"reason":"Customer requested a full refund"}},"partial":{"summary":"Refund a specific amount","value":{"amount":"10.00","reason":"Returned one item"}}}}}},"responses":{"200":{"description":"Idempotent replay; the previously recorded refund is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRefundEnvelope"}}}},"201":{"description":"Refund recorded for the first time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRefundEnvelope"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"API key lacks orders:manage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"Refund amount exceeds the remaining refundable amount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"orderPaid":{"post":{"tags":["Webhook deliveries"],"operationId":"receiveOrderPaidWebhook","summary":"Receive a verified paid-order event","description":"Paymegate POSTs this compact event after verified settlement. It contains the order and transaction IDs, amount, customer email, paid timestamp, and the merchant-supplied `externalId` and `metadata` correlation fields. Internal order state, provider details, credentials, callback tokens, and signing material are not included. Verify the signature against the raw request body before parsing, reject stale timestamps, and deduplicate by event ID.","parameters":[{"name":"X-Paymegate-Event","in":"header","required":true,"schema":{"type":"string","const":"order.paid"}},{"name":"X-Paymegate-Event-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Idempotency key. Process each event ID once."},{"name":"X-Paymegate-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix timestamp used in signature verification and replay protection."},{"name":"X-Paymegate-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"description":"Unpadded Base64url HMAC-SHA256 of timestamp + \".\" + the exact raw request body."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPaidWebhookEvent"},"example":{"id":"f15068cf-c0ea-4b67-91bb-4c45ec6eac88","type":"order.paid","createdAt":"2026-07-23T12:00:00.000Z","orderUUID":"9cb50d55-9e02-4fc0-a824-277ac39b4144","transactionUUID":"30569045-9e69-41cb-9083-8ac5e3d76a5e","transactionRef":"provider_transaction_reference","status":"PAID","amount":"20.00","currency":"USD","customerEmail":"customer@example.com","externalId":"invoice_2026_0042","metadata":{"cartId":"cart_42","workspaceId":"workspace_7"},"paidAt":"2026-07-23T12:00:00.000Z"}}}},"responses":{"200":{"description":"Event accepted. Return exactly HTTP 200; other responses are recorded as failed deliveries and may be retried."}}}}},"components":{"schemas":{"ApiWalletEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiWallet"}}}]},"ApiWalletUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"payoutWallet":{"type":"string","pattern":"^0x[0-9A-Fa-f]{40}$","description":"Backward-compatible alias for cryptoWallets.evm."},"cryptoWallets":{"$ref":"#/components/schemas/CryptoWallets"},"orderWalletOverrideEnabled":{"type":"boolean","description":"Allows receivingWallet on API order creation when true."},"includeCrypto":{"type":"boolean","default":true,"description":"Includes crypto in the merchant's payment-method catalogue when true."}}},"ApiWebhookEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiWebhook"}}}]},"ApiWebhookUpdateRequest":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://","maxLength":2048,"description":"Public HTTPS destination. Localhost","private IP ranges":null,"credentials":null,"and internal hostnames are rejected.":null}}},"ApiWebhookCreatedEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiWebhookCreated"}}}]},"ProviderStatusMethodListEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","required":["paymentMethods","paymentMethodsKeys"],"properties":{"paymentMethods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"paymentMethodsKeys":{"type":"array","items":{"type":"string"}}}}}}]},"PublicCheckoutProductEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicCheckoutProduct"}}}]},"PublicProductOrderRequest":{"type":"object","additionalProperties":false,"required":["customer","paymentMethodKey"],"dependentRequired":{"amount":["currency"],"currency":["amount"]},"properties":{"customer":{"$ref":"#/components/schemas/CustomerInput"},"paymentMethodKey":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$","not":{"enum":["all","hosted"]},"description":"One concrete method enabled by the product."},"amount":{"$ref":"#/components/schemas/Amount","description":"Optional only when allowPriceOverride is enabled."},"currency":{"$ref":"#/components/schemas/Currency","description":"Optional only when allowPriceOverride is enabled."}}},"PublicProductOrderCreatedEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","additionalProperties":false,"required":["orderUUID","status","redirectUrl"],"properties":{"orderUUID":{"type":"string","format":"uuid"},"status":{"type":"string","const":"UNPAID"},"redirectUrl":{"type":"string","format":"uri"}}}}}]},"Error":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}},"CreateProductRequest":{"type":"object","additionalProperties":false,"required":["name","orderTemplate"],"not":{"required":["imageUrl","imageBase64"],"properties":{"imageUrl":{"type":"string"},"imageBase64":{"type":"string"}}},"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"minLength":1,"maxLength":512},"imageUrl":{"type":["string","null"],"format":"uri","maxLength":2048,"pattern":"^https?://"},"imageBase64":{"type":"string","maxLength":410000,"description":"Raw Base64 or a PNG/JPEG/WebP data URI. The decoded image must be exactly 800x800 and at most 300 KB."},"imageDisplaySize":{"type":"integer","minimum":160,"maximum":512,"default":512,"description":"Rendered checkout image width in pixels."},"active":{"type":"boolean","default":true},"allowPriceOverride":{"type":"boolean","default":true,"description":"Allows API callers and public checkout buyers to override amount and currency together."},"orderTemplate":{"$ref":"#/components/schemas/ProductOrderTemplate"}}},"ProductEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}]},"ProductPageEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"nextPageToken":{"type":"string"}}}}}]},"BulkCreateProductsRequest":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/CreateProductRequest"}}}},"BulkCreateProductsEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","additionalProperties":false,"required":["items","createdCount"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/Product"}},"createdCount":{"type":"integer","minimum":1,"maximum":50}}}}}]},"BulkUpsertProductsRequest":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/UpsertProductRequest"}}}},"BulkUpsertProductsEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","additionalProperties":false,"required":["items","createdCount","updatedCount"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/Product"}},"createdCount":{"type":"integer","minimum":0,"maximum":50},"updatedCount":{"type":"integer","minimum":0,"maximum":50}}}}}]},"BulkProductStatusRequest":{"type":"object","additionalProperties":false,"required":["productUUIDs","active"],"properties":{"productUUIDs":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"items":{"type":"string","format":"uuid"}},"active":{"type":"boolean","description":"false disables every product; true re-enables every product."}}},"BulkProductStatusEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","additionalProperties":false,"required":["items","updatedCount","active"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/Product"}},"updatedCount":{"type":"integer","minimum":1,"maximum":100},"active":{"type":"boolean"}}}}}]},"UpdateProductRequest":{"type":"object","additionalProperties":false,"minProperties":1,"not":{"required":["imageUrl","imageBase64"],"properties":{"imageUrl":{"type":"string"},"imageBase64":{"type":"string"}}},"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"minLength":1,"maxLength":512},"imageUrl":{"type":["string","null"],"format":"uri","maxLength":2048,"pattern":"^https?://"},"imageBase64":{"type":"string","maxLength":410000,"description":"Raw Base64 or a PNG/JPEG/WebP data URI. The decoded image must be exactly 800x800 and at most 300 KB."},"imageDisplaySize":{"type":"integer","minimum":160,"maximum":512},"active":{"type":"boolean"},"allowPriceOverride":{"type":"boolean"},"orderTemplate":{"$ref":"#/components/schemas/ProductOrderTemplate"}}},"CreatePaymentRequest":{"type":"object","additionalProperties":false,"required":["customer"],"anyOf":[{"required":["amount","currency","paymentMethodsKeys"]},{"required":["productUUID"]}],"properties":{"productUUID":{"type":"string","format":"uuid","description":"Active catalog product owned by the authenticated merchant. Its template supplies authoritative defaults."},"externalId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$","description":"Optional non-unique merchant correlation label, such as an invoice or cart ID. It is stored and returned unchanged in order responses, transactions, and order.paid webhooks."},"amount":{"$ref":"#/components/schemas/Amount","description":"Required without productUUID. With productUUID","may override the template only when allowPriceOverride is enabled.":null},"currency":{"$ref":"#/components/schemas/Currency","description":"Required without productUUID. With productUUID","may override the template only when allowPriceOverride is enabled.":null},"paymentMethodsKeys":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodsKeys"}],"description":"Required for ad-hoc orders. For product orders","omit it to use the template or provide a subset of the product's enabled methods.":null},"receivingWallet":{"type":"string","pattern":"^0x[0-9A-Fa-f]{40}$","description":"Optional order-scoped payout wallet. The merchant must first enable order wallet overrides."},"customer":{"$ref":"#/components/schemas/CustomerInput"},"description":{"type":"string","minLength":1,"maxLength":512},"productImageUrl":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://"},"returnUrl":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://","description":"Optional order-specific customer return destination. This has priority over checkoutBranding.returnUrl from Custom Checkout settings. Localhost","private-network":null,"credential-bearing":null,"and fragment URLs are rejected.":null},"expiresAt":{"type":"string","format":"date-time","description":"Optional future expiry no more than one year from creation."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"OrderEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}]},"CancelOrderRequest":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","minLength":3,"maxLength":500}}},"CreatedOrderEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","required":["order"],"properties":{"order":{"$ref":"#/components/schemas/Order"}}}}}]},"RefundOrderRequest":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"amount":{"$ref":"#/components/schemas/Amount","description":"Omit to refund the full remaining balance."},"reason":{"type":"string","minLength":3,"maxLength":500}}},"OrderRefundEnvelope":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","required":["order","transaction","refund"],"properties":{"order":{"$ref":"#/components/schemas/Order"},"transaction":{"$ref":"#/components/schemas/Payment"},"refund":{"$ref":"#/components/schemas/Refund"}}}}}]},"OrderPaidWebhookEvent":{"type":"object","additionalProperties":false,"required":["id","type","createdAt","orderUUID","status","amount","currency","customerEmail","externalId","metadata","paidAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Stable event ID; use it for idempotency."},"type":{"type":"string","const":"order.paid"},"createdAt":{"type":"string","format":"date-time"},"orderUUID":{"type":"string","format":"uuid"},"transactionUUID":{"type":"string","format":"uuid","description":"Present only for verified provider-settled payments."},"transactionRef":{"type":["string","null"],"description":"Provider transaction reference; omitted for manually forced payments."},"status":{"type":"string","const":"PAID"},"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"$ref":"#/components/schemas/Currency"},"customerEmail":{"type":"string","format":"email"},"externalId":{"type":["string","null"],"description":"Merchant-supplied correlation ID returned unchanged."},"metadata":{"$ref":"#/components/schemas/Metadata"},"paidAt":{"type":"string","format":"date-time"}}},"SuccessEnvelope":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{}}},"ApiWallet":{"type":"object","required":["configured","payoutWallet","cryptoWallets","configuredCryptoNetworks","walletType","orderWalletOverrideEnabled","includeCrypto","createdAt","updatedAt"],"properties":{"configured":{"type":"boolean","description":"True when an EVM wallet is configured for hosted/card-provider payouts."},"payoutWallet":{"type":"string"},"cryptoWallets":{"$ref":"#/components/schemas/CryptoWallets"},"configuredCryptoNetworks":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["evm","btc","bitcoincash","ltc","doge","solana","trc20"]}},"walletType":{"type":"string","enum":["custom","custodial"]},"orderWalletOverrideEnabled":{"type":"boolean"},"includeCrypto":{"type":"boolean","default":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}},"CryptoWallets":{"type":"object","additionalProperties":false,"description":"Only networks supported by both Paymegate and the merchant are offered.","properties":{"evm":{"type":"string","description":"Ethereum-compatible payout address used by EVM networks."},"btc":{"type":"string","description":"Bitcoin mainnet address."},"bitcoincash":{"type":"string","description":"Bitcoin Cash mainnet CashAddr or checksum-valid legacy address."},"ltc":{"type":"string","description":"Litecoin mainnet address."},"doge":{"type":"string","description":"Dogecoin mainnet address."},"solana":{"type":"string","description":"Solana public address."},"trc20":{"type":"string","description":"TRON mainnet address used by TRX and TRC-20 assets."},"zec":{"type":"string","description":"Transparent Zcash mainnet address."},"xmr":{"type":"string","description":"Monero mainnet standard address","subaddress":null,"or integrated address.":null}}},"ApiWebhook":{"type":"object","additionalProperties":false,"required":["configured","endpointId","url","events","status","createdAt","updatedAt"],"properties":{"configured":{"type":"boolean"},"endpointId":{"type":["string","null"],"format":"uuid"},"url":{"type":["string","null"],"format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["order.paid","payment.created","payment.processing","payment.paid","payment.failed","payment.expired"]}},"status":{"type":"string","enum":["not_configured","active","disabled"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"ApiWebhookCreated":{"type":"object","additionalProperties":false,"required":["configured","endpointId","url","events","status","createdAt","updatedAt","signingSecret"],"properties":{"configured":{"type":"boolean","const":true},"endpointId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["order.paid","payment.created","payment.processing","payment.paid","payment.failed","payment.expired"]}},"status":{"type":"string","enum":["active","disabled"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"signingSecret":{"type":"string","readOnly":true,"description":"Returned once","and only when PUT creates the first webhook configuration. Store it securely for signature verification.":null}}},"PaymentMethod":{"type":"object","required":["key","displayName","minimumAmount","minimumCurrency","status"],"properties":{"key":{"type":"string","examples":["stripe","crypto"],"pattern":"^[a-z0-9][a-z0-9_-]*$"},"displayName":{"type":"string","examples":["Stripe","Crypto"]},"minimumAmount":{"$ref":"#/components/schemas/Amount"},"minimumCurrency":{"$ref":"#/components/schemas/Currency"},"status":{"type":"string","const":"AVAILABLE"}}},"PublicCheckoutProduct":{"type":"object","additionalProperties":false,"required":["productUUID","merchantName","name","description","imageUrl","imageDisplaySize","allowPriceOverride","amount","currency","paymentMethodsKeys","checkoutUrl"],"properties":{"productUUID":{"type":"string","format":"uuid"},"merchantName":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"imageUrl":{"type":["string","null"],"description":"HTTP/HTTPS URL or image data URI."},"imageDisplaySize":{"type":"integer","minimum":160,"maximum":512},"allowPriceOverride":{"type":"boolean"},"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"$ref":"#/components/schemas/Currency"},"paymentMethodsKeys":{"$ref":"#/components/schemas/PaymentMethodsKeys"},"checkoutUrl":{"type":"string","format":"uri"}}},"CustomerInput":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":254},"fullName":{"type":["string","null"],"maxLength":128,"description":"Optional customer display name. Omit","use null":null,"or send whitespace to leave it blank.":null}}},"Amount":{"type":"string","pattern":"^[0-9]{1,18}(?:\\\\.[0-9]{1,3})?$","example":"100.00","description":"Positive exact decimal string. The permitted scale is determined by the ISO 4217 currency (zero","two":null,"or three decimal places); the service normalizes valid values.":null},"Currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"USD"},"ProductOrderTemplate":{"type":"object","additionalProperties":false,"required":["amount","currency","paymentMethodsKeys"],"properties":{"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"$ref":"#/components/schemas/Currency"},"paymentMethodsKeys":{"$ref":"#/components/schemas/PaymentMethodsKeys"},"metadata":{"$ref":"#/components/schemas/Metadata","default":{}}}},"Product":{"type":"object","required":["productUUID","merchantId","checkoutUrl","name","description","imageUrl","imageDisplaySize","active","allowPriceOverride","orderTemplate","createdAt","updatedAt"],"properties":{"productUUID":{"type":"string","format":"uuid"},"merchantId":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri","description":"Stable public hosted checkout URL at /checkout/{productUUID}."},"name":{"type":"string"},"description":{"type":["string","null"]},"imageUrl":{"type":["string","null"],"description":"HTTP/HTTPS URL or a normalized image data URI."},"imageDisplaySize":{"type":"integer","minimum":160,"maximum":512},"active":{"type":"boolean"},"allowPriceOverride":{"type":"boolean"},"orderTemplate":{"$ref":"#/components/schemas/ProductOrderTemplate"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"UpsertProductRequest":{"type":"object","additionalProperties":false,"required":["productUUID","name","orderTemplate"],"not":{"required":["imageUrl","imageBase64"],"properties":{"imageUrl":{"type":"string"},"imageBase64":{"type":"string"}}},"properties":{"productUUID":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"minLength":1,"maxLength":512},"imageUrl":{"type":["string","null"],"format":"uri","maxLength":2048,"pattern":"^https?://"},"imageBase64":{"type":"string","maxLength":410000},"imageDisplaySize":{"type":"integer","minimum":160,"maximum":512,"default":512},"active":{"type":"boolean","default":true},"allowPriceOverride":{"type":"boolean","default":true,"description":"When true","later orders may override the product amount and currency together.":null},"orderTemplate":{"$ref":"#/components/schemas/ProductOrderTemplate"}}},"PaymentMethodsKeys":{"description":"Unique payment-method keys. Use crypto for hosted crypto checkout, combine it with concrete provider keys for a mixed checkout, or send [\"*\"] by itself to offer every currently available method.","anyOf":[{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"prefixItems":[{"type":"string","const":"*"}],"items":false},{"type":"array","minItems":1,"maxItems":64,"uniqueItems":true,"items":{"type":"string","maxLength":64,"pattern":"^(?!(?:all|hosted)$)[a-z0-9][a-z0-9_-]{0,63}$"}}]},"Metadata":{"type":"object","additionalProperties":true,"description":"Merchant-supplied JSON context, maximum depth 3. Store internal IDs or workflow context here; it is returned unchanged in order responses, settled transactions, and order.paid webhooks. Dangerous prototype keys are rejected. Do not place secrets or payment-card data here."},"Order":{"type":"object","required":["merchantId","orderUUID","transactionRef","externalId","amount","currency","status","customerId","customerEmail","customerFullName","feePercent","platformFeeAmount","netAmount","feeCollectionStatus","paymentMethodsKeys","checkoutUrl","createdAt","updatedAt"],"properties":{"merchantId":{"type":"string"},"merchantEmail":{"type":"string","format":"email"},"merchantName":{"type":"string"},"orderUUID":{"type":"string","format":"uuid"},"productUUID":{"type":"string","format":"uuid","description":"Catalog product selected when the order was created."},"productName":{"type":"string","description":"Immutable product-name snapshot for historical display."},"transactionRef":{"type":["string","null"],"description":"Null until a verified provider webhook supplies the reference; remains null for forced reconciliation."},"externalId":{"type":["string","null"],"description":"Merchant-supplied, non-unique correlation label returned unchanged, including in order.paid webhooks."},"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"$ref":"#/components/schemas/Currency"},"receivingWallet":{"type":"string","pattern":"^0x[0-9A-Fa-f]{40}$"},"status":{"type":"string","enum":["UNPAID","PAID","FAILED","EXPIRED","CANCELLED"]},"provisioningStatus":{"type":"string","enum":["CREATED","PROVISIONING","READY","FAILED","SETTLED","EXPIRED","ABANDONED"],"description":"Safe lifecycle value derived from the order's active private checkout session."},"expiresAt":{"type":"string","format":"date-time"},"customerId":{"type":"string","format":"uuid"},"customerEmail":{"type":"string","format":"email"},"customerFullName":{"type":"string"},"feePercent":{"$ref":"#/components/schemas/FeePercent"},"platformFeeAmount":{"$ref":"#/components/schemas/Amount"},"netAmount":{"$ref":"#/components/schemas/Amount"},"feeCollectionStatus":{"type":"string","enum":["PROVIDER_SPLIT","ACCOUNTED_NOT_COLLECTED"]},"paymentMethodsKeys":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Concrete provider keys, or [\"*\"] when the order offers every currently available method."},"source":{"type":"string","enum":["api","web"]},"checkoutUrl":{"type":"string","format":"uri","description":"Platform-owned customer checkout URL at /pay/{orderUUID}; upstream provider URLs are never returned."},"directPaymentLink":{"type":"string","format":"uri","description":"Present only when paymentMethodsKeys contains exactly one concrete provider; points to /payment/process/{orderUUID}."},"providerAddressIn":{"type":"string"},"providerPayoutAddress":{"type":"string"},"providerTxIn":{"type":"string"},"providerTxOut":{"type":"string"},"receivedAmount":{"type":"string"},"receivedCurrency":{"type":"string"},"paidTransactionUUID":{"type":"string"},"paidAt":{"type":"string","format":"date-time"},"forced":{"type":"boolean"},"forcedAt":{"type":"string","format":"date-time"},"forcedBy":{"type":"string"},"forceReason":{"type":"string"},"forcedProviderStatus":{"type":"string","description":"PayMeGate status observed immediately before the merchant forced payment."},"cancelledAt":{"type":"string","format":"date-time"},"cancelledBy":{"type":"string"},"cancelReason":{"type":"string","maxLength":500},"refundStatus":{"type":"string","enum":["PARTIAL","FULL"],"description":"Orthogonal refund state; the order remains PAID because settlement history is preserved."},"refundedAmount":{"$ref":"#/components/schemas/Amount"},"refundCount":{"type":"string","pattern":"^[0-9]+$"},"lastRefundedAt":{"type":"string","format":"date-time"},"refundedAt":{"type":"string","format":"date-time"},"description":{"type":"string"},"productImageUrl":{"type":"string","format":"uri","description":"Immutable product-image snapshot."},"returnUrl":{"type":"string","format":"uri"},"metadata":{"$ref":"#/components/schemas/Metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Payment":{"type":"object","required":["merchantId","tenantId","orderUUID","transactionRef","transactionId","transactionUUID","externalId","amount","currency","feePercent","platformFeeAmount","netAmount","feeCollectionStatus","paymentMethodsKeys","source","customerId","customerEmail","customerFullName","receivingWallet","status","createdAt","updatedAt","expiresAt"],"properties":{"merchantId":{"type":"string","description":"Immutable authenticated merchant UID."},"tenantId":{"type":"string","format":"email"},"orderUUID":{"type":"string","format":"uuid"},"productUUID":{"type":"string","format":"uuid"},"productName":{"type":"string"},"transactionRef":{"type":["string","null"],"description":"Provider reference copied from a verified webhook."},"transactionId":{"type":"string","format":"uuid","description":"UUID for provider-settled transactions."},"transactionUUID":{"type":"string","format":"uuid","description":"Compatibility alias of transactionId."},"externalId":{"type":["string","null"]},"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"$ref":"#/components/schemas/Currency"},"feePercent":{"$ref":"#/components/schemas/FeePercent"},"platformFeeAmount":{"$ref":"#/components/schemas/Amount"},"netAmount":{"$ref":"#/components/schemas/Amount"},"feeCollectionStatus":{"type":"string","enum":["PROVIDER_SPLIT","ACCOUNTED_NOT_COLLECTED"],"description":"PROVIDER_SPLIT means a nonzero fee was accepted through PayMeGate custom-affiliate provisioning. Zero-fee and legacy sessions use ACCOUNTED_NOT_COLLECTED."},"paymentMethodsKeys":{"type":"array","uniqueItems":true,"items":{"type":"string"}},"source":{"type":"string","enum":["api","web"]},"customerId":{"type":"string","format":"uuid"},"customerEmail":{"type":"string","format":"email"},"customerFullName":{"type":"string"},"description":{"type":"string"},"productImageUrl":{"type":"string","format":"uri"},"returnUrl":{"type":"string","format":"uri"},"metadata":{"$ref":"#/components/schemas/Metadata"},"receivingWallet":{"type":"string"},"status":{"type":"string","enum":["PAID","PARTIALLY_REFUNDED","REFUNDED"]},"refundStatus":{"type":"string","enum":["PARTIAL","FULL"]},"refundedAmount":{"$ref":"#/components/schemas/Amount"},"refundCount":{"type":"string","pattern":"^[0-9]+$"},"lastRefundedAt":{"type":"string","format":"date-time"},"refundedAt":{"type":"string","format":"date-time"},"providerTxIn":{"type":"string"},"providerTxOut":{"type":"string"},"receivedAmount":{"type":"string"},"receivedCurrency":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"}}},"Refund":{"type":"object","additionalProperties":false,"required":["merchantId","refundId","orderUUID","transactionId","amount","amountMinor","currency","paymentMethodKey","reason","status","createdBy","createdAt","updatedAt"],"properties":{"merchantId":{"type":"string"},"refundId":{"type":"string","description":"Deterministic digest of the merchant and Idempotency-Key."},"orderUUID":{"type":"string","format":"uuid"},"transactionId":{"type":"string","format":"uuid"},"amount":{"$ref":"#/components/schemas/Amount"},"amountMinor":{"type":"string","pattern":"^[0-9]+$"},"currency":{"$ref":"#/components/schemas/Currency"},"paymentMethodKey":{"type":"string"},"reason":{"type":"string"},"status":{"type":"string","const":"RECORDED","description":"Accounting record only; it does not assert PayMeGate transferred funds."},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"FeePercent":{"type":"string","pattern":"^(?:(?:\\\\d|[1-8]\\\\d)(?:\\\\.\\\\d{1,4})?|99(?:\\\\.0{1,4})?)$","example":"0.8","description":"Exact percentage from 0 through 99","snapshotted on each order and transaction.":null}},"responses":{"InvalidApiKey":{"description":"Invalid","unknown":null,"or revoked API key.":null,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"invalid_api_key","message":"Invalid API key.","requestId":"req_01J123"}}}}},"ValidationError":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"validation_error","message":"Invalid request data.","requestId":"req_01J123"}}}}},"UnprocessableEntity":{"description":"The request is valid but cannot be fulfilled in current merchant or provider state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"payout_wallet_required","message":"Configure a valid EVM payout wallet before creating payments.","requestId":"req_01J123"}}}}},"Unauthorized":{"description":"Missing or invalid authentication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"unauthorized","message":"Authentication is required.","requestId":"req_01J123"}}}}},"ProviderUnavailable":{"description":"Provider unavailable; no provider secrets are exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"provider_unavailable","message":"Payment provider is temporarily unavailable.","requestId":"req_01J123"}}}}},"NotFound":{"description":"Resource not found in the authenticated merchant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"not_found","message":"Resource not found.","requestId":"req_01J123"}}}}},"TooManyRequests":{"description":"Request rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until this client may retry."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"rate_limited","message":"Too many requests.","requestId":"req_01J123"}}}}},"Conflict":{"description":"Existing state conflicts with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"ProductUUID":{"name":"productUUID","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"PageSize":{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"PageToken":{"name":"pageToken","in":"query","schema":{"type":"string","minLength":1,"maxLength":2048}},"OrderUUID":{"name":"orderUUID","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Stable unique key for one refund intent. Reusing it returns the original result and never records the amount twice."}},"securitySchemes":{"MerchantApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your live merchant API key. Keep it on your server and never expose it in browser code."}}}}