{"openapi":"3.1.0","info":{"title":"ArvonaPay Sandbox API","version":"1.1.0","description":"Sandbox payment orchestration. Live processing is disabled. Never send card numbers, CVV or real customer banking data. Amounts are decimal strings. Currency totals must be kept separate."},"servers":[{"url":"https://api.arvonapay.com","description":"Sandbox only"}],"security":[{"BearerAuth":[]}],"paths":{"/v1/payments":{"post":{"operationId":"createPayment","summary":"Create a sandbox payment","description":"Requires payments:create. Mandatory Idempotency-Key, bound to merchant, method, path and body. Concurrent retries return the original result; a different body returns 409. Withdrawals require approval by a different authorized console user. Merchant pricing and daily/monthly limits apply. Cross-currency payments require a direct rate for the current Dubai business day; FX_RATE_MISSING returns 409. Original and charge currencies may differ; inspect the immutable pricing snapshot. No real charge is made in sandbox.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePayment"}}}},"responses":{"201":{"description":"Created or replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listPayments","summary":"List your own payments","description":"Requires payments:read. Page size up to 100.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated payments","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"pages":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/v1/payments/{id}":{"get":{"operationId":"getPayment","summary":"Read one of your payments","description":"Cross-merchant identifiers return 404.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/sandbox/payments/{id}/complete":{"post":{"operationId":"simulatePayment","summary":"Complete a pending sandbox payment","description":"Requires sandbox:simulate and an Idempotency-Key. No money is moved. A withdrawal must already have received independent approval.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["outcome"],"properties":{"outcome":{"enum":["SUCCEEDED","FAILED"]}}}}}},"responses":{"200":{"description":"Final sandbox payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"409":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"A server-side avp_test_ key from your merchant portal. Never expose it in browser or mobile code."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[-a-zA-Z0-9_.:]+$"}}},"responses":{"Error":{"description":"Structured error; retry only transient errors and keep the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"CreatePayment":{"type":"object","additionalProperties":false,"required":["reference","amount","currency","method","direction"],"properties":{"reference":{"type":"string","maxLength":120},"amount":{"type":"string","pattern":"^\\d{1,10}(\\.\\d{1,2})?$","examples":["1250.50"]},"currency":{"enum":["TRY","EUR","USD","GBP","AED","SAR","CHF"]},"method":{"enum":["BANK_TRANSFER","GATEWAY"]},"direction":{"enum":["DEPOSIT","WITHDRAWAL"]},"description":{"type":"string","maxLength":500}}},"Payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"merchantId":{"type":"string","format":"uuid"},"reference":{"type":"string"},"amount":{"type":"string"},"fee":{"type":"string"},"currency":{"type":"string"},"method":{"type":"string"},"direction":{"type":"string"},"environment":{"const":"sandbox"},"status":{"enum":["PENDING_APPROVAL","PENDING","SUCCEEDED","FAILED","CANCELLED"]},"pricing":{"$ref":"#/components/schemas/PricingSnapshot"},"bankAccountId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"approvedAt":{"type":["string","null"],"format":"date-time"},"finalizedAt":{"type":["string","null"],"format":"date-time"}}},"PricingSnapshot":{"type":["object","null"],"description":"Immutable commercial terms from creation time. Minor-unit values are integer strings in the indicated two-decimal currency. Internal provider costs and company profit are never included. Historical v0.1 payments may return null.","properties":{"schema":{"const":1},"fallback":{"type":"boolean"},"ruleId":{"type":["string","null"],"format":"uuid"},"ruleVersion":{"type":"integer"},"rateDay":{"type":"string","format":"date"},"timezone":{"const":"Asia/Dubai"},"originalCurrency":{"type":"string"},"chargeCurrency":{"type":"string"},"settlementCurrency":{"type":"string"},"baseRate":{"type":"string"},"effectiveRate":{"type":"string"},"settlementRate":{"type":"string"},"commissionBps":{"type":"integer"},"markupBps":{"type":"integer"},"bufferBps":{"type":"integer"},"reserveBps":{"type":"integer"},"amountMinor":{"type":"string"},"fee":{"type":"string"},"reserve":{"type":"string"},"merchantNet":{"type":"string"},"settlementNet":{"type":"string"},"gateway":{"type":"string"},"atBase":{"type":"string"},"markupIncome":{"type":"string"},"bufferIncome":{"type":"string"},"fxIncome":{"type":"string"},"delayDays":{"type":"integer"},"reserveDays":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"enum":["payment.succeeded","payment.failed"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Payment"}}}}}}