{"openapi":"3.0.0","paths":{"/api/v1/payments/collections":{"post":{"description":"Requires collections:create. Supports bank transfer, USSD, and QR without accepting raw card data. Use POST /v1/checkout/sessions for card-capable hosted checkout. Atomically records a pending transaction before provider initialization. Retry with the same key and body to replay the initial response.","operationId":"initialize-a-server-side-collection","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCreationResponse"}}}},"400":{"description":"Invalid input, missing wallet, or missing payer email/phone required by Paga."},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."},"409":{"description":"Idempotency key already used for a different request."},"503":{"description":"Paga credentials or callback URL are missing for the selected environment. No funds or records are changed."}},"security":[{"api-key":[]}],"summary":"Initialize a server-side collection","tags":["Collections"]}},"/api/v1/payouts/recipients/validate":{"post":{"description":"Requires payouts:create. Uses the environment on the API key and Paga Business Validate Deposit to Bank. Simulated sandbox behavior is available only when PAGA_SANDBOX_SIMULATE=true.","operationId":"validate-a-payout-recipient","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRecipientDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientValidationResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Validate a payout recipient","tags":["Payouts"]}},"/api/v1/payouts":{"post":{"description":"Requires payouts:create. Validates the recipient, atomically reserves funds, and writes a durable payout-dispatch record before BullMQ sends it to Paga. Provider calls are never retried automatically after dispatch begins.","operationId":"queue-a-payout","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePayoutDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutCreationResponse"}}}},"400":{"description":"Invalid input, missing wallet, or insufficient balance."},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."},"409":{"description":"Idempotency key already used for a different request."}},"security":[{"api-key":[]}],"summary":"Queue a payout","tags":["Payouts"]}},"/api/v1/virtual-accounts":{"get":{"description":"Requires virtual-accounts:read. Results are scoped to the API key environment. Provision accounts through the Business owner/admin API.","operationId":"list-dedicated-collection-accounts","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VirtualAccountResponse"}}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List dedicated collection accounts","tags":["Virtual accounts"]}},"/api/v1/sandbox/virtual-accounts/{id}/transfers":{"post":{"description":"Requires sandbox:simulate and a sandbox API key. Immediately creates and posts a collection ledger entry and credits available balance. This route simulates a verified bank notification; it does not accept or process real transfers.","operationId":"simulate-an-incoming-transfer-to-a-sandbox-virtual-account","parameters":[{"name":"id","required":true,"in":"path","description":"Sandbox virtual-account ID returned by the list/provision endpoints.","schema":{"type":"string"}},{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateVirtualTransferDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","required":["id","transactionId","reference","status","amountMinor","currency","virtualAccountId"],"properties":{"id":{"type":"string"},"transactionId":{"type":"string"},"reference":{"type":"string"},"status":{"type":"string","enum":["SUCCESS"]},"amountMinor":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"providerReference":{"type":"string"},"virtualAccountId":{"type":"string"},"requiresReconciliation":{"type":"boolean","example":false}}}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."},"404":{"description":"No active virtual account belonging to this sandbox merchant."},"409":{"description":"Duplicate/changed idempotency key or duplicate collection reference."},"501":{"description":"Live virtual account callbacks are not implemented."}},"security":[{"api-key":[]}],"summary":"Simulate an incoming transfer to a sandbox virtual account","tags":["Virtual accounts"]}},"/api/v1/bills/categories":{"get":{"description":"Uses the environment attached to the API key. VTpass is selected by default; pass FLUTTERWAVE to use the secondary provider.","operationId":"list-bill-categories","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"provider","required":false,"in":"query","schema":{"default":"VTPASS","type":"string","enum":["VTPASS","FLUTTERWAVE"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillCatalogResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List bill categories","tags":["Bills"]}},"/api/v1/bills/billers":{"get":{"operationId":"list-billers-services-for-a-provider-category","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"provider","required":false,"in":"query","schema":{"default":"VTPASS","type":"string","enum":["VTPASS","FLUTTERWAVE"]}},{"name":"category","required":true,"in":"query","description":"Provider category code returned by the categories endpoint.","schema":{"example":"electricity-bill","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillCatalogResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List billers/services for a provider category","tags":["Bills"]}},"/api/v1/bills/products":{"get":{"operationId":"list-bill-products-or-variations","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"provider","required":false,"in":"query","schema":{"default":"VTPASS","type":"string","enum":["VTPASS","FLUTTERWAVE"]}},{"name":"serviceCode","required":true,"in":"query","description":"VTpass serviceID or Flutterwave biller_code.","schema":{"example":"ikeja-electric","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillCatalogResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List bill products or variations","tags":["Bills"]}},"/api/v1/bills/validate":{"post":{"description":"Validates a meter, smartcard, internet account, or phone number with the selected provider before payment.","operationId":"validate-a-bill-customer","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateBillCustomerDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillValidationResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]},{"api-key":[]}],"summary":"Validate a bill customer","tags":["Bills"]}},"/api/v1/bills":{"post":{"description":"Reserves the selected environment wallet before dispatch. Success consumes the reservation, a definite failure releases it, and an unknown provider outcome remains PROCESSING for requery. Payments are never automatically retried through the secondary provider.","operationId":"pay-a-bill-from-the-merchant-wallet","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBillPaymentDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillPaymentResponse"}}}},"400":{"description":"Invalid request, missing wallet, or insufficient available balance."},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."},"409":{"description":"Duplicate reference or idempotency conflict."},"503":{"description":"Selected provider/environment credentials are missing or unavailable."}},"security":[{"api-key":[]},{"api-key":[]}],"summary":"Pay a bill from the merchant wallet","tags":["Bills"]},"get":{"description":"The API-key environment is authoritative; an environment query value is ignored.","operationId":"list-bill-payments","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"provider","required":false,"in":"query","schema":{"type":"string","enum":["VTPASS","FLUTTERWAVE"]}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["AIRTIME","DATA","ELECTRICITY","TV","INTERNET","OTHER"]}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillPaymentHistoryResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List bill payments","tags":["Bills"]}},"/api/v1/bills/{id}":{"get":{"operationId":"get-a-bill-payment-and-its-token","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillPaymentResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Get a bill payment and its token","tags":["Bills"]}},"/api/v1/bills/{id}/requery":{"post":{"description":"Checks the original provider only and finalizes reserved wallet funds when a definitive outcome is returned.","operationId":"requery-a-pending-bill-payment","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillPaymentResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]},{"api-key":[]}],"summary":"Requery a pending bill payment","tags":["Bills"]}},"/api/v1/transactions":{"get":{"description":"Lists transactions in the API key environment with currency, status, type, channel, date, amount, search, sorting, and pagination filters.","operationId":"list-transactions","parameters":[{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"currency","required":false,"in":"query","description":"Account currency. Results never mix currencies.","schema":{"default":"NGN","example":"NGN","type":"string"}},{"name":"direction","required":false,"in":"query","description":"MONEY_IN selects collections. MONEY_OUT selects payouts, refunds, reversals, and bill payments.","schema":{"type":"string","enum":["MONEY_IN","MONEY_OUT"]}},{"name":"status","required":false,"in":"query","description":"Repeat the query parameter or send a comma-separated list.","schema":{"example":["SUCCESS","PENDING"],"type":"array","items":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]}}},{"name":"type","required":false,"in":"query","description":"Repeat the query parameter or send a comma-separated list.","schema":{"example":["COLLECTION"],"type":"array","items":{"type":"string","enum":["COLLECTION","PAYOUT","REFUND","REVERSAL","BILL_PAYMENT"]}}},{"name":"channel","required":false,"in":"query","description":"Repeat the query parameter or send a comma-separated list.","schema":{"example":["BANK_TRANSFER"],"type":"array","items":{"type":"string","enum":["BANK_TRANSFER","CARD","USSD","QR","PAGA_REQUEST","INTERNAL_TRANSFER","BILL_PAYMENT","OTHER"]}}},{"name":"dateFrom","required":false,"in":"query","description":"Inclusive lower ISO 8601 UTC date/time. A YYYY-MM-DD value starts at 00:00:00 UTC.","schema":{"example":"2026-09-01","type":"string"}},{"name":"dateTo","required":false,"in":"query","description":"Inclusive upper ISO 8601 UTC date/time. A YYYY-MM-DD value includes the entire UTC day.","schema":{"example":"2026-09-30","type":"string"}},{"name":"minAmountMinor","required":false,"in":"query","description":"Inclusive minimum in integer minor units.","schema":{"pattern":"^\\d{1,19}$","example":"10000","type":"string"}},{"name":"maxAmountMinor","required":false,"in":"query","description":"Inclusive maximum in integer minor units.","schema":{"pattern":"^\\d{1,19}$","example":"5000000","type":"string"}},{"name":"search","required":false,"in":"query","description":"Case-insensitive partial match across reference, provider reference, customer name, and customer email.","schema":{"maxLength":120,"example":"Mary","type":"string"}},{"name":"sortBy","required":false,"in":"query","schema":{"default":"createdAt","type":"string","enum":["createdAt","amountMinor"]}},{"name":"sortDirection","required":false,"in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}}],"responses":{"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List transactions","tags":["Transactions"]}},"/api/v1/transactions/by-reference/{reference}":{"get":{"description":"Requires transactions:read. Scoped to the API key merchant and environment. Use after uncertain responses; never resend with a new key.","operationId":"find-a-transaction-by-merchant-reference","parameters":[{"name":"reference","required":true,"in":"path","description":"Merchant transaction reference returned when the collection or payout was initialized.","schema":{"type":"string"}},{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionDetailResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."},"404":{"description":"No matching transaction in this merchant/environment."}},"security":[{"api-key":[]}],"summary":"Find a transaction by merchant reference","tags":["Transactions"]}},"/api/v1/transactions/{id}":{"get":{"description":"Requires transactions:read. Creation retries replay the original response; this endpoint returns current status.","operationId":"read-current-transaction-status","parameters":[{"name":"id","required":true,"in":"path","description":"Creddot transaction ID.","schema":{"type":"string"}},{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionDetailResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."},"404":{"description":"Transaction not found."}},"security":[{"api-key":[]}],"summary":"Read current transaction status","tags":["Transactions"]}},"/api/v1/wallets":{"get":{"description":"Requires wallets:read. Pending is unconfirmed collection money; reserved is money held for payouts; only available can be spent.","operationId":"read-wallet-balances","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WalletResponse"}}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Read wallet balances","tags":["Transactions"]}},"/api/v1/sandbox/transactions/{id}/complete":{"post":{"description":"Requires sandbox:simulate and a sandbox API key. SUCCESS posts the entry; FAILED reverses it and releases payout funds. Repeating an outcome is safe; changing a terminal outcome returns 409. No real money moves.","operationId":"simulate-a-final-sandbox-collection-or-payout-outcome","parameters":[{"name":"id","required":true,"in":"path","description":"Pending sandbox transaction ID to finalize.","schema":{"type":"string"}},{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteSandboxTransactionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionDetailResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."},"404":{"description":"Transaction not found in this sandbox merchant."},"409":{"description":"Conflicting outcome, legacy record, initialization in progress, or idempotency conflict."}},"security":[{"api-key":[]}],"summary":"Simulate a final sandbox collection or payout outcome","tags":["Transactions"]}},"/api/v1/checkout/payments/{reference}":{"get":{"description":"No authentication. Poll this payer-safe endpoint after starting a Pay Link, event, Split Pay, or storefront order payment. It returns current database status immediately after callback or reconciliation settlement and never exposes payer contact details, provider references, or internal IDs.","operationId":"read-public-checkout-payment-status","parameters":[{"name":"reference","required":true,"in":"path","description":"Opaque pl_, evt_, sp_, or sf_ checkout reference returned by payment initialization.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutPaymentStatusResponse"}}}},"404":{"description":"Payment not found."},"429":{"description":"Too many status checks from this IP address."}},"summary":"Read public checkout payment status","tags":["public checkout"]}},"/api/v1/checkout/sessions":{"post":{"description":"Creates a single-use hosted checkout in the API key environment. Redirect the customer to checkoutUrl. Card details are collected only by Creddot checkout; they never pass through the merchant server.","operationId":"create-a-hosted-checkout-session","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHostedCheckoutDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostedCheckoutResponse"}}}},"400":{"description":"Invalid amount, currency, redirect URL, reference, or expiry."},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."},"409":{"description":"Reference or idempotency key already exists."}},"security":[{"api-key":[]}],"summary":"Create a hosted checkout session","tags":["Checkout"]}},"/api/v1/checkout/sessions/{session}":{"get":{"description":"Requires collections:create. Use on your return page or after a webhook to confirm the order is paid: status PAID means a payment succeeded. Scoped to the API key merchant and environment.","operationId":"get-a-hosted-checkout-session","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"session","required":true,"in":"path","description":"The session id returned at creation, or your own reference.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostedCheckoutStatusResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."},"404":{"description":"No checkout session with this id or reference in this merchant/environment."}},"security":[{"api-key":[]}],"summary":"Get a hosted checkout session","tags":["Checkout"]}},"/api/v1/payment-links":{"get":{"operationId":"list-pay-links-in-the-api-key-environment","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}}],"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List Pay Links in the API key environment","tags":["Payment links"]},"post":{"operationId":"create-a-reusable-pay-link","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantPaymentLinkDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Create a reusable Pay Link","tags":["Payment links"]}},"/api/v1/payment-links/{id}":{"get":{"operationId":"get-pay-link-details-and-progress","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkDetailResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Get Pay Link details and progress","tags":["Payment links"]},"patch":{"operationId":"update-an-active-pay-link","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePaymentLinkDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkDetailResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Update an active Pay Link","tags":["Payment links"]}},"/api/v1/payment-links/{id}/offline-payments":{"post":{"operationId":"record-an-offline-payment-against-a-pay-link","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordOfflinePaymentDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkDetailResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Record an offline payment against a Pay Link","tags":["Payment links"]}},"/api/v1/payment-links/{id}/offline-payments/{transactionId}":{"delete":{"operationId":"void-an-offline-pay-link-payment","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"transactionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkDetailResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Void an offline Pay Link payment","tags":["Payment links"]}},"/api/v1/payment-links/{id}/disable":{"post":{"operationId":"disable-a-pay-link","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Disable a Pay Link","tags":["Payment links"]}},"/api/v1/invoices":{"get":{"operationId":"list-invoices-in-the-api-key-environment","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}}],"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List invoices in the API key environment","tags":["Invoices"]},"post":{"operationId":"create-an-invoice-draft","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantInvoiceDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Create an invoice draft","tags":["Invoices"]}},"/api/v1/invoices/{id}":{"get":{"operationId":"get-an-invoice","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Get an invoice","tags":["Invoices"]}},"/api/v1/invoices/{id}/send":{"post":{"operationId":"send-an-invoice-and-create-its-checkout-link","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Send an invoice and create its checkout link","tags":["Invoices"]}},"/api/v1/customers":{"get":{"operationId":"list-customers-in-the-api-key-environment","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"default":"ALL","type":"string","enum":["ALL","ACTIVE","DISABLED"]}},{"name":"search","required":false,"in":"query","description":"Searches name, customer ID, email, and phone number.","schema":{"maxLength":120,"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerListResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List customers in the API key environment","tags":["Customers"]},"post":{"operationId":"create-a-customer-in-the-api-key-environment","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantCustomerDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Create a customer in the API key environment","tags":["Customers"]}},"/api/v1/customers/{customerId}":{"get":{"operationId":"get-a-customer","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"customerId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Get a customer","tags":["Customers"]},"patch":{"operationId":"update-a-customer","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"customerId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Update a customer","tags":["Customers"]},"delete":{"operationId":"soft-delete-a-customer","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"customerId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Soft-delete a customer","tags":["Customers"]}},"/api/v1/customers/{customerId}/status":{"put":{"operationId":"enable-or-disable-a-customer","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"customerId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Enable or disable a customer","tags":["Customers"]}},"/api/v1/subscriptions/{subscriptionId}/subscribers":{"get":{"description":"Filter by email to check one customer. Accepts the subscription ID or code (SUB-001). Up to 100, newest first.","operationId":"list-a-subscription-s-subscribers","parameters":[{"name":"subscriptionId","required":true,"in":"path","schema":{"type":"string"}},{"name":"email","required":false,"in":"query","description":"Find a customer's subscription by email.","schema":{"format":"email","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["PENDING","PROCESSING","ACTIVE","OVERDUE","LAPSED","CANCELLED"]}},{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionSubscriberResponse"}}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."},"404":{"description":"Subscription not found for this API key."}},"security":[{"api-key":[]}],"summary":"List a subscription's subscribers","tags":["subscriptions"]},"post":{"operationId":"add-a-customer-to-a-subscription","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"subscriptionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSubscriptionSubscriberDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionSubscriberResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Add a customer to a subscription","tags":["Subscriptions"]}},"/api/v1/subscriptions/subscribers/{subscriberId}":{"get":{"description":"active is true while the customer has paid for the current cycle (ACTIVE) or is inside the grace period (OVERDUE).","operationId":"read-one-subscriber","parameters":[{"name":"subscriberId","required":true,"in":"path","schema":{"type":"string"}},{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionSubscriberResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Read one subscriber","tags":["subscriptions"]}},"/api/v1/subscription-plans":{"get":{"operationId":"list-subscription-plans-in-the-api-key-environment","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"default":"ALL","type":"string","enum":["ALL","ACTIVE","ARCHIVED"]}},{"name":"search","required":false,"in":"query","schema":{"maxLength":120,"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List subscription plans in the API key environment","tags":["Subscription plans"]},"post":{"operationId":"create-a-subscription-plan","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantPlanDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionPlanResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Create a subscription plan","tags":["Subscription plans"]}},"/api/v1/subscription-plans/{planId}":{"get":{"operationId":"get-a-subscription-plan","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"planId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionPlanResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Get a subscription plan","tags":["Subscription plans"]},"patch":{"operationId":"update-a-subscription-plan","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"planId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionPlanDto"}}}},"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Update a subscription plan","tags":["Subscription plans"]}},"/api/v1/subscription-plans/{planId}/archive":{"post":{"operationId":"archive-a-subscription-plan","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"planId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Archive a subscription plan","tags":["Subscription plans"]}},"/api/v1/subscriptions":{"get":{"operationId":"list-subscriptions-in-the-api-key-environment","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"default":"ALL","type":"string","enum":["ALL","DRAFT","ACTIVE","CANCELLED"]}},{"name":"search","required":false,"in":"query","description":"Searches subscription name, ID, and plan.","schema":{"maxLength":120,"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List subscriptions in the API key environment","tags":["Subscriptions"]},"post":{"operationId":"create-a-subscription","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantSubscriptionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionDetailResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Create a subscription","tags":["Subscriptions"]}},"/api/v1/subscriptions/{subscriptionId}":{"get":{"operationId":"get-subscription-details","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"subscriptionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionDetailResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Get subscription details","tags":["Subscriptions"]},"patch":{"operationId":"update-a-subscription","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"subscriptionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionDto"}}}},"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Update a subscription","tags":["Subscriptions"]},"delete":{"operationId":"delete-an-unused-draft-subscription","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"subscriptionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Delete an unused draft subscription","tags":["Subscriptions"]}},"/api/v1/subscriptions/{subscriptionId}/activate":{"post":{"operationId":"activate-a-draft-subscription","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"subscriptionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Activate a draft subscription","tags":["Subscriptions"]}},"/api/v1/subscriptions/{subscriptionId}/cancel":{"post":{"operationId":"cancel-a-subscription","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"subscriptionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Cancel a subscription","tags":["Subscriptions"]}},"/api/v1/subscriptions/{subscriptionId}/subscribers/{subscriberId}/status":{"patch":{"operationId":"update-a-subscriber-status","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"subscriptionId","required":true,"in":"path","schema":{"type":"string"}},{"name":"subscriberId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionSubscriberStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionSubscriberResponse"}}}},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Update a subscriber status","tags":["Subscriptions"]}},"/api/v1/refunds":{"get":{"operationId":"list-refund-requests-in-the-api-key-environment","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["REQUESTED","APPROVED","PROCESSING","SUCCESS","FAILED","REJECTED"]}},{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"List refund requests in the API key environment","tags":["Refunds"]}},"/api/v1/refunds/transactions/{transactionId}":{"post":{"description":"Creates a REQUESTED refund for admin review. This call never dispatches funds directly.","operationId":"request-a-full-or-partial-collection-refund","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"transactionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundRequestDto"}}}},"responses":{"201":{"description":"Refund request created."},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Request a full or partial collection refund","tags":["Refunds"]}},"/api/v1/refunds/{refundId}":{"get":{"operationId":"get-a-refund-request","parameters":[{"name":"x-api-secret","in":"header","description":"Recommended: API secret sent over HTTPS. You may send it as Authorization: Bearer instead. If supplied, x-timestamp and x-signature are not required.","required":false,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Legacy signed mode: Unix time in milliseconds; maximum clock skew five minutes.","required":false,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"Legacy signed mode: HMAC-SHA256(secret, timestamp.METHOD.url.idempotencyKey.bodyHash).","required":false,"schema":{"type":"string"}},{"name":"x-idempotency-key","in":"header","description":"1–128 letters/digits or ._:-. Same key and payload replay for 24 hours; conflicting, in-flight, or expired keys return 409. Never change a key to retry an uncertain payment.","required":true,"schema":{"type":"string"}},{"name":"refundId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Invalid API key/secret, signed request, timestamp, or IP whitelist."},"403":{"description":"API key lacks the required permission or environment is not allowed."}},"security":[{"api-key":[]}],"summary":"Get a refund request","tags":["Refunds"]}}},"info":{"title":"Creddot Merchant API","description":"Base URL: https://api.creddot.com/api/v1\n\nSend x-api-key and x-api-secret over HTTPS. For POST requests, also send a unique x-idempotency-key.\nCreate a card-capable hosted payment with POST /checkout/sessions and redirect the payer to checkoutUrl.\nUse POST /payments/collections only for bank transfer, USSD, and QR collections.\nConfigure a merchant webhook endpoint in the Creddot console. Transaction events are signed and retried automatically.\nCustomer, Pay Link, invoice, subscription, refund, and filtered transaction resources use this same base URL.","version":"1.0","contact":{}},"tags":[{"name":"Collections","description":"Merchant collection initialization. Requires signed merchant API headers."},{"name":"Checkout","description":"Server-created, single-use hosted checkout sessions. Raw card data never passes through merchant servers."},{"name":"Customers","description":"Customer directory access scoped to the API key business and environment."},{"name":"Payment links","description":"Reusable Pay Link lifecycle access for server integrations."},{"name":"Invoices","description":"Invoice creation, listing, and checkout-link delivery for server integrations."},{"name":"Subscription plans","description":"Subscription plan lifecycle access for server integrations."},{"name":"Subscriptions","description":"Subscription and subscriber lifecycle access for server integrations."},{"name":"Refunds","description":"Merchant refund requests routed through the admin approval queue."},{"name":"Payouts","description":"Merchant payout initialization. Requires signed merchant API headers."},{"name":"Bills","description":"VTpass and Flutterwave bill catalogs, validation, wallet-funded payments, history, and status requery."},{"name":"Transactions","description":"Merchant transaction lookup, balances, and sandbox completion."},{"name":"Virtual accounts","description":"Business provisioning and merchant virtual-account APIs."}],"servers":[{"url":"https://api.creddot.com","description":"Production (sandbox and live keys)"}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key: ck_test_... for test mode, ck_live_... for live. Send it with x-api-secret (or Authorization: Bearer <secret>)."},"api-secret":{"type":"apiKey","in":"header","name":"x-api-secret","description":"Merchant API secret. Recommended over request signing; send only over HTTPS. Authorization: Bearer is also accepted."}},"schemas":{"CreateCollectionDto":{"type":"object","properties":{"amountMinor":{"type":"string","example":"150000"},"currency":{"type":"string","example":"NGN"},"channel":{"type":"string","enum":["BANK_TRANSFER","USSD","QR"],"description":"Card payments are available only through hosted checkout."},"reference":{"type":"string","example":"ORD-100001"},"customerEmail":{"type":"string","example":"customer@example.com"},"customerPhone":{"type":"string","example":"+2348012345678","description":"Required when customerEmail is omitted. Paga requires at least one payer identifier."},"customerName":{"type":"string","example":"Ada Okafor","maxLength":120},"callbackUrl":{"type":"string","example":"https://merchant.example.com/payments/callback"}},"required":["amountMinor","currency","channel"]},"CollectionCreationResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string","description":"Use this ID for transaction lookup and sandbox completion. Payout id is a separate payout record ID."},"reference":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]},"amountMinor":{"type":"string","example":"100000","description":"Integer minor units, encoded as a string."},"currency":{"type":"string","example":"NGN"},"provider":{"type":"string","example":"PAGA"},"providerReference":{"type":"string","nullable":true},"requiresReconciliation":{"type":"boolean","description":"True when provider outcome is uncertain. Do not retry with a new key; query the transaction or reconcile it."},"feeMinor":{"type":"string","example":"1500","description":"Creddot fee charged to the business in minor units."},"totalDebitMinor":{"type":"string","example":"101500","description":"Wallet debit for payouts; equals amountMinor for incoming transfers."},"netCreditMinor":{"type":"string","example":"98500","description":"Wallet credit for incoming transfers; equals amountMinor for payouts."},"paymentUrl":{"type":"string","nullable":true,"format":"uri","description":"Provider checkout URL. Current sandbox URLs are placeholders."}},"required":["id","transactionId","reference","status","amountMinor","currency","provider","providerReference","requiresReconciliation","feeMinor","totalDebitMinor","netCreditMinor","paymentUrl"]},"ValidateRecipientDto":{"type":"object","properties":{"bankCode":{"type":"string","example":"044","description":"Bank code supplied by the connected banking provider."},"accountNumber":{"type":"string","example":"0123456789"},"amountMinor":{"type":"string","example":"100","default":"100","description":"Amount in minor units used by Paga to calculate transfer fees during validation."},"currency":{"type":"string","example":"NGN","default":"NGN"}},"required":["bankCode","accountNumber"]},"RecipientValidationResponse":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"bankCode":{"type":"string","example":"044"},"accountNumberMasked":{"type":"string","example":"******6789"},"accountName":{"type":"string","nullable":true,"example":"Sandbox Account 6789"},"provider":{"type":"string","example":"PAGA"},"simulated":{"type":"boolean","example":true,"description":"True only for the simulated sandbox validation response."},"feeMinor":{"type":"string","nullable":true,"example":"5000","description":"Estimated Paga fee in minor units."},"message":{"type":"string","nullable":true}},"required":["valid","bankCode","accountNumberMasked","accountName","provider","simulated","feeMinor","message"]},"CreatePayoutDto":{"type":"object","properties":{"amountMinor":{"type":"string","example":"100000"},"currency":{"type":"string","example":"NGN"},"bankCode":{"type":"string","example":"044"},"accountNumber":{"type":"string","example":"0123456789"},"accountName":{"type":"string","example":"Ada Merchant"},"reference":{"type":"string","example":"PYT-100001"},"narration":{"type":"string","example":"Vendor settlement"}},"required":["amountMinor","currency","bankCode","accountNumber"]},"PayoutCreationResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string","description":"Use this ID for transaction lookup and sandbox completion. Payout id is a separate payout record ID."},"reference":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]},"amountMinor":{"type":"string","example":"100000","description":"Integer minor units, encoded as a string."},"currency":{"type":"string","example":"NGN"},"provider":{"type":"string","example":"PAGA"},"providerReference":{"type":"string","nullable":true},"requiresReconciliation":{"type":"boolean","description":"True when provider outcome is uncertain. Do not retry with a new key; query the transaction or reconcile it."},"feeMinor":{"type":"string","example":"1500","description":"Creddot fee charged to the business in minor units."},"totalDebitMinor":{"type":"string","example":"101500","description":"Wallet debit for payouts; equals amountMinor for incoming transfers."},"netCreditMinor":{"type":"string","example":"98500","description":"Wallet credit for incoming transfers; equals amountMinor for payouts."},"queued":{"type":"boolean","enum":[true],"description":"The payout was reserved and accepted by the durable dispatch queue."},"queueJobId":{"type":"string","description":"Durable payout dispatch job ID. Administrators can monitor this ID."}},"required":["id","transactionId","reference","status","amountMinor","currency","provider","providerReference","requiresReconciliation","feeMinor","totalDebitMinor","netCreditMinor","queued","queueJobId"]},"RegisterBusinessDto":{"type":"object","properties":{"email":{"type":"string","example":"owner@example.com","format":"email","maxLength":191},"firstName":{"type":"string","example":"Ada","minLength":1,"maxLength":60},"lastName":{"type":"string","example":"Okafor","minLength":1,"maxLength":60},"phoneNumber":{"type":"string","example":"+2348012345678","description":"Complete phone number in international E.164 format."},"businessName":{"type":"string","example":"Ada Commerce Limited","minLength":2,"maxLength":120},"password":{"type":"string","example":"Password1!","format":"password","minLength":6,"maxLength":128,"writeOnly":true,"description":"At least six characters with one uppercase letter, one number, and one special character."},"confirmPassword":{"type":"string","example":"Password1!","format":"password","writeOnly":true}},"required":["email","firstName","lastName","phoneNumber","businessName","password","confirmPassword"]},"OtpChallengeResponse":{"type":"object","properties":{"nextStep":{"type":"string","enum":["VERIFY_EMAIL","VERIFY_PHONE","VERIFY_PASSWORD_RESET"]},"destination":{"type":"string","example":"a***@example.com","description":"Masked destination of the verification code."},"expiresAt":{"type":"string","format":"date-time"},"resendAvailableAt":{"type":"string","format":"date-time"},"developmentCode":{"type":"string","example":"1234","description":"Returned only when AUTH_OTP_EXPOSE_IN_RESPONSE=true. Never enable it in production."}},"required":["nextStep","destination","expiresAt","resendAvailableAt"]},"VerifyOtpDto":{"type":"object","properties":{"email":{"type":"string","example":"owner@example.com","format":"email","maxLength":191},"code":{"type":"string","example":"1234","minLength":4,"maxLength":4,"pattern":"^\\d{4}$"}},"required":["email","code"]},"EmailDto":{"type":"object","properties":{"email":{"type":"string","example":"owner@example.com","format":"email","maxLength":191}},"required":["email"]},"BusinessMembershipMerchantResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"Ada Commerce Limited"},"status":{"type":"string","enum":["PENDING","ACTIVE","SUSPENDED","CLOSED"]},"kycStatus":{"type":"string","enum":["NOT_STARTED","PENDING","VERIFIED","REJECTED","REQUIRES_UPDATE"]}},"required":["id","name","status","kycStatus"]},"BusinessMembershipResponse":{"type":"object","properties":{"role":{"type":"string","enum":["OWNER","ADMIN","DEVELOPER","FINANCE","SUPPORT","VIEWER"]},"merchant":{"$ref":"#/components/schemas/BusinessMembershipMerchantResponse"}},"required":["role","merchant"]},"UserProfileResponse":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","example":"owner@example.com"},"fullName":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"phoneNumber":{"type":"string","nullable":true},"status":{"type":"string","enum":["PENDING_VERIFICATION","ACTIVE","SUSPENDED"]},"emailVerified":{"type":"boolean"},"phoneVerified":{"type":"boolean"},"members":{"type":"array","items":{"$ref":"#/components/schemas/BusinessMembershipResponse"}}},"required":["id","email","fullName","firstName","lastName","phoneNumber","status","emailVerified","phoneVerified","members"]},"AuthResponse":{"type":"object","properties":{"accessToken":{"type":"string","description":"Opaque session token. Paste this value into Swagger Authorize → bearer. Never use a merchant API secret here."},"tokenType":{"type":"string","enum":["Bearer"]},"expiresAt":{"type":"string","format":"date-time","description":"Session expires 12 hours after creation."},"user":{"$ref":"#/components/schemas/UserProfileResponse"}},"required":["accessToken","tokenType","expiresAt","user"]},"LoginDto":{"type":"object","properties":{"email":{"type":"string","example":"owner@example.com","format":"email","maxLength":191},"password":{"type":"string","example":"Password1!","format":"password","minLength":1,"maxLength":128,"writeOnly":true},"twoFactorCode":{"type":"string","description":"Required when two-factor authentication is enabled. Accepts an authenticator or recovery code."}},"required":["email","password"]},"PasskeyAuthenticationOptionsDto":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]},"PasskeyOptionsResponse":{"type":"object","properties":{"challengeId":{"type":"string"},"options":{"type":"object","additionalProperties":true}},"required":["challengeId","options"]},"VerifyPasskeyAuthenticationDto":{"type":"object","properties":{"challengeId":{"type":"string"},"response":{"type":"object","additionalProperties":true}},"required":["challengeId","response"]},"PasswordResetVerificationResponse":{"type":"object","properties":{"resetToken":{"type":"string","description":"Single-use token accepted by POST /auth/password/reset."},"expiresAt":{"type":"string","format":"date-time"}},"required":["resetToken","expiresAt"]},"ResetPasswordDto":{"type":"object","properties":{"resetToken":{"type":"string","description":"One-time token returned after the password-reset OTP is verified.","minLength":43},"newPassword":{"type":"string","example":"NewPassword1!","format":"password","minLength":6,"maxLength":128,"writeOnly":true},"confirmPassword":{"type":"string","example":"NewPassword1!","format":"password","writeOnly":true}},"required":["resetToken","newPassword","confirmPassword"]},"EffectiveFeeResponse":{"type":"object","properties":{"id":{"type":"string","nullable":true},"scope":{"type":"string","enum":["GENERAL","BUSINESS"],"nullable":true},"merchantId":{"type":"string","nullable":true},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"type":{"type":"string","enum":["INCOMING_TRANSFER","PAYOUT"]},"method":{"type":"string","enum":["VIRTUAL_ACCOUNT_TRANSFER","CHECKOUT_PAYMENT_LINK","CHECKOUT_SPLIT_PAY","CHECKOUT_EVENT","CHECKOUT_STOREFRONT","CHECKOUT_SUBSCRIPTION","API_COLLECTION","PAYOUT_BANK_TRANSFER"]},"currency":{"type":"string"},"fixedFeeMinor":{"type":"string"},"percentageBasisPoints":{"type":"number"},"minimumFeeMinor":{"type":"string","nullable":true},"maximumFeeMinor":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true},"source":{"type":"string","enum":["BUSINESS","GENERAL","NONE"]}},"required":["id","scope","merchantId","environment","type","method","currency","fixedFeeMinor","percentageBasisPoints","minimumFeeMinor","maximumFeeMinor","active","createdAt","updatedAt","source"]},"EstimateFeeDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"currency":{"type":"string","example":"NGN","default":"NGN"},"method":{"type":"string","enum":["VIRTUAL_ACCOUNT_TRANSFER","CHECKOUT_PAYMENT_LINK","CHECKOUT_SPLIT_PAY","CHECKOUT_EVENT","CHECKOUT_STOREFRONT","CHECKOUT_SUBSCRIPTION","API_COLLECTION","PAYOUT_BANK_TRANSFER"]},"amountMinor":{"type":"string","example":"1000000"}},"required":["method","amountMinor"]},"FeeEstimateResponse":{"type":"object","properties":{"type":{"type":"string","enum":["INCOMING_TRANSFER","PAYOUT"]},"method":{"type":"string","enum":["VIRTUAL_ACCOUNT_TRANSFER","CHECKOUT_PAYMENT_LINK","CHECKOUT_SPLIT_PAY","CHECKOUT_EVENT","CHECKOUT_STOREFRONT","CHECKOUT_SUBSCRIPTION","API_COLLECTION","PAYOUT_BANK_TRANSFER"]},"amountMinor":{"type":"string"},"feeMinor":{"type":"string"},"totalDebitMinor":{"type":"string"},"netCreditMinor":{"type":"string"},"source":{"type":"string","enum":["BUSINESS","GENERAL","NONE"]},"ruleId":{"type":"string","nullable":true}},"required":["type","method","amountMinor","feeMinor","totalDebitMinor","netCreditMinor","source","ruleId"]},"BusinessAddressResponse":{"type":"object","properties":{"addressLine1":{"type":"string","nullable":true,"example":"12 Marina Road"},"addressLine2":{"type":"string","nullable":true,"example":"3rd Floor"},"city":{"type":"string","nullable":true,"example":"Lagos"},"state":{"type":"string","nullable":true,"example":"Lagos"},"postalCode":{"type":"string","nullable":true,"example":"101001","description":"ZIP or postal code."},"countryCode":{"type":"string","example":"NG"}},"required":["addressLine1","addressLine2","city","state","postalCode","countryCode"]},"BusinessProfileResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"businessEmail":{"type":"string","format":"email"},"baseCurrency":{"type":"string","example":"NGN"},"status":{"type":"string","enum":["PENDING","ACTIVE","SUSPENDED","CLOSED"]},"kycStatus":{"type":"string","enum":["NOT_STARTED","PENDING","VERIFIED","REJECTED","REQUIRES_UPDATE"]},"address":{"$ref":"#/components/schemas/BusinessAddressResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","businessEmail","baseCurrency","status","kycStatus","address","createdAt","updatedAt"]},"UpdateBusinessProfileDto":{"type":"object","properties":{"name":{"type":"string","example":"Acme Limited","minLength":2,"maxLength":160},"addressLine1":{"type":"string","example":"12 Marina Road","nullable":true,"maxLength":191},"addressLine2":{"type":"string","example":"3rd Floor","nullable":true,"maxLength":191},"city":{"type":"string","example":"Lagos","nullable":true,"maxLength":100},"state":{"type":"string","example":"Lagos","nullable":true,"maxLength":100,"description":"State, province, or region shown on invoices."},"postalCode":{"type":"string","example":"101001","nullable":true,"maxLength":20,"description":"ZIP or postal code shown on invoices."},"countryCode":{"type":"string","example":"NG","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code."}}},"MerchantOverviewResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"businessEmail":{"type":"string","format":"email"},"status":{"type":"string","enum":["PENDING","ACTIVE","SUSPENDED","CLOSED"]},"kycStatus":{"type":"string","enum":["NOT_STARTED","PENDING","VERIFIED","REJECTED","REQUIRES_UPDATE"]},"kycStatusLabel":{"type":"string","example":"KYC Pending"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","businessEmail","status","kycStatus","kycStatusLabel","createdAt"]},"RevenuePointResponse":{"type":"object","properties":{"date":{"type":"string","example":"2026-10-07","format":"date"},"amountMinor":{"type":"string","example":"150000","description":"Net successful collection amount for this UTC day in minor units."}},"required":["date","amountMinor"]},"RevenueOverviewResponse":{"type":"object","properties":{"rangeDays":{"type":"number","example":30},"totalMinor":{"type":"string","example":"1500000","description":"Sum of the returned daily net revenue values in minor units."},"series":{"type":"array","items":{"$ref":"#/components/schemas/RevenuePointResponse"}}},"required":["rangeDays","totalMinor","series"]},"PayoutResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]},"reference":{"type":"string"},"amountMinor":{"type":"string","example":"100000"},"currency":{"type":"string","example":"NGN"},"accountNumberMasked":{"type":"string","example":"******6789"},"bankCode":{"type":"string","example":"044"},"accountName":{"type":"string","nullable":true},"narration":{"type":"string","nullable":true},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","reference","amountMinor","currency","accountNumberMasked","bankCode","accountName","narration","environment","createdAt","updatedAt"]},"DashboardBalanceResponse":{"type":"object","properties":{"availableBalanceMinor":{"type":"string","example":"1000000"},"pendingBalanceMinor":{"type":"string","example":"50000"},"reservedBalanceMinor":{"type":"string","example":"25000"},"lastWithdrawal":{"nullable":true,"description":"Most recent successful payout in this environment and currency.","type":"object","allOf":[{"$ref":"#/components/schemas/PayoutResponse"}]}},"required":["availableBalanceMinor","pendingBalanceMinor","reservedBalanceMinor","lastWithdrawal"]},"TransactionResponse":{"type":"object","properties":{"requiresReconciliation":{"type":"boolean"},"id":{"type":"string"},"type":{"type":"string","enum":["COLLECTION","PAYOUT","REFUND","REVERSAL","BILL_PAYMENT"]},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]},"reference":{"type":"string"},"amountMinor":{"type":"string","example":"100000","description":"Integer minor units encoded as a string."},"currency":{"type":"string","example":"NGN"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"provider":{"type":"string"},"direction":{"type":"string","enum":["MONEY_IN","MONEY_OUT"]},"channel":{"type":"string","nullable":true,"example":"BANK_TRANSFER"},"customerName":{"type":"string","nullable":true,"example":"Mary Sam Michael"},"customerEmail":{"type":"string","nullable":true,"format":"email"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["requiresReconciliation","id","type","status","reference","amountMinor","currency","environment","provider","direction","channel","customerName","customerEmail","createdAt","updatedAt"]},"VolumePointResponse":{"type":"object","properties":{"month":{"type":"string","example":"2026-10","pattern":"^\\d{4}-\\d{2}$"},"grossVolumeMinor":{"type":"string","example":"5000000"},"refundedVolumeMinor":{"type":"string","example":"250000"},"netVolumeMinor":{"type":"string","example":"4750000"}},"required":["month","grossVolumeMinor","refundedVolumeMinor","netVolumeMinor"]},"VolumeOverviewResponse":{"type":"object","properties":{"rangeMonths":{"type":"number","example":3},"grossVolumeMinor":{"type":"string","example":"5000000"},"refundedVolumeMinor":{"type":"string","example":"250000"},"netVolumeMinor":{"type":"string","example":"4750000"},"series":{"type":"array","items":{"$ref":"#/components/schemas/VolumePointResponse"}}},"required":["rangeMonths","grossVolumeMinor","refundedVolumeMinor","netVolumeMinor","series"]},"PaymentBreakdownResponse":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCEEDED","PENDING","REFUNDED","FAILED"]},"amountMinor":{"type":"string","example":"1500000"},"count":{"type":"number","example":12},"percentageBasisPoints":{"type":"number","example":7500,"minimum":0,"maximum":10000,"description":"Share of categorized payment amount in basis points. 7500 means 75.00%."}},"required":["status","amountMinor","count","percentageBasisPoints"]},"WalletResponse":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string","example":"NGN"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"status":{"type":"string","enum":["ACTIVE","FROZEN","CLOSED"]},"availableBalanceMinor":{"type":"string","example":"0","description":"Integer minor units encoded as a string."},"pendingBalanceMinor":{"type":"string","example":"0","description":"Integer minor units encoded as a string."},"reservedBalanceMinor":{"type":"string","example":"0","description":"Funds held for pending payouts, excluded from available balance."}},"required":["id","currency","environment","status","availableBalanceMinor","pendingBalanceMinor","reservedBalanceMinor"]},"VirtualAccountResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"currency":{"type":"string","example":"NGN"},"accountNumber":{"type":"string","example":"1023456789"},"accountName":{"type":"string","example":"Creddot Business Ltd."},"bankName":{"type":"string","example":"Creddot Sandbox Bank"},"provider":{"type":"string","example":"CREDDOT_SANDBOX"},"providerReference":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","environment","currency","accountNumber","accountName","bankName","provider","providerReference","active","createdAt","updatedAt"]},"BusinessOverviewResponse":{"type":"object","properties":{"merchant":{"$ref":"#/components/schemas/MerchantOverviewResponse"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"currency":{"type":"string","example":"NGN"},"revenue":{"$ref":"#/components/schemas/RevenueOverviewResponse"},"balance":{"$ref":"#/components/schemas/DashboardBalanceResponse"},"recentPayments":{"description":"Five most recent collection payments in this environment and currency.","type":"array","items":{"$ref":"#/components/schemas/TransactionResponse"}},"volume":{"$ref":"#/components/schemas/VolumeOverviewResponse"},"paymentBreakdown":{"description":"Always contains SUCCEEDED, PENDING, REFUNDED, and FAILED in that order.","type":"array","items":{"$ref":"#/components/schemas/PaymentBreakdownResponse"}},"wallets":{"type":"array","items":{"$ref":"#/components/schemas/WalletResponse"}},"virtualAccounts":{"type":"array","items":{"$ref":"#/components/schemas/VirtualAccountResponse"}},"recentTransactions":{"type":"array","items":{"$ref":"#/components/schemas/TransactionResponse"}},"recentPayouts":{"type":"array","items":{"$ref":"#/components/schemas/PayoutResponse"}}},"required":["merchant","environment","currency","revenue","balance","recentPayments","volume","paymentBreakdown","wallets","virtualAccounts","recentTransactions","recentPayouts"]},"TransactionHistoryResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TransactionResponse"}},"total":{"type":"number","example":0},"page":{"type":"number","example":1},"pageSize":{"type":"number","example":20}},"required":["items","total","page","pageSize"]},"TransactionDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string","description":"Use this ID for transaction lookup and sandbox completion. Payout id is a separate payout record ID."},"reference":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]},"amountMinor":{"type":"string","example":"100000","description":"Integer minor units, encoded as a string."},"currency":{"type":"string","example":"NGN"},"provider":{"type":"string","example":"PAGA"},"providerReference":{"type":"string","nullable":true},"requiresReconciliation":{"type":"boolean","description":"True when provider outcome is uncertain. Do not retry with a new key; query the transaction or reconcile it."},"feeMinor":{"type":"string","example":"1500","description":"Creddot fee charged to the business in minor units."},"totalDebitMinor":{"type":"string","example":"101500","description":"Wallet debit for payouts; equals amountMinor for incoming transfers."},"netCreditMinor":{"type":"string","example":"98500","description":"Wallet credit for incoming transfers; equals amountMinor for payouts."},"type":{"type":"string","enum":["COLLECTION","PAYOUT","REFUND","REVERSAL","BILL_PAYMENT"]},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"payoutId":{"type":"string","nullable":true},"paymentUrl":{"type":"string","nullable":true,"format":"uri"},"direction":{"type":"string","enum":["MONEY_IN","MONEY_OUT"]},"channel":{"type":"string","nullable":true,"example":"BANK_TRANSFER"},"customerName":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true,"format":"email"},"providerFeeMinor":{"type":"string","example":"5375","description":"Upstream provider fee in minor units."},"feeMethod":{"type":"string","nullable":true},"feeRuleId":{"type":"string","nullable":true},"sender":{"type":"object","properties":{"name":{"type":"string","nullable":true},"bankName":{"type":"string","nullable":true},"accountNumberMasked":{"type":"string","nullable":true}}},"sessionId":{"type":"string","nullable":true,"description":"NIBSS/Paga session identifier when supplied by the provider."},"settlement":{"type":"object","properties":{"status":{"type":"string"},"reference":{"type":"string","nullable":true},"settledAt":{"type":"string","format":"date-time","nullable":true}}},"payout":{"type":"object","nullable":true,"additionalProperties":true},"billPayment":{"type":"object","nullable":true,"additionalProperties":true},"ledgerEntries":{"type":"array","items":{"type":"object"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","transactionId","reference","status","amountMinor","currency","provider","providerReference","requiresReconciliation","feeMinor","totalDebitMinor","netCreditMinor","type","environment","payoutId","paymentUrl","direction","channel","customerName","customerEmail","providerFeeMinor","feeMethod","feeRuleId","sender","sessionId","settlement","payout","billPayment","ledgerEntries","createdAt","updatedAt"]},"WebhookEventResponse":{"type":"object","properties":{"id":{"type":"string"},"eventType":{"type":"string"},"status":{"type":"string","enum":["PENDING","DELIVERED","FAILED"]},"attempts":{"type":"number"},"lastStatusCode":{"type":"number","nullable":true},"lastError":{"type":"string","nullable":true},"lastAttemptAt":{"type":"string","nullable":true,"format":"date-time"},"deliveredAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"payload":{"type":"object","additionalProperties":true}},"required":["id","eventType","status","attempts","lastStatusCode","lastError","lastAttemptAt","deliveredAt","createdAt","payload"]},"ConfigureWebhookEndpointDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"url":{"type":"string","format":"uri","example":"https://merchant.example.com/webhooks/creddot"},"active":{"type":"boolean","default":true}},"required":["environment","url"]},"WebhookEndpointResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"url":{"type":"string","format":"uri"},"active":{"type":"boolean"},"signingSecret":{"type":"string","writeOnly":true,"description":"Returned only when the endpoint is created or replaced. Store it securely."}},"required":["id","environment","url","active","signingSecret"]},"MainAccountWalletResponse":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string","example":"NGN"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"status":{"type":"string","enum":["ACTIVE","FROZEN","CLOSED"]},"availableBalanceMinor":{"type":"string","example":"0","description":"Integer minor units encoded as a string."},"pendingBalanceMinor":{"type":"string","example":"0","description":"Integer minor units encoded as a string."},"reservedBalanceMinor":{"type":"string","example":"0","description":"Funds held for pending payouts, excluded from available balance."}},"required":["id","currency","environment","status","availableBalanceMinor","pendingBalanceMinor","reservedBalanceMinor"]},"MainAccountResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"currency":{"type":"string","example":"NGN"},"wallet":{"$ref":"#/components/schemas/MainAccountWalletResponse"},"collectionAccount":{"nullable":true,"description":"Dedicated collection account in the selected environment and currency. LIVE may be null until provider provisioning completes.","type":"object","allOf":[{"$ref":"#/components/schemas/VirtualAccountResponse"}]},"transactions":{"$ref":"#/components/schemas/TransactionHistoryResponse"}},"required":["environment","currency","wallet","collectionAccount","transactions"]},"PayoutHistoryResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PayoutResponse"}},"total":{"type":"number","example":0},"page":{"type":"number","example":1},"pageSize":{"type":"number","example":20}},"required":["items","total","page","pageSize"]},"PayoutBankResponse":{"type":"object","properties":{"code":{"type":"string","example":"40090E2F-7446-4217-9345-7BBAB7043C4C","description":"Paga bank UUID. Send this as bankCode for validation and payout."},"name":{"type":"string","example":"Access Bank"},"sortCode":{"type":"string","nullable":true,"example":"044"},"interInstitutionCode":{"type":"string","nullable":true,"example":"000014"},"ussdCode":{"type":"string","nullable":true,"example":"901"}},"required":["code","name","sortCode","interInstitutionCode","ussdCode"]},"BusinessValidateRecipientDto":{"type":"object","properties":{"beneficiaryId":{"type":"string","example":"cmbeneficiary123"},"bankCode":{"type":"string","example":"044","description":"Required unless beneficiaryId is set."},"accountNumber":{"type":"string","example":"0123456789","description":"Required unless beneficiaryId is set."},"amountMinor":{"type":"string","example":"100","default":"100"},"currency":{"type":"string","example":"NGN","default":"NGN"}}},"PayoutBeneficiaryResponse":{"type":"object","properties":{"id":{"type":"string"},"bankCode":{"type":"string","example":"40090E2F-7446-4217-9345-7BBAB7043C4C"},"accountNumberMasked":{"type":"string","example":"******6789"},"accountName":{"type":"string","example":"Ada Obi"},"lastPaidAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","bankCode","accountNumberMasked","accountName","lastPaidAt","createdAt"]},"BusinessCreatePayoutDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"example":"SANDBOX"},"transactionPin":{"type":"string","example":"1234","pattern":"^\\d{4}$","writeOnly":true},"amountMinor":{"type":"string","example":"100000"},"currency":{"type":"string","example":"NGN"},"beneficiaryId":{"type":"string","example":"cmbeneficiary123","description":"Saved beneficiary to pay. When set, bankCode and accountNumber are taken from it."},"bankCode":{"type":"string","example":"044","description":"Required unless beneficiaryId is set."},"accountNumber":{"type":"string","example":"0123456789","description":"Required unless beneficiaryId is set."},"accountName":{"type":"string","example":"Ada Merchant"},"reference":{"type":"string","example":"PYT-100001"},"narration":{"type":"string","example":"Vendor settlement"},"saveBeneficiary":{"type":"boolean","default":true,"description":"Save the recipient as a beneficiary once the payout is accepted."}},"required":["environment","transactionPin","amountMinor","currency"]},"TransactionPinStatusResponse":{"type":"object","properties":{"configured":{"type":"boolean"},"lockedUntil":{"type":"string","nullable":true,"format":"date-time"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["configured","lockedUntil","updatedAt"]},"SetTransactionPinDto":{"type":"object","properties":{"currentPin":{"type":"string","example":"1234","pattern":"^\\d{4}$","writeOnly":true,"description":"Required when replacing an existing PIN."},"pin":{"type":"string","example":"4321","pattern":"^\\d{4}$","writeOnly":true},"confirmPin":{"type":"string","example":"4321","pattern":"^\\d{4}$","writeOnly":true}},"required":["pin","confirmPin"]},"ProvisionVirtualAccountDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX","description":"SANDBOX provisions through Paga beta when PAGA_SANDBOX_SIMULATE=false, otherwise it creates a simulated account. LIVE provisions through Paga production for a verified active business."},"currency":{"type":"object","example":"NGN","default":"NGN"}}},"FundSandboxWalletDto":{"type":"object","properties":{"amountMinor":{"type":"string","example":"500000","description":"Positive integer minor units. For NGN, 500000 represents ₦5,000.00."},"reference":{"type":"string","example":"PORTAL-FUND-20261011-001","minLength":1,"maxLength":80,"description":"Client-generated reference. It must be unique within the merchant sandbox."},"description":{"type":"string","example":"QA payout testing","maxLength":160}},"required":["amountMinor","reference"]},"SandboxWalletFundingResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string"},"reference":{"type":"string","example":"PORTAL-FUND-20261011-001"},"status":{"type":"string","enum":["SUCCESS"]},"amountMinor":{"type":"string","example":"500000"},"currency":{"type":"string","example":"NGN"},"availableBalanceMinor":{"type":"string","example":"1500000","description":"Sandbox available balance after this funding operation."},"provider":{"type":"string","example":"CREDDOT_SANDBOX"},"providerReference":{"type":"string","example":"sandbox_portal_PORTAL-FUND-20261011-001"},"requiresReconciliation":{"type":"boolean","example":false}},"required":["id","transactionId","reference","status","amountMinor","currency","availableBalanceMinor","provider","providerReference","requiresReconciliation"]},"BillCatalogItemResponse":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"amountMinor":{"type":"string"},"fixedPrice":{"type":"boolean"},"customerFieldLabel":{"type":"string"},"imageUrl":{"type":"string"}},"required":["code","name"]},"BillCatalogResponse":{"type":"object","properties":{"provider":{"type":"string","enum":["VTPASS","FLUTTERWAVE"]},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/BillCatalogItemResponse"}}},"required":["provider","environment","items"]},"BusinessValidateBillCustomerDto":{"type":"object","properties":{"provider":{"type":"string","enum":["VTPASS","FLUTTERWAVE"],"default":"VTPASS"},"serviceCode":{"type":"string","example":"ikeja-electric","description":"VTpass serviceID or Flutterwave biller_code."},"productCode":{"type":"string","example":"prepaid","description":"VTpass variation/type or Flutterwave item_code."},"customerId":{"type":"string","example":"1111111111111","description":"Meter, smartcard, account, or phone number expected by the selected product."},"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"}},"required":["serviceCode","customerId"]},"BillValidationResponse":{"type":"object","properties":{"provider":{"type":"string","enum":["VTPASS","FLUTTERWAVE"]},"valid":{"type":"boolean"},"customerName":{"type":"string"},"address":{"type":"string"},"minimumAmountMinor":{"type":"string"},"maximumAmountMinor":{"type":"string"},"message":{"type":"string"}},"required":["provider","valid"]},"BusinessCreateBillPaymentDto":{"type":"object","properties":{"provider":{"type":"string","enum":["VTPASS","FLUTTERWAVE"],"default":"VTPASS"},"serviceCode":{"type":"string","example":"ikeja-electric","description":"VTpass serviceID or Flutterwave biller_code."},"productCode":{"type":"string","example":"prepaid","description":"VTpass variation/type or Flutterwave item_code."},"customerId":{"type":"string","example":"1111111111111","description":"Meter, smartcard, account, or phone number expected by the selected product."},"category":{"type":"string","enum":["AIRTIME","DATA","ELECTRICITY","TV","INTERNET","OTHER"],"example":"ELECTRICITY"},"amountMinor":{"type":"string","example":"500000","description":"Positive integer minor units. 500000 means NGN 5,000.00."},"currency":{"type":"string","example":"NGN","default":"NGN"},"phoneNumber":{"type":"string","example":"+2348012345678"},"reference":{"type":"string","example":"BILL-20261011-001","minLength":1,"maxLength":80},"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"transactionPin":{"type":"string","example":"1234","pattern":"^\\d{4}$","writeOnly":true,"description":"The signed-in member's transaction PIN, as for Send Money."}},"required":["serviceCode","customerId","category","amountMinor","phoneNumber","transactionPin"]},"BillPaymentResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string"},"reference":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]},"amountMinor":{"type":"string"},"currency":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"provider":{"type":"string","enum":["VTPASS","FLUTTERWAVE"]},"category":{"type":"string"},"serviceCode":{"type":"string"},"productCode":{"type":"object"},"customerIdMasked":{"type":"string"},"providerReference":{"type":"object"},"token":{"type":"object","description":"Electricity/recharge token when supplied by the provider. Returned on the first successful response and authenticated detail reads."},"requiresReconciliation":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","transactionId","reference","status","amountMinor","currency","environment","provider","category","serviceCode","customerIdMasked","requiresReconciliation","createdAt","updatedAt"]},"BillPaymentHistoryResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BillPaymentResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]},"SaveKycBusinessDto":{"type":"object","properties":{"companyType":{"type":"string","enum":["RC","BN","IT","LP","LLP"],"example":"RC","description":"Nigeria CAC entity type. RC represents a limited liability company; BN a business name; IT an incorporated trustee."},"registrationNumber":{"type":"string","example":"1234567","minLength":2,"maxLength":30,"description":"CAC registration number without the company type prefix when entered separately."},"registeredCompanyName":{"type":"string","example":"Acme Limited","minLength":2,"maxLength":160},"industry":{"type":"string","example":"Healthcare","minLength":2,"maxLength":100},"countryOfRegistration":{"type":"string","example":"NG","enum":["NG"],"description":"ISO 3166-1 alpha-2 country code. Nigeria CAC verification is currently supported."}},"required":["companyType","registrationNumber","registeredCompanyName","industry","countryOfRegistration"]},"KycVerificationResponse":{"type":"object","properties":{"status":{"type":"string","enum":["VERIFIED","REJECTED","REQUIRES_UPDATE"]},"provider":{"type":"string","example":"PREMBLY"},"providerEnvironment":{"type":"string","enum":["SANDBOX","LIVE"]},"reference":{"type":"string","nullable":true},"message":{"type":"string"},"checkedAt":{"type":"string","format":"date-time"},"confidence":{"type":"number","nullable":true,"example":99.7,"description":"Provider face-match confidence when this verification includes facial comparison."}},"required":["status","provider","providerEnvironment","reference","message","checkedAt"]},"KycDirectorSuggestionResponse":{"type":"object","properties":{"fullName":{"type":"string","example":"Jane Adaeze Okafor"},"role":{"type":"string","nullable":true,"example":"DIRECTOR"}},"required":["fullName","role"]},"DirectorDto":{"type":"object","properties":{"fullName":{"type":"string","example":"Ada Okafor","minLength":2,"maxLength":120},"phoneNumber":{"type":"string","example":"+2349155550100","pattern":"^\\+[1-9]\\d{7,14}$"},"email":{"type":"string","example":"jane@acme.co","format":"email","maxLength":191},"role":{"type":"string","example":"Managing Director","minLength":2,"maxLength":80}},"required":["fullName","phoneNumber","email"]},"KycDocumentResponse":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["CAC","MEMART","UTILITY_BILL","VALID_ID"]},"filename":{"type":"string"},"mimeType":{"type":"string","enum":["application/pdf","image/jpeg","image/png"]},"sizeBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time","description":"Changes when a document is replaced."}},"required":["id","kind","filename","mimeType","sizeBytes","createdAt","updatedAt"]},"KycDocumentRequirementResponse":{"type":"object","properties":{"kind":{"type":"string","enum":["CAC","MEMART","UTILITY_BILL","VALID_ID"]},"label":{"type":"string"},"required":{"type":"boolean"},"uploaded":{"type":"boolean"}},"required":["kind","label","required","uploaded"]},"KycStepResponse":{"type":"object","properties":{"id":{"type":"string","enum":["BUSINESS","DOCUMENTS","DIRECTOR","PREVIEW"]},"status":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","COMPLETE","READY","BLOCKED"]}},"required":["id","status"]},"KycResponse":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_STARTED","PENDING","VERIFIED","REJECTED","REQUIRES_UPDATE"]},"statusLabel":{"type":"string","example":"KYC Pending"},"rejectionReason":{"type":"string","nullable":true},"business":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/SaveKycBusinessDto"}]},"businessVerification":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/KycVerificationResponse"}]},"directorSuggestions":{"description":"Safe name/role options returned by verified CAC data for the director selector. May be empty.","type":"array","items":{"$ref":"#/components/schemas/KycDirectorSuggestionResponse"}},"bvnProvided":{"type":"boolean"},"bvnMasked":{"type":"string","nullable":true,"example":"*******8901"},"bvnVerification":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/KycVerificationResponse"}]},"facialVerification":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/KycVerificationResponse"}]},"authorizedRepresentativeEmail":{"type":"string","nullable":true,"format":"email","description":"Email of the saved director whose BVN and face were verified."},"directors":{"type":"array","items":{"$ref":"#/components/schemas/DirectorDto"}},"submittedAt":{"type":"string","format":"date-time","nullable":true},"documents":{"type":"array","items":{"$ref":"#/components/schemas/KycDocumentResponse"}},"documentRequirements":{"type":"array","items":{"$ref":"#/components/schemas/KycDocumentRequirementResponse"}},"steps":{"description":"Four stable steps for the business KYC UI.","type":"array","items":{"$ref":"#/components/schemas/KycStepResponse"}},"missingRequirements":{"example":["CAC_VERIFICATION","BVN_VERIFICATION","FACIAL_VERIFICATION","MEMART"],"type":"array","items":{"type":"string"}},"canSubmit":{"type":"boolean","description":"True only when every submit requirement is complete and KYC is still editable."},"editable":{"type":"boolean","description":"False when under review or verified."}},"required":["status","statusLabel","rejectionReason","business","businessVerification","directorSuggestions","bvnProvided","bvnMasked","bvnVerification","facialVerification","authorizedRepresentativeEmail","directors","submittedAt","documents","documentRequirements","steps","missingRequirements","canSubmit","editable"]},"SaveKycDraftDto":{"type":"object","properties":{"bvn":{"type":"string","example":"12345678901","pattern":"^\\d{11}$","description":"Encrypted at rest; responses expose only the last four digits. Omit to retain the existing BVN.","writeOnly":true},"directors":{"maxItems":20,"description":"Replaces the draft director list. At least one director is required when submitting.","type":"array","items":{"$ref":"#/components/schemas/DirectorDto"}}}},"VerifyBvnDto":{"type":"object","properties":{"bvn":{"type":"string","example":"12345678901","pattern":"^\\d{11}$","writeOnly":true,"description":"The authorized representative BVN. It is encrypted at rest and never returned unmasked."},"consent":{"type":"boolean","example":true,"description":"Must be true to confirm that the BVN owner consented to this identity verification."}},"required":["bvn","consent"]},"VerifyDirectorIdentityDto":{"type":"object","properties":{"directorEmail":{"type":"string","example":"jane@acme.co","format":"email","description":"Identifies the saved director whose BVN and face are being verified."},"bvn":{"type":"string","example":"12345678901","pattern":"^\\d{11}$","writeOnly":true,"description":"The selected director BVN. It is encrypted at rest and only returned in masked form."},"selfieMimeType":{"type":"string","enum":["image/jpeg","image/png"],"example":"image/jpeg"},"selfieImageBase64":{"type":"string","format":"byte","writeOnly":true,"description":"A fresh camera image encoded as base64, without a data-URL prefix. Maximum decoded size is 5 MB. The image is sent to Prembly and is not stored as a KYC draft field."},"consent":{"type":"boolean","example":true,"description":"Must be true to confirm the director consented to BVN and facial verification."}},"required":["directorEmail","bvn","selfieMimeType","selfieImageBase64","consent"]},"SaveKycDirectorsDto":{"type":"object","properties":{"directors":{"minItems":1,"maxItems":20,"description":"The current directors or controlling persons for the business.","type":"array","items":{"$ref":"#/components/schemas/DirectorDto"}}},"required":["directors"]},"UploadKycDocumentDto":{"type":"object","properties":{"kind":{"type":"string","enum":["CAC","MEMART","UTILITY_BILL","VALID_ID"],"example":"CAC"},"filename":{"type":"string","example":"cac-certificate.pdf","maxLength":150},"mimeType":{"type":"string","enum":["application/pdf","image/jpeg","image/png"]},"contentBase64":{"type":"string","format":"byte","description":"Base64-encoded PDF, JPEG, or PNG; decoded size at most 10 MB. No data-URL prefix. Uploading the same kind replaces its draft document."}},"required":["kind","filename","mimeType","contentBase64"]},"KycDocumentDownloadResponse":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Short-lived private Cloudflare R2 download URL."},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","expiresAt"]},"SimulateVirtualTransferDto":{"type":"object","properties":{"amountMinor":{"type":"string","example":"500000","description":"Positive integer minor units. For NGN, 500000 represents ₦5,000.00."},"reference":{"type":"string","example":"BANK-TRANSFER-20260919-001","minLength":1,"maxLength":80,"description":"External transfer reference. Unique per business environment across collections and payouts."},"senderName":{"type":"string","example":"Ada Okafor","maxLength":120,"description":"Displayed only in the recorded provider response; do not send sensitive bank data."}},"required":["amountMinor","reference"]},"ValidateBillCustomerDto":{"type":"object","properties":{"provider":{"type":"string","enum":["VTPASS","FLUTTERWAVE"],"default":"VTPASS"},"serviceCode":{"type":"string","example":"ikeja-electric","description":"VTpass serviceID or Flutterwave biller_code."},"productCode":{"type":"string","example":"prepaid","description":"VTpass variation/type or Flutterwave item_code."},"customerId":{"type":"string","example":"1111111111111","description":"Meter, smartcard, account, or phone number expected by the selected product."}},"required":["serviceCode","customerId"]},"CreateBillPaymentDto":{"type":"object","properties":{"provider":{"type":"string","enum":["VTPASS","FLUTTERWAVE"],"default":"VTPASS"},"serviceCode":{"type":"string","example":"ikeja-electric","description":"VTpass serviceID or Flutterwave biller_code."},"productCode":{"type":"string","example":"prepaid","description":"VTpass variation/type or Flutterwave item_code."},"customerId":{"type":"string","example":"1111111111111","description":"Meter, smartcard, account, or phone number expected by the selected product."},"category":{"type":"string","enum":["AIRTIME","DATA","ELECTRICITY","TV","INTERNET","OTHER"],"example":"ELECTRICITY"},"amountMinor":{"type":"string","example":"500000","description":"Positive integer minor units. 500000 means NGN 5,000.00."},"currency":{"type":"string","example":"NGN","default":"NGN"},"phoneNumber":{"type":"string","example":"+2348012345678"},"reference":{"type":"string","example":"BILL-20261011-001","minLength":1,"maxLength":80}},"required":["serviceCode","customerId","category","amountMinor","phoneNumber"]},"CompleteSandboxTransactionDto":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCESS","FAILED"],"example":"SUCCESS"}},"required":["status"]},"CheckoutPaymentStatusResponse":{"type":"object","properties":{"reference":{"type":"string","example":"pl_cmv7uxfry000mnz074ljtuh7e_6dc9360a-c028-421d-a176-8559dc56b9f2"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]},"amountMinor":{"type":"string","example":"10000","description":"Integer minor units encoded as a string."},"currency":{"type":"string","example":"NGN"},"channel":{"type":"string","enum":["BANK_TRANSFER","CARD","USSD","QR"],"nullable":true},"merchantName":{"type":"string"},"paidAt":{"type":"string","format":"date-time","nullable":true},"failureReason":{"type":"string","nullable":true},"redirectUrl":{"type":"string","format":"uri","nullable":true},"kind":{"type":"string","enum":["PAYMENT_LINK","EVENT","SPLIT_PAY","STOREFRONT","SUBSCRIPTION"]},"orderCode":{"type":"string","nullable":true,"description":"Event ticket or storefront order code. Null for Pay Links and Split Pay."}},"required":["reference","status","amountMinor","currency","channel","merchantName","paidAt","failureReason","redirectUrl","kind","orderCode"]},"PaymentLinkCustomerFieldsDto":{"type":"object","properties":{"customerName":{"type":"boolean","default":false},"customerEmail":{"type":"boolean","default":true,"description":"Collect payer email. Defaults to true when neither email nor phone is selected because Paga requires one payer identifier."},"customerPhone":{"type":"boolean","default":false,"description":"Collect payer phone. At least email or phone is required by Paga."},"billingAddress":{"type":"boolean","default":false},"deliveryAddress":{"type":"boolean","default":false}}},"PaymentLinkAllowedCustomerDto":{"type":"object","properties":{"fullName":{"type":"string","maxLength":120},"email":{"type":"string","format":"email"},"phoneNumber":{"type":"string","example":"+2348012345678"}}},"CreatePaymentLinkDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX","description":"Creates the link in the selected isolated environment. Live use requires an active, KYC-approved business."},"amountMinor":{"type":"string","example":"500000","description":"Maximum amount for each payment in positive integer minor units. The Pay Link remains reusable while active. Omit to let each payer enter any positive amount."},"currency":{"type":"object","example":"NGN","default":"NGN"},"pageName":{"type":"string","example":"Meat Supplies","maxLength":160,"description":"Name displayed on the Pay Link. Existing clients may continue sending description instead."},"description":{"type":"string","example":"September design retainer","maxLength":160},"linkNumber":{"type":"string","example":"LNK-0003","maxLength":80,"description":"Merchant-facing link number. Omit to generate the next LNK number."},"visibility":{"type":"string","enum":["PUBLIC","PRIVATE"],"default":"PUBLIC"},"imageFileId":{"type":"string","description":"READY image/jpeg or image/png file uploaded through the business file endpoints."},"customerFields":{"$ref":"#/components/schemas/PaymentLinkCustomerFieldsDto"},"customers":{"maxItems":100,"description":"Allowed recipients for a PRIVATE Pay Link. Each entry needs an email address or phone number.","type":"array","items":{"$ref":"#/components/schemas/PaymentLinkAllowedCustomerDto"}},"customerName":{"type":"string","example":"Ada Okafor","maxLength":120},"customerEmail":{"type":"string","example":"ada@example.com","format":"email"},"redirectUrl":{"type":"string","example":"https://merchant.example/thank-you","description":"Optional HTTPS destination returned by the public payment-status endpoint after a successful payment."},"reference":{"type":"string","example":"INV-2026-001","maxLength":80},"expiresAt":{"format":"date-time","type":"string","example":"2026-12-31T23:59:59.000Z","description":"Must be in the future. Omit for no expiry."}}},"PaymentLinkCustomerFieldsResponse":{"type":"object","properties":{"customerName":{"type":"boolean"},"customerEmail":{"type":"boolean"},"customerPhone":{"type":"boolean"},"billingAddress":{"type":"boolean"},"deliveryAddress":{"type":"boolean"}},"required":["customerName","customerEmail","customerPhone","billingAddress","deliveryAddress"]},"PaymentLinkAllowedCustomerResponse":{"type":"object","properties":{"fullName":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"phoneNumber":{"type":"string","nullable":true}},"required":["fullName","email","phoneNumber"]},"PaymentLinkProgressResponse":{"type":"object","properties":{"collectedAmountMinor":{"type":"string","example":"2000000"},"pendingAmountMinor":{"type":"string","nullable":true,"example":"1200000","description":"Null for an open-amount link."},"totalAmountMinor":{"type":"string","nullable":true,"example":"3200000"},"percentageCompleted":{"type":"number","nullable":true,"example":62.5},"paymentStatus":{"type":"string","enum":["UNPAID","PARTIALLY_PAID","PAID"]},"successfulPayments":{"type":"number"}},"required":["collectedAmountMinor","pendingAmountMinor","totalAmountMinor","percentageCompleted","paymentStatus","successfulPayments"]},"PaymentLinkResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"slug":{"type":"string","example":"cpl_abc123"},"status":{"type":"string","enum":["ACTIVE","DISABLED","EXPIRED"]},"amountMinor":{"type":"string","nullable":true,"example":"500000","description":"Null means the payer chooses an amount."},"currency":{"type":"string","example":"NGN"},"description":{"type":"string"},"pageName":{"type":"string"},"linkNumber":{"type":"string"},"payCode":{"type":"string"},"visibility":{"type":"string","enum":["PUBLIC","PRIVATE"]},"imageFileId":{"type":"string","nullable":true},"customerFields":{"$ref":"#/components/schemas/PaymentLinkCustomerFieldsResponse"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLinkAllowedCustomerResponse"}},"progress":{"$ref":"#/components/schemas/PaymentLinkProgressResponse"},"reusable":{"type":"boolean","description":"True for standard Pay Links, which accept unlimited payments until disabled or expired. Invoice links are single-use."},"customerName":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true,"format":"uri"},"reference":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"viewedAt":{"type":"string","format":"date-time","nullable":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkoutPath":{"type":"string","example":"/api/v1/checkout/payment-links/cpl_abc123","description":"Public checkout metadata endpoint. A hosted payment page is not included in this backend."}},"required":["id","environment","slug","status","amountMinor","currency","description","pageName","linkNumber","payCode","visibility","imageFileId","customerFields","customers","progress","reusable","customerName","customerEmail","redirectUrl","reference","expiresAt","viewedAt","disabledAt","createdAt","updatedAt","checkoutPath"]},"PaymentLinkBusinessResponse":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["name","email"]},"PaymentLinkRecentActivityResponse":{"type":"object","properties":{"transactionId":{"type":"string"},"customerName":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true,"format":"email"},"amountMinor":{"type":"string","example":"1200000"},"paidAt":{"type":"string","format":"date-time"},"offline":{"type":"boolean","description":"True when the business recorded money received outside Creddot."}},"required":["transactionId","customerName","customerEmail","amountMinor","paidAt","offline"]},"PaymentLinkDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"slug":{"type":"string","example":"cpl_abc123"},"status":{"type":"string","enum":["ACTIVE","DISABLED","EXPIRED"]},"amountMinor":{"type":"string","nullable":true,"example":"500000","description":"Null means the payer chooses an amount."},"currency":{"type":"string","example":"NGN"},"description":{"type":"string"},"pageName":{"type":"string"},"linkNumber":{"type":"string"},"payCode":{"type":"string"},"visibility":{"type":"string","enum":["PUBLIC","PRIVATE"]},"imageFileId":{"type":"string","nullable":true},"customerFields":{"$ref":"#/components/schemas/PaymentLinkCustomerFieldsResponse"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLinkAllowedCustomerResponse"}},"progress":{"$ref":"#/components/schemas/PaymentLinkProgressResponse"},"reusable":{"type":"boolean","description":"True for standard Pay Links, which accept unlimited payments until disabled or expired. Invoice links are single-use."},"customerName":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true,"format":"uri"},"reference":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"viewedAt":{"type":"string","format":"date-time","nullable":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkoutPath":{"type":"string","example":"/api/v1/checkout/payment-links/cpl_abc123","description":"Public checkout metadata endpoint. A hosted payment page is not included in this backend."},"business":{"$ref":"#/components/schemas/PaymentLinkBusinessResponse"},"imageUrl":{"type":"string","nullable":true,"format":"uri"},"imageUrlExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"recentActivity":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLinkRecentActivityResponse"}}},"required":["id","environment","slug","status","amountMinor","currency","description","pageName","linkNumber","payCode","visibility","imageFileId","customerFields","customers","progress","reusable","customerName","customerEmail","redirectUrl","reference","expiresAt","viewedAt","disabledAt","createdAt","updatedAt","checkoutPath","business","imageUrl","imageUrlExpiresAt","recentActivity"]},"UpdatePaymentLinkDto":{"type":"object","properties":{"pageName":{"type":"string","example":"Meat Supplies","maxLength":160},"description":{"type":"string","example":"September design retainer","maxLength":160},"amountMinor":{"type":"string","nullable":true,"example":"500000","description":"Positive integer minor units, or null to make this an open-amount link."},"visibility":{"type":"string","enum":["PUBLIC","PRIVATE"]},"customers":{"maxItems":100,"description":"Replaces the complete private-customer allowlist.","type":"array","items":{"$ref":"#/components/schemas/PaymentLinkAllowedCustomerDto"}},"customerFields":{"$ref":"#/components/schemas/PaymentLinkCustomerFieldsDto"},"customerName":{"type":"string","nullable":true,"maxLength":120},"customerEmail":{"type":"string","nullable":true,"format":"email"},"imageFileId":{"type":"string","nullable":true,"description":"READY PNG/JPEG in the same environment; null removes the image."},"redirectUrl":{"type":"string","nullable":true,"example":"https://merchant.example/thank-you"},"reference":{"type":"string","maxLength":80},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"A future date-time, or null to remove the expiry."}}},"RecordOfflinePaymentDto":{"type":"object","properties":{"amountMinor":{"type":"string","example":"3200000","description":"Defaults to the remaining target amount. Required for open-amount links."},"customerName":{"type":"string","maxLength":120},"customerEmail":{"type":"string","format":"email"},"note":{"type":"string","example":"Paid cash at the shop","maxLength":500},"paidAt":{"format":"date-time","type":"string","description":"Defaults to now and cannot be in the future."}}},"PublicPaymentLinkResponse":{"type":"object","properties":{"merchantName":{"type":"string","example":"Ada Commerce Limited"},"amountMinor":{"type":"string","nullable":true,"example":"500000"},"currency":{"type":"string","example":"NGN"},"description":{"type":"string"},"pageName":{"type":"string"},"payCode":{"type":"string"},"visibility":{"type":"string","enum":["PUBLIC","PRIVATE"]},"customerFields":{"$ref":"#/components/schemas/PaymentLinkCustomerFieldsResponse"},"imageUrl":{"type":"string","nullable":true,"format":"uri"},"imageUrlExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"progress":{"description":"For reusable links this represents a fresh checkout attempt and remains UNPAID; lifetime totals remain available on authenticated business endpoints.","allOf":[{"$ref":"#/components/schemas/PaymentLinkProgressResponse"}]},"reusable":{"type":"boolean","description":"When true, the link accepts unlimited payment attempts until disabled or expired."},"redirectUrl":{"type":"string","nullable":true,"format":"uri","description":"Optional destination returned by the payment-status endpoint after successful payment."},"reference":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["ACTIVE","DISABLED","EXPIRED"]}},"required":["merchantName","amountMinor","currency","description","pageName","payCode","visibility","customerFields","imageUrl","imageUrlExpiresAt","progress","reusable","redirectUrl","reference","expiresAt","status"]},"CheckoutMethodResponse":{"type":"object","properties":{"id":{"type":"string","enum":["CREDDOT","CARD","TRANSFER","BANK","USSD","SPLIT","STABLECOIN"]},"label":{"type":"string"},"availability":{"type":"string","enum":["AVAILABLE","UNAVAILABLE"]},"provider":{"type":"string","nullable":true},"channel":{"type":"string","nullable":true,"enum":["BANK_TRANSFER","CARD","USSD","QR"]},"description":{"type":"string"}},"required":["id","label","availability","provider","channel","description"]},"CheckoutMethodsResponse":{"type":"object","properties":{"merchantName":{"type":"string","example":"Ada Commerce Limited"},"amountMinor":{"type":"string","nullable":true,"example":"500000"},"currency":{"type":"string","example":"NGN"},"description":{"type":"string"},"pageName":{"type":"string"},"payCode":{"type":"string"},"visibility":{"type":"string","enum":["PUBLIC","PRIVATE"]},"customerFields":{"$ref":"#/components/schemas/PaymentLinkCustomerFieldsResponse"},"imageUrl":{"type":"string","nullable":true,"format":"uri"},"imageUrlExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"progress":{"description":"For reusable links this represents a fresh checkout attempt and remains UNPAID; lifetime totals remain available on authenticated business endpoints.","allOf":[{"$ref":"#/components/schemas/PaymentLinkProgressResponse"}]},"reusable":{"type":"boolean","description":"When true, the link accepts unlimited payment attempts until disabled or expired."},"redirectUrl":{"type":"string","nullable":true,"format":"uri","description":"Optional destination returned by the payment-status endpoint after successful payment."},"reference":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["ACTIVE","DISABLED","EXPIRED"]},"methods":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutMethodResponse"}},"supportedBanks":{"type":"array","description":"Paga Collect banks. Send id as bankCode for USSD; id is a Paga UUID, not the bank sort code.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ussdCode":{"type":"string","nullable":true}}}}},"required":["merchantName","amountMinor","currency","description","pageName","payCode","visibility","customerFields","imageUrl","imageUrlExpiresAt","progress","reusable","redirectUrl","reference","expiresAt","status","methods","supportedBanks"]},"CheckoutAddressDto":{"type":"object","properties":{"addressLine1":{"type":"string","maxLength":191},"addressLine2":{"type":"string","maxLength":191},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","example":"NG"}},"required":["addressLine1","state","postalCode","countryCode"]},"CardPaymentDto":{"type":"object","properties":{"number":{"type":"string","example":"4000000000000009","writeOnly":true},"cvv":{"type":"string","example":"130","writeOnly":true},"expiryMonth":{"type":"string","example":"02","writeOnly":true},"expiryYear":{"type":"string","example":"29","description":"Two-digit expiry year.","writeOnly":true},"pin":{"type":"string","example":"1234","description":"Required by Cashonrails for local NGN cards.","writeOnly":true}},"required":["number","cvv","expiryMonth","expiryYear","pin"]},"PayPaymentLinkDto":{"type":"object","properties":{"channel":{"type":"string","enum":["BANK_TRANSFER","CARD","USSD","QR"],"example":"BANK_TRANSFER"},"amountMinor":{"type":"string","example":"1200000","description":"Payment in positive integer minor units. Required for an open-amount link; optional for a configured-amount link. It cannot exceed the configured amount."},"customerName":{"type":"string","example":"Ada Okafor","maxLength":120},"customerEmail":{"type":"string","example":"payer@example.com","format":"email","description":"Required when customerPhone is omitted."},"customerPhone":{"type":"string","example":"+2348012345678","description":"Required when customerEmail is omitted."},"billingAddress":{"$ref":"#/components/schemas/CheckoutAddressDto"},"deliveryAddress":{"$ref":"#/components/schemas/CheckoutAddressDto"},"bankCode":{"type":"string","example":"3E94C4BC-6F9A-442F-8F1A-8214478D5D86","description":"Required for USSD payments. Use supportedBanks[].id from GET /api/v1/checkout/payment-links/{slug}/methods. This is a Paga bank UUID, not a sort code such as 058."},"card":{"description":"Required when channel is CARD. Sent only to Cashonrails after server-side encryption.","allOf":[{"$ref":"#/components/schemas/CardPaymentDto"}]}},"required":["channel"]},"PaymentLinkPaymentResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]},"reference":{"type":"string"},"amountMinor":{"type":"string","example":"500000"},"currency":{"type":"string","example":"NGN"},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"paymentUrl":{"type":"string","nullable":true,"format":"uri"},"paymentInstructions":{"type":"object","nullable":true,"example":{"type":"CARD_3DS","authenticationUrl":"https://api.cashonrails.com/auth-payer/example","authenticationMethod":"GET"},"description":"Method-specific checkout data. BANK_TRANSFER returns Paga account details; USSD returns a code; CARD returns Cashonrails 3DS authentication data; QR returns a Paga app link."},"requiresReconciliation":{"type":"boolean"},"feeMinor":{"type":"string","example":"1500"},"totalDebitMinor":{"type":"string","example":"100000"},"netCreditMinor":{"type":"string","example":"98500"}},"required":["id","transactionId","status","reference","amountMinor","currency","provider","providerReference","paymentUrl","paymentInstructions","requiresReconciliation","feeMinor","totalDebitMinor","netCreditMinor"]},"CreateHostedCheckoutDto":{"type":"object","properties":{"amountMinor":{"type":"string","example":"125000","description":"Amount in positive integer minor units."},"currency":{"type":"string","example":"NGN"},"reference":{"type":"string","example":"ORDER-10042","maxLength":80,"description":"Your unique reference for this checkout."},"description":{"type":"string","example":"Order 10042","maxLength":160},"customerName":{"type":"string","example":"Ada Okafor","maxLength":120},"customerEmail":{"type":"string","example":"ada@example.com"},"redirectUrl":{"type":"string","example":"https://merchant.example.com/orders/10042/complete","description":"HTTPS destination returned after successful payment."},"expiresAt":{"format":"date-time","type":"string","description":"Defaults to 30 minutes from creation."}},"required":["amountMinor","currency","reference"]},"HostedCheckoutResponse":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"amountMinor":{"type":"string"},"currency":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"},"checkoutPath":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","reference","amountMinor","currency","checkoutUrl","checkoutPath","expiresAt"]},"HostedCheckoutPaymentResponse":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string","description":"Creddot transaction reference (pl_...). Your reference is on the session."},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]},"channel":{"type":"string","nullable":true},"amountMinor":{"type":"string"},"feeMinor":{"type":"string"},"currency":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","reference","status","channel","amountMinor","feeMinor","currency","createdAt"]},"HostedCheckoutStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"amountMinor":{"type":"string"},"currency":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"},"checkoutPath":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["OPEN","PAID","EXPIRED","CLOSED"],"description":"OPEN: awaiting payment. PAID: a payment succeeded (the session is then closed to further payments). EXPIRED: past expiresAt without payment. CLOSED: disabled without payment."},"paidAt":{"type":"string","nullable":true,"format":"date-time"},"payment":{"nullable":true,"description":"The successful payment, otherwise the latest attempt.","type":"object","allOf":[{"$ref":"#/components/schemas/HostedCheckoutPaymentResponse"}]},"attempts":{"type":"number","description":"Payment attempts on this session."}},"required":["id","reference","amountMinor","currency","checkoutUrl","checkoutPath","expiresAt","status","paidAt","payment","attempts"]},"CreateMerchantPaymentLinkDto":{"type":"object","properties":{"amountMinor":{"type":"string","example":"500000","description":"Maximum amount for each payment in positive integer minor units. The Pay Link remains reusable while active. Omit to let each payer enter any positive amount."},"currency":{"type":"object","example":"NGN","default":"NGN"},"pageName":{"type":"string","example":"Meat Supplies","maxLength":160,"description":"Name displayed on the Pay Link. Existing clients may continue sending description instead."},"description":{"type":"string","example":"September design retainer","maxLength":160},"linkNumber":{"type":"string","example":"LNK-0003","maxLength":80,"description":"Merchant-facing link number. Omit to generate the next LNK number."},"visibility":{"type":"string","enum":["PUBLIC","PRIVATE"],"default":"PUBLIC"},"imageFileId":{"type":"string","description":"READY image/jpeg or image/png file uploaded through the business file endpoints."},"customerFields":{"$ref":"#/components/schemas/PaymentLinkCustomerFieldsDto"},"customers":{"maxItems":100,"description":"Allowed recipients for a PRIVATE Pay Link. Each entry needs an email address or phone number.","type":"array","items":{"$ref":"#/components/schemas/PaymentLinkAllowedCustomerDto"}},"customerName":{"type":"string","example":"Ada Okafor","maxLength":120},"customerEmail":{"type":"string","example":"ada@example.com","format":"email"},"redirectUrl":{"type":"string","example":"https://merchant.example/thank-you","description":"Optional HTTPS destination returned by the public payment-status endpoint after a successful payment."},"reference":{"type":"string","example":"INV-2026-001","maxLength":80},"expiresAt":{"format":"date-time","type":"string","example":"2026-12-31T23:59:59.000Z","description":"Must be in the future. Omit for no expiry."}}},"InvoiceBillingAddressDto":{"type":"object","properties":{"addressLine1":{"type":"string","example":"18 Admiralty Way","minLength":2,"maxLength":191},"addressLine2":{"type":"string","example":"Suite 5","maxLength":191},"city":{"type":"string","example":"Lagos","maxLength":100},"state":{"type":"string","example":"Lagos","minLength":1,"maxLength":100,"description":"State, province, or region."},"postalCode":{"type":"string","example":"101001","minLength":2,"maxLength":20,"description":"ZIP or postal code."},"countryCode":{"type":"string","example":"NG","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code."}},"required":["addressLine1","state","postalCode","countryCode"]},"CreateInvoiceItemDto":{"type":"object","properties":{"description":{"type":"string","example":"Product design retainer","maxLength":191},"quantity":{"type":"number","example":2,"minimum":1,"maximum":1000000},"unitAmountMinor":{"type":"string","example":"250000","description":"Positive integer minor units per item."}},"required":["description","quantity","unitAmountMinor"]},"CreateInvoiceDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX","description":"Live invoices can be configured, but payment processing stays unavailable until a live provider is connected."},"invoiceNumber":{"type":"string","example":"INV-2026-001","maxLength":80,"description":"Unique within this business and environment."},"customerName":{"type":"string","example":"Ada Okafor","maxLength":120},"customerEmail":{"type":"string","example":"ada@example.com","format":"email"},"customerPhoneNumber":{"type":"string","example":"+2348012345678","nullable":true,"description":"Customer phone number in international E.164 format."},"billingAddress":{"nullable":true,"description":"Optional customer billing address printed on the invoice.","type":"object","allOf":[{"$ref":"#/components/schemas/InvoiceBillingAddressDto"}]},"currency":{"type":"string","example":"NGN","default":"NGN"},"items":{"minItems":1,"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/CreateInvoiceItemDto"}},"taxMinor":{"type":"string","example":"37500","default":"0","description":"Non-negative integer minor units."},"discountMinor":{"type":"string","example":"0","default":"0","description":"Non-negative integer minor units. Cannot exceed subtotal plus tax."},"dueAt":{"format":"date-time","type":"string","example":"2026-12-31T23:59:59.000Z","description":"Optional payment due date. It must be in the future."},"description":{"type":"string","example":"Thank you for your business.","maxLength":5000}},"required":["invoiceNumber","customerName","customerEmail","items"]},"InvoiceBillingAddressResponse":{"type":"object","properties":{"addressLine1":{"type":"string"},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string"},"postalCode":{"type":"string","description":"ZIP or postal code."},"countryCode":{"type":"string","example":"NG"}},"required":["addressLine1","addressLine2","city","state","postalCode","countryCode"]},"InvoiceBusinessAddressResponse":{"type":"object","properties":{"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true,"description":"ZIP or postal code."},"countryCode":{"type":"string","example":"NG"}},"required":["addressLine1","addressLine2","city","state","postalCode","countryCode"]},"InvoiceIssuerResponse":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"$ref":"#/components/schemas/InvoiceBusinessAddressResponse"}},"required":["name","email","address"]},"InvoicePaymentLinkResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","DISABLED","EXPIRED"]},"checkoutPath":{"type":"string"}},"required":["id","slug","status","checkoutPath"]},"InvoiceItemResponse":{"type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"unitAmountMinor":{"type":"string","example":"250000"},"totalAmountMinor":{"type":"string","example":"500000"}},"required":["id","description","quantity","unitAmountMinor","totalAmountMinor"]},"InvoiceResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"invoiceNumber":{"type":"string"},"status":{"type":"string","enum":["DRAFT","SENT","VIEWED","PAID","OVERDUE"]},"customerName":{"type":"string"},"customerEmail":{"type":"string","format":"email"},"customerPhoneNumber":{"type":"string","nullable":true,"example":"+2348012345678"},"billingAddress":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/InvoiceBillingAddressResponse"}]},"issuer":{"description":"Immutable business identity and address captured when the invoice was created.","allOf":[{"$ref":"#/components/schemas/InvoiceIssuerResponse"}]},"currency":{"type":"string"},"subtotalMinor":{"type":"string","example":"500000"},"taxMinor":{"type":"string","example":"37500"},"discountMinor":{"type":"string","example":"0"},"totalMinor":{"type":"string","example":"537500"},"description":{"type":"string","nullable":true},"dueAt":{"type":"string","format":"date-time","nullable":true},"sentAt":{"type":"string","format":"date-time","nullable":true},"paidAt":{"type":"string","format":"date-time","nullable":true},"paymentLink":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/InvoicePaymentLinkResponse"}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponse"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","environment","invoiceNumber","status","customerName","customerEmail","customerPhoneNumber","billingAddress","issuer","currency","subtotalMinor","taxMinor","discountMinor","totalMinor","description","dueAt","sentAt","paidAt","paymentLink","items","createdAt","updatedAt"]},"CreateMerchantInvoiceDto":{"type":"object","properties":{"invoiceNumber":{"type":"string","example":"INV-2026-001","maxLength":80,"description":"Unique within this business and environment."},"customerName":{"type":"string","example":"Ada Okafor","maxLength":120},"customerEmail":{"type":"string","example":"ada@example.com","format":"email"},"customerPhoneNumber":{"type":"string","example":"+2348012345678","nullable":true,"description":"Customer phone number in international E.164 format."},"billingAddress":{"nullable":true,"description":"Optional customer billing address printed on the invoice.","type":"object","allOf":[{"$ref":"#/components/schemas/InvoiceBillingAddressDto"}]},"currency":{"type":"string","example":"NGN","default":"NGN"},"items":{"minItems":1,"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/CreateInvoiceItemDto"}},"taxMinor":{"type":"string","example":"37500","default":"0","description":"Non-negative integer minor units."},"discountMinor":{"type":"string","example":"0","default":"0","description":"Non-negative integer minor units. Cannot exceed subtotal plus tax."},"dueAt":{"format":"date-time","type":"string","example":"2026-12-31T23:59:59.000Z","description":"Optional payment due date. It must be in the future."},"description":{"type":"string","example":"Thank you for your business.","maxLength":5000}},"required":["invoiceNumber","customerName","customerEmail","items"]},"CreateFileUploadDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"purpose":{"type":"string","enum":["KYC_DOCUMENT","INVOICE_ATTACHMENT","BULK_PAYOUT","GENERAL"]},"filename":{"type":"string","example":"certificate.pdf","maxLength":180},"mimeType":{"type":"string","enum":["application/pdf","image/jpeg","image/png","text/csv","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"]},"sizeBytes":{"type":"number","minimum":1,"maximum":10485760,"description":"Exact byte size of the file that will be uploaded to the signed Cloudflare R2 URL."}},"required":["environment","purpose","filename","mimeType","sizeBytes"]},"FileUploadResponse":{"type":"object","properties":{"fileId":{"type":"string"},"method":{"type":"string","enum":["PUT"]},"uploadUrl":{"type":"string","format":"uri","description":"Short-lived Cloudflare R2 S3 URL. Do not store or log this URL."},"headers":{"type":"object","example":{"Content-Type":"application/pdf","Cache-Control":"private, no-store"}},"expiresAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["PENDING","READY","FAILED"],"example":"PENDING"}},"required":["fileId","method","uploadUrl","headers","expiresAt","status"]},"StoredFileResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"purpose":{"type":"string","enum":["KYC_DOCUMENT","INVOICE_ATTACHMENT","BULK_PAYOUT","GENERAL"]},"status":{"type":"string","enum":["PENDING","READY","FAILED"]},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","environment","purpose","status","filename","mimeType","sizeBytes","createdAt","updatedAt"]},"FileDownloadResponse":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Short-lived private Cloudflare R2 download URL. Do not store or log this URL."},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","expiresAt"]},"AdminProfileResponse":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"fullName":{"type":"string"},"role":{"type":"string","enum":["SUPER_ADMIN","COMPLIANCE","OPERATIONS","SUPPORT","VIEWER"]},"status":{"type":"string","enum":["INVITED","ACTIVE","SUSPENDED"]},"twoFactorEnabled":{"type":"boolean"},"lastLoginAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","email","fullName","role","status","twoFactorEnabled","lastLoginAt","createdAt"]},"AdminAuthResponse":{"type":"object","properties":{"accessToken":{"type":"string"},"tokenType":{"type":"string","enum":["Bearer"]},"expiresAt":{"type":"string","format":"date-time"},"admin":{"$ref":"#/components/schemas/AdminProfileResponse"},"twoFactorSetupRequired":{"type":"boolean","description":"True until this admin finishes authenticator enrollment."}},"required":["accessToken","tokenType","expiresAt","admin","twoFactorSetupRequired"]},"AdminTwoFactorChallengeResponse":{"type":"object","properties":{"requiresTwoFactor":{"type":"boolean","enum":[true]},"challengeToken":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["requiresTwoFactor","challengeToken","expiresAt"]},"AdminInvitationTokenDto":{"type":"object","properties":{"token":{"type":"string","writeOnly":true,"description":"Single-use invitation token from the invitation email."}},"required":["token"]},"InspectAdminInvitationResponse":{"type":"object","properties":{"email":{"type":"string","format":"email"},"fullName":{"type":"string"},"role":{"type":"string","enum":["SUPER_ADMIN","COMPLIANCE","OPERATIONS","SUPPORT","VIEWER"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["email","fullName","role","expiresAt"]},"AcceptAdminInvitationDto":{"type":"object","properties":{"token":{"type":"string","writeOnly":true,"description":"Single-use invitation token from the invitation email."},"password":{"type":"string","format":"password","writeOnly":true,"minLength":12,"maxLength":128},"confirmPassword":{"type":"string","format":"password","writeOnly":true,"maxLength":128}},"required":["token","password","confirmPassword"]},"AcceptAdminInvitationResponse":{"type":"object","properties":{"accepted":{"type":"boolean","enum":[true]},"admin":{"$ref":"#/components/schemas/AdminProfileResponse"}},"required":["accepted","admin"]},"AdminLoginDto":{"type":"object","properties":{"email":{"type":"string","example":"admin@creddot.com","format":"email"},"password":{"type":"string","format":"password","writeOnly":true,"maxLength":128}},"required":["email","password"]},"VerifyAdminTwoFactorDto":{"type":"object","properties":{"challengeToken":{"type":"string","description":"Short-lived token returned after a successful password check."},"code":{"type":"string","example":"123456","description":"A 6-digit authenticator code or a one-time recovery code."}},"required":["challengeToken","code"]},"AdminTwoFactorSetupResponse":{"type":"object","properties":{"secret":{"type":"string","example":"JBSWY3DPEHPK3PXP"},"issuer":{"type":"string","example":"Creddot"},"accountName":{"type":"string","format":"email"},"otpauthUri":{"type":"string","description":"otpauth URI accepted by Google Authenticator and compatible apps."},"qrCodeDataUrl":{"type":"string","description":"PNG QR code represented as a data URL."}},"required":["secret","issuer","accountName","otpauthUri","qrCodeDataUrl"]},"EnableAdminTwoFactorDto":{"type":"object","properties":{"code":{"type":"string","example":"123456","pattern":"^\\d{6}$"}},"required":["code"]},"AdminRecoveryCodesResponse":{"type":"object","properties":{"enabled":{"type":"boolean","enum":[true]},"recoveryCodes":{"description":"Shown once. Store these one-time recovery codes securely.","type":"array","items":{"type":"string"}}},"required":["enabled","recoveryCodes"]},"AdminTwoFactorCodeDto":{"type":"object","properties":{"code":{"type":"string","example":"123456","description":"A 6-digit authenticator code or a one-time recovery code."}},"required":["code"]},"DisableAdminTwoFactorDto":{"type":"object","properties":{"code":{"type":"string","example":"123456","description":"A 6-digit authenticator code or a one-time recovery code."},"password":{"type":"string","format":"password","writeOnly":true,"maxLength":128}},"required":["code","password"]},"AdminTwoFactorDisabledResponse":{"type":"object","properties":{"enabled":{"type":"boolean","enum":[false]}},"required":["enabled"]},"AdminDashboardRangeResponse":{"type":"object","properties":{"days":{"type":"number","example":30},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}},"required":["days","from","to"]},"AdminDashboardMetricsResponse":{"type":"object","properties":{"collectionVolumeMinor":{"type":"string","example":"250000000"},"payoutVolumeMinor":{"type":"string","example":"125000000"},"refundVolumeMinor":{"type":"string","example":"5000000"},"feeRevenueMinor":{"type":"string","example":"2500000"},"netCollectionVolumeMinor":{"type":"string","example":"242500000","description":"Successful collections minus successful refunds and fees during the selected window."},"transactionCount":{"type":"number"},"successfulTransactionCount":{"type":"number"},"successRate":{"type":"number","example":98.42,"description":"Successful transactions divided by all transactions in the selected window."}},"required":["collectionVolumeMinor","payoutVolumeMinor","refundVolumeMinor","feeRevenueMinor","netCollectionVolumeMinor","transactionCount","successfulTransactionCount","successRate"]},"AdminDashboardChartPointResponse":{"type":"object","properties":{"date":{"type":"string","example":"2026-10-13","description":"UTC calendar date."},"collectionVolumeMinor":{"type":"string","example":"1000000"},"payoutVolumeMinor":{"type":"string","example":"500000"},"refundVolumeMinor":{"type":"string","example":"25000"},"feeRevenueMinor":{"type":"string","example":"10000"},"successfulCount":{"type":"number"},"failedCount":{"type":"number"}},"required":["date","collectionVolumeMinor","payoutVolumeMinor","refundVolumeMinor","feeRevenueMinor","successfulCount","failedCount"]},"AdminDashboardAttentionResponse":{"type":"object","properties":{"kycAwaitingReview":{"type":"number"},"refundsAwaitingReview":{"type":"number"},"transactionsRequiringReconciliation":{"type":"number"},"suspendedBusinesses":{"type":"number"},"processingTransactions":{"type":"number"}},"required":["kycAwaitingReview","refundsAwaitingReview","transactionsRequiringReconciliation","suspendedBusinesses","processingTransactions"]},"AdminDashboardRecentTransactionResponse":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string"},"businessName":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"type":{"type":"string","enum":["COLLECTION","PAYOUT","REFUND","REVERSAL","BILL_PAYMENT"]},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]},"amountMinor":{"type":"string","example":"1500000"},"currency":{"type":"string"},"reference":{"type":"string"},"channel":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","merchantId","businessName","environment","type","status","amountMinor","currency","reference","channel","createdAt"]},"AdminStatusCountResponse":{"type":"object","properties":{"status":{"type":"string"},"count":{"type":"number"}},"required":["status","count"]},"AdminTransactionStatusResponse":{"type":"object","properties":{"status":{"type":"string"},"count":{"type":"number"},"amountMinor":{"type":"string","example":"1500000"}},"required":["status","count","amountMinor"]},"AdminDashboardResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"currency":{"type":"string"},"range":{"$ref":"#/components/schemas/AdminDashboardRangeResponse"},"metrics":{"$ref":"#/components/schemas/AdminDashboardMetricsResponse"},"chart":{"type":"array","items":{"$ref":"#/components/schemas/AdminDashboardChartPointResponse"}},"attention":{"$ref":"#/components/schemas/AdminDashboardAttentionResponse"},"recentTransactions":{"type":"array","items":{"$ref":"#/components/schemas/AdminDashboardRecentTransactionResponse"}},"businesses":{"type":"array","items":{"$ref":"#/components/schemas/AdminStatusCountResponse"}},"kyc":{"type":"array","items":{"$ref":"#/components/schemas/AdminStatusCountResponse"}},"transactions":{"description":"All-time status breakdown for the selected environment and currency.","type":"array","items":{"$ref":"#/components/schemas/AdminTransactionStatusResponse"}}},"required":["environment","currency","range","metrics","chart","attention","recentTransactions","businesses","kyc","transactions"]},"AdminAnalyticsRangeResponse":{"type":"object","properties":{"days":{"type":"number","example":30},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"previousFrom":{"type":"string","format":"date-time"},"previousTo":{"type":"string","format":"date-time"}},"required":["days","from","to","previousFrom","previousTo"]},"AdminMoneyComparisonResponse":{"type":"object","properties":{"currentMinor":{"type":"string","example":"250000000"},"previousMinor":{"type":"string","example":"200000000"},"changePercent":{"type":"number","nullable":true,"example":25,"description":"Null when the previous period is zero and the current period is non-zero."}},"required":["currentMinor","previousMinor","changePercent"]},"AdminCountComparisonResponse":{"type":"object","properties":{"current":{"type":"number"},"previous":{"type":"number"},"changePercent":{"type":"number","nullable":true,"example":12.5}},"required":["current","previous","changePercent"]},"AdminRateComparisonResponse":{"type":"object","properties":{"current":{"type":"number","example":98.5},"previous":{"type":"number","example":97.2},"changePercentagePoints":{"type":"number","example":1.3}},"required":["current","previous","changePercentagePoints"]},"AdminAnalyticsSummaryResponse":{"type":"object","properties":{"collectionVolume":{"$ref":"#/components/schemas/AdminMoneyComparisonResponse"},"payoutVolume":{"$ref":"#/components/schemas/AdminMoneyComparisonResponse"},"billPaymentVolume":{"$ref":"#/components/schemas/AdminMoneyComparisonResponse"},"refundVolume":{"$ref":"#/components/schemas/AdminMoneyComparisonResponse"},"feeRevenue":{"$ref":"#/components/schemas/AdminMoneyComparisonResponse"},"netCollectionVolume":{"$ref":"#/components/schemas/AdminMoneyComparisonResponse"},"transactionCount":{"$ref":"#/components/schemas/AdminCountComparisonResponse"},"successfulTransactionCount":{"$ref":"#/components/schemas/AdminCountComparisonResponse"},"successRate":{"$ref":"#/components/schemas/AdminRateComparisonResponse"}},"required":["collectionVolume","payoutVolume","billPaymentVolume","refundVolume","feeRevenue","netCollectionVolume","transactionCount","successfulTransactionCount","successRate"]},"AdminAnalyticsTimeSeriesPointResponse":{"type":"object","properties":{"date":{"type":"string","example":"2026-10-13","description":"UTC calendar date."},"collectionVolumeMinor":{"type":"string","example":"1000000"},"payoutVolumeMinor":{"type":"string","example":"500000"},"refundVolumeMinor":{"type":"string","example":"25000"},"feeRevenueMinor":{"type":"string","example":"10000"},"successfulCount":{"type":"number"},"failedCount":{"type":"number"},"billPaymentVolumeMinor":{"type":"string","example":"250000"}},"required":["date","collectionVolumeMinor","payoutVolumeMinor","refundVolumeMinor","feeRevenueMinor","successfulCount","failedCount","billPaymentVolumeMinor"]},"AdminAnalyticsTypeBreakdownResponse":{"type":"object","properties":{"type":{"type":"string","enum":["COLLECTION","PAYOUT","REFUND","REVERSAL","BILL_PAYMENT"]},"count":{"type":"number"},"amountMinor":{"type":"string","example":"1500000"}},"required":["type","count","amountMinor"]},"AdminAnalyticsChannelBreakdownResponse":{"type":"object","properties":{"channel":{"type":"string","example":"BANK_TRANSFER"},"count":{"type":"number"},"amountMinor":{"type":"string","example":"1500000"}},"required":["channel","count","amountMinor"]},"AdminAnalyticsProviderBreakdownResponse":{"type":"object","properties":{"provider":{"type":"string","example":"PAGA"},"count":{"type":"number"},"amountMinor":{"type":"string","example":"1500000"}},"required":["provider","count","amountMinor"]},"AdminAnalyticsBreakdownsResponse":{"type":"object","properties":{"byStatus":{"type":"array","items":{"$ref":"#/components/schemas/AdminTransactionStatusResponse"}},"byType":{"type":"array","items":{"$ref":"#/components/schemas/AdminAnalyticsTypeBreakdownResponse"}},"byChannel":{"description":"Successful transactions only.","type":"array","items":{"$ref":"#/components/schemas/AdminAnalyticsChannelBreakdownResponse"}},"byProvider":{"description":"Successful transactions only.","type":"array","items":{"$ref":"#/components/schemas/AdminAnalyticsProviderBreakdownResponse"}}},"required":["byStatus","byType","byChannel","byProvider"]},"AdminAnalyticsTopBusinessResponse":{"type":"object","properties":{"merchantId":{"type":"string"},"businessName":{"type":"string"},"successfulCollectionCount":{"type":"number"},"collectionVolumeMinor":{"type":"string","example":"1500000"}},"required":["merchantId","businessName","successfulCollectionCount","collectionVolumeMinor"]},"AdminAnalyticsResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"currency":{"type":"string","example":"NGN"},"range":{"$ref":"#/components/schemas/AdminAnalyticsRangeResponse"},"summary":{"$ref":"#/components/schemas/AdminAnalyticsSummaryResponse"},"timeSeries":{"type":"array","items":{"$ref":"#/components/schemas/AdminAnalyticsTimeSeriesPointResponse"}},"breakdowns":{"$ref":"#/components/schemas/AdminAnalyticsBreakdownsResponse"},"topBusinesses":{"type":"array","items":{"$ref":"#/components/schemas/AdminAnalyticsTopBusinessResponse"}}},"required":["environment","currency","range","summary","timeSeries","breakdowns","topBusinesses"]},"AdminOperationsQueuesResponse":{"type":"object","properties":{"transactionsRequiringReconciliation":{"type":"number"},"staleProcessingTransactions":{"type":"number"},"refundsAwaitingReview":{"type":"number"},"failedTransactionsLast24Hours":{"type":"number"},"successfulTransactionsAwaitingSettlement":{"type":"number"},"pendingWebhooks":{"type":"number"},"failedWebhooks":{"type":"number"}},"required":["transactionsRequiringReconciliation","staleProcessingTransactions","refundsAwaitingReview","failedTransactionsLast24Hours","successfulTransactionsAwaitingSettlement","pendingWebhooks","failedWebhooks"]},"AdminOperationsWalletResponse":{"type":"object","properties":{"status":{"type":"string"},"count":{"type":"number"},"availableBalanceMinor":{"type":"string","example":"1500000"},"pendingBalanceMinor":{"type":"string","example":"250000"},"reservedBalanceMinor":{"type":"string","example":"50000"}},"required":["status","count","availableBalanceMinor","pendingBalanceMinor","reservedBalanceMinor"]},"AdminOperationsVirtualAccountsResponse":{"type":"object","properties":{"active":{"type":"number"},"inactive":{"type":"number"}},"required":["active","inactive"]},"AdminOperationsFailureResponse":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string"},"businessName":{"type":"string"},"type":{"type":"string","enum":["COLLECTION","PAYOUT","REFUND","REVERSAL","BILL_PAYMENT"]},"amountMinor":{"type":"string","example":"1500000"},"currency":{"type":"string","example":"NGN"},"reference":{"type":"string"},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","merchantId","businessName","type","amountMinor","currency","reference","provider","providerReference","updatedAt"]},"AdminOperationsSummaryResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"currency":{"type":"string","example":"NGN"},"generatedAt":{"type":"string","format":"date-time"},"staleAfterMinutes":{"type":"number"},"queues":{"$ref":"#/components/schemas/AdminOperationsQueuesResponse"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/AdminTransactionStatusResponse"}},"payouts":{"type":"array","items":{"$ref":"#/components/schemas/AdminTransactionStatusResponse"}},"billPayments":{"type":"array","items":{"$ref":"#/components/schemas/AdminTransactionStatusResponse"}},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/AdminTransactionStatusResponse"}},"settlements":{"type":"array","items":{"$ref":"#/components/schemas/AdminTransactionStatusResponse"}},"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/AdminStatusCountResponse"}},"wallets":{"type":"array","items":{"$ref":"#/components/schemas/AdminOperationsWalletResponse"}},"virtualAccounts":{"$ref":"#/components/schemas/AdminOperationsVirtualAccountsResponse"},"recentFailures":{"type":"array","items":{"$ref":"#/components/schemas/AdminOperationsFailureResponse"}}},"required":["environment","currency","generatedAt","staleAfterMinutes","queues","transactions","payouts","billPayments","refunds","settlements","webhooks","wallets","virtualAccounts","recentFailures"]},"UpsertFeeRuleDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"type":{"type":"string","enum":["INCOMING_TRANSFER","PAYOUT"]},"method":{"type":"string","enum":["VIRTUAL_ACCOUNT_TRANSFER","CHECKOUT_PAYMENT_LINK","CHECKOUT_SPLIT_PAY","CHECKOUT_EVENT","CHECKOUT_STOREFRONT","CHECKOUT_SUBSCRIPTION","API_COLLECTION","PAYOUT_BANK_TRANSFER"]},"currency":{"type":"string","example":"NGN"},"fixedFeeMinor":{"type":"string","example":"10000","description":"Non-negative fixed fee in minor units."},"percentageBasisPoints":{"type":"number","example":150,"description":"Percentage in basis points. 150 means 1.5%."},"minimumFeeMinor":{"type":"string","nullable":true,"example":"10000"},"maximumFeeMinor":{"type":"string","nullable":true,"example":"200000"},"active":{"type":"boolean","default":true,"description":"An inactive business rule falls back to the active general rule."}},"required":["environment","type","method","currency","fixedFeeMinor","percentageBasisPoints"]},"FeeRuleResponse":{"type":"object","properties":{"id":{"type":"string"},"scope":{"type":"string","enum":["GENERAL","BUSINESS"]},"merchantId":{"type":"string","nullable":true},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"type":{"type":"string","enum":["INCOMING_TRANSFER","PAYOUT"]},"method":{"type":"string","enum":["VIRTUAL_ACCOUNT_TRANSFER","CHECKOUT_PAYMENT_LINK","CHECKOUT_SPLIT_PAY","CHECKOUT_EVENT","CHECKOUT_STOREFRONT","CHECKOUT_SUBSCRIPTION","API_COLLECTION","PAYOUT_BANK_TRANSFER"]},"currency":{"type":"string"},"fixedFeeMinor":{"type":"string"},"percentageBasisPoints":{"type":"number"},"minimumFeeMinor":{"type":"string","nullable":true},"maximumFeeMinor":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","scope","merchantId","environment","type","method","currency","fixedFeeMinor","percentageBasisPoints","minimumFeeMinor","maximumFeeMinor","active","createdAt","updatedAt"]},"AdminPayoutQueueRuntimeResponse":{"type":"object","properties":{"available":{"type":"boolean"},"paused":{"type":"boolean"},"waiting":{"type":"number"},"active":{"type":"number"},"completed":{"type":"number"},"failed":{"type":"number"},"delayed":{"type":"number"},"error":{"type":"string","nullable":true}},"required":["available","paused","waiting","active","completed","failed","delayed"]},"AdminPayoutQueueStatusResponse":{"type":"object","properties":{"status":{"type":"string","enum":["QUEUED","ACTIVE","COMPLETED","FAILED"]},"count":{"type":"number"}},"required":["status","count"]},"AdminPayoutQueueJobResponse":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string"},"businessName":{"type":"string"},"transactionId":{"type":"string"},"payoutId":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"status":{"type":"string","enum":["QUEUED","ACTIVE","COMPLETED","FAILED"]},"attempts":{"type":"number"},"maxAttempts":{"type":"number"},"reference":{"type":"string"},"transactionStatus":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]},"requiresReconciliation":{"type":"boolean"},"amountMinor":{"type":"string","example":"100000"},"currency":{"type":"string"},"accountNumberMasked":{"type":"string"},"accountName":{"type":"string","nullable":true},"bankCode":{"type":"string"},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"queuedAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time","nullable":true},"providerAttemptedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string","nullable":true},"workerId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","merchantId","businessName","transactionId","payoutId","environment","status","attempts","maxAttempts","reference","transactionStatus","requiresReconciliation","amountMinor","currency","accountNumberMasked","accountName","bankCode","provider","providerReference","queuedAt","startedAt","providerAttemptedAt","completedAt","failedAt","lastError","workerId","createdAt","updatedAt"]},"AdminPayoutQueueListResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"enabled":{"type":"boolean"},"runtime":{"$ref":"#/components/schemas/AdminPayoutQueueRuntimeResponse"},"summary":{"type":"array","items":{"$ref":"#/components/schemas/AdminPayoutQueueStatusResponse"}},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminPayoutQueueJobResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["environment","enabled","runtime","summary","items","total","page","pageSize"]},"AdminPayoutQueueDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string"},"businessName":{"type":"string"},"transactionId":{"type":"string"},"payoutId":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"status":{"type":"string","enum":["QUEUED","ACTIVE","COMPLETED","FAILED"]},"attempts":{"type":"number"},"maxAttempts":{"type":"number"},"reference":{"type":"string"},"transactionStatus":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]},"requiresReconciliation":{"type":"boolean"},"amountMinor":{"type":"string","example":"100000"},"currency":{"type":"string"},"accountNumberMasked":{"type":"string"},"accountName":{"type":"string","nullable":true},"bankCode":{"type":"string"},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"queuedAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time","nullable":true},"providerAttemptedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string","nullable":true},"workerId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"runtimeState":{"type":"string","nullable":true},"progress":{"type":"object","nullable":true}},"required":["id","merchantId","businessName","transactionId","payoutId","environment","status","attempts","maxAttempts","reference","transactionStatus","requiresReconciliation","amountMinor","currency","accountNumberMasked","accountName","bankCode","provider","providerReference","queuedAt","startedAt","providerAttemptedAt","completedAt","failedAt","lastError","workerId","createdAt","updatedAt","runtimeState","progress"]},"AdminThirdPartyLogListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE","GLOBAL","UNKNOWN"]},"provider":{"type":"string","example":"PAGA"},"direction":{"type":"string","enum":["INBOUND","OUTBOUND"]},"operation":{"type":"string","example":"collection_callback"},"status":{"type":"string","enum":["RECEIVED","SUCCESS","FAILED","IGNORED"]},"merchantId":{"type":"string","nullable":true},"transactionId":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"providerReference":{"type":"string","nullable":true},"httpMethod":{"type":"string","nullable":true},"endpoint":{"type":"string","nullable":true},"httpStatus":{"type":"number","nullable":true},"providerCode":{"type":"string","nullable":true},"message":{"type":"string","nullable":true},"durationMs":{"type":"number","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","environment","provider","direction","operation","status","merchantId","transactionId","reference","providerReference","httpMethod","endpoint","httpStatus","providerCode","message","durationMs","completedAt","createdAt"]},"AdminThirdPartyLogStatusCountResponse":{"type":"object","properties":{"status":{"type":"string","enum":["RECEIVED","SUCCESS","FAILED","IGNORED"]},"count":{"type":"number"}},"required":["status","count"]},"AdminThirdPartyLogListResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE","GLOBAL","UNKNOWN"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminThirdPartyLogListItemResponse"}},"summary":{"type":"array","items":{"$ref":"#/components/schemas/AdminThirdPartyLogStatusCountResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["environment","items","summary","total","page","pageSize"]},"AdminThirdPartyLogResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE","GLOBAL","UNKNOWN"]},"provider":{"type":"string","example":"PAGA"},"direction":{"type":"string","enum":["INBOUND","OUTBOUND"]},"operation":{"type":"string","example":"collection_callback"},"status":{"type":"string","enum":["RECEIVED","SUCCESS","FAILED","IGNORED"]},"merchantId":{"type":"string","nullable":true},"transactionId":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"providerReference":{"type":"string","nullable":true},"httpMethod":{"type":"string","nullable":true},"endpoint":{"type":"string","nullable":true},"httpStatus":{"type":"number","nullable":true},"providerCode":{"type":"string","nullable":true},"message":{"type":"string","nullable":true},"durationMs":{"type":"number","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"requestPayload":{"type":"object","nullable":true,"additionalProperties":true},"responsePayload":{"type":"object","nullable":true,"additionalProperties":true}},"required":["id","environment","provider","direction","operation","status","merchantId","transactionId","reference","providerReference","httpMethod","endpoint","httpStatus","providerCode","message","durationMs","completedAt","createdAt","requestPayload","responsePayload"]},"AdminKycDocumentResponse":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["CAC","MEMART","UTILITY_BILL","VALID_ID"]},"filename":{"type":"string"},"mimeType":{"type":"string","enum":["application/pdf","image/jpeg","image/png"]},"sizeBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time","description":"Changes when a document is replaced."},"url":{"type":"string","format":"uri","nullable":true,"description":"Full short-lived signed Cloudflare R2 URL. Null only for a legacy document that must be re-uploaded."},"urlExpiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Expiry time for the signed document URL."}},"required":["id","kind","filename","mimeType","sizeBytes","createdAt","updatedAt","url","urlExpiresAt"]},"AdminKycQueueItemResponse":{"type":"object","properties":{"merchantId":{"type":"string"},"businessName":{"type":"string"},"businessEmail":{"type":"string","format":"email"},"businessStatus":{"type":"string","enum":["PENDING","ACTIVE","SUSPENDED","CLOSED"]},"kycStatus":{"type":"string","enum":["NOT_STARTED","PENDING","VERIFIED","REJECTED","REQUIRES_UPDATE"]},"profileId":{"type":"string"},"documentCount":{"type":"number"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/AdminKycDocumentResponse"}},"submittedAt":{"type":"string","format":"date-time"}},"required":["merchantId","businessName","businessEmail","businessStatus","kycStatus","profileId","documentCount","documents","submittedAt"]},"AdminKycQueueResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminKycQueueItemResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]},"AdminKycResponse":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_STARTED","PENDING","VERIFIED","REJECTED","REQUIRES_UPDATE"]},"statusLabel":{"type":"string","example":"KYC Pending"},"rejectionReason":{"type":"string","nullable":true},"business":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/SaveKycBusinessDto"}]},"businessVerification":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/KycVerificationResponse"}]},"directorSuggestions":{"description":"Safe name/role options returned by verified CAC data for the director selector. May be empty.","type":"array","items":{"$ref":"#/components/schemas/KycDirectorSuggestionResponse"}},"bvnProvided":{"type":"boolean"},"bvnMasked":{"type":"string","nullable":true,"example":"*******8901"},"bvnVerification":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/KycVerificationResponse"}]},"facialVerification":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/KycVerificationResponse"}]},"authorizedRepresentativeEmail":{"type":"string","nullable":true,"format":"email","description":"Email of the saved director whose BVN and face were verified."},"directors":{"type":"array","items":{"$ref":"#/components/schemas/DirectorDto"}},"submittedAt":{"type":"string","format":"date-time","nullable":true},"documents":{"type":"array","items":{"$ref":"#/components/schemas/AdminKycDocumentResponse"}},"documentRequirements":{"type":"array","items":{"$ref":"#/components/schemas/KycDocumentRequirementResponse"}},"steps":{"description":"Four stable steps for the business KYC UI.","type":"array","items":{"$ref":"#/components/schemas/KycStepResponse"}},"missingRequirements":{"example":["CAC_VERIFICATION","BVN_VERIFICATION","FACIAL_VERIFICATION","MEMART"],"type":"array","items":{"type":"string"}},"canSubmit":{"type":"boolean","description":"True only when every submit requirement is complete and KYC is still editable."},"editable":{"type":"boolean","description":"False when under review or verified."}},"required":["status","statusLabel","rejectionReason","business","businessVerification","directorSuggestions","bvnProvided","bvnMasked","bvnVerification","facialVerification","authorizedRepresentativeEmail","directors","submittedAt","documents","documentRequirements","steps","missingRequirements","canSubmit","editable"]},"AdminKycDetailResponse":{"type":"object","properties":{"merchantId":{"type":"string"},"businessName":{"type":"string"},"businessEmail":{"type":"string","format":"email"},"businessStatus":{"type":"string","enum":["PENDING","ACTIVE","SUSPENDED","CLOSED"]},"kyc":{"$ref":"#/components/schemas/AdminKycResponse"}},"required":["merchantId","businessName","businessEmail","businessStatus","kyc"]},"AdminTransactionBusinessResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"businessEmail":{"type":"string","format":"email"}},"required":["id","name","businessEmail"]},"AdminTransactionListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"business":{"$ref":"#/components/schemas/AdminTransactionBusinessResponse"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"type":{"type":"string","enum":["COLLECTION","PAYOUT","REFUND","REVERSAL","BILL_PAYMENT"]},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]},"amountMinor":{"type":"string","example":"1500000"},"currency":{"type":"string"},"reference":{"type":"string"},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"direction":{"type":"string","enum":["MONEY_IN","MONEY_OUT"]},"channel":{"type":"string","nullable":true},"customerName":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true,"format":"email"},"requiresReconciliation":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","business","environment","type","status","amountMinor","currency","reference","provider","providerReference","direction","channel","customerName","customerEmail","requiresReconciliation","createdAt","updatedAt"]},"AdminTransactionListResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminTransactionListItemResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["environment","items","total","page","pageSize"]},"AdminTransactionDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string","description":"Use this ID for transaction lookup and sandbox completion. Payout id is a separate payout record ID."},"reference":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]},"amountMinor":{"type":"string","example":"100000","description":"Integer minor units, encoded as a string."},"currency":{"type":"string","example":"NGN"},"provider":{"type":"string","example":"PAGA"},"providerReference":{"type":"string","nullable":true},"requiresReconciliation":{"type":"boolean","description":"True when provider outcome is uncertain. Do not retry with a new key; query the transaction or reconcile it."},"feeMinor":{"type":"string","example":"1500","description":"Creddot fee charged to the business in minor units."},"totalDebitMinor":{"type":"string","example":"101500","description":"Wallet debit for payouts; equals amountMinor for incoming transfers."},"netCreditMinor":{"type":"string","example":"98500","description":"Wallet credit for incoming transfers; equals amountMinor for payouts."},"type":{"type":"string","enum":["COLLECTION","PAYOUT","REFUND","REVERSAL","BILL_PAYMENT"]},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"payoutId":{"type":"string","nullable":true},"paymentUrl":{"type":"string","nullable":true,"format":"uri"},"direction":{"type":"string","enum":["MONEY_IN","MONEY_OUT"]},"channel":{"type":"string","nullable":true,"example":"BANK_TRANSFER"},"customerName":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true,"format":"email"},"providerFeeMinor":{"type":"string","example":"5375","description":"Upstream provider fee in minor units."},"feeMethod":{"type":"string","nullable":true},"feeRuleId":{"type":"string","nullable":true},"sender":{"type":"object","properties":{"name":{"type":"string","nullable":true},"bankName":{"type":"string","nullable":true},"accountNumberMasked":{"type":"string","nullable":true}}},"sessionId":{"type":"string","nullable":true,"description":"NIBSS/Paga session identifier when supplied by the provider."},"settlement":{"type":"object","properties":{"status":{"type":"string"},"reference":{"type":"string","nullable":true},"settledAt":{"type":"string","format":"date-time","nullable":true}}},"payout":{"type":"object","nullable":true,"additionalProperties":true},"billPayment":{"type":"object","nullable":true,"additionalProperties":true},"ledgerEntries":{"type":"array","items":{"type":"object"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"business":{"$ref":"#/components/schemas/AdminTransactionBusinessResponse"}},"required":["id","transactionId","reference","status","amountMinor","currency","provider","providerReference","requiresReconciliation","feeMinor","totalDebitMinor","netCreditMinor","type","environment","payoutId","paymentUrl","direction","channel","customerName","customerEmail","providerFeeMinor","feeMethod","feeRuleId","sender","sessionId","settlement","payout","billPayment","ledgerEntries","createdAt","updatedAt","business"]},"AdminReconciliationItemResponse":{"type":"object","properties":{"id":{"type":"string"},"business":{"$ref":"#/components/schemas/AdminTransactionBusinessResponse"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"type":{"type":"string","enum":["COLLECTION","PAYOUT","REFUND","REVERSAL","BILL_PAYMENT"]},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]},"amountMinor":{"type":"string","example":"1500000"},"currency":{"type":"string"},"reference":{"type":"string"},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"direction":{"type":"string","enum":["MONEY_IN","MONEY_OUT"]},"channel":{"type":"string","nullable":true},"customerName":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true,"format":"email"},"requiresReconciliation":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastCheckedAt":{"type":"string","nullable":true,"format":"date-time"},"attemptCount":{"type":"number"}},"required":["id","business","environment","type","status","amountMinor","currency","reference","provider","providerReference","direction","channel","customerName","customerEmail","requiresReconciliation","createdAt","updatedAt","lastCheckedAt","attemptCount"]},"AdminReconciliationListResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminReconciliationItemResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["environment","items","total","page","pageSize"]},"AdminReconciliationAttemptResponse":{"type":"object","properties":{"id":{"type":"string"},"adminUserId":{"type":"string"},"action":{"type":"string"},"previousStatus":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]},"providerStatus":{"type":"string","nullable":true},"resolvedStatus":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"],"nullable":true},"reason":{"type":"string","nullable":true},"evidenceReference":{"type":"string","nullable":true},"providerResponse":{"type":"object","nullable":true,"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","adminUserId","action","previousStatus","providerStatus","resolvedStatus","reason","evidenceReference","providerResponse","createdAt"]},"AdminReconciliationDetailResponse":{"type":"object","properties":{"transaction":{"$ref":"#/components/schemas/AdminTransactionDetailResponse"},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/AdminReconciliationAttemptResponse"}}},"required":["transaction","attempts"]},"ResolveReconciliationDto":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCESS","FAILED"]},"reason":{"type":"string","minLength":10,"maxLength":500,"description":"Operational reason and evidence supporting the manual outcome."},"evidenceReference":{"type":"string","minLength":3,"maxLength":191,"description":"Provider ticket, statement, or settlement evidence reference."}},"required":["status","reason","evidenceReference"]},"AdminRefundResponse":{"type":"object","properties":{"id":{"type":"string"},"business":{"$ref":"#/components/schemas/AdminTransactionBusinessResponse"},"originalTransactionId":{"type":"string"},"refundTransactionId":{"type":"string","nullable":true},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"status":{"type":"string","enum":["REQUESTED","APPROVED","PROCESSING","SUCCESS","FAILED","REJECTED"]},"amountMinor":{"type":"string","example":"150000"},"currency":{"type":"string"},"reason":{"type":"string"},"rejectionReason":{"type":"string","nullable":true},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"requestedByAdminId":{"type":"string","nullable":true},"reviewedByAdminId":{"type":"string","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","business","originalTransactionId","refundTransactionId","environment","status","amountMinor","currency","reason","rejectionReason","provider","providerReference","requestedByAdminId","reviewedByAdminId","reviewedAt","createdAt","updatedAt"]},"AdminRefundListResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminRefundResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["environment","items","total","page","pageSize"]},"CreateAdminRefundDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"description":"Required admin operating mode. Financial records from the other environment are never included."},"amountMinor":{"type":"string","pattern":"^\\d{1,19}$","description":"Defaults to the remaining refundable amount."},"reason":{"type":"string","minLength":5,"maxLength":500}},"required":["environment","reason"]},"RejectAdminRefundDto":{"type":"object","properties":{"reason":{"type":"string","minLength":5,"maxLength":500}},"required":["reason"]},"AdminSettlementResponse":{"type":"object","properties":{"id":{"type":"string","description":"Stable settlement record ID. Currently the underlying transaction ID."},"business":{"$ref":"#/components/schemas/AdminTransactionBusinessResponse"},"transactionId":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"transactionType":{"type":"string","enum":["COLLECTION","PAYOUT","REFUND","REVERSAL","BILL_PAYMENT"]},"status":{"type":"string"},"grossAmountMinor":{"type":"string","example":"150000"},"feeAmountMinor":{"type":"string","example":"2500"},"refundedAmountMinor":{"type":"string","example":"0"},"netAmountMinor":{"type":"string","example":"147500"},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"provider":{"type":"string"},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","business","transactionId","environment","transactionType","status","grossAmountMinor","feeAmountMinor","refundedAmountMinor","netAmountMinor","currency","reference","provider","settledAt","createdAt"]},"AdminSettlementListResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminSettlementResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["environment","items","total","page","pageSize"]},"AdminAuditLogItemResponse":{"type":"object","properties":{"id":{"type":"string"},"actorType":{"type":"string"},"actorId":{"type":"string","nullable":true},"merchantId":{"type":"string","nullable":true},"action":{"type":"string"},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"ipAddress":{"type":"string","nullable":true},"userAgent":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","actorType","actorId","merchantId","action","metadata","ipAddress","userAgent","createdAt"]},"AdminAuditLogListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminAuditLogItemResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]},"AdminUserListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminProfileResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["items","total","page","pageSize"]},"CreateAdminUserDto":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"compliance@creddot.com"},"fullName":{"type":"string","minLength":2,"maxLength":120},"role":{"type":"string","enum":["SUPER_ADMIN","COMPLIANCE","OPERATIONS","SUPPORT","VIEWER"]}},"required":["email","fullName","role"]},"AdminInvitationSummaryResponse":{"type":"object","properties":{"id":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"emailSent":{"type":"boolean","description":"True when the email provider accepted the invitation for delivery."},"simulated":{"type":"boolean","description":"True when email delivery is disabled and no real message was sent."}},"required":["id","expiresAt","emailSent","simulated"]},"CreateAdminInvitationResponse":{"type":"object","properties":{"admin":{"$ref":"#/components/schemas/AdminProfileResponse"},"invitation":{"$ref":"#/components/schemas/AdminInvitationSummaryResponse"}},"required":["admin","invitation"]},"UpdateAdminUserDto":{"type":"object","properties":{"fullName":{"type":"string","minLength":2,"maxLength":120},"role":{"type":"string","enum":["SUPER_ADMIN","COMPLIANCE","OPERATIONS","SUPPORT","VIEWER"]},"status":{"type":"string","enum":["INVITED","ACTIVE","SUSPENDED"]}}},"AdminBusinessCountsResponse":{"type":"object","properties":{"members":{"type":"number"},"transactions":{"type":"number"},"invoices":{"type":"number"},"paymentLinks":{"type":"number"}},"required":["members","transactions","invoices","paymentLinks"]},"AdminBusinessListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"businessEmail":{"type":"string","format":"email"},"status":{"type":"string","enum":["PENDING","ACTIVE","SUSPENDED","CLOSED"]},"kycStatus":{"type":"string","enum":["NOT_STARTED","PENDING","VERIFIED","REJECTED","REQUIRES_UPDATE"]},"countryCode":{"type":"string"},"baseCurrency":{"type":"string"},"counts":{"$ref":"#/components/schemas/AdminBusinessCountsResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","businessEmail","status","kycStatus","countryCode","baseCurrency","counts","createdAt","updatedAt"]},"AdminBusinessListResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminBusinessListItemResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["environment","items","total","page","pageSize"]},"AdminBusinessAddressResponse":{"type":"object","properties":{"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"countryCode":{"type":"string"}},"required":["addressLine1","addressLine2","city","state","postalCode","countryCode"]},"AdminBusinessMemberUserResponse":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"fullName":{"type":"string","nullable":true},"phoneNumber":{"type":"string","nullable":true},"status":{"type":"string","enum":["PENDING_VERIFICATION","ACTIVE","SUSPENDED"]}},"required":["id","email","fullName","phoneNumber","status"]},"AdminBusinessMemberResponse":{"type":"object","properties":{"role":{"type":"string","enum":["OWNER","ADMIN","DEVELOPER","FINANCE","SUPPORT","VIEWER"]},"user":{"$ref":"#/components/schemas/AdminBusinessMemberUserResponse"},"createdAt":{"type":"string","format":"date-time"}},"required":["role","user","createdAt"]},"AdminWalletResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"currency":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","FROZEN","CLOSED"]},"availableBalanceMinor":{"type":"string","example":"0"},"pendingBalanceMinor":{"type":"string","example":"0"},"reservedBalanceMinor":{"type":"string","example":"0"}},"required":["id","environment","currency","status","availableBalanceMinor","pendingBalanceMinor","reservedBalanceMinor"]},"AdminBusinessDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"businessEmail":{"type":"string","format":"email"},"status":{"type":"string","enum":["PENDING","ACTIVE","SUSPENDED","CLOSED"]},"kycStatus":{"type":"string","enum":["NOT_STARTED","PENDING","VERIFIED","REJECTED","REQUIRES_UPDATE"]},"countryCode":{"type":"string"},"baseCurrency":{"type":"string"},"counts":{"$ref":"#/components/schemas/AdminBusinessCountsResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"address":{"$ref":"#/components/schemas/AdminBusinessAddressResponse"},"members":{"type":"array","items":{"$ref":"#/components/schemas/AdminBusinessMemberResponse"}},"wallets":{"type":"array","items":{"$ref":"#/components/schemas/AdminWalletResponse"}},"virtualAccounts":{"type":"array","items":{"$ref":"#/components/schemas/VirtualAccountResponse"}},"kyc":{"$ref":"#/components/schemas/KycResponse"}},"required":["id","name","businessEmail","status","kycStatus","countryCode","baseCurrency","counts","createdAt","updatedAt","environment","address","members","wallets","virtualAccounts","kyc"]},"RequestKycChangesDto":{"type":"object","properties":{"reason":{"type":"string","example":"The utility bill is older than three months.","minLength":5,"maxLength":500}},"required":["reason"]},"UpdateAdminBusinessStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["ACTIVE","SUSPENDED"]},"reason":{"type":"string","maxLength":500,"description":"Required when suspending a business and written to the audit log."}},"required":["status"]},"AdminBusinessSettingsResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"business":{"type":"object"},"preferences":{"type":"object"},"payoutAccount":{"type":"object","nullable":true},"team":{"type":"array","items":{"type":"object"}},"invitations":{"type":"array","items":{"type":"object"}},"customRoles":{"type":"array","items":{"type":"object"}},"developer":{"type":"object"}},"required":["environment","business","preferences","payoutAccount","team","invitations","customRoles","developer"]},"UpdateAdminEnabledStatusDto":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500},"enabled":{"type":"boolean"}},"required":["reason","enabled"]},"AdminResourceStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","updatedAt"]},"AdminReasonDto":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"]},"UpdateAdminWebhookStatusDto":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500},"active":{"type":"boolean"}},"required":["reason","active"]},"AdminProductSummaryResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"currency":{"type":"string"},"paymentLinks":{"type":"object","example":{"total":12,"active":8,"disabled":2,"expired":2,"successfulPayments":20,"collectedAmountMinor":"4500000"}},"splitPays":{"type":"object","example":{"total":8,"unpaid":2,"inProgress":2,"paid":3,"overdue":1,"disabled":0,"targetAmountMinor":"8000000","collectedAmountMinor":"5000000"}},"events":{"type":"object","example":{"total":5,"draft":1,"published":2,"ended":1,"cancelled":1,"successfulOrders":50,"ticketsSold":85,"grossAmountMinor":"12500000"}},"storefronts":{"type":"object","example":{"total":4,"draft":1,"published":2,"disabled":1,"products":30,"orders":80,"successfulOrders":60,"grossAmountMinor":"22500000"}},"invoices":{"type":"object","example":{"total":20,"draft":4,"sent":6,"viewed":2,"paid":7,"overdue":1,"totalAmountMinor":"12000000","paidAmountMinor":"7000000"}},"subscriptions":{"type":"object","example":{"plans":5,"total":8,"draft":1,"active":6,"cancelled":1,"subscribers":200,"activeSubscribers":176,"collectedAmountMinor":"40000000"}}},"required":["environment","currency","paymentLinks","splitPays","events","storefronts","invoices","subscriptions"]},"AdminProductBusinessResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["id","name","email"]},"AdminPaymentLinkListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"linkNumber":{"type":"object","nullable":true},"pageName":{"type":"string"},"status":{"type":"string"},"visibility":{"type":"string"},"amountMinor":{"type":"object","nullable":true},"currency":{"type":"string"},"collectedAmountMinor":{"type":"string"},"successfulPayments":{"type":"number"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"expiresAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","slug","linkNumber","pageName","status","visibility","amountMinor","currency","collectedAmountMinor","successfulPayments","business","expiresAt","createdAt"]},"AdminPaymentLinkListResponse":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminPaymentLinkListItemResponse"}}},"required":["total","page","pageSize","environment","items"]},"AdminProductTransactionResponse":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"status":{"type":"string"},"amountMinor":{"type":"string"},"channel":{"type":"object","nullable":true},"providerReference":{"type":"object","nullable":true},"customerName":{"type":"object","nullable":true},"customerEmail":{"type":"object","nullable":true,"format":"email"},"customerPhone":{"type":"object","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","reference","status","amountMinor","channel","providerReference","customerName","customerEmail","customerPhone","createdAt","updatedAt"]},"AdminPaymentLinkDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"linkNumber":{"type":"object","nullable":true},"pageName":{"type":"string"},"status":{"type":"string"},"visibility":{"type":"string"},"amountMinor":{"type":"object","nullable":true},"currency":{"type":"string"},"collectedAmountMinor":{"type":"string"},"successfulPayments":{"type":"number"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"expiresAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"checkoutPath":{"type":"string"},"imageUrl":{"type":"object","nullable":true},"imageUrlExpiresAt":{"type":"object","nullable":true,"format":"date-time"},"customerFields":{"type":"object"},"allowedCustomers":{"type":"array","items":{"type":"object"}},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/AdminProductTransactionResponse"}}},"required":["id","slug","linkNumber","pageName","status","visibility","amountMinor","currency","collectedAmountMinor","successfulPayments","business","expiresAt","createdAt","checkoutPath","imageUrl","imageUrlExpiresAt","customerFields","allowedCustomers","transactions"]},"AdminSplitPayListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"linkNumber":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"method":{"type":"string"},"amountMinor":{"type":"string"},"collectedAmountMinor":{"type":"string"},"pendingAmountMinor":{"type":"string"},"currency":{"type":"string"},"paidParticipants":{"type":"number"},"totalParticipants":{"type":"number"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"dueAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","slug","linkNumber","title","status","method","amountMinor","collectedAmountMinor","pendingAmountMinor","currency","paidParticipants","totalParticipants","business","dueAt","createdAt"]},"AdminSplitPayListResponse":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminSplitPayListItemResponse"}}},"required":["total","page","pageSize","environment","items"]},"AdminSplitPayDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"linkNumber":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"method":{"type":"string"},"amountMinor":{"type":"string"},"collectedAmountMinor":{"type":"string"},"pendingAmountMinor":{"type":"string"},"currency":{"type":"string"},"paidParticipants":{"type":"number"},"totalParticipants":{"type":"number"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"dueAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"checkoutPath":{"type":"string"},"participants":{"description":"Full participant contact and payment progress; available only to authorized admin roles.","type":"array","items":{"type":"object"}},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/AdminProductTransactionResponse"}}},"required":["id","slug","linkNumber","title","status","method","amountMinor","collectedAmountMinor","pendingAmountMinor","currency","paidParticipants","totalParticipants","business","dueAt","createdAt","checkoutPath","participants","transactions"]},"AdminEventListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"eventCode":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"type":{"type":"string"},"currency":{"type":"string"},"grossAmountMinor":{"type":"string"},"ticketsSold":{"type":"number"},"successfulOrders":{"type":"number"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"startAt":{"type":"object","nullable":true,"format":"date-time"},"endAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","slug","eventCode","title","status","type","currency","grossAmountMinor","ticketsSold","successfulOrders","business","startAt","endAt","createdAt"]},"AdminEventListResponse":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminEventListItemResponse"}}},"required":["total","page","pageSize","environment","items"]},"AdminEventDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"eventCode":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"type":{"type":"string"},"currency":{"type":"string"},"grossAmountMinor":{"type":"string"},"ticketsSold":{"type":"number"},"successfulOrders":{"type":"number"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"startAt":{"type":"object","nullable":true,"format":"date-time"},"endAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"checkoutPath":{"type":"string"},"coverImageUrl":{"type":"object","nullable":true},"companyLogoUrl":{"type":"object","nullable":true},"tickets":{"type":"array","items":{"type":"object"}},"orders":{"description":"Recent ticket orders with customer identity, line items, and transaction outcome.","type":"array","items":{"type":"object"}}},"required":["id","slug","eventCode","title","status","type","currency","grossAmountMinor","ticketsSold","successfulOrders","business","startAt","endAt","createdAt","checkoutPath","coverImageUrl","companyLogoUrl","tickets","orders"]},"AdminStorefrontListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"totalProducts":{"type":"number"},"totalOrders":{"type":"number"},"successfulOrders":{"type":"number"},"grossAmountMinor":{"type":"string"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","slug","name","category","status","currency","totalProducts","totalOrders","successfulOrders","grossAmountMinor","business","createdAt","updatedAt"]},"AdminStorefrontListResponse":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminStorefrontListItemResponse"}}},"required":["total","page","pageSize","environment","items"]},"AdminStorefrontOrderListResponse":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"storefrontId":{"type":"string"},"items":{"type":"array","items":{"type":"object"}}},"required":["total","page","pageSize","environment","storefrontId","items"]},"AdminStorefrontOrderDetailResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"storefront":{"type":"object"},"order":{"type":"object"}},"required":["environment","storefront","order"]},"UpdateAdminStorefrontStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["PUBLISHED","DISABLED"],"description":"PUBLISHED restores a previously published storefront; it cannot publish a merchant draft."},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["status","reason"]},"AdminStorefrontDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"totalProducts":{"type":"number"},"totalOrders":{"type":"number"},"successfulOrders":{"type":"number"},"grossAmountMinor":{"type":"string"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"description":{"type":"object","nullable":true},"checkoutPath":{"type":"string"},"coverImageUrl":{"type":"object","nullable":true},"coverImageUrlExpiresAt":{"type":"object","nullable":true,"format":"date-time"},"publishedAt":{"type":"object","nullable":true,"format":"date-time"},"disabledAt":{"type":"object","nullable":true,"format":"date-time"},"products":{"type":"array","items":{"type":"object"}},"recentOrders":{"description":"The latest 50 orders with customer, delivery, line-item, and payment status details.","type":"array","items":{"type":"object"}}},"required":["id","slug","name","category","status","currency","totalProducts","totalOrders","successfulOrders","grossAmountMinor","business","createdAt","updatedAt","description","checkoutPath","coverImageUrl","coverImageUrlExpiresAt","publishedAt","disabledAt","products","recentOrders"]},"AdminInvoiceListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"invoiceNumber":{"type":"string"},"status":{"type":"string"},"customerName":{"type":"string"},"customerEmail":{"type":"string","format":"email"},"totalMinor":{"type":"string"},"currency":{"type":"string"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"dueAt":{"type":"string","nullable":true,"format":"date-time"},"paidAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","invoiceNumber","status","customerName","customerEmail","totalMinor","currency","business","dueAt","paidAt","createdAt","updatedAt"]},"AdminInvoiceListResponse":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminInvoiceListItemResponse"}}},"required":["total","page","pageSize","environment","items"]},"UpdateAdminInvoiceStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["PAID","OVERDUE"],"description":"PAID records an offline/manual resolution and does not credit a wallet."},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["status","reason"]},"AdminInvoiceDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"invoiceNumber":{"type":"string"},"status":{"type":"string"},"customerName":{"type":"string"},"customerEmail":{"type":"string","format":"email"},"totalMinor":{"type":"string"},"currency":{"type":"string"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"dueAt":{"type":"string","nullable":true,"format":"date-time"},"paidAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"description":{"type":"string","nullable":true},"subtotalMinor":{"type":"string"},"taxMinor":{"type":"string"},"discountMinor":{"type":"string"},"issuer":{"type":"object"},"billingAddress":{"type":"object","nullable":true},"items":{"type":"array","items":{"type":"object"}},"paymentLink":{"type":"object","nullable":true}},"required":["id","invoiceNumber","status","customerName","customerEmail","totalMinor","currency","business","dueAt","paidAt","createdAt","updatedAt","description","subtotalMinor","taxMinor","discountMinor","issuer","billingAddress","items","paymentLink"]},"AdminSubscriptionPlanListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"amountMinor":{"type":"string"},"currency":{"type":"string"},"billingCycle":{"type":"string"},"status":{"type":"string"},"subscriptions":{"type":"number"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","amountMinor","currency","billingCycle","status","subscriptions","business","createdAt","updatedAt"]},"AdminSubscriptionPlanListResponse":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminSubscriptionPlanListItemResponse"}}},"required":["total","page","pageSize","environment","items"]},"UpdateAdminSubscriptionPlanStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["status","reason"]},"AdminSubscriptionPlanDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"amountMinor":{"type":"string"},"currency":{"type":"string"},"billingCycle":{"type":"string"},"status":{"type":"string"},"subscriptions":{"type":"number"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"recentSubscriptions":{"description":"Recent subscriptions using this plan.","type":"array","items":{"type":"object"}}},"required":["id","name","description","amountMinor","currency","billingCycle","status","subscriptions","business","createdAt","updatedAt","recentSubscriptions"]},"AdminSubscriptionListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"subscriptionCode":{"type":"string"},"name":{"type":"string"},"planId":{"type":"string"},"planName":{"type":"string"},"amountMinor":{"type":"string"},"currency":{"type":"string"},"billingCycle":{"type":"string"},"status":{"type":"string"},"totalSubscribers":{"type":"number"},"activeSubscribers":{"type":"number"},"collectedAmountMinor":{"type":"string"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"startAt":{"type":"string","format":"date-time"},"nextBillingAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","subscriptionCode","name","planId","planName","amountMinor","currency","billingCycle","status","totalSubscribers","activeSubscribers","collectedAmountMinor","business","startAt","nextBillingAt","createdAt","updatedAt"]},"AdminSubscriptionListResponse":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminSubscriptionListItemResponse"}}},"required":["total","page","pageSize","environment","items"]},"AdminSubscriptionSubscriberListResponse":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"subscriptionId":{"type":"string"},"items":{"type":"array","items":{"type":"object"}}},"required":["total","page","pageSize","environment","subscriptionId","items"]},"UpdateAdminSubscriptionStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["ACTIVE","CANCELLED"],"description":"ACTIVE can restore a previously active subscription, but cannot activate a merchant draft."},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["status","reason"]},"AdminSubscriptionDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"subscriptionCode":{"type":"string"},"name":{"type":"string"},"planId":{"type":"string"},"planName":{"type":"string"},"amountMinor":{"type":"string"},"currency":{"type":"string"},"billingCycle":{"type":"string"},"status":{"type":"string"},"totalSubscribers":{"type":"number"},"activeSubscribers":{"type":"number"},"collectedAmountMinor":{"type":"string"},"business":{"$ref":"#/components/schemas/AdminProductBusinessResponse"},"startAt":{"type":"string","format":"date-time"},"nextBillingAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"description":{"type":"string","nullable":true},"autoRenewal":{"type":"boolean"},"renewalReminders":{"type":"boolean"},"allowPlanUpgrade":{"type":"boolean"},"plan":{"type":"object"},"progress":{"type":"object"},"recentSubscribers":{"type":"array","items":{"type":"object"}}},"required":["id","subscriptionCode","name","planId","planName","amountMinor","currency","billingCycle","status","totalSubscribers","activeSubscribers","collectedAmountMinor","business","startAt","nextBillingAt","createdAt","updatedAt","description","autoRenewal","renewalReminders","allowPlanUpgrade","plan","progress","recentSubscribers"]},"CreateAdminEmailBroadcastDto":{"type":"object","properties":{"audience":{"type":"string","enum":["SINGLE_EMAIL","SINGLE_BUSINESS","SINGLE_USER","ALL_BUSINESSES","ALL_USERS"]},"recipientEmail":{"type":"string","format":"email","description":"Required only for SINGLE_EMAIL."},"recipientName":{"type":"string","maxLength":160,"description":"Optional greeting name for SINGLE_EMAIL."},"merchantId":{"type":"string","maxLength":191,"description":"Required only for SINGLE_BUSINESS."},"userId":{"type":"string","maxLength":191,"description":"Required only for SINGLE_USER."},"subject":{"type":"string","minLength":2,"maxLength":150,"example":"Scheduled platform maintenance"},"message":{"type":"string","minLength":2,"maxLength":10000,"description":"Plain-text body or fallback. Required when htmlContent is omitted."},"htmlContent":{"type":"string","maxLength":100000,"description":"HTML produced by Summernote. The backend sanitizes it before storage or delivery. Required when message is omitted."},"attachmentIds":{"maxItems":5,"description":"READY attachment IDs created with the admin broadcast attachment upload endpoints. Combined size cannot exceed 10 MB.","type":"array","items":{"type":"string"}},"actionLabel":{"type":"string","maxLength":60,"example":"Open Creddot"},"actionUrl":{"type":"string","format":"uri","example":"https://app.creddot.com"},"includeInactive":{"type":"boolean","default":false,"description":"For ALL_USERS or ALL_BUSINESSES, include inactive, suspended, unverified, or closed records. Restricted to deliberate super-admin broadcasts."}},"required":["audience","subject"]},"AdminEmailBroadcastCreatorResponse":{"type":"object","properties":{"id":{"type":"string"},"fullName":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["id","fullName","email"]},"AdminEmailBroadcastResponse":{"type":"object","properties":{"id":{"type":"string"},"audience":{"type":"string","enum":["SINGLE_EMAIL","SINGLE_BUSINESS","SINGLE_USER","ALL_BUSINESSES","ALL_USERS"]},"subject":{"type":"string"},"message":{"type":"string"},"htmlContent":{"type":"object","nullable":true,"description":"Sanitized Summernote HTML. Null for plain-text broadcasts."},"attachments":{"example":[{"id":"attachment-id","filename":"notice.pdf","mimeType":"application/pdf","sizeBytes":125000,"status":"READY"}],"type":"array","items":{"type":"object"}},"actionLabel":{"type":"object","nullable":true},"actionUrl":{"type":"object","nullable":true,"format":"uri"},"status":{"type":"string","enum":["QUEUED","PROCESSING","COMPLETED","PARTIAL","FAILED"]},"recipientCount":{"type":"number"},"sentCount":{"type":"number"},"failedCount":{"type":"number"},"queuedCount":{"type":"number"},"workerEnabled":{"type":"boolean","description":"False when EMAIL_ENABLED is off; queued records remain durable until delivery is enabled."},"createdBy":{"$ref":"#/components/schemas/AdminEmailBroadcastCreatorResponse"},"startedAt":{"type":"object","nullable":true,"format":"date-time"},"completedAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","audience","subject","message","htmlContent","attachments","actionLabel","actionUrl","status","recipientCount","sentCount","failedCount","queuedCount","workerEnabled","startedAt","completedAt","createdAt","updatedAt"]},"CreateAdminEmailAttachmentUploadDto":{"type":"object","properties":{"filename":{"type":"string","example":"maintenance-notice.pdf","maxLength":180},"mimeType":{"type":"string","enum":["application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","text/csv","text/plain"]},"sizeBytes":{"type":"number","minimum":1,"maximum":10485760,"description":"Exact upload size. Each attachment is limited to 10 MB."}},"required":["filename","mimeType","sizeBytes"]},"AdminEmailAttachmentUploadResponse":{"type":"object","properties":{"attachmentId":{"type":"string"},"method":{"type":"string","enum":["PUT"]},"uploadUrl":{"type":"string","format":"uri"},"headers":{"type":"object","example":{"Content-Type":"application/pdf","Cache-Control":"private, no-store"}},"expiresAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["PENDING"]}},"required":["attachmentId","method","uploadUrl","headers","expiresAt","status"]},"AdminEmailAttachmentResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","READY","FAILED"]},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"},"broadcastId":{"type":"object","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","filename","mimeType","sizeBytes","broadcastId","createdAt","updatedAt"]},"AdminEmailAttachmentDownloadResponse":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","expiresAt"]},"AdminEmailBroadcastListResponse":{"type":"object","properties":{"workerEnabled":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminEmailBroadcastResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["workerEnabled","items","total","page","pageSize"]},"AdminEmailBroadcastRecipientResponse":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"displayName":{"type":"object","nullable":true},"sourceType":{"type":"string","enum":["DIRECT","BUSINESS","USER"]},"sourceId":{"type":"object","nullable":true},"status":{"type":"string","enum":["QUEUED","SENDING","SENT","FAILED"]},"attempts":{"type":"number"},"providerReference":{"type":"object","nullable":true},"simulated":{"type":"boolean"},"lastError":{"type":"object","nullable":true},"sentAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","email","displayName","sourceType","sourceId","status","attempts","providerReference","simulated","lastError","sentAt","createdAt","updatedAt"]},"AdminEmailBroadcastDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"audience":{"type":"string","enum":["SINGLE_EMAIL","SINGLE_BUSINESS","SINGLE_USER","ALL_BUSINESSES","ALL_USERS"]},"subject":{"type":"string"},"message":{"type":"string"},"htmlContent":{"type":"object","nullable":true,"description":"Sanitized Summernote HTML. Null for plain-text broadcasts."},"attachments":{"example":[{"id":"attachment-id","filename":"notice.pdf","mimeType":"application/pdf","sizeBytes":125000,"status":"READY"}],"type":"array","items":{"type":"object"}},"actionLabel":{"type":"object","nullable":true},"actionUrl":{"type":"object","nullable":true,"format":"uri"},"status":{"type":"string","enum":["QUEUED","PROCESSING","COMPLETED","PARTIAL","FAILED"]},"recipientCount":{"type":"number"},"sentCount":{"type":"number"},"failedCount":{"type":"number"},"queuedCount":{"type":"number"},"workerEnabled":{"type":"boolean","description":"False when EMAIL_ENABLED is off; queued records remain durable until delivery is enabled."},"createdBy":{"$ref":"#/components/schemas/AdminEmailBroadcastCreatorResponse"},"startedAt":{"type":"object","nullable":true,"format":"date-time"},"completedAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/AdminEmailBroadcastRecipientResponse"}},"recipientTotal":{"type":"number"},"recipientPage":{"type":"number"},"recipientPageSize":{"type":"number"}},"required":["id","audience","subject","message","htmlContent","attachments","actionLabel","actionUrl","status","recipientCount","sentCount","failedCount","queuedCount","workerEnabled","startedAt","completedAt","createdAt","updatedAt","recipients","recipientTotal","recipientPage","recipientPageSize"]},"AdminEmailBroadcastRetryResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["QUEUED"]},"queuedRecipients":{"type":"number"},"workerEnabled":{"type":"boolean","enum":[true]}},"required":["id","status","queuedRecipients","workerEnabled"]},"SplitPayParticipantInputDto":{"type":"object","properties":{"firstName":{"type":"string","example":"Akanji","maxLength":80},"lastName":{"type":"string","example":"Joseph","maxLength":80},"email":{"type":"string","example":"akanji@example.com","format":"email"},"phoneNumber":{"type":"string","example":"+2348012345678"},"amountMinor":{"type":"string","example":"16666700","description":"Required for DYNAMIC allocation. Omit for AUTO allocation."}},"required":["firstName","lastName"]},"CreateSplitPayDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"title":{"type":"string","example":"Boss Birthday","maxLength":160},"currency":{"type":"object","example":"NGN","default":"NGN"},"amountMinor":{"type":"string","example":"50000000","description":"Total target in positive integer minor units."},"method":{"type":"string","enum":["AUTO","DYNAMIC"],"description":"AUTO divides the target exactly across participants. DYNAMIC uses each participant amount."},"dueAt":{"format":"date-time","type":"string","example":"2026-12-10T23:59:59.000Z"},"participants":{"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/SplitPayParticipantInputDto"}}},"required":["title","amountMinor","method"]},"SplitPayProgressResponse":{"type":"object","properties":{"collectedAmountMinor":{"type":"string","example":"33333300"},"pendingAmountMinor":{"type":"string","example":"16666700"},"totalAmountMinor":{"type":"string","example":"50000000"},"percentageCompleted":{"type":"number","example":66.67},"paidParticipants":{"type":"number"},"totalParticipants":{"type":"number"},"successfulPayments":{"type":"number"}},"required":["collectedAmountMinor","pendingAmountMinor","totalAmountMinor","percentageCompleted","paidParticipants","totalParticipants","successfulPayments"]},"SplitPayParticipantResponse":{"type":"object","properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","nullable":true},"phoneNumber":{"type":"string","nullable":true},"amountMinor":{"type":"string","example":"16666700"},"paidAmountMinor":{"type":"string","example":"16666700"},"pendingAmountMinor":{"type":"string","example":"0"},"status":{"type":"string","enum":["PENDING","PROCESSING","PAID"]}},"required":["id","firstName","lastName","email","phoneNumber","amountMinor","paidAmountMinor","pendingAmountMinor","status"]},"SplitPayResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"slug":{"type":"string"},"linkNumber":{"type":"string","example":"SPL-0001"},"payCode":{"type":"string"},"title":{"type":"string"},"currency":{"type":"string"},"amountMinor":{"type":"string","example":"50000000"},"method":{"type":"string","enum":["AUTO","DYNAMIC"]},"status":{"type":"string","enum":["UNPAID","IN_PROGRESS","PAID","OVERDUE","DISABLED"]},"dueAt":{"type":"string","format":"date-time","nullable":true},"progress":{"$ref":"#/components/schemas/SplitPayProgressResponse"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/SplitPayParticipantResponse"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkoutPath":{"type":"string"}},"required":["id","environment","slug","linkNumber","payCode","title","currency","amountMinor","method","status","dueAt","progress","participants","createdAt","updatedAt","checkoutPath"]},"SplitPayRecentActivityResponse":{"type":"object","properties":{"transactionId":{"type":"string"},"participantId":{"type":"string","nullable":true},"customerName":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"amountMinor":{"type":"string"},"paidAt":{"type":"string","format":"date-time"}},"required":["transactionId","participantId","customerName","customerEmail","amountMinor","paidAt"]},"SplitPayDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"slug":{"type":"string"},"linkNumber":{"type":"string","example":"SPL-0001"},"payCode":{"type":"string"},"title":{"type":"string"},"currency":{"type":"string"},"amountMinor":{"type":"string","example":"50000000"},"method":{"type":"string","enum":["AUTO","DYNAMIC"]},"status":{"type":"string","enum":["UNPAID","IN_PROGRESS","PAID","OVERDUE","DISABLED"]},"dueAt":{"type":"string","format":"date-time","nullable":true},"progress":{"$ref":"#/components/schemas/SplitPayProgressResponse"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/SplitPayParticipantResponse"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkoutPath":{"type":"string"},"business":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}}},"recentActivity":{"type":"array","items":{"$ref":"#/components/schemas/SplitPayRecentActivityResponse"}}},"required":["id","environment","slug","linkNumber","payCode","title","currency","amountMinor","method","status","dueAt","progress","participants","createdAt","updatedAt","checkoutPath","business","recentActivity"]},"UpdateSplitPayDto":{"type":"object","properties":{"title":{"type":"string","example":"Boss Birthday","maxLength":160},"dueAt":{"type":"object","example":"2026-12-10T23:59:59.000Z","format":"date-time","nullable":true,"description":"Use null to remove the due date."}}},"AddSplitPayParticipantDto":{"type":"object","properties":{"firstName":{"type":"string","example":"Akanji","maxLength":80},"lastName":{"type":"string","example":"Joseph","maxLength":80},"email":{"type":"string","example":"akanji@example.com","format":"email"},"phoneNumber":{"type":"string","example":"+2348012345678"},"amountMinor":{"type":"string","example":"16666700","description":"Required for DYNAMIC allocation. Omit for AUTO allocation."}},"required":["firstName","lastName"]},"PublicSplitPayResponse":{"type":"object","properties":{"merchantName":{"type":"string"},"title":{"type":"string"},"currency":{"type":"string"},"amountMinor":{"type":"string"},"method":{"type":"string","enum":["AUTO","DYNAMIC"]},"status":{"type":"string","enum":["UNPAID","IN_PROGRESS","PAID","OVERDUE","DISABLED"]},"dueAt":{"type":"string","nullable":true,"format":"date-time"},"progress":{"$ref":"#/components/schemas/SplitPayProgressResponse"},"participants":{"description":"Contact details are masked on public checkout.","type":"array","items":{"$ref":"#/components/schemas/SplitPayParticipantResponse"}}},"required":["merchantName","title","currency","amountMinor","method","status","dueAt","progress","participants"]},"SplitPayMethodsResponse":{"type":"object","properties":{"merchantName":{"type":"string"},"title":{"type":"string"},"currency":{"type":"string"},"amountMinor":{"type":"string"},"method":{"type":"string","enum":["AUTO","DYNAMIC"]},"status":{"type":"string","enum":["UNPAID","IN_PROGRESS","PAID","OVERDUE","DISABLED"]},"dueAt":{"type":"string","nullable":true,"format":"date-time"},"progress":{"$ref":"#/components/schemas/SplitPayProgressResponse"},"participants":{"description":"Contact details are masked on public checkout.","type":"array","items":{"$ref":"#/components/schemas/SplitPayParticipantResponse"}},"methods":{"type":"array","items":{"type":"object"}},"supportedBanks":{"type":"array","items":{"type":"object"}}},"required":["merchantName","title","currency","amountMinor","method","status","dueAt","progress","participants","methods","supportedBanks"]},"PaySplitPayDto":{"type":"object","properties":{"channel":{"type":"string","enum":["BANK_TRANSFER","CARD","USSD","QR"],"example":"BANK_TRANSFER"},"participantId":{"type":"string","description":"Participant selected on the split checkout. Required when the split has assigned participants."},"amountMinor":{"type":"string","example":"16666700","description":"Optional partial participant contribution, or required amount for an unassigned shared split."},"customerName":{"type":"string","example":"Akanji Joseph","maxLength":120},"customerEmail":{"type":"string","example":"akanji@example.com","format":"email","description":"Required when the selected participant and request have no phone number."},"customerPhone":{"type":"string","example":"+2348012345678","description":"Required when the selected participant and request have no email address."},"bankCode":{"type":"string","example":"3E94C4BC-6F9A-442F-8F1A-8214478D5D86","description":"Required for USSD; use a Paga bank UUID from the methods endpoint."},"card":{"description":"Required when channel is CARD.","allOf":[{"$ref":"#/components/schemas/CardPaymentDto"}]}},"required":["channel"]},"SplitPayPaymentResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]},"reference":{"type":"string"},"amountMinor":{"type":"string","example":"500000"},"currency":{"type":"string","example":"NGN"},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"paymentUrl":{"type":"string","nullable":true,"format":"uri"},"paymentInstructions":{"type":"object","nullable":true,"example":{"type":"CARD_3DS","authenticationUrl":"https://api.cashonrails.com/auth-payer/example","authenticationMethod":"GET"},"description":"Method-specific checkout data. BANK_TRANSFER returns Paga account details; USSD returns a code; CARD returns Cashonrails 3DS authentication data; QR returns a Paga app link."},"requiresReconciliation":{"type":"boolean"},"feeMinor":{"type":"string","example":"1500"},"totalDebitMinor":{"type":"string","example":"100000"},"netCreditMinor":{"type":"string","example":"98500"}},"required":["id","transactionId","status","reference","amountMinor","currency","provider","providerReference","paymentUrl","paymentInstructions","requiresReconciliation","feeMinor","totalDebitMinor","netCreditMinor"]},"CreateEventDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"title":{"type":"string","example":"Lagos Design Conference","maxLength":160},"currency":{"type":"string","example":"NGN","default":"NGN"},"description":{"type":"string","maxLength":5000},"category":{"type":"string","example":"Conference","maxLength":80},"location":{"type":"string","example":"Eko Hotel, Lagos","maxLength":255},"redirectUrl":{"type":"string","example":"https://example.com/thank-you"},"coverImageFileId":{"type":"string","description":"READY PNG or JPEG uploaded using the business file API in the same environment."},"companyLogoFileId":{"type":"string","description":"READY PNG or JPEG uploaded using the business file API in the same environment."},"type":{"type":"string","enum":["SINGLE","RECURRING"],"default":"SINGLE"},"startAt":{"format":"date-time","type":"string"},"endAt":{"format":"date-time","type":"string"},"timezone":{"type":"string","example":"Africa/Lagos","maxLength":80},"recurrenceRule":{"type":"string","example":"FREQ=WEEKLY;BYDAY=SA","maxLength":191,"description":"Optional iCalendar recurrence rule for recurring events."}}},"EventSalesResponse":{"type":"object","properties":{"grossAmountMinor":{"type":"string"},"ticketsSold":{"type":"number"},"successfulOrders":{"type":"number"},"pendingOrders":{"type":"number"}},"required":["grossAmountMinor","ticketsSold","successfulOrders","pendingOrders"]},"EventTicketResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"priceMinor":{"type":"string"},"quantity":{"type":"number"},"reservedQuantity":{"type":"number"},"soldQuantity":{"type":"number"},"availableQuantity":{"type":"number"},"minPerOrder":{"type":"number"},"maxPerOrder":{"type":"number"},"active":{"type":"boolean"},"salesStartAt":{"type":"string","nullable":true,"format":"date-time"},"salesEndAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","name","description","priceMinor","quantity","reservedQuantity","soldQuantity","availableQuantity","minPerOrder","maxPerOrder","active","salesStartAt","salesEndAt"]},"EventDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"slug":{"type":"string"},"eventCode":{"type":"string"},"title":{"type":"string","nullable":true},"displayTitle":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","ENDED","CANCELLED"]},"type":{"type":"string","enum":["SINGLE","RECURRING"]},"sales":{"$ref":"#/components/schemas/EventSalesResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"coverImageFileId":{"type":"string","nullable":true},"coverImageUrl":{"type":"string","nullable":true,"format":"uri"},"coverImageUrlExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"companyLogoFileId":{"type":"string","nullable":true},"companyLogoUrl":{"type":"string","nullable":true,"format":"uri"},"companyLogoUrlExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"startAt":{"type":"string","nullable":true,"format":"date-time"},"endAt":{"type":"string","nullable":true,"format":"date-time"},"timezone":{"type":"string","nullable":true},"recurrenceRule":{"type":"string","nullable":true},"tickets":{"type":"array","items":{"$ref":"#/components/schemas/EventTicketResponse"}},"recentSales":{"type":"array","items":{"type":"object"}},"checkoutPath":{"type":"string"}},"required":["id","environment","slug","eventCode","title","displayTitle","currency","status","type","sales","createdAt","updatedAt","description","category","location","redirectUrl","coverImageFileId","coverImageUrl","coverImageUrlExpiresAt","companyLogoFileId","companyLogoUrl","companyLogoUrlExpiresAt","startAt","endAt","timezone","recurrenceRule","tickets","recentSales","checkoutPath"]},"UpdateEventDto":{"type":"object","properties":{"title":{"type":"string","example":"Lagos Design Conference","maxLength":160},"description":{"type":"string","maxLength":5000},"category":{"type":"string","example":"Conference","maxLength":80},"location":{"type":"string","example":"Eko Hotel, Lagos","maxLength":255},"redirectUrl":{"type":"string","example":"https://example.com/thank-you"},"coverImageFileId":{"type":"string","description":"READY PNG or JPEG uploaded using the business file API in the same environment."},"companyLogoFileId":{"type":"string","description":"READY PNG or JPEG uploaded using the business file API in the same environment."},"type":{"type":"string","enum":["SINGLE","RECURRING"],"default":"SINGLE"},"startAt":{"format":"date-time","type":"string"},"endAt":{"format":"date-time","type":"string"},"timezone":{"type":"string","example":"Africa/Lagos","maxLength":80},"recurrenceRule":{"type":"string","example":"FREQ=WEEKLY;BYDAY=SA","maxLength":191,"description":"Optional iCalendar recurrence rule for recurring events."},"currency":{"type":"string","example":"NGN"}}},"CreateEventTicketDto":{"type":"object","properties":{"name":{"type":"string","example":"General Admission","maxLength":120},"description":{"type":"string","maxLength":500},"priceMinor":{"type":"string","example":"2500000","description":"Positive ticket price in minor units."},"quantity":{"type":"number","minimum":1,"maximum":1000000},"minPerOrder":{"type":"number","default":1,"minimum":1},"maxPerOrder":{"type":"number","default":10,"minimum":1,"maximum":100},"salesStartAt":{"format":"date-time","type":"string"},"salesEndAt":{"format":"date-time","type":"string"}},"required":["name","priceMinor","quantity"]},"UpdateEventTicketDto":{"type":"object","properties":{"name":{"type":"string","example":"General Admission","maxLength":120},"description":{"type":"string","maxLength":500},"priceMinor":{"type":"string","example":"2500000","description":"Positive ticket price in minor units."},"quantity":{"type":"number","minimum":1,"maximum":1000000},"minPerOrder":{"type":"number","default":1,"minimum":1},"maxPerOrder":{"type":"number","default":10,"minimum":1,"maximum":100},"salesStartAt":{"format":"date-time","type":"string"},"salesEndAt":{"format":"date-time","type":"string"}}},"PublicEventResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"slug":{"type":"string"},"eventCode":{"type":"string"},"title":{"type":"string","nullable":true},"displayTitle":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","ENDED","CANCELLED"]},"type":{"type":"string","enum":["SINGLE","RECURRING"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"coverImageFileId":{"type":"string","nullable":true},"coverImageUrl":{"type":"string","nullable":true,"format":"uri"},"coverImageUrlExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"companyLogoFileId":{"type":"string","nullable":true},"companyLogoUrl":{"type":"string","nullable":true,"format":"uri"},"companyLogoUrlExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"startAt":{"type":"string","nullable":true,"format":"date-time"},"endAt":{"type":"string","nullable":true,"format":"date-time"},"timezone":{"type":"string","nullable":true},"recurrenceRule":{"type":"string","nullable":true},"tickets":{"type":"array","items":{"$ref":"#/components/schemas/EventTicketResponse"}},"checkoutPath":{"type":"string"},"merchantName":{"type":"string"}},"required":["id","environment","slug","eventCode","title","displayTitle","currency","status","type","createdAt","updatedAt","description","category","location","redirectUrl","coverImageFileId","coverImageUrl","coverImageUrlExpiresAt","companyLogoFileId","companyLogoUrl","companyLogoUrlExpiresAt","startAt","endAt","timezone","recurrenceRule","tickets","checkoutPath","merchantName"]},"EventMethodsResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"slug":{"type":"string"},"eventCode":{"type":"string"},"title":{"type":"string","nullable":true},"displayTitle":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","ENDED","CANCELLED"]},"type":{"type":"string","enum":["SINGLE","RECURRING"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"coverImageFileId":{"type":"string","nullable":true},"coverImageUrl":{"type":"string","nullable":true,"format":"uri"},"coverImageUrlExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"companyLogoFileId":{"type":"string","nullable":true},"companyLogoUrl":{"type":"string","nullable":true,"format":"uri"},"companyLogoUrlExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"startAt":{"type":"string","nullable":true,"format":"date-time"},"endAt":{"type":"string","nullable":true,"format":"date-time"},"timezone":{"type":"string","nullable":true},"recurrenceRule":{"type":"string","nullable":true},"tickets":{"type":"array","items":{"$ref":"#/components/schemas/EventTicketResponse"}},"checkoutPath":{"type":"string"},"merchantName":{"type":"string"},"methods":{"type":"array","items":{"type":"object"}},"supportedBanks":{"type":"array","items":{"type":"object"}}},"required":["id","environment","slug","eventCode","title","displayTitle","currency","status","type","createdAt","updatedAt","description","category","location","redirectUrl","coverImageFileId","coverImageUrl","coverImageUrlExpiresAt","companyLogoFileId","companyLogoUrl","companyLogoUrlExpiresAt","startAt","endAt","timezone","recurrenceRule","tickets","checkoutPath","merchantName","methods","supportedBanks"]},"EventOrderItemDto":{"type":"object","properties":{"ticketId":{"type":"string"},"quantity":{"type":"number","minimum":1,"maximum":100}},"required":["ticketId","quantity"]},"PayEventDto":{"type":"object","properties":{"channel":{"type":"string","enum":["BANK_TRANSFER","CARD","USSD","QR"]},"items":{"minItems":1,"maxItems":20,"type":"array","items":{"$ref":"#/components/schemas/EventOrderItemDto"}},"customerName":{"type":"string","example":"Akanji Joseph","maxLength":120},"customerEmail":{"type":"string","example":"akanji@example.com","format":"email"},"customerPhone":{"type":"string","example":"+2348012345678"},"bankCode":{"type":"string","description":"Required for USSD; use the Paga bank UUID returned by the methods endpoint."},"card":{"description":"Required when channel is CARD.","allOf":[{"$ref":"#/components/schemas/CardPaymentDto"}]}},"required":["channel","items","customerName","customerEmail"]},"EventPaymentResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]},"reference":{"type":"string"},"amountMinor":{"type":"string","example":"500000"},"currency":{"type":"string","example":"NGN"},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"paymentUrl":{"type":"string","nullable":true,"format":"uri"},"paymentInstructions":{"type":"object","nullable":true,"example":{"type":"CARD_3DS","authenticationUrl":"https://api.cashonrails.com/auth-payer/example","authenticationMethod":"GET"},"description":"Method-specific checkout data. BANK_TRANSFER returns Paga account details; USSD returns a code; CARD returns Cashonrails 3DS authentication data; QR returns a Paga app link."},"requiresReconciliation":{"type":"boolean"},"feeMinor":{"type":"string","example":"1500"},"totalDebitMinor":{"type":"string","example":"100000"},"netCreditMinor":{"type":"string","example":"98500"}},"required":["id","transactionId","status","reference","amountMinor","currency","provider","providerReference","paymentUrl","paymentInstructions","requiresReconciliation","feeMinor","totalDebitMinor","netCreditMinor"]},"StorefrontSummaryResponse":{"type":"object","properties":{"totalStores":{"type":"number"},"totalSalesMinor":{"type":"string"},"orders":{"type":"number"},"published":{"type":"number"}},"required":["totalStores","totalSalesMinor","orders","published"]},"StorefrontSocialLinkResponse":{"type":"object","properties":{"platform":{"type":"string","enum":["WHATSAPP","FACEBOOK","INSTAGRAM","LINKEDIN","X","TIKTOK"]},"url":{"type":"string","format":"uri"},"enabled":{"type":"boolean"}},"required":["platform","url","enabled"]},"StorefrontSalesResponse":{"type":"object","properties":{"totalSalesMinor":{"type":"string"},"totalOrders":{"type":"number"},"completedOrders":{"type":"number"},"pendingOrders":{"type":"number"}},"required":["totalSalesMinor","totalOrders","completedOrders","pendingOrders"]},"StorefrontResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","DISABLED"]},"description":{"type":"string","nullable":true},"coverImageFileId":{"type":"string","nullable":true},"coverImageUrl":{"type":"string","format":"uri","nullable":true},"coverImageUrlExpiresAt":{"type":"string","format":"date-time","nullable":true},"contactPhone":{"type":"string","nullable":true},"contactEmail":{"type":"string","nullable":true},"socialLinks":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontSocialLinkResponse"}},"checkoutPath":{"type":"string"},"totalProducts":{"type":"number"},"sales":{"$ref":"#/components/schemas/StorefrontSalesResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","environment","slug","name","category","currency","status","description","coverImageFileId","coverImageUrl","coverImageUrlExpiresAt","contactPhone","contactEmail","socialLinks","checkoutPath","totalProducts","sales","createdAt","updatedAt"]},"StorefrontProductVariantResponse":{"type":"object","properties":{"id":{"type":"string"},"color":{"type":"string","nullable":true},"size":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"additionalPriceMinor":{"type":"string"},"stockQuantity":{"type":"number"},"reservedQuantity":{"type":"number"},"soldQuantity":{"type":"number"},"availableQuantity":{"type":"number","nullable":true},"active":{"type":"boolean"}},"required":["id","color","size","name","sku","additionalPriceMinor","stockQuantity","reservedQuantity","soldQuantity","availableQuantity","active"]},"StorefrontProductImageResponse":{"type":"object","properties":{"fileId":{"type":"string"},"sortOrder":{"type":"number"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}},"required":["fileId","sortOrder","url","expiresAt"]},"StorefrontProductResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string","nullable":true},"priceMinor":{"type":"string"},"sku":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PUBLISHED","OUT_OF_STOCK","ARCHIVED"]},"stockQuantity":{"type":"number"},"reservedQuantity":{"type":"number"},"soldQuantity":{"type":"number"},"availableQuantity":{"type":"number","nullable":true},"trackInventory":{"type":"boolean"},"lowStockAlert":{"type":"boolean"},"lowStockThreshold":{"type":"number"},"lowStock":{"type":"boolean"},"featured":{"type":"boolean"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductVariantResponse"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductImageResponse"}},"primaryImageUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","slug","name","category","description","priceMinor","sku","status","stockQuantity","reservedQuantity","soldQuantity","availableQuantity","trackInventory","lowStockAlert","lowStockThreshold","lowStock","featured","variants","images","primaryImageUrl","createdAt","updatedAt"]},"StorefrontOrderItemResponse":{"type":"object","properties":{"productId":{"type":"string"},"variantId":{"type":"string","nullable":true},"productName":{"type":"string"},"variantName":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"quantity":{"type":"number"},"unitAmountMinor":{"type":"string"},"totalAmountMinor":{"type":"string"},"imageUrl":{"type":"string","format":"uri","nullable":true}},"required":["productId","variantId","productName","variantName","sku","quantity","unitAmountMinor","totalAmountMinor","imageUrl"]},"StorefrontOrderResponse":{"type":"object","properties":{"id":{"type":"string"},"orderCode":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","CANCELLED"]},"customerName":{"type":"string"},"customerEmail":{"type":"string"},"customerPhone":{"type":"string","nullable":true},"totalQuantity":{"type":"number"},"subtotalAmountMinor":{"type":"string"},"totalAmountMinor":{"type":"string"},"currency":{"type":"string"},"paymentMethod":{"type":"string","nullable":true},"paymentReference":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontOrderItemResponse"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","orderCode","status","customerName","customerEmail","customerPhone","totalQuantity","subtotalAmountMinor","totalAmountMinor","currency","paymentMethod","paymentReference","items","createdAt","updatedAt"]},"StorefrontSocialLinkDto":{"type":"object","properties":{"platform":{"type":"string","enum":["WHATSAPP","FACEBOOK","INSTAGRAM","LINKEDIN","X","TIKTOK"]},"url":{"type":"string","example":"https://instagram.com/joestore","maxLength":255,"description":"https link to the seller's page (WhatsApp: https://wa.me/234…)."},"enabled":{"type":"boolean","default":true,"description":"Only enabled links are shown on the public store."}},"required":["platform","url"]},"CreateStorefrontDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"name":{"type":"string","example":"Joe Store","maxLength":120},"slug":{"type":"string","example":"joe-store","description":"Public URL slug. Lowercase letters, numbers, and single hyphens only."},"category":{"type":"string","example":"Electronics","maxLength":80},"description":{"type":"string","maxLength":5000},"currency":{"type":"string","example":"NGN","default":"NGN"},"coverImageFileId":{"type":"string","description":"READY PNG or JPEG uploaded through the business file API in the same environment."},"contactPhone":{"type":"string","example":"+2348012345678","description":"Seller phone shown on the public store (E.164)."},"contactEmail":{"type":"string","format":"email","maxLength":191,"description":"Seller email shown on the public store."},"socialLinks":{"maxItems":6,"description":"One link per platform.","type":"array","items":{"$ref":"#/components/schemas/StorefrontSocialLinkDto"}}},"required":["name","slug","category"]},"StorefrontDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["DRAFT","PUBLISHED","DISABLED"]},"description":{"type":"string","nullable":true},"coverImageFileId":{"type":"string","nullable":true},"coverImageUrl":{"type":"string","format":"uri","nullable":true},"coverImageUrlExpiresAt":{"type":"string","format":"date-time","nullable":true},"contactPhone":{"type":"string","nullable":true},"contactEmail":{"type":"string","nullable":true},"socialLinks":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontSocialLinkResponse"}},"checkoutPath":{"type":"string"},"totalProducts":{"type":"number"},"sales":{"$ref":"#/components/schemas/StorefrontSalesResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"products":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductResponse"}}},"required":["id","environment","slug","name","category","currency","status","description","coverImageFileId","coverImageUrl","coverImageUrlExpiresAt","contactPhone","contactEmail","socialLinks","checkoutPath","totalProducts","sales","createdAt","updatedAt","products"]},"UpdateStorefrontDto":{"type":"object","properties":{"name":{"type":"string","example":"Joe Store","maxLength":120},"slug":{"type":"string","example":"joe-store","description":"Public URL slug. Lowercase letters, numbers, and single hyphens only."},"category":{"type":"string","example":"Electronics","maxLength":80},"currency":{"type":"string","example":"NGN","default":"NGN"},"socialLinks":{"maxItems":6,"description":"One link per platform.","type":"array","items":{"$ref":"#/components/schemas/StorefrontSocialLinkDto"}},"description":{"type":"string","nullable":true},"coverImageFileId":{"type":"string","nullable":true},"contactPhone":{"type":"string","nullable":true,"example":"+2348012345678","description":"null removes it."},"contactEmail":{"type":"string","nullable":true,"format":"email","description":"null removes it."}}},"StorefrontProductVariantDto":{"type":"object","properties":{"id":{"type":"string","description":"Supply an existing variant ID when replacing variants during an update."},"color":{"type":"string","example":"Black","maxLength":60},"size":{"type":"string","example":"Medium","maxLength":60},"name":{"type":"string","example":"Black / Medium","maxLength":120},"sku":{"type":"string","example":"WH-BLK-M","maxLength":80},"additionalPriceMinor":{"type":"string","example":"0","default":"0"},"stockQuantity":{"type":"number","minimum":0,"maximum":100000000},"active":{"type":"boolean","default":true}},"required":["stockQuantity"]},"CreateStorefrontProductDto":{"type":"object","properties":{"name":{"type":"string","example":"Wireless Headphones","maxLength":160},"slug":{"type":"string","example":"wireless-headphones","description":"Generated from name when omitted."},"category":{"type":"string","example":"Electronics","maxLength":80},"description":{"type":"string","maxLength":5000},"priceMinor":{"type":"string","example":"4500000"},"sku":{"type":"string","example":"SKU-WH-001","maxLength":80},"stockQuantity":{"type":"number","default":0,"minimum":0,"maximum":100000000},"trackInventory":{"type":"boolean","default":true},"lowStockAlert":{"type":"boolean","default":false},"lowStockThreshold":{"type":"number","default":5,"minimum":0},"featured":{"type":"boolean","default":false},"status":{"type":"string","enum":["DRAFT","PUBLISHED"],"default":"PUBLISHED"},"variants":{"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductVariantDto"}},"imageFileIds":{"maxItems":5,"description":"Ordered READY PNG/JPEG file IDs from the same business and environment.","type":"array","items":{"type":"string"}}},"required":["name","category","priceMinor"]},"UpdateStorefrontProductDto":{"type":"object","properties":{"name":{"type":"string","example":"Wireless Headphones","maxLength":160},"slug":{"type":"string","example":"wireless-headphones","description":"Generated from name when omitted."},"category":{"type":"string","example":"Electronics","maxLength":80},"description":{"type":"string","maxLength":5000},"priceMinor":{"type":"string","example":"4500000"},"sku":{"type":"string","example":"SKU-WH-001","maxLength":80},"stockQuantity":{"type":"number","default":0,"minimum":0,"maximum":100000000},"trackInventory":{"type":"boolean","default":true},"lowStockAlert":{"type":"boolean","default":false},"lowStockThreshold":{"type":"number","default":5,"minimum":0},"featured":{"type":"boolean","default":false},"status":{"type":"string","enum":["DRAFT","PUBLISHED"],"default":"PUBLISHED"},"variants":{"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductVariantDto"}},"imageFileIds":{"maxItems":5,"description":"Ordered READY PNG/JPEG file IDs from the same business and environment.","type":"array","items":{"type":"string"}}}},"PublicStorefrontResponse":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string","nullable":true},"currency":{"type":"string"},"merchantName":{"type":"string"},"contactPhone":{"type":"string","nullable":true},"contactEmail":{"type":"string","nullable":true},"socialLinks":{"description":"Enabled links only.","type":"array","items":{"$ref":"#/components/schemas/StorefrontSocialLinkResponse"}},"coverImageUrl":{"type":"string","format":"uri","nullable":true},"coverImageUrlExpiresAt":{"type":"string","format":"date-time","nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductResponse"}}},"required":["id","slug","name","category","description","currency","merchantName","contactPhone","contactEmail","socialLinks","coverImageUrl","coverImageUrlExpiresAt","products"]},"StorefrontPaymentMethodResponse":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"availability":{"type":"string","enum":["AVAILABLE","UNAVAILABLE"]},"provider":{"type":"string","nullable":true},"channel":{"type":"string","nullable":true}},"required":["id","label","availability","provider","channel"]},"StorefrontBankResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ussdCode":{"type":"string","nullable":true}},"required":["id","name","ussdCode"]},"StorefrontCheckoutMethodsResponse":{"type":"object","properties":{"methods":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontPaymentMethodResponse"}},"supportedBanks":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontBankResponse"}}},"required":["methods","supportedBanks"]},"StorefrontOrderItemDto":{"type":"object","properties":{"productId":{"type":"string"},"variantId":{"type":"string"},"quantity":{"type":"number","minimum":1,"maximum":1000}},"required":["productId","quantity"]},"CreateStorefrontOrderDto":{"type":"object","properties":{"channel":{"type":"string","enum":["BANK_TRANSFER","CARD","USSD","QR"]},"items":{"minItems":1,"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/StorefrontOrderItemDto"}},"customerName":{"type":"string","maxLength":120},"customerEmail":{"type":"string","format":"email"},"customerPhone":{"type":"string"},"deliveryAddressLine1":{"type":"string"},"deliveryAddressLine2":{"type":"string"},"deliveryCity":{"type":"string"},"deliveryState":{"type":"string"},"deliveryPostalCode":{"type":"string"},"deliveryCountryCode":{"type":"string","example":"NG"},"bankCode":{"type":"string","description":"Required for USSD. Use a bank ID returned by the methods endpoint."},"card":{"description":"Required when channel is CARD.","allOf":[{"$ref":"#/components/schemas/CardPaymentDto"}]}},"required":["channel","items","customerName","customerEmail"]},"StorefrontCheckoutResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"]},"reference":{"type":"string"},"amountMinor":{"type":"string","example":"500000"},"currency":{"type":"string","example":"NGN"},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"paymentUrl":{"type":"string","nullable":true,"format":"uri"},"paymentInstructions":{"type":"object","nullable":true,"example":{"type":"CARD_3DS","authenticationUrl":"https://api.cashonrails.com/auth-payer/example","authenticationMethod":"GET"},"description":"Method-specific checkout data. BANK_TRANSFER returns Paga account details; USSD returns a code; CARD returns Cashonrails 3DS authentication data; QR returns a Paga app link."},"requiresReconciliation":{"type":"boolean"},"feeMinor":{"type":"string","example":"1500"},"totalDebitMinor":{"type":"string","example":"100000"},"netCreditMinor":{"type":"string","example":"98500"},"orderCode":{"type":"string"}},"required":["id","transactionId","status","reference","amountMinor","currency","provider","providerReference","paymentUrl","paymentInstructions","requiresReconciliation","feeMinor","totalDebitMinor","netCreditMinor","orderCode"]},"SettingsProfileResponse":{"type":"object","properties":{"identifier":{"type":"string"},"organizationSlug":{"type":"string"},"organizationName":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"phoneNumber":{"type":"object","nullable":true},"countryCode":{"type":"string"},"logoFileId":{"type":"object","nullable":true},"logoUrl":{"type":"object","nullable":true,"format":"uri"}},"required":["identifier","organizationSlug","organizationName","firstName","lastName","email","phoneNumber","countryCode","logoFileId","logoUrl"]},"UpdateSettingsProfileDto":{"type":"object","properties":{"organizationName":{"type":"string","maxLength":120},"organizationSlug":{"type":"string","example":"meatyshop-global"},"firstName":{"type":"string","maxLength":60},"lastName":{"type":"string","maxLength":60},"email":{"type":"string","format":"email"},"phoneNumber":{"type":"string","example":"+2348012345678"},"countryCode":{"type":"string","example":"NG"},"logoFileId":{"type":"object","nullable":true,"description":"READY PNG/JPEG file in this business; null removes the logo."}}},"CloseBusinessDto":{"type":"object","properties":{"confirmation":{"type":"string","description":"Exact organization name."},"password":{"type":"string","writeOnly":true}},"required":["confirmation","password"]},"PasskeyResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"deviceType":{"type":"object","nullable":true},"backedUp":{"type":"boolean"},"lastUsedAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","deviceType","backedUp","lastUsedAt","createdAt"]},"SecuritySettingsResponse":{"type":"object","properties":{"passwordConfigured":{"type":"boolean"},"twoFactorEnabled":{"type":"boolean"},"twoFactorEnabledAt":{"type":"object","nullable":true,"format":"date-time"},"passkeys":{"type":"array","items":{"$ref":"#/components/schemas/PasskeyResponse"}}},"required":["passwordConfigured","twoFactorEnabled","twoFactorEnabledAt","passkeys"]},"ChangePasswordDto":{"type":"object","properties":{"currentPassword":{"type":"string","writeOnly":true},"newPassword":{"type":"string","writeOnly":true,"minLength":8},"confirmPassword":{"type":"string","writeOnly":true}},"required":["currentPassword","newPassword","confirmPassword"]},"TwoFactorSetupResponse":{"type":"object","properties":{"secret":{"type":"string","writeOnly":true},"provisioningUri":{"type":"string","writeOnly":true},"qrCodeDataUrl":{"type":"string","writeOnly":true}},"required":["secret","provisioningUri","qrCodeDataUrl"]},"TwoFactorCodeDto":{"type":"object","properties":{"code":{"type":"string","example":"123456"}},"required":["code"]},"TwoFactorEnabledResponse":{"type":"object","properties":{"enabled":{"type":"boolean"},"recoveryCodes":{"writeOnly":true,"description":"Shown once.","type":"array","items":{"type":"string"}}},"required":["enabled","recoveryCodes"]},"DisableTwoFactorDto":{"type":"object","properties":{"password":{"type":"string","writeOnly":true},"code":{"type":"string","description":"Authenticator code or unused recovery code."}},"required":["password","code"]},"VerifyPasskeyRegistrationDto":{"type":"object","properties":{"challengeId":{"type":"string"},"name":{"type":"string","maxLength":120},"response":{"type":"object","additionalProperties":true}},"required":["challengeId","name","response"]},"ComplianceSettingsResponse":{"type":"object","properties":{"organizationName":{"type":"string"},"registrationType":{"type":"string"},"description":{"type":"object","nullable":true},"businessEmail":{"type":"string"},"phoneNumber":{"type":"object","nullable":true},"websiteUrl":{"type":"object","nullable":true},"facebookHandle":{"type":"object","nullable":true},"instagramHandle":{"type":"object","nullable":true},"accountName":{"type":"object","nullable":true},"bankName":{"type":"object","nullable":true},"documentKinds":{"type":"array","items":{"type":"string"}},"directors":{"type":"array","items":{"type":"string"}},"beneficialOwners":{"type":"array","items":{"type":"string"}},"contractingEntity":{"type":"string"},"agreementStatus":{"type":"string"},"kycStatus":{"type":"string"}},"required":["organizationName","registrationType","description","businessEmail","phoneNumber","websiteUrl","facebookHandle","instagramHandle","accountName","bankName","documentKinds","directors","beneficialOwners","contractingEntity","agreementStatus","kycStatus"]},"UpdateComplianceProfileDto":{"type":"object","properties":{"businessEmail":{"type":"string","format":"email"},"phoneNumber":{"type":"string","example":"+2348012345678"},"websiteUrl":{"type":"object","format":"uri","nullable":true},"facebookHandle":{"type":"object","nullable":true},"instagramHandle":{"type":"object","nullable":true}}},"PayoutSettingsResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"schedule":{"type":"string","enum":["NEXT_DAY","DAILY","WEEKLY","MANUAL"]},"account":{"type":"object","nullable":true,"additionalProperties":true}},"required":["environment","schedule","account"]},"UpdatePayoutAccountDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"currency":{"type":"string","example":"NGN"},"bankCode":{"type":"string","maxLength":64},"accountNumber":{"type":"string","example":"0123456789"},"bankName":{"type":"string","maxLength":160}},"required":["currency","bankCode","accountNumber"]},"UpdatePayoutScheduleDto":{"type":"object","properties":{"schedule":{"type":"string","enum":["NEXT_DAY","DAILY","WEEKLY","MANUAL"]}},"required":["schedule"]},"PreferencesResponse":{"type":"object","properties":{"defaultCurrency":{"type":"string"},"acceptedPaymentMethods":{"type":"array","items":{"type":"string"}},"receiptToMerchant":{"type":"boolean"},"receiptToCustomer":{"type":"boolean"},"virtualAccountNameMode":{"type":"string"},"lowBalanceCurrency":{"type":"string"},"lowBalanceSmsEnabled":{"type":"boolean"},"lowBalanceEmailEnabled":{"type":"boolean"},"lowBalanceWarningMinor":{"type":"string"},"lowBalanceCriticalMinor":{"type":"string"}},"required":["defaultCurrency","acceptedPaymentMethods","receiptToMerchant","receiptToCustomer","virtualAccountNameMode","lowBalanceCurrency","lowBalanceSmsEnabled","lowBalanceEmailEnabled","lowBalanceWarningMinor","lowBalanceCriticalMinor"]},"UpdatePreferencesDto":{"type":"object","properties":{"defaultCurrency":{"type":"string","example":"NGN"},"acceptedPaymentMethods":{"type":"array","items":{"type":"string","enum":["BANK","CARD","USSD","STABLECOIN","BANK_TRANSFER","SPLIT_PAYMENT","QR","CREDDOT"]}},"receiptToMerchant":{"type":"boolean"},"receiptToCustomer":{"type":"boolean"},"virtualAccountNameMode":{"type":"string","enum":["CREDDOT_CHECKOUT","TRADING_NAME"]},"lowBalanceCurrency":{"type":"string","example":"NGN"},"lowBalanceSmsEnabled":{"type":"boolean"},"lowBalanceEmailEnabled":{"type":"boolean"},"lowBalanceWarningMinor":{"type":"string","example":"100000"},"lowBalanceCriticalMinor":{"type":"string","example":"50000"}}},"InviteTeamMemberDto":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["ADMIN","DEVELOPER","FINANCE","SUPPORT","VIEWER"]},"customRoleId":{"type":"string","description":"Custom role ID. Send either role or customRoleId."}},"required":["email"]},"UpdateTeamMemberDto":{"type":"object","properties":{"role":{"type":"string","enum":["ADMIN","DEVELOPER","FINANCE","SUPPORT","VIEWER"]},"customRoleId":{"type":"string","description":"Custom role ID. Send either role or customRoleId."}}},"CreateCustomRoleDto":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name","permissions"]},"CustomRoleResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"memberCount":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","permissions","memberCount","createdAt","updatedAt"]},"UpdateCustomRoleDto":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"permissions":{"type":"array","items":{"type":"string"}}}},"AssignCustomRoleMemberDto":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]},"ApiKeyResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"environment":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"type":"object","nullable":true,"format":"date-time"},"expiresAt":{"type":"object","nullable":true,"format":"date-time"},"revokedAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","keyPrefix","environment","permissions","lastUsedAt","expiresAt","revokedAt","createdAt"]},"DeveloperSettingsResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"apiKeys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyResponse"}},"webhookEndpoint":{"type":"object","nullable":true,"additionalProperties":true},"ipWhitelists":{"type":"array","items":{"type":"object"}},"callbackUrl":{"type":"object","nullable":true,"format":"uri"},"primaryApiKey":{"type":"object","nullable":true,"additionalProperties":true}},"required":["environment","apiKeys","webhookEndpoint","ipWhitelists","callbackUrl","primaryApiKey"]},"DeveloperOverviewResponse":{"type":"object","properties":{"liveModeAvailable":{"type":"boolean"},"sandbox":{"$ref":"#/components/schemas/DeveloperSettingsResponse"},"live":{"$ref":"#/components/schemas/DeveloperSettingsResponse"}},"required":["liveModeAvailable","sandbox","live"]},"CreateApiKeyDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"name":{"type":"string","maxLength":120},"permissions":{"type":"array","items":{"type":"string","enum":["collections:create","payouts:create","bills:read","bills:create","transactions:read","wallets:read","sandbox:simulate","virtual-accounts:read","customers:read","customers:manage","payment-links:read","payment-links:manage","invoices:read","invoices:manage","subscriptions:read","subscriptions:manage","refunds:read","refunds:create"]}},"expiresAt":{"type":"object","format":"date-time","nullable":true}},"required":["name","permissions"]},"CreatedApiKeyResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"environment":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"type":"object","nullable":true,"format":"date-time"},"expiresAt":{"type":"object","nullable":true,"format":"date-time"},"revokedAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"apiKey":{"type":"string","writeOnly":true,"description":"Shown once."},"apiSecret":{"type":"string","writeOnly":true,"description":"Shown once."}},"required":["id","name","keyPrefix","environment","permissions","lastUsedAt","expiresAt","revokedAt","createdAt","apiKey","apiSecret"]},"RevealApiKeyDto":{"type":"object","properties":{"password":{"type":"string","writeOnly":true},"twoFactorCode":{"type":"string","description":"Required when the signed-in user has 2FA enabled."}},"required":["password"]},"UpdateDeveloperCallbackDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"callbackUrl":{"type":"object","format":"uri","nullable":true}}},"UpdateWebhookStateDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"active":{"type":"boolean"}},"required":["active"]},"CreateIpWhitelistDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"cidr":{"type":"string","example":"203.0.113.10/32"},"label":{"type":"string","maxLength":120}},"required":["cidr"]},"ReplaceIpWhitelistsDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"cidrs":{"example":["192.168.1.1","203.0.113.0/24"],"type":"array","items":{"type":"string"}}},"required":["cidrs"]},"InvitationTokenDto":{"type":"object","properties":{"token":{"type":"string","minLength":43}},"required":["token"]},"InvitationInspectionResponse":{"type":"object","properties":{"invitationId":{"type":"string"},"businessName":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"customRoleId":{"type":"object","nullable":true},"roleName":{"type":"string"},"existingAccount":{"type":"boolean"},"expiresAt":{"type":"string","format":"date-time"}},"required":["invitationId","businessName","email","role","customRoleId","roleName","existingAccount","expiresAt"]},"AcceptMerchantInvitationDto":{"type":"object","properties":{"token":{"type":"string","minLength":43},"firstName":{"type":"string","maxLength":60},"lastName":{"type":"string","maxLength":60},"password":{"type":"string","writeOnly":true},"confirmPassword":{"type":"string","writeOnly":true}},"required":["token"]},"CustomerListItemResponse":{"type":"object","properties":{"id":{"type":"string"},"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phoneNumber":{"type":"object","nullable":true},"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","customerId","name","email","phoneNumber","status","createdAt"]},"CustomerListResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"summary":{"type":"object","example":{"total":20,"active":18,"disabled":2}},"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomerListItemResponse"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}},"required":["environment","summary","items","total","page","pageSize"]},"CreateCustomerDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"firstName":{"type":"string","example":"Akanji","maxLength":80},"lastName":{"type":"string","example":"Joseph","maxLength":80},"email":{"type":"string","format":"email","example":"akanji@example.com"},"phoneNumber":{"type":"object","example":"+23480987654321","nullable":true},"billingAddressLine1":{"type":"object","maxLength":255,"nullable":true},"billingAddressLine2":{"type":"object","maxLength":255,"nullable":true},"billingCity":{"type":"object","maxLength":120,"nullable":true},"billingState":{"type":"object","maxLength":120,"nullable":true},"billingPostalCode":{"type":"object","maxLength":32,"nullable":true},"billingCountryCode":{"type":"object","example":"NG","nullable":true}},"required":["firstName","lastName","email"]},"CustomerResponse":{"type":"object","properties":{"id":{"type":"string"},"customerId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phoneNumber":{"type":"object","nullable":true},"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"billingAddress":{"type":"object"},"disabledAt":{"type":"object","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","customerId","firstName","lastName","name","email","phoneNumber","status","environment","billingAddress","disabledAt","createdAt","updatedAt"]},"UpdateCustomerDto":{"type":"object","properties":{"firstName":{"type":"string","maxLength":80},"lastName":{"type":"string","maxLength":80},"email":{"type":"string","format":"email"},"phoneNumber":{"type":"object","nullable":true},"billingAddressLine1":{"type":"object","maxLength":255,"nullable":true},"billingAddressLine2":{"type":"object","maxLength":255,"nullable":true},"billingCity":{"type":"object","maxLength":120,"nullable":true},"billingState":{"type":"object","maxLength":120,"nullable":true},"billingPostalCode":{"type":"object","maxLength":32,"nullable":true},"billingCountryCode":{"type":"object","nullable":true}}},"UpdateCustomerStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["ACTIVE","DISABLED"]}},"required":["status"]},"CreateMerchantCustomerDto":{"type":"object","properties":{"firstName":{"type":"string","example":"Akanji","maxLength":80},"lastName":{"type":"string","example":"Joseph","maxLength":80},"email":{"type":"string","format":"email","example":"akanji@example.com"},"phoneNumber":{"type":"object","example":"+23480987654321","nullable":true},"billingAddressLine1":{"type":"object","maxLength":255,"nullable":true},"billingAddressLine2":{"type":"object","maxLength":255,"nullable":true},"billingCity":{"type":"object","maxLength":120,"nullable":true},"billingState":{"type":"object","maxLength":120,"nullable":true},"billingPostalCode":{"type":"object","maxLength":32,"nullable":true},"billingCountryCode":{"type":"object","example":"NG","nullable":true}},"required":["firstName","lastName","email"]},"SubscriptionPlanResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"name":{"type":"string"},"description":{"type":"string","nullable":true},"amountMinor":{"type":"string"},"currency":{"type":"string"},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"]},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"features":{"description":"What's included (up to 8 lines).","type":"array","items":{"type":"string"}},"highlight":{"type":"string","nullable":true,"description":"Badge on the subscribe page."},"subscriptionId":{"type":"string","nullable":true,"description":"The subscription offering this plan."},"position":{"type":"number","description":"Display order within the subscription."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","environment","name","description","amountMinor","currency","billingCycle","status","features","highlight","subscriptionId","position","createdAt","updatedAt"]},"SubscriptionPlanOptionResponse":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"name":{"type":"string"},"description":{"type":"string","nullable":true},"amountMinor":{"type":"string"},"currency":{"type":"string"},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"]},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"features":{"description":"What's included (up to 8 lines).","type":"array","items":{"type":"string"}},"highlight":{"type":"string","nullable":true,"description":"Badge on the subscribe page."},"subscriptionId":{"type":"string","nullable":true,"description":"The subscription offering this plan."},"position":{"type":"number","description":"Display order within the subscription."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isDefault":{"type":"boolean","description":"Shown first and used when a subscriber is added without a plan."},"activeSubscribers":{"type":"number"},"subscribers":{"type":"number","description":"All subscribers on this plan, any status."}},"required":["id","environment","name","description","amountMinor","currency","billingCycle","status","features","highlight","subscriptionId","position","createdAt","updatedAt","isDefault","activeSubscribers","subscribers"]},"SubscriptionSummaryResponse":{"type":"object","properties":{"totalSubscriptions":{"type":"number"},"totalCollectedAmountMinor":{"type":"string"},"active":{"type":"number"},"cancelled":{"type":"number"},"drafts":{"type":"number"},"currency":{"type":"string"}},"required":["totalSubscriptions","totalCollectedAmountMinor","active","cancelled","drafts","currency"]},"SubscriptionResponse":{"type":"object","properties":{"id":{"type":"string"},"subscriptionCode":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"name":{"type":"string"},"description":{"type":"string","nullable":true},"planId":{"type":"string"},"planName":{"type":"string"},"amountMinor":{"type":"string"},"currency":{"type":"string"},"billingCycle":{"type":"string"},"status":{"type":"string","enum":["DRAFT","ACTIVE","CANCELLED"]},"startAt":{"type":"string"},"nextBillingAt":{"type":"string"},"autoRenewal":{"type":"boolean"},"renewalReminders":{"type":"boolean"},"allowPlanUpgrade":{"type":"boolean"},"slug":{"type":"string","nullable":true,"description":"Public share code (checkout /sub/{slug})."},"shareUrl":{"type":"string","nullable":true,"description":"Hosted subscribe page, while the subscription is active."},"gracePeriodDays":{"type":"number","description":"Days after a missed billing date before a subscriber lapses."},"activatedAt":{"type":"string","nullable":true},"cancelledAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","subscriptionCode","environment","name","description","planId","planName","amountMinor","currency","billingCycle","status","startAt","nextBillingAt","autoRenewal","renewalReminders","allowPlanUpgrade","slug","shareUrl","gracePeriodDays","activatedAt","cancelledAt","createdAt","updatedAt"]},"SubscriptionSubscriberResponse":{"type":"object","properties":{"id":{"type":"string"},"orderCode":{"type":"string"},"customerId":{"type":"string","nullable":true},"customerName":{"type":"string"},"customerEmail":{"type":"string"},"amountMinor":{"type":"string"},"currency":{"type":"string"},"paymentMethod":{"type":"string","nullable":true},"status":{"type":"string","enum":["PENDING","PROCESSING","ACTIVE","OVERDUE","LAPSED","CANCELLED"]},"customerPhone":{"type":"string","nullable":true},"lastPaidAt":{"type":"string","nullable":true},"overdueAt":{"type":"string","nullable":true},"lapsedAt":{"type":"string","nullable":true},"planId":{"type":"string","nullable":true},"planName":{"type":"string","nullable":true},"billingCycle":{"type":"string","nullable":true,"enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"]},"startedAt":{"type":"string","nullable":true},"nextBillingAt":{"type":"string","nullable":true},"cancelledAt":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","orderCode","customerId","customerName","customerEmail","amountMinor","currency","paymentMethod","status","customerPhone","lastPaidAt","overdueAt","lapsedAt","planId","planName","billingCycle","startedAt","nextBillingAt","cancelledAt","createdAt"]},"CreateSubscriptionPlanDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"name":{"type":"string","example":"Business Pro","maxLength":120},"description":{"type":"string","maxLength":5000},"amountMinor":{"type":"string","example":"2000000","description":"Positive integer minor units."},"currency":{"type":"string","example":"NGN","default":"NGN"},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"],"example":"MONTHLY"},"features":{"maxItems":8,"example":["Unlimited group classes","Sauna and steam room"],"description":"What's included, shown on the subscribe page. Start with \"Everything in Basic\" to build on a cheaper plan.","type":"array","items":{"type":"string"}},"highlight":{"type":"string","maxLength":24,"example":"Most popular","description":"Optional badge on the subscribe page. Empty to remove."}},"required":["name","amountMinor","billingCycle"]},"UpdateSubscriptionPlanDto":{"type":"object","properties":{"name":{"type":"string","example":"Business Pro","maxLength":120},"description":{"type":"string","maxLength":5000},"amountMinor":{"type":"string","example":"2000000","description":"Positive integer minor units."},"currency":{"type":"string","example":"NGN","default":"NGN"},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"],"example":"MONTHLY"},"features":{"maxItems":8,"example":["Unlimited group classes","Sauna and steam room"],"description":"What's included, shown on the subscribe page. Start with \"Everything in Basic\" to build on a cheaper plan.","type":"array","items":{"type":"string"}},"highlight":{"type":"string","maxLength":24,"example":"Most popular","description":"Optional badge on the subscribe page. Empty to remove."}}},"SubscriptionPlanInputDto":{"type":"object","properties":{"name":{"type":"string","example":"Business Pro","maxLength":120},"description":{"type":"string","maxLength":5000},"amountMinor":{"type":"string","example":"2000000","description":"Positive integer minor units."},"currency":{"type":"string","example":"NGN","default":"NGN"},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"],"example":"MONTHLY"},"features":{"maxItems":8,"example":["Unlimited group classes","Sauna and steam room"],"description":"What's included, shown on the subscribe page. Start with \"Everything in Basic\" to build on a cheaper plan.","type":"array","items":{"type":"string"}},"highlight":{"type":"string","maxLength":24,"example":"Most popular","description":"Optional badge on the subscribe page. Empty to remove."}},"required":["name","amountMinor","billingCycle"]},"CreateSubscriptionDto":{"type":"object","properties":{"environment":{"type":"string","enum":["SANDBOX","LIVE"],"default":"SANDBOX"},"name":{"type":"string","example":"Meaty Enterprise","maxLength":160},"plans":{"description":"The plans offered (1–10); the first is the default. Required unless planId is given.","type":"array","items":{"$ref":"#/components/schemas/SubscriptionPlanInputDto"}},"planId":{"type":"string","description":"Legacy: an existing plan in the same environment, copied onto this subscription as its only plan. Use plans instead."},"description":{"type":"string","maxLength":5000},"amountMinor":{"type":"string","example":"5000000","description":"Legacy (with planId): overrides the copied plan amount."},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"],"description":"Legacy (with planId): overrides the copied plan cycle."},"startAt":{"format":"date-time","type":"string","description":"Defaults to now."},"status":{"type":"string","enum":["DRAFT","ACTIVE"],"default":"ACTIVE"},"autoRenewal":{"type":"object","default":true},"renewalReminders":{"type":"object","default":true},"allowPlanUpgrade":{"type":"object","default":true},"gracePeriodDays":{"type":"number","default":3,"minimum":0,"maximum":30,"description":"Days after a missed billing date before a subscriber lapses."}},"required":["name"]},"SubscriptionProgressResponse":{"type":"object","properties":{"total":{"type":"number"},"active":{"type":"number"},"cancelled":{"type":"number"},"pending":{"type":"number"},"processing":{"type":"number"},"overdue":{"type":"number"},"lapsed":{"type":"number"},"percentageActive":{"type":"number"},"collectedAmountMinor":{"type":"string"}},"required":["total","active","cancelled","pending","processing","overdue","lapsed","percentageActive","collectedAmountMinor"]},"SubscriptionDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"subscriptionCode":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"name":{"type":"string"},"description":{"type":"string","nullable":true},"planId":{"type":"string"},"planName":{"type":"string"},"amountMinor":{"type":"string"},"currency":{"type":"string"},"billingCycle":{"type":"string"},"status":{"type":"string","enum":["DRAFT","ACTIVE","CANCELLED"]},"startAt":{"type":"string"},"nextBillingAt":{"type":"string"},"autoRenewal":{"type":"boolean"},"renewalReminders":{"type":"boolean"},"allowPlanUpgrade":{"type":"boolean"},"slug":{"type":"string","nullable":true,"description":"Public share code (checkout /sub/{slug})."},"shareUrl":{"type":"string","nullable":true,"description":"Hosted subscribe page, while the subscription is active."},"gracePeriodDays":{"type":"number","description":"Days after a missed billing date before a subscriber lapses."},"activatedAt":{"type":"string","nullable":true},"cancelledAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"plan":{"description":"The default plan.","allOf":[{"$ref":"#/components/schemas/SubscriptionPlanResponse"}]},"plans":{"description":"Every plan of this subscription, in display order (archived included).","type":"array","items":{"$ref":"#/components/schemas/SubscriptionPlanOptionResponse"}},"progress":{"$ref":"#/components/schemas/SubscriptionProgressResponse"},"recentSubscribers":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionSubscriberResponse"}}},"required":["id","subscriptionCode","environment","name","description","planId","planName","amountMinor","currency","billingCycle","status","startAt","nextBillingAt","autoRenewal","renewalReminders","allowPlanUpgrade","slug","shareUrl","gracePeriodDays","activatedAt","cancelledAt","createdAt","updatedAt","plan","plans","progress","recentSubscribers"]},"AddSubscriptionSubscriberDto":{"type":"object","properties":{"customerId":{"type":"string","description":"Active customer ID or CRD customer code from the same environment."},"planId":{"type":"string","description":"An active plan of this subscription. Defaults to the default plan."},"status":{"type":"string","enum":["PENDING","PROCESSING","ACTIVE"],"default":"PENDING"},"paymentMethod":{"type":"string","example":"BANK_TRANSFER","maxLength":40},"notifyCustomer":{"type":"boolean","default":true,"description":"Email the customer their link: pay the first cycle (pending) or manage it (active)."}},"required":["customerId"]},"SubscriberPaymentResponse":{"type":"object","properties":{"id":{"type":"string"},"transactionId":{"type":"string","description":"The transaction behind this payment."},"kind":{"type":"string","enum":["FIRST","RENEWAL"]},"reference":{"type":"string"},"amountMinor":{"type":"string"},"feeMinor":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED","CANCELLED","REVERSED"]},"channel":{"type":"string","nullable":true},"planName":{"type":"string","nullable":true,"description":"Plan name at the time of payment."},"appliedAt":{"type":"string","nullable":true,"description":"When the payment extended the subscription."},"createdAt":{"type":"string"}},"required":["id","transactionId","kind","reference","amountMinor","feeMinor","currency","status","channel","planName","appliedAt","createdAt"]},"SubscriberNotificationResponse":{"type":"object","properties":{"type":{"type":"string","enum":["PAY_FIRST","WELCOME","RENEWAL_REMINDER","RENEWED","OVERDUE","LAPSED","CANCELLED","MANAGE_LINK"]},"status":{"type":"string","description":"QUEUED, SENT or FAILED."},"sentAt":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["type","status","sentAt","createdAt"]},"SubscriberDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"orderCode":{"type":"string"},"customerId":{"type":"string","nullable":true},"customerName":{"type":"string"},"customerEmail":{"type":"string"},"amountMinor":{"type":"string"},"currency":{"type":"string"},"paymentMethod":{"type":"string","nullable":true},"status":{"type":"string","enum":["PENDING","PROCESSING","ACTIVE","OVERDUE","LAPSED","CANCELLED"]},"customerPhone":{"type":"string","nullable":true},"lastPaidAt":{"type":"string","nullable":true},"overdueAt":{"type":"string","nullable":true},"lapsedAt":{"type":"string","nullable":true},"planId":{"type":"string","nullable":true},"planName":{"type":"string","nullable":true},"billingCycle":{"type":"string","nullable":true,"enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"]},"startedAt":{"type":"string","nullable":true},"nextBillingAt":{"type":"string","nullable":true},"cancelledAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"totalPaidMinor":{"type":"string","description":"Successful payments, in minor units."},"successfulPayments":{"type":"number"},"payments":{"description":"Newest first, up to 50.","type":"array","items":{"$ref":"#/components/schemas/SubscriberPaymentResponse"}},"notifications":{"description":"Emails to the customer, newest first, up to 20.","type":"array","items":{"$ref":"#/components/schemas/SubscriberNotificationResponse"}}},"required":["id","orderCode","customerId","customerName","customerEmail","amountMinor","currency","paymentMethod","status","customerPhone","lastPaidAt","overdueAt","lapsedAt","planId","planName","billingCycle","startedAt","nextBillingAt","cancelledAt","createdAt","totalPaidMinor","successfulPayments","payments","notifications"]},"ChangeSubscriberPlanDto":{"type":"object","properties":{"planId":{"type":"string","description":"An active plan of the same subscription."}},"required":["planId"]},"AddSubscriptionPlanDto":{"type":"object","properties":{"name":{"type":"string","example":"Business Pro","maxLength":120},"description":{"type":"string","maxLength":5000},"amountMinor":{"type":"string","example":"2000000","description":"Positive integer minor units."},"currency":{"type":"string","example":"NGN","default":"NGN"},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"],"example":"MONTHLY"},"features":{"maxItems":8,"example":["Unlimited group classes","Sauna and steam room"],"description":"What's included, shown on the subscribe page. Start with \"Everything in Basic\" to build on a cheaper plan.","type":"array","items":{"type":"string"}},"highlight":{"type":"string","maxLength":24,"example":"Most popular","description":"Optional badge on the subscribe page. Empty to remove."},"makeDefault":{"type":"boolean","default":false,"description":"Make this the default plan (shown first and used for new subscribers)."}},"required":["name","amountMinor","billingCycle"]},"UpdateSubscriptionSubscriberStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","PROCESSING","ACTIVE","CANCELLED"]},"paymentMethod":{"type":"string","example":"CARD","maxLength":40}},"required":["status"]},"UpdateSubscriptionDto":{"type":"object","properties":{"name":{"type":"string","maxLength":160},"planId":{"type":"string","description":"Make another plan of this subscription the default."},"description":{"type":"object","maxLength":5000,"nullable":true},"amountMinor":{"type":"string","description":"Changes the default plan price."},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"],"description":"Changes the default plan cycle."},"startAt":{"format":"date-time","type":"string"},"autoRenewal":{"type":"boolean"},"renewalReminders":{"type":"boolean"},"allowPlanUpgrade":{"type":"boolean"},"gracePeriodDays":{"type":"number","minimum":0,"maximum":30}}},"SubscriptionCheckoutPlanResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"amountMinor":{"type":"string"},"currency":{"type":"string"},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"]},"isDefault":{"type":"boolean"},"features":{"type":"array","items":{"type":"string"}},"highlight":{"type":"string","nullable":true}},"required":["id","name","description","amountMinor","currency","billingCycle","isDefault","features","highlight"]},"SubscriptionCheckoutMethodResponse":{"type":"object","properties":{"id":{"type":"string","enum":["CREDDOT","TRANSFER","BANK","USSD","CARD"]},"label":{"type":"string"},"availability":{"type":"string","enum":["AVAILABLE","UNAVAILABLE"]},"provider":{"type":"string","nullable":true},"channel":{"type":"string","nullable":true}},"required":["id","label","availability","provider","channel"]},"SubscriptionCheckoutBankResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"ussdCode":{"type":"string","nullable":true}},"required":["id","name","ussdCode"]},"SubscriptionManageSubscriberResponse":{"type":"object","properties":{"id":{"type":"string"},"orderCode":{"type":"string"},"customerName":{"type":"string"},"customerEmail":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","ACTIVE","OVERDUE","LAPSED","CANCELLED"]},"planId":{"type":"string","nullable":true},"planName":{"type":"string"},"amountMinor":{"type":"string"},"currency":{"type":"string"},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"]},"startedAt":{"type":"string","nullable":true},"lastPaidAt":{"type":"string","nullable":true},"nextBillingAt":{"type":"string","nullable":true},"graceEndsAt":{"type":"string","nullable":true,"description":"When an overdue subscription lapses."},"canPay":{"type":"boolean"},"canChangePlan":{"type":"boolean"},"canCancel":{"type":"boolean"}},"required":["id","orderCode","customerName","customerEmail","status","planId","planName","amountMinor","currency","billingCycle","startedAt","lastPaidAt","nextBillingAt","graceEndsAt","canPay","canChangePlan","canCancel"]},"SubscriptionManageResponse":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","ACTIVE","CANCELLED"]},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"currency":{"type":"string"},"merchantName":{"type":"string"},"gracePeriodDays":{"type":"number"},"allowPlanUpgrade":{"type":"boolean"},"plans":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionCheckoutPlanResponse"}},"methods":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionCheckoutMethodResponse"}},"supportedBanks":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionCheckoutBankResponse"}},"subscriber":{"$ref":"#/components/schemas/SubscriptionManageSubscriberResponse"}},"required":["slug","name","description","status","environment","currency","merchantName","gracePeriodDays","allowPlanUpgrade","plans","methods","supportedBanks","subscriber"]},"SubscriptionPaymentMethodDto":{"type":"object","properties":{"channel":{"type":"string","enum":["BANK_TRANSFER","CARD","USSD","QR"]},"bankCode":{"type":"string","description":"Required for USSD; use the Paga bank UUID returned by the checkout endpoint."},"card":{"description":"Required when channel is CARD.","allOf":[{"$ref":"#/components/schemas/CardPaymentDto"}]}},"required":["channel"]},"ManageChangePlanDto":{"type":"object","properties":{"planId":{"type":"string","description":"An active plan of the same subscription."}},"required":["planId"]},"SubscriptionCheckoutResponse":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","ACTIVE","CANCELLED"]},"environment":{"type":"string","enum":["SANDBOX","LIVE"]},"currency":{"type":"string"},"merchantName":{"type":"string"},"gracePeriodDays":{"type":"number"},"allowPlanUpgrade":{"type":"boolean"},"plans":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionCheckoutPlanResponse"}},"methods":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionCheckoutMethodResponse"}},"supportedBanks":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionCheckoutBankResponse"}}},"required":["slug","name","description","status","environment","currency","merchantName","gracePeriodDays","allowPlanUpgrade","plans","methods","supportedBanks"]},"SubscribeDto":{"type":"object","properties":{"channel":{"type":"string","enum":["BANK_TRANSFER","CARD","USSD","QR"]},"bankCode":{"type":"string","description":"Required for USSD; use the Paga bank UUID returned by the checkout endpoint."},"card":{"description":"Required when channel is CARD.","allOf":[{"$ref":"#/components/schemas/CardPaymentDto"}]},"planId":{"type":"string","description":"An active plan of this subscription."},"customerName":{"type":"string","example":"Ada Obi","maxLength":120},"customerEmail":{"type":"string","example":"ada@example.com","format":"email"},"customerPhone":{"type":"string","example":"+2348012345678"}},"required":["channel","planId","customerName","customerEmail"]},"CreateMerchantPlanDto":{"type":"object","properties":{"name":{"type":"string","example":"Business Pro","maxLength":120},"description":{"type":"string","maxLength":5000},"amountMinor":{"type":"string","example":"2000000","description":"Positive integer minor units."},"currency":{"type":"string","example":"NGN","default":"NGN"},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"],"example":"MONTHLY"},"features":{"maxItems":8,"example":["Unlimited group classes","Sauna and steam room"],"description":"What's included, shown on the subscribe page. Start with \"Everything in Basic\" to build on a cheaper plan.","type":"array","items":{"type":"string"}},"highlight":{"type":"string","maxLength":24,"example":"Most popular","description":"Optional badge on the subscribe page. Empty to remove."}},"required":["name","amountMinor","billingCycle"]},"CreateMerchantSubscriptionDto":{"type":"object","properties":{"name":{"type":"string","example":"Meaty Enterprise","maxLength":160},"plans":{"description":"The plans offered (1–10); the first is the default. Required unless planId is given.","type":"array","items":{"$ref":"#/components/schemas/SubscriptionPlanInputDto"}},"planId":{"type":"string","description":"Legacy: an existing plan in the same environment, copied onto this subscription as its only plan. Use plans instead."},"description":{"type":"string","maxLength":5000},"amountMinor":{"type":"string","example":"5000000","description":"Legacy (with planId): overrides the copied plan amount."},"billingCycle":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY","BIANNUALLY","ANNUALLY"],"description":"Legacy (with planId): overrides the copied plan cycle."},"startAt":{"format":"date-time","type":"string","description":"Defaults to now."},"status":{"type":"string","enum":["DRAFT","ACTIVE"],"default":"ACTIVE"},"autoRenewal":{"type":"object","default":true},"renewalReminders":{"type":"object","default":true},"allowPlanUpgrade":{"type":"object","default":true},"gracePeriodDays":{"type":"number","default":3,"minimum":0,"maximum":30,"description":"Days after a missed billing date before a subscriber lapses."}},"required":["name"]},"SearchHitResponse":{"type":"object","properties":{"kind":{"type":"string","enum":["TRANSACTION","CUSTOMER","INVOICE","PAY_LINK","SPLIT_PAY","EVENT","STOREFRONT","PRODUCT","SUBSCRIPTION","SUBSCRIBER","PAYOUT","BILL"]},"id":{"type":"string"},"title":{"type":"string","description":"Main line, e.g. a customer or invoice number."},"subtitle":{"type":"string","nullable":true,"description":"Second line, e.g. email or reference."},"amountMinor":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"date":{"type":"string","nullable":true,"format":"date-time"},"parentId":{"type":"string","nullable":true,"description":"Parent id, e.g. the subscription of a subscriber or the store of a product."},"exact":{"type":"boolean","description":"The query matched a reference or code exactly."}},"required":["kind","id","title","subtitle","amountMinor","currency","status","date","parentId","exact"]},"SearchGroupResponse":{"type":"object","properties":{"kind":{"type":"string","enum":["TRANSACTION","CUSTOMER","INVOICE","PAY_LINK","SPLIT_PAY","EVENT","STOREFRONT","PRODUCT","SUBSCRIPTION","SUBSCRIBER","PAYOUT","BILL"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/SearchHitResponse"}}},"required":["kind","items"]},"SearchResponse":{"type":"object","properties":{"query":{"type":"string"},"amountMinor":{"type":"string","nullable":true,"description":"When the query reads as an amount, in minor units."},"interpretedAs":{"type":"string","enum":["TEXT","AMOUNT","EMAIL","PHONE","REFERENCE"]},"groups":{"description":"Non-empty groups, best first.","type":"array","items":{"$ref":"#/components/schemas/SearchGroupResponse"}}},"required":["query","amountMinor","interpretedAs","groups"]},"ReportTotalsResponse":{"type":"object","properties":{"moneyInMinor":{"type":"string","description":"Successful collections, gross."},"feesMinor":{"type":"string"},"refundsMinor":{"type":"string"},"netRevenueMinor":{"type":"string","description":"Money in minus fees and refunds."},"moneyOutMinor":{"type":"string","description":"Successful payouts and bill payments."},"payoutsMinor":{"type":"string"},"billsMinor":{"type":"string"},"payoutsCount":{"type":"number"},"billsCount":{"type":"number"},"refundsCount":{"type":"number"},"successfulCount":{"type":"number"},"failedCount":{"type":"number"},"pendingCount":{"type":"number"},"failedMinor":{"type":"string","description":"Collected amount not received from failed payments."},"pendingMinor":{"type":"string"},"successRateBasisPoints":{"type":"number","description":"Successful / (successful + failed), in basis points; 0 when nothing finished."},"averagePaymentMinor":{"type":"string"},"customers":{"type":"number","description":"Distinct paying customers (by email, else phone, else name)."},"newCustomers":{"type":"number","description":"Customers whose first ever successful payment falls in the period."}},"required":["moneyInMinor","feesMinor","refundsMinor","netRevenueMinor","moneyOutMinor","payoutsMinor","billsMinor","payoutsCount","billsCount","refundsCount","successfulCount","failedCount","pendingCount","failedMinor","pendingMinor","successRateBasisPoints","averagePaymentMinor","customers","newCustomers"]},"ReportBucketResponse":{"type":"object","properties":{"date":{"type":"string","description":"Bucket start date (YYYY-MM-DD, business time zone)."},"moneyInMinor":{"type":"string"},"previousMoneyInMinor":{"type":"string","description":"Money in for the same position in the previous period."},"moneyOutMinor":{"type":"string"},"payoutsMinor":{"type":"string"},"billsMinor":{"type":"string"},"feesMinor":{"type":"string"},"successfulCount":{"type":"number"},"failedCount":{"type":"number"},"successRateBasisPoints":{"type":"number","description":"Success rate for the bucket in basis points (null when nothing finished).","nullable":true},"newCustomers":{"type":"number"},"returningCustomers":{"type":"number"}},"required":["date","moneyInMinor","previousMoneyInMinor","moneyOutMinor","payoutsMinor","billsMinor","feesMinor","successfulCount","failedCount","successRateBasisPoints","newCustomers","returningCustomers"]},"ReportSourceResponse":{"type":"object","properties":{"source":{"type":"string","enum":["PAY_LINK","INVOICE","STOREFRONT","EVENT","SPLIT_PAY","API"]},"amountMinor":{"type":"string"},"count":{"type":"number"},"feesMinor":{"type":"string"},"failedCount":{"type":"number"}},"required":["source","amountMinor","count","feesMinor","failedCount"]},"ReportChannelResponse":{"type":"object","properties":{"channel":{"type":"string","description":"BANK_TRANSFER, CARD, USSD, QR or OTHER."},"amountMinor":{"type":"string"},"successfulCount":{"type":"number"},"failedCount":{"type":"number"},"successRateBasisPoints":{"type":"number","nullable":true}},"required":["channel","amountMinor","successfulCount","failedCount","successRateBasisPoints"]},"ReportItemResponse":{"type":"object","properties":{"type":{"type":"string","enum":["PAY_LINK","INVOICE","STOREFRONT","STOREFRONT_PRODUCT","EVENT","SPLIT_PAY"]},"id":{"type":"string"},"name":{"type":"string"},"count":{"type":"number"},"amountMinor":{"type":"string"},"previousAmountMinor":{"type":"string"}},"required":["type","id","name","count","amountMinor","previousAmountMinor"]},"ReportCustomerResponse":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","nullable":true},"count":{"type":"number"},"amountMinor":{"type":"string"},"lastPaidAt":{"type":"string"},"firstPaidAt":{"type":"string"}},"required":["name","email","count","amountMinor","lastPaidAt","firstPaidAt"]},"ReportMonthResponse":{"type":"object","properties":{"month":{"type":"string","example":"2026-10"},"moneyInMinor":{"type":"string"},"moneyOutMinor":{"type":"string"}},"required":["month","moneyInMinor","moneyOutMinor"]},"ReportBankResponse":{"type":"object","properties":{"bankCode":{"type":"string"},"count":{"type":"number"},"amountMinor":{"type":"string"}},"required":["bankCode","count","amountMinor"]},"ReportBalanceResponse":{"type":"object","properties":{"openingMinor":{"type":"string","description":"Posted ledger balance at the start of dateFrom."},"closingMinor":{"type":"string","description":"Posted ledger balance at the end of dateTo."}},"required":["openingMinor","closingMinor"]},"ReportsResponse":{"type":"object","properties":{"currency":{"type":"string"},"dateFrom":{"type":"string"},"dateTo":{"type":"string"},"previousDateFrom":{"type":"string"},"previousDateTo":{"type":"string"},"granularity":{"type":"string","enum":["day","week","month"]},"totals":{"$ref":"#/components/schemas/ReportTotalsResponse"},"previousTotals":{"$ref":"#/components/schemas/ReportTotalsResponse"},"series":{"type":"array","items":{"$ref":"#/components/schemas/ReportBucketResponse"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ReportSourceResponse"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/ReportChannelResponse"}},"topItems":{"type":"array","items":{"$ref":"#/components/schemas/ReportItemResponse"}},"topCustomers":{"type":"array","items":{"$ref":"#/components/schemas/ReportCustomerResponse"}},"customerFrequency":{"description":"Customers by number of successful payments in the period: [1, 2-3, 4-9, 10+].","type":"array","items":{"type":"number"}},"heatmap":{"type":"array","description":"7 rows (Monday first) x 24 hours of successful payment counts, business time zone.","items":{"type":"array","items":{"type":"integer"}}},"bestDay":{"nullable":true,"description":"Day with the most money in.","type":"object","allOf":[{"$ref":"#/components/schemas/ReportBucketResponse"}]},"months":{"description":"Last six calendar months up to dateTo.","type":"array","items":{"$ref":"#/components/schemas/ReportMonthResponse"}},"payoutBanks":{"type":"array","items":{"$ref":"#/components/schemas/ReportBankResponse"}},"balance":{"$ref":"#/components/schemas/ReportBalanceResponse"},"truncated":{"type":"boolean","description":"True when the period had more transactions than one report reads (the figures cover the first ones)."}},"required":["currency","dateFrom","dateTo","previousDateFrom","previousDateTo","granularity","totals","previousTotals","series","sources","channels","topItems","topCustomers","customerFrequency","heatmap","bestDay","months","payoutBanks","balance","truncated"]},"StatementEntryResponse":{"type":"object","properties":{"id":{"type":"string"},"postedAt":{"type":"string"},"type":{"type":"string","enum":["COLLECTION","PAYOUT","BILL_PAYMENT","FEE","SPLIT","REVERSAL","SETTLEMENT","ADJUSTMENT"]},"description":{"type":"string"},"reference":{"type":"string","nullable":true},"amountMinor":{"type":"string","description":"Signed minor units: positive in, negative out."},"balanceMinor":{"type":"string","description":"Balance after this entry."}},"required":["id","postedAt","type","description","reference","amountMinor","balanceMinor"]},"StatementResponse":{"type":"object","properties":{"currency":{"type":"string"},"dateFrom":{"type":"string"},"dateTo":{"type":"string"},"businessName":{"type":"string"},"openingMinor":{"type":"string"},"closingMinor":{"type":"string"},"moneyInMinor":{"type":"string"},"moneyOutMinor":{"type":"string"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/StatementEntryResponse"}},"truncated":{"type":"boolean"}},"required":["currency","dateFrom","dateTo","businessName","openingMinor","closingMinor","moneyInMinor","moneyOutMinor","entries","truncated"]},"CreateRefundRequestDto":{"type":"object","properties":{"amountMinor":{"type":"string","example":"150000","description":"Positive integer minor units. Defaults to the remaining refundable amount."},"reason":{"type":"string","minLength":5,"maxLength":500}},"required":["reason"]}}}}