{
"openapi": "3.1.1",
"info": {
"title": "Tapaya Integrator API",
"description": "Public API for integrating with Tapaya Accept: onboard and manage merchants and organizations, list payments and invoices, refund transactions.\n\n## Auth\n\nAuthenticate API requests with a Server Secret Token, generated on the [API Keys page](https://platform.tapaya.com/api-keys/). Send the token directly in the Authorization header `Authorization: API_TOKEN`. Keep it secure and use it only from your backend; never expose it in client-side applications.\n\n## Servers\n\n- Production: Hosted at `https://api.tapaya.com`. This environment uses real accounts and involves real funds. Do not use the production environment for testing.\n- Sandbox: Hosted at `https://api.sandbox.tapaya.com`. This environment allows you to test your integration without any movement of real funds. Learn more about testing in our [Testing/Sandbox guide](https://docs.tapaya.com/getting-started/testing).",
"termsOfService": "https://weathered-pond-f6e5.weathered-paper-b2f0.workers.dev/terms_en_1_0.pdf",
"contact": {
"email": "developers@tapaya.com"
},
"version": "1.0"
},
"servers": [
{
"url": "https://api.tapaya.com",
"description": "Production"
},
{
"url": "https://api.sandbox.tapaya.com",
"description": "Sandbox"
}
],
"paths": {
"/integrator/merchant/{merchantId}/active-locations": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get active terminal locations for a merchant.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "List of active terminal locations",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantActiveLocationsGetResponse"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "List merchants registered under this organization.",
"responses": {
"200": {
"description": "List of merchants.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantsGetResponse"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Create a new merchant under the current organization.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Merchant created successfully."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/bank-accounts": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "List the merchant's settlement bank accounts. Ordered: `isPrimary` first, then by creation time.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantBankAccountsGetResult"
}
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Add a bank account to the merchant. The first account added becomes the primary settlement\ndestination automatically; use `PUT /bank-accounts/primary` to change it later.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantBankAccountsPostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantBankAccountsPostResult"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/bank-accounts/{bankAccountId}": {
"delete": {
"tags": [
"Integrator/Merchant"
],
"summary": "Remove one bank account. If the deleted account was the primary and others remain,\nthe oldest remaining account is automatically promoted to primary.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "bankAccountId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/bank-accounts/primary": {
"put": {
"tags": [
"Integrator/Merchant"
],
"summary": "Mark a bank account as the merchant's primary settlement destination. Idempotent.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantBankAccountPrimaryPutRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/payout-state": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get merchant payout state.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Payout state including balance, recent payouts, and schedule",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PayoutStateResponse"
}
}
}
},
"404": {
"description": "Merchant not found or not onboarded to a payment processor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/stats": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get merchant stats for a time window.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"description": "Merchant ID.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "from",
"in": "query",
"description": "Window start, ISO 8601 UTC (e.g. 2025-05-01T00:00:00Z). Inclusive.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "Window end, ISO 8601 UTC. Exclusive.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "granularity",
"in": "query",
"description": "Bucket size: hour, day (default), or week.",
"schema": {
"type": "string",
"default": "day"
}
}
],
"responses": {
"200": {
"description": "Merchant stats",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantStatsGetResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/stats/heatmap": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get a 7×24 heatmap of average transaction counts for a merchant.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"description": "Merchant ID.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "from",
"in": "query",
"description": "Window start, ISO 8601 UTC. Inclusive.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "Window end, ISO 8601 UTC. Exclusive. Max 366 days from from.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Heatmap matrix — non-zero cells only, ordered by dayOfWeek then hour.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantStatsHeatmapGetResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/stats/terminals": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get per-terminal stats for a merchant. Terminals with no activity in the window are still returned.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"description": "Merchant ID.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "from",
"in": "query",
"description": "Window start, ISO 8601 UTC. Inclusive.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "Window end, ISO 8601 UTC. Exclusive.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "currency",
"in": "query",
"description": "ISO 4217 currency code for volume (default CZK).",
"schema": {
"type": "string",
"default": "CZK"
}
}
],
"responses": {
"200": {
"description": "Per-terminal stats list.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantStatsTerminalsGetResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/payment": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "List the latest 50 payments of this merchant.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "List of recent payments.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantPaymentsGetResult"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/transaction-reports": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "List transaction reports for a merchant ordered by period descending.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "List of merchant transaction reports",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantTransactionReportsGetResponse"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/transaction-reports/{reportId}": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get merchant transaction report detail including billing snapshot and payment list.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "reportId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Merchant transaction report detail",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantTransactionReportGetResponse"
}
}
}
},
"404": {
"description": "Transaction report not found or belongs to a different merchant/organization"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/transaction-reports/{reportId}/download": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get a pre-signed download URL for a merchant transaction report PDF.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "reportId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Pre-signed download URL (valid 15 minutes)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantTransactionReportDownloadGetResponse"
}
}
}
},
"404": {
"description": "Transaction report not found or belongs to a different merchant/organization"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/document": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Upload merchant verification document.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantDocumentPostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Document uploaded successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantDocumentPostResponse"
}
}
}
},
"404": {
"description": "Merchant not found"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/onboarding": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Create a new merchant and submit onboarding in a single call.\nThe payment processor is resolved from the organization's preferred processor.\nReturns 422 with validation errors if the onboarding data is invalid (merchant is NOT created).",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Created"
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidationResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/onboarding/validate/address": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Validate a merchant address without persisting it.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidateAddressRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Validation result with a list of field-level errors; empty when valid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidateAddressResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/onboarding/validate/business": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Validate business profile fields without persisting them.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidateBusinessRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Validation result with a list of field-level errors; empty when valid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidateBusinessResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/onboarding/validate/identity": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Validate business identity fields without persisting them.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidateIdentityRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Validation result with a list of field-level errors; empty when valid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidateIdentityResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/onboarding/validate/kyb": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Validate full KYB data without persisting it; returns a list of field-level errors.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidateKybRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Validation result with a list of field-level errors; empty when valid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidateKybResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/onboarding/validate/reference-id": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Validate that a reference id (integrator-supplied merchant token) is not already used by\nanother merchant under this integrator.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidateReferenceIdRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Validation result with a list of field-level errors; empty when valid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingValidateReferenceIdResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/processor": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get processor merchant onboarding data and status for a specific merchant.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "paymentProcessorId",
"in": "query",
"required": true,
"schema": {
"$ref": "#/components/schemas/PaymentProcessorEnum"
}
}
],
"responses": {
"200": {
"description": "Processor account data and requirement status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantProcessorGetResponse"
}
}
}
},
"404": {
"description": "Merchant not found, belongs to a different organization, or not registered with this processor."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Register a merchant with a payment processor; required before the merchant's terminals can process payments.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantRegisterProcessorMerchantRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Registration submitted; returns onboarding URL if further action is needed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantRegisterProcessorMerchantResponse"
}
}
}
},
"404": {
"description": "Merchant not found or belongs to a different organization."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"put": {
"tags": [
"Integrator/Merchant"
],
"summary": "Update processor merchant with payment processor.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantUpdateProcessorMerchantRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantUpdateProcessorMerchantResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/processor/shift4": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Register a merchant with Shift4 by submitting official identity documents for each stakeholder; requires an `Idempotency-Key` header.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantShift4ProcessorRegisterPostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Registration submitted to Shift4; use the returned crxRequestId to track the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantShift4ProcessorRegisterPostResponse"
}
}
}
},
"404": {
"description": "Merchant not found or belongs to a different organization."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/profile": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get the stored onboarding profile for a merchant.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Merchant profile; data is null if no profile has been submitted yet.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantProfileGetResponse"
}
}
}
},
"404": {
"description": "Merchant not found or belongs to a different organization."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Submit the merchant's onboarding profile and return the current payment method readiness status.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantProfileInitializeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Profile saved; returns per-payment-method readiness.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantProfilePostStatusResponse"
}
}
}
},
"404": {
"description": "Merchant not found or belongs to a different organization."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"put": {
"tags": [
"Integrator/Merchant"
],
"summary": "Update merchant profile information, return onboarding status.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantProfileUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantProfilePutStatusResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/pricing-request/{mcc}": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get indicative pricing for an MCC and persist the quote for later listing.",
"description": "When reference rates exist for the MCC, returns approved pricing with indicative rates.\nWhen rates are missing, returns a pending response and notifies ops via Slack.\nEach call creates a new persisted quote row for the authenticated organization.",
"parameters": [
{
"name": "mcc",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantMccPricingRequestPostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Indicative pricing result for the MCC.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantMccPricingRequestPostResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/pricing-request/known-mcc": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "List MCC codes with reference rates that are auto-approved for card pricing.",
"description": "Returns indicative card rates per MCC, grouped by payment method → card type → currency.",
"responses": {
"200": {
"description": "Known auto-approved MCC codes.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantKnownMccGetResponse"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/pricing-request": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Submit a new pricing request for a merchant.",
"description": "Supersedes any previously pending request unless it is awaiting ops review (409).\nMCC is read from the merchant onboarding profile server-side.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantPricingRequestPostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Pricing request created or updated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantPricingRequestResponse"
}
}
}
},
"404": {
"description": "Merchant not found or has no completed onboarding profile (MCC unavailable)."
},
"409": {
"description": "A pending request is under ops review and cannot be superseded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/pricing-request/current": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get the merchant's single active pricing request.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Active pricing request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantPricingRequestResponse"
}
}
}
},
"404": {
"description": "Merchant not found or no active pricing request exists."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/pricing-request": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Lists MCC pricing quotes submitted via POST pricing-request/{mcc} for the authenticated organization.",
"parameters": [
{
"name": "isActive",
"in": "query",
"description": "When set, filters by whether the quote row is marked active.",
"schema": {
"type": "boolean"
}
},
{
"name": "from",
"in": "query",
"description": "Optional lower bound on submission time, ISO 8601 UTC. Inclusive.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "Optional upper bound on submission time, ISO 8601 UTC. Exclusive.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Optional maximum number of pricing requests to return.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "offset",
"in": "query",
"description": "Optional number of pricing requests to skip before returning results.",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Pricing requests listed successfully.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantPricingRequestsGetResponse"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/status": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get onboarding status for merchant and connected payment methods.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Current onboarding and payment method readiness status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantStatusGetResponse"
}
}
}
},
"404": {
"description": "Merchant not found or belongs to a different organization."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/onboarding/status": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Get the processor onboarding status for a specific merchant.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Processor registration and capability statuses for the merchant.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantOnboardingStatusResponse"
}
}
}
},
"404": {
"description": "Merchant not found or belongs to a different organization."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/activate": {
"put": {
"tags": [
"Integrator/Merchant"
],
"summary": "Enable a merchant so that their registered terminals can accept payments.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Merchant activated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantActivateResponse"
}
}
}
},
"404": {
"description": "Merchant not found or belongs to a different organization."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/deactivate": {
"put": {
"tags": [
"Integrator/Merchant"
],
"summary": "Disable a merchant, preventing their terminals from accepting new payments.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Merchant deactivated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantDeactivateResponse"
}
}
}
},
"404": {
"description": "Merchant not found or belongs to a different organization."
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/invite": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Generate a platform user invite for an existing merchant (login / dashboard access).\nThis does not start KYC onboarding. For KYC, use\n`POST /integrator/merchant/send-registration-invite` with `merchantToken`.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantInvitePostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Invite created — returns the registration URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantInvitePostResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/send-registration-invite": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Send a merchant KYC registration invite email.\nWithout `merchantToken`, completing the invite creates a new merchant.\nWith `merchantToken` (from `POST /merchant/auth/register` or\n`POST /integrator/merchant`), KYC is submitted onto that existing merchant shell\nso the partner-owned token is preserved.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendRegistrationInvitePostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Invite created — returns the registration URL (also emailed).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendRegistrationInvitePostResponse"
}
}
}
},
"404": {
"description": "Organization or bound merchant not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/invites": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Lists merchant registration invites with their invite URLs and recipient emails.",
"parameters": [
{
"name": "isActive",
"in": "query",
"description": "When set, filters by whether the invite is still usable (not used/revoked and not expired).",
"schema": {
"type": "boolean"
}
},
{
"name": "from",
"in": "query",
"description": "Optional lower bound on invite creation time, ISO 8601 UTC. Inclusive.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "Optional upper bound on invite creation time, ISO 8601 UTC. Exclusive.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Optional maximum number of invites to return.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "offset",
"in": "query",
"description": "Optional number of invites to skip before returning results.",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Invites listed successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RegistrationInvitesGetResponse"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/invites/{inviteId}": {
"delete": {
"tags": [
"Integrator/Merchant"
],
"summary": "Revokes a pending merchant registration invite.\nRevoked invite links return 410 Gone when used.",
"parameters": [
{
"name": "inviteId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Invite revoked"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/reusable-registration-invites": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Creates a multi-use merchant registration link.\nThe same link can be used by multiple people to complete registration until it expires or is revoked.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReusableRegistrationInvitePostRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Reusable invite created"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Lists reusable registration invites for the organization.",
"parameters": [
{
"name": "isActive",
"in": "query",
"description": "When set, filters by whether the invite is still usable (not revoked and not expired).",
"schema": {
"type": "boolean"
}
},
{
"name": "from",
"in": "query",
"description": "Optional lower bound on invite creation time, ISO 8601 UTC. Inclusive.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "Optional upper bound on invite creation time, ISO 8601 UTC. Exclusive.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Optional maximum number of invites to return.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "offset",
"in": "query",
"description": "Optional number of invites to skip before returning results.",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Invites listed successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReusableRegistrationInvitesGetResponse"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/reusable-registration-invites/{inviteId}": {
"delete": {
"tags": [
"Integrator/Merchant"
],
"summary": "Revokes a reusable registration invite.\nRevoked links return 410 Gone when used.",
"parameters": [
{
"name": "inviteId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Invite revoked"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/members/invite": {
"post": {
"tags": [
"Integrator/Merchant"
],
"summary": "Invites a user to access an existing merchant (login / dashboard). Does not start KYC.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantMembersInvitePostRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Invite sent successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorMerchantMembersInvitePostResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/members/invites": {
"get": {
"tags": [
"Integrator/Merchant"
],
"summary": "Lists merchant member invites (user access) with invite URLs and recipient emails.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "isActive",
"in": "query",
"description": "When set, filters by whether the invite is still usable.",
"schema": {
"type": "boolean"
}
},
{
"name": "from",
"in": "query",
"description": "Optional lower bound on invite creation time, ISO 8601 UTC. Inclusive.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "Optional upper bound on invite creation time, ISO 8601 UTC. Exclusive.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Optional maximum number of invites to return.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "offset",
"in": "query",
"description": "Optional number of invites to skip before returning results.",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Invites listed successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantMembersInvitesGetResponse"
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/merchant/{merchantId}/members/invites/{inviteId}": {
"delete": {
"tags": [
"Integrator/Merchant"
],
"summary": "Revokes a pending merchant member invite. Revoked invite links return 410 Gone when used.",
"parameters": [
{
"name": "merchantId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "inviteId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Invite revoked"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "Get details of the currently authenticated organization.",
"responses": {
"200": {
"description": "Organization details retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationGetResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"put": {
"tags": [
"Integrator/Organization"
],
"summary": "Update organization details.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationPutRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Organization updated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationPutResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/bank-accounts": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "List the organization's settlement bank accounts, one per currency, ordered by currency.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationBankAccountsGetResult"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"post": {
"tags": [
"Integrator/Organization"
],
"summary": "Set the organization's settlement bank account for a currency. If an account already\nexists for that currency, it is overwritten in place (same bank account id).",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationBankAccountsPostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationBankAccountsPostResult"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/bank-accounts/{bankAccountId}": {
"delete": {
"tags": [
"Integrator/Organization"
],
"summary": "Remove one of the organization's settlement bank accounts.",
"parameters": [
{
"name": "bankAccountId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/config": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "Get configuration for the currently authenticated organization.",
"responses": {
"200": {
"description": "Organization configuration retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationConfigGetResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"put": {
"tags": [
"Integrator/Organization"
],
"summary": "Update configuration for the currently authenticated organization.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationConfigPutRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Organization configuration updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationConfigPutResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/payment": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "List the latest 50 payments of all merchants in this organization.",
"responses": {
"200": {
"description": "List of recent payments across all merchants.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentsGetResult"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/payment/stats": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "Get payment statistics aggregated across all merchants in this organization.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentStatsGetResult"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/stats": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "Get organization stats for a time window.",
"parameters": [
{
"name": "from",
"in": "query",
"description": "Window start, ISO 8601 UTC (e.g. 2025-05-01T00:00:00Z). Inclusive.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "Window end, ISO 8601 UTC. Exclusive.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "granularity",
"in": "query",
"description": "Bucket size: hour, day (default), or week.",
"schema": {
"type": "string",
"default": "day"
}
},
{
"name": "currency",
"in": "query",
"description": "ISO 4217 currency code for monetary amounts (e.g. CZK, EUR).",
"schema": {
"type": "string",
"default": "CZK"
}
}
],
"responses": {
"200": {
"description": "Organization stats",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationStatsGetResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/invoice": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "List organization invoices ordered by period descending.",
"responses": {
"200": {
"description": "List of organization invoices",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationInvoicesGetResponse"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/invoice/{invoiceId}": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "Get organization invoice detail including billing snapshot and payment list.",
"parameters": [
{
"name": "invoiceId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Organization invoice detail",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationInvoiceGetResponse"
}
}
}
},
"404": {
"description": "Invoice not found or belongs to a different organization"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/invoice/{invoiceId}/download": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "Get a pre-signed download URL for an organization invoice PDF.",
"parameters": [
{
"name": "invoiceId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Pre-signed download URL (valid 15 minutes)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationInvoiceDownloadGetResponse"
}
}
}
},
"404": {
"description": "Invoice not found or belongs to a different organization"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/payment-method": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "List allowed payment methods.",
"responses": {
"200": {
"description": "List of allowed payment methods",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentMethodsGetResponse"
}
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"post": {
"tags": [
"Integrator/Organization"
],
"summary": "Add allowed payment method.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentMethodsPostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Payment method added successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentMethodsPostResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/payment-method/{paymentMethodId}": {
"put": {
"tags": [
"Integrator/Organization"
],
"summary": "Update allowed payment method.",
"parameters": [
{
"name": "paymentMethodId",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PaymentMethodEnum"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentMethodPutRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Payment method updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentMethodPutResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"delete": {
"tags": [
"Integrator/Organization"
],
"summary": "Delete allowed payment method.",
"parameters": [
{
"name": "paymentMethodId",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/PaymentMethodEnum"
}
}
],
"responses": {
"200": {
"description": "Payment method deleted successfully"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/payment/{paymentToken}": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "Get full detail for a single payment, including all transactions, charges, fees, and refunds.",
"parameters": [
{
"name": "paymentToken",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Payment detail returned successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentGetResult"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/payment/{paymentToken}/refund": {
"post": {
"tags": [
"Integrator/Organization"
],
"summary": "Initiates a refund for a previously successful payment.",
"parameters": [
{
"name": "paymentToken",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentRefundPostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Refund initiated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentRefundPostResult"
}
}
}
},
"404": {
"description": "Not Found"
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/api-key": {
"get": {
"tags": [
"Integrator/Organization"
],
"summary": "Get active API keys for the organization.",
"responses": {
"200": {
"description": "API keys retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationApiKeyGetResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
},
"post": {
"tags": [
"Integrator/Organization"
],
"summary": "Create a new API key for the organization.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationApiKeyPostRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "New API key generated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegratorOrganizationApiKeyPostResponse"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/integrator/organization/api-key/{apiTokenId}": {
"delete": {
"tags": [
"Integrator/Organization"
],
"summary": "Revoke an API key for the organization.",
"parameters": [
{
"name": "apiTokenId",
"in": "path",
"description": "ID of the API token to revoke",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "API key revoked successfully"
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/merchant/auth/register": {
"post": {
"tags": [
"Merchant"
],
"summary": "Register new merchant into the system.",
"description": "Must be called on the server before any other merchant request.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MerchantAuthRegisterRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Merchant successfully registered",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MerchantAuthRegisterResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
},
"/merchant/auth/login": {
"post": {
"tags": [
"Merchant"
],
"summary": "Generate SDK login token for merchant.",
"description": "Must be called on server-side prior to any SDK activity.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MerchantAuthLoginRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Merchant successfully logged in",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MerchantAuthLoginResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"400": {
"description": "Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicExceptionPayload"
}
}
}
}
},
"security": [
{
"ApiTokenScheme": [ ]
}
]
}
}
},
"components": {
"schemas": {
"AddressInformation": {
"type": "object",
"properties": {
"countryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "The country identifier for the address.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"city": {
"maxLength": 100,
"minLength": 0,
"type": [
"null",
"string"
],
"description": "The city name for the address."
},
"state": {
"maxLength": 100,
"minLength": 0,
"type": [
"null",
"string"
],
"description": "The state or region for the address."
},
"postalCode": {
"maxLength": 20,
"minLength": 0,
"pattern": "^[a-zA-Z0-9\\s\\-]+$",
"type": [
"null",
"string"
],
"description": "The postal or ZIP code for the address."
},
"line1": {
"maxLength": 255,
"minLength": 0,
"type": [
"null",
"string"
],
"description": "The first line of the street address."
},
"line2": {
"maxLength": 255,
"minLength": 0,
"type": [
"null",
"string"
],
"description": "The second line of the street address."
}
},
"description": "Represents address information, including country, city, state, postal code, and address lines."
},
"AddressObjectPayload": {
"type": "object",
"properties": {
"countryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Country.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"city": {
"type": [
"null",
"string"
],
"description": "City."
},
"line1": {
"type": [
"null",
"string"
],
"description": "Street address line 1."
},
"line2": {
"type": [
"null",
"string"
],
"description": "Street address line 2."
},
"state": {
"type": [
"null",
"string"
],
"description": "State or province."
},
"postalCode": {
"type": [
"null",
"string"
],
"description": "Postal or ZIP code."
}
}
},
"AddressPayload": {
"required": [
"line1",
"city",
"postalCode",
"countryId"
],
"type": "object",
"properties": {
"line1": {
"type": "string",
"description": "Street address line 1."
},
"line2": {
"type": [
"null",
"string"
],
"description": "Street address line 2."
},
"city": {
"type": "string",
"description": "City."
},
"postalCode": {
"type": "string",
"description": "Postal or ZIP code."
},
"state": {
"type": [
"null",
"string"
],
"description": "State or province."
},
"countryId": {
"description": "Country.",
"$ref": "#/components/schemas/CountryEnum"
}
}
},
"BalanceResponse": {
"required": [
"available",
"pending",
"paidOut"
],
"type": "object",
"properties": {
"available": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MoneyResponse"
},
"description": "Available balance."
},
"pending": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MoneyResponse"
},
"description": "Pending balance."
},
"paidOut": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MoneyResponse"
},
"description": "Settlements that have been paid out."
}
}
},
"BankAccountInformation": {
"required": [
"accountNumber"
],
"type": "object",
"properties": {
"accountNumber": {
"maxLength": 34,
"type": "string",
"description": "The account number associated with the bank account (e.g., IBAN)."
},
"bic": {
"maxLength": 11,
"type": [
"null",
"string"
],
"description": "BIC / SWIFT code. Required by Shift4."
},
"bankName": {
"maxLength": 200,
"type": [
"null",
"string"
],
"description": "Bank name. Required by Shift4."
},
"beneficiaryName": {
"maxLength": 200,
"type": [
"null",
"string"
],
"description": "Beneficiary name on the bank account."
},
"currencyId": {
"type": [
"null",
"integer"
],
"description": "Settlement currency ID (FK to global.currency, e.g. 978 = EUR).",
"format": "int32"
}
},
"description": "Represents the bank account information, including account number, country, and currency."
},
"BankAccountPayload": {
"type": "object",
"properties": {
"accountNumber": {
"type": [
"null",
"string"
],
"description": "Bank account number."
},
"iban": {
"type": [
"null",
"string"
],
"description": "International Bank Account Number."
},
"bic": {
"type": [
"null",
"string"
],
"description": "Bank Identifier Code (SWIFT)."
},
"currencyId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Account currency.",
"$ref": "#/components/schemas/CurrencyEnum"
}
]
},
"beneficiaryName": {
"type": [
"null",
"string"
],
"description": "Name of the account beneficiary."
},
"addressCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Beneficiary address country.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"addressCity": {
"type": [
"null",
"string"
],
"description": "Beneficiary address city."
},
"addressLine1": {
"type": [
"null",
"string"
],
"description": "Beneficiary address line 1."
},
"addressLine2": {
"type": [
"null",
"string"
],
"description": "Beneficiary address line 2."
},
"addressState": {
"type": [
"null",
"string"
],
"description": "Beneficiary address state."
},
"addressPostalCode": {
"type": [
"null",
"string"
],
"description": "Beneficiary address postal code."
},
"bankName": {
"type": [
"null",
"string"
],
"description": "Name of the bank."
},
"bankCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Country where the bank is registered.",
"$ref": "#/components/schemas/CountryEnum"
}
]
}
}
},
"BusinessPayload": {
"required": [
"mcc",
"supportPhone",
"statementDescriptor"
],
"type": "object",
"properties": {
"mcc": {
"type": "string",
"description": "4-digit Merchant Category Code."
},
"url": {
"type": [
"null",
"string"
],
"description": "Business website URL."
},
"productDescription": {
"type": [
"null",
"string"
],
"description": "Short description of the products or services sold."
},
"supportPhone": {
"type": "string",
"description": "Customer support phone number."
},
"statementDescriptor": {
"type": "string",
"description": "Statement descriptor shown on cardholder statements (5–22 characters)."
},
"averageItemValue": {
"type": [
"null",
"integer"
],
"description": "Average transaction value in the smallest currency unit.",
"format": "int64"
},
"expectedMonthlyTurnover": {
"type": [
"null",
"integer"
],
"description": "Expected monthly turnover in the smallest currency unit.",
"format": "int64"
},
"numberOfEmployees": {
"type": [
"null",
"integer"
],
"description": "Number of employees.",
"format": "int32"
},
"numberOfTerminals": {
"maximum": 9999,
"minimum": 1,
"type": [
"null",
"integer"
],
"description": "Number of POS terminals at this location (1–9999). Sent to Shift4 as pos_device.number_of_devices.",
"format": "int32"
},
"annualTurnover": {
"type": [
"null",
"integer"
],
"description": "Annual turnover in the smallest currency unit.",
"format": "int64"
},
"balanceSheetTotal": {
"type": [
"null",
"integer"
],
"description": "Balance sheet total in the smallest currency unit.",
"format": "int64"
}
}
},
"BusinessTypeEnum": {
"enum": [
1,
2,
3,
4,
5
],
"type": "integer",
"description": "Allowed values:\n - 1 = Individual (Individual entrepreneur, company is bound to the person.\n \n Maps to Shift4's sole_trader when forwarding onboarding data via the eventual Shift4\n mapping guardrail. Note: our Individual is semantically broader (\"any natural person\n operating as a business\") than Shift4's sole_trader (\"owns and runs the business, no\n legal distinction between person and business\"). The mapping is correct for the common case;\n edge cases like a natural person holding non-trader business registrations are handled by\n the validator at the submit-to-PSP boundary before forwarding.)\n - 2 = Company (Legally setup for-profit company.)\n - 3 = NonprofitOrganization (Non-profit company.)\n - 4 = GovernmentEntity (Govermental entity.)\n - 5 = Partnership (Partnership — osobní společnost (personal company) where at least one partner has\n unlimited personal liability for the firm's debts. Distinct from \n (kapitálová společnost), where shareholder liability is capped at their capital\n contribution. Classification is determined by registered legal form, NOT by headcount —\n a multi-shareholder s.r.o. is still , a two-partner v.o.s. is\n Partnership.\n \n Maps to Shift4's partnership business_type. Stripe has no equivalent value\n — its enum is { individual, company, non_profit, government_entity } — so the\n Stripe connector maps this to as a lossy fallback (Stripe\n classifies multi-owner entities under company regardless of liability\n structure).\n \n CZ legal forms in scope: v.o.s. (veřejná obchodní společnost — všichni společníci\n ručí osobně) and k.s. (komanditní společnost — komplementáři ručí osobně,\n komanditisté do výše vkladu). Per ZOK 90/2012 Sb. § 95 et seq. KYB workflow\n consequence: Shift4 requires ≥2 individuals tagged partner (no\n director or UBO_ownership allowed) because partnerships have no\n separate management body and the UBO ≥25% threshold doesn't apply to partner\n stakes — every general partner must be identified regardless of share size, per\n AMLD 5/6 and CZ zákon č. 253/2008 Sb.)\n",
"x-enum-varnames": [
"Individual",
"Company",
"NonprofitOrganization",
"GovernmentEntity",
"Partnership"
]
},
"CardHolderTypeEnum": {
"enum": [
1,
2
],
"description": "Allowed values:\n - 1 = Customer (Consumer / personal cards.)\n - 2 = Company (Corporate / business cards.)\n",
"x-enum-varnames": [
"Customer",
"Company"
]
},
"CardIndicativeRatesJson": {
"required": [
"consumerEea",
"consumerNonEea",
"commercialEea",
"commercialNonEea"
],
"type": "object",
"properties": {
"consumerEea": {
"$ref": "#/components/schemas/IndicativeFeeRateJson"
},
"consumerNonEea": {
"$ref": "#/components/schemas/IndicativeFeeRateJson"
},
"commercialEea": {
"$ref": "#/components/schemas/IndicativeFeeRateJson"
},
"commercialNonEea": {
"$ref": "#/components/schemas/IndicativeFeeRateJson"
}
}
},
"CardRegionEnum": {
"enum": [
1,
2
],
"description": "Allowed values:\n - 1 = Domestic (Domestic cards.)\n - 2 = International (International cards.)\n",
"x-enum-varnames": [
"Domestic",
"International"
]
},
"CardSchemeEnum": {
"enum": [
1,
2
],
"description": "Allowed values:\n - 1 = Visa (Visa.)\n - 2 = Mastercard (Mastercard.)\n",
"x-enum-varnames": [
"Visa",
"Mastercard"
]
},
"CompanyInformation": {
"required": [
"name",
"registrationNumber",
"people"
],
"type": "object",
"properties": {
"name": {
"maxLength": 150,
"type": "string",
"description": "Legal name of the company as written in the legal register.",
"example": "Acme Corporation"
},
"address": {
"oneOf": [
{
"type": "null"
},
{
"description": "Company registered headquarters address.",
"$ref": "#/components/schemas/AddressInformation"
}
]
},
"phone": {
"maxLength": 20,
"type": [
"null",
"string"
],
"description": "Contact phone number of the company.",
"example": "+1-800-555-1234"
},
"registrationNumber": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "Business identifier of the company from the register, such as a company number,\nbusiness number, or employer identifier.",
"example": 123456789
},
"vatNumber": {
"maxLength": 50,
"minLength": 0,
"type": [
"null",
"string"
],
"description": "VAT number. Only fill if the company is VAT registered.",
"example": "DE123456789"
},
"people": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PersonInformation"
},
"description": "List of individuals associated with the company, such as directors, or beneficial owners."
},
"verificationDocument": {
"oneOf": [
{
"type": "null"
},
{
"description": "Company verification document (proof of entity). Might be required if it cannot be automatically verified.",
"$ref": "#/components/schemas/DocumentReference"
}
]
}
},
"description": "Represents detailed information about a company, including its name, business type,\naddress, contact details, and tax-related identifiers."
},
"CompanyPayload": {
"required": [
"people"
],
"type": "object",
"properties": {
"people": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PersonPayload"
},
"description": "Company representatives, directors, and UBOs."
},
"verificationDocument": {
"oneOf": [
{
"type": "null"
},
{
"description": "Company incorporation or registration document.",
"$ref": "#/components/schemas/DocumentReferencePayload"
}
]
}
}
},
"CountryEnum": {
"enum": [
4,
8,
10,
12,
16,
20,
24,
28,
31,
32,
36,
40,
44,
48,
50,
51,
52,
56,
60,
64,
68,
70,
72,
74,
76,
84,
86,
90,
92,
96,
100,
104,
108,
112,
116,
120,
124,
132,
136,
140,
144,
148,
152,
156,
158,
162,
166,
170,
174,
175,
178,
180,
184,
188,
191,
192,
196,
203,
204,
208,
212,
214,
218,
222,
226,
231,
232,
233,
234,
238,
239,
242,
246,
248,
250,
254,
258,
260,
262,
266,
268,
270,
275,
276,
288,
292,
296,
300,
304,
308,
312,
316,
320,
324,
328,
332,
334,
336,
340,
344,
348,
352,
356,
360,
364,
368,
372,
376,
380,
384,
388,
392,
398,
400,
404,
408,
410,
414,
417,
418,
422,
426,
428,
430,
434,
438,
440,
442,
446,
450,
454,
458,
462,
466,
470,
474,
478,
480,
484,
492,
496,
498,
499,
500,
504,
508,
512,
516,
520,
524,
528,
531,
533,
534,
535,
540,
548,
554,
558,
562,
566,
570,
574,
578,
580,
581,
583,
584,
585,
586,
591,
598,
600,
604,
608,
612,
616,
620,
624,
626,
630,
634,
638,
642,
643,
646,
652,
654,
659,
660,
662,
663,
666,
670,
674,
678,
682,
686,
688,
690,
694,
702,
703,
704,
705,
706,
710,
716,
724,
728,
729,
732,
740,
744,
748,
752,
756,
760,
762,
764,
768,
772,
776,
780,
784,
788,
792,
795,
796,
798,
800,
804,
807,
818,
826,
831,
832,
833,
834,
840,
850,
854,
858,
860,
862,
876,
882,
887,
894
],
"type": "integer",
"description": "Allowed values:\n - 4 = AF (Afghanistan (AF / AFG))\n - 8 = AL (Albania (AL / ALB))\n - 10 = AQ (Antarctica (AQ / ATA))\n - 12 = DZ (Algeria (DZ / DZA))\n - 16 = AS (American Samoa (AS / ASM))\n - 20 = AD (Andorra (AD / AND))\n - 24 = AO (Angola (AO / AGO))\n - 28 = AG (Antigua and Barbuda (AG / ATG))\n - 31 = AZ (Azerbaijan (AZ / AZE))\n - 32 = AR (Argentina (AR / ARG))\n - 36 = AU (Australia (AU / AUS))\n - 40 = AT (Austria (AT / AUT))\n - 44 = BS (Bahamas (BS / BHS))\n - 48 = BH (Bahrain (BH / BHR))\n - 50 = BD (Bangladesh (BD / BGD))\n - 51 = AM (Armenia (AM / ARM))\n - 52 = BB (Barbados (BB / BRB))\n - 56 = BE (Belgium (BE / BEL))\n - 60 = BM (Bermuda (BM / BMU))\n - 64 = BT (Bhutan (BT / BTN))\n - 68 = BO (Bolivia, Plurinational State of (BO / BOL))\n - 70 = BA (Bosnia and Herzegovina (BA / BIH))\n - 72 = BW (Botswana (BW / BWA))\n - 74 = BV (Bouvet Island (BV / BVT))\n - 76 = BR (Brazil (BR / BRA))\n - 84 = BZ (Belize (BZ / BLZ))\n - 86 = IO (British Indian Ocean Territory (IO / IOT))\n - 90 = SB (Solomon Islands (SB / SLB))\n - 92 = VG (Virgin Islands (British) (VG / VGB))\n - 96 = BN (Brunei Darussalam (BN / BRN))\n - 100 = BG (Bulgaria (BG / BGR))\n - 104 = MM (Myanmar (MM / MMR))\n - 108 = BI (Burundi (BI / BDI))\n - 112 = BY (Belarus (BY / BLR))\n - 116 = KH (Cambodia (KH / KHM))\n - 120 = CM (Cameroon (CM / CMR))\n - 124 = CA (Canada (CA / CAN))\n - 132 = CV (Cabo Verde (CV / CPV))\n - 136 = KY (Cayman Islands (KY / CYM))\n - 140 = CF (Central African Republic (CF / CAF))\n - 144 = LK (Sri Lanka (LK / LKA))\n - 148 = TD (Chad (TD / TCD))\n - 152 = CL (Chile (CL / CHL))\n - 156 = CN (China (CN / CHN))\n - 158 = TW (Taiwan, Province of China (TW / TWN))\n - 162 = CX (Christmas Island (CX / CXR))\n - 166 = CC (Cocos (Keeling) Islands (CC / CCK))\n - 170 = CO (Colombia (CO / COL))\n - 174 = KM (Comoros (KM / COM))\n - 175 = YT (Mayotte (YT / MYT))\n - 178 = CG (Congo (CG / COG))\n - 180 = CD (Congo, Democratic Republic of the (CD / COD))\n - 184 = CK (Cook Islands (CK / COK))\n - 188 = CR (Costa Rica (CR / CRI))\n - 191 = HR (Croatia (HR / HRV))\n - 192 = CU (Cuba (CU / CUB))\n - 196 = CY (Cyprus (CY / CYP))\n - 203 = CZ (Czechia (CZ / CZE))\n - 204 = BJ (Benin (BJ / BEN))\n - 208 = DK (Denmark (DK / DNK))\n - 212 = DM (Dominica (DM / DMA))\n - 214 = DO (Dominican Republic (DO / DOM))\n - 218 = EC (Ecuador (EC / ECU))\n - 222 = SV (El Salvador (SV / SLV))\n - 226 = GQ (Equatorial Guinea (GQ / GNQ))\n - 231 = ET (Ethiopia (ET / ETH))\n - 232 = ER (Eritrea (ER / ERI))\n - 233 = EE (Estonia (EE / EST))\n - 234 = FO (Faroe Islands (FO / FRO))\n - 238 = FK (Falkland Islands (Malvinas) (FK / FLK))\n - 239 = GS (South Georgia and the South Sandwich Islands (GS / SGS))\n - 242 = FJ (Fiji (FJ / FJI))\n - 246 = FI (Finland (FI / FIN))\n - 248 = AX (Åland Islands (AX / ALA))\n - 250 = FR (France (FR / FRA))\n - 254 = GF (French Guiana (GF / GUF))\n - 258 = PF (French Polynesia (PF / PYF))\n - 260 = TF (French Southern Territories (TF / ATF))\n - 262 = DJ (Djibouti (DJ / DJI))\n - 266 = GA (Gabon (GA / GAB))\n - 268 = GE (Georgia (GE / GEO))\n - 270 = GM (Gambia (GM / GMB))\n - 275 = PS (Palestine, State of (PS / PSE))\n - 276 = DE (Germany (DE / DEU))\n - 288 = GH (Ghana (GH / GHA))\n - 292 = GI (Gibraltar (GI / GIB))\n - 296 = KI (Kiribati (KI / KIR))\n - 300 = GR (Greece (GR / GRC))\n - 304 = GL (Greenland (GL / GRL))\n - 308 = GD (Grenada (GD / GRD))\n - 312 = GP (Guadeloupe (GP / GLP))\n - 316 = GU (Guam (GU / GUM))\n - 320 = GT (Guatemala (GT / GTM))\n - 324 = GN (Guinea (GN / GIN))\n - 328 = GY (Guyana (GY / GUY))\n - 332 = HT (Haiti (HT / HTI))\n - 334 = HM (Heard Island and McDonald Islands (HM / HMD))\n - 336 = VA (Holy See (VA / VAT))\n - 340 = HN (Honduras (HN / HND))\n - 344 = HK (Hong Kong (HK / HKG))\n - 348 = HU (Hungary (HU / HUN))\n - 352 = IS (Iceland (IS / ISL))\n - 356 = IN (India (IN / IND))\n - 360 = ID (Indonesia (ID / IDN))\n - 364 = IR (Iran, Islamic Republic of (IR / IRN))\n - 368 = IQ (Iraq (IQ / IRQ))\n - 372 = IE (Ireland (IE / IRL))\n - 376 = IL (Israel (IL / ISR))\n - 380 = IT (Italy (IT / ITA))\n - 384 = CI (Côte d'Ivoire (CI / CIV))\n - 388 = JM (Jamaica (JM / JAM))\n - 392 = JP (Japan (JP / JPN))\n - 398 = KZ (Kazakhstan (KZ / KAZ))\n - 400 = JO (Jordan (JO / JOR))\n - 404 = KE (Kenya (KE / KEN))\n - 408 = KP (Korea, Democratic People's Republic of (KP / PRK))\n - 410 = KR (Korea, Republic of (KR / KOR))\n - 414 = KW (Kuwait (KW / KWT))\n - 417 = KG (Kyrgyzstan (KG / KGZ))\n - 418 = LA (Lao People's Democratic Republic (LA / LAO))\n - 422 = LB (Lebanon (LB / LBN))\n - 426 = LS (Lesotho (LS / LSO))\n - 428 = LV (Latvia (LV / LVA))\n - 430 = LR (Liberia (LR / LBR))\n - 434 = LY (Libya (LY / LBY))\n - 438 = LI (Liechtenstein (LI / LIE))\n - 440 = LT (Lithuania (LT / LTU))\n - 442 = LU (Luxembourg (LU / LUX))\n - 446 = MO (Macao (MO / MAC))\n - 450 = MG (Madagascar (MG / MDG))\n - 454 = MW (Malawi (MW / MWI))\n - 458 = MY (Malaysia (MY / MYS))\n - 462 = MV (Maldives (MV / MDV))\n - 466 = ML (Mali (ML / MLI))\n - 470 = MT (Malta (MT / MLT))\n - 474 = MQ (Martinique (MQ / MTQ))\n - 478 = MR (Mauritania (MR / MRT))\n - 480 = MU (Mauritius (MU / MUS))\n - 484 = MX (Mexico (MX / MEX))\n - 492 = MC (Monaco (MC / MCO))\n - 496 = MN (Mongolia (MN / MNG))\n - 498 = MD (Moldova, Republic of (MD / MDA))\n - 499 = ME (Montenegro (ME / MNE))\n - 500 = MS (Montserrat (MS / MSR))\n - 504 = MA (Morocco (MA / MAR))\n - 508 = MZ (Mozambique (MZ / MOZ))\n - 512 = OM (Oman (OM / OMN))\n - 516 = NA (Namibia (NA / NAM))\n - 520 = NR (Nauru (NR / NRU))\n - 524 = NP (Nepal (NP / NPL))\n - 528 = NL (Netherlands, Kingdom of the (NL / NLD))\n - 531 = CW (Curaçao (CW / CUW))\n - 533 = AW (Aruba (AW / ABW))\n - 534 = SX (Sint Maarten (Dutch part) (SX / SXM))\n - 535 = BQ (Bonaire, Sint Eustatius and Saba (BQ / BES))\n - 540 = NC (New Caledonia (NC / NCL))\n - 548 = VU (Vanuatu (VU / VUT))\n - 554 = NZ (New Zealand (NZ / NZL))\n - 558 = NI (Nicaragua (NI / NIC))\n - 562 = NE (Niger (NE / NER))\n - 566 = NG (Nigeria (NG / NGA))\n - 570 = NU (Niue (NU / NIU))\n - 574 = NF (Norfolk Island (NF / NFK))\n - 578 = NO (Norway (NO / NOR))\n - 580 = MP (Northern Mariana Islands (MP / MNP))\n - 581 = UM (United States Minor Outlying Islands (UM / UMI))\n - 583 = FM (Micronesia, Federated States of (FM / FSM))\n - 584 = MH (Marshall Islands (MH / MHL))\n - 585 = PW (Palau (PW / PLW))\n - 586 = PK (Pakistan (PK / PAK))\n - 591 = PA (Panama (PA / PAN))\n - 598 = PG (Papua New Guinea (PG / PNG))\n - 600 = PY (Paraguay (PY / PRY))\n - 604 = PE (Peru (PE / PER))\n - 608 = PH (Philippines (PH / PHL))\n - 612 = PN (Pitcairn (PN / PCN))\n - 616 = PL (Poland (PL / POL))\n - 620 = PT (Portugal (PT / PRT))\n - 624 = GW (Guinea-Bissau (GW / GNB))\n - 626 = TL (Timor-Leste (TL / TLS))\n - 630 = PR (Puerto Rico (PR / PRI))\n - 634 = QA (Qatar (QA / QAT))\n - 638 = RE (Réunion (RE / REU))\n - 642 = RO (Romania (RO / ROU))\n - 643 = RU (Russian Federation (RU / RUS))\n - 646 = RW (Rwanda (RW / RWA))\n - 652 = BL (Saint Barthélemy (BL / BLM))\n - 654 = SH (Saint Helena, Ascension and Tristan da Cunha (SH / SHN))\n - 659 = KN (Saint Kitts and Nevis (KN / KNA))\n - 660 = AI (Anguilla (AI / AIA))\n - 662 = LC (Saint Lucia (LC / LCA))\n - 663 = MF (Saint Martin (French part) (MF / MAF))\n - 666 = PM (Saint Pierre and Miquelon (PM / SPM))\n - 670 = VC (Saint Vincent and the Grenadines (VC / VCT))\n - 674 = SM (San Marino (SM / SMR))\n - 678 = ST (Sao Tome and Principe (ST / STP))\n - 682 = SA (Saudi Arabia (SA / SAU))\n - 686 = SN (Senegal (SN / SEN))\n - 688 = RS (Serbia (RS / SRB))\n - 690 = SC (Seychelles (SC / SYC))\n - 694 = SL (Sierra Leone (SL / SLE))\n - 702 = SG (Singapore (SG / SGP))\n - 703 = SK (Slovakia (SK / SVK))\n - 704 = VN (Viet Nam (VN / VNM))\n - 705 = SI (Slovenia (SI / SVN))\n - 706 = SO (Somalia (SO / SOM))\n - 710 = ZA (South Africa (ZA / ZAF))\n - 716 = ZW (Zimbabwe (ZW / ZWE))\n - 724 = ES (Spain (ES / ESP))\n - 728 = SS (South Sudan (SS / SSD))\n - 729 = SD (Sudan (SD / SDN))\n - 732 = EH (Western Sahara (EH / ESH))\n - 740 = SR (Suriname (SR / SUR))\n - 744 = SJ (Svalbard and Jan Mayen (SJ / SJM))\n - 748 = SZ (Eswatini (SZ / SWZ))\n - 752 = SE (Sweden (SE / SWE))\n - 756 = CH (Switzerland (CH / CHE))\n - 760 = SY (Syrian Arab Republic (SY / SYR))\n - 762 = TJ (Tajikistan (TJ / TJK))\n - 764 = TH (Thailand (TH / THA))\n - 768 = TG (Togo (TG / TGO))\n - 772 = TK (Tokelau (TK / TKL))\n - 776 = TO (Tonga (TO / TON))\n - 780 = TT (Trinidad and Tobago (TT / TTO))\n - 784 = AE (United Arab Emirates (AE / ARE))\n - 788 = TN (Tunisia (TN / TUN))\n - 792 = TR (Türkiye (TR / TUR))\n - 795 = TM (Turkmenistan (TM / TKM))\n - 796 = TC (Turks and Caicos Islands (TC / TCA))\n - 798 = TV (Tuvalu (TV / TUV))\n - 800 = UG (Uganda (UG / UGA))\n - 804 = UA (Ukraine (UA / UKR))\n - 807 = MK (North Macedonia (MK / MKD))\n - 818 = EG (Egypt (EG / EGY))\n - 826 = GB (United Kingdom of Great Britain and Northern Ireland (GB / GBR))\n - 831 = GG (Guernsey (GG / GGY))\n - 832 = JE (Jersey (JE / JEY))\n - 833 = IM (Isle of Man (IM / IMN))\n - 834 = TZ (Tanzania, United Republic of (TZ / TZA))\n - 840 = US (United States of America (US / USA))\n - 850 = VI (Virgin Islands (U.S.) (VI / VIR))\n - 854 = BF (Burkina Faso (BF / BFA))\n - 858 = UY (Uruguay (UY / URY))\n - 860 = UZ (Uzbekistan (UZ / UZB))\n - 862 = VE (Venezuela, Bolivarian Republic of (VE / VEN))\n - 876 = WF (Wallis and Futuna (WF / WLF))\n - 882 = WS (Samoa (WS / WSM))\n - 887 = YE (Yemen (YE / YEM))\n - 894 = ZM (Zambia (ZM / ZMB))\n",
"x-enum-varnames": [
"AF",
"AL",
"AQ",
"DZ",
"AS",
"AD",
"AO",
"AG",
"AZ",
"AR",
"AU",
"AT",
"BS",
"BH",
"BD",
"AM",
"BB",
"BE",
"BM",
"BT",
"BO",
"BA",
"BW",
"BV",
"BR",
"BZ",
"IO",
"SB",
"VG",
"BN",
"BG",
"MM",
"BI",
"BY",
"KH",
"CM",
"CA",
"CV",
"KY",
"CF",
"LK",
"TD",
"CL",
"CN",
"TW",
"CX",
"CC",
"CO",
"KM",
"YT",
"CG",
"CD",
"CK",
"CR",
"HR",
"CU",
"CY",
"CZ",
"BJ",
"DK",
"DM",
"DO",
"EC",
"SV",
"GQ",
"ET",
"ER",
"EE",
"FO",
"FK",
"GS",
"FJ",
"FI",
"AX",
"FR",
"GF",
"PF",
"TF",
"DJ",
"GA",
"GE",
"GM",
"PS",
"DE",
"GH",
"GI",
"KI",
"GR",
"GL",
"GD",
"GP",
"GU",
"GT",
"GN",
"GY",
"HT",
"HM",
"VA",
"HN",
"HK",
"HU",
"IS",
"IN",
"ID",
"IR",
"IQ",
"IE",
"IL",
"IT",
"CI",
"JM",
"JP",
"KZ",
"JO",
"KE",
"KP",
"KR",
"KW",
"KG",
"LA",
"LB",
"LS",
"LV",
"LR",
"LY",
"LI",
"LT",
"LU",
"MO",
"MG",
"MW",
"MY",
"MV",
"ML",
"MT",
"MQ",
"MR",
"MU",
"MX",
"MC",
"MN",
"MD",
"ME",
"MS",
"MA",
"MZ",
"OM",
"NA",
"NR",
"NP",
"NL",
"CW",
"AW",
"SX",
"BQ",
"NC",
"VU",
"NZ",
"NI",
"NE",
"NG",
"NU",
"NF",
"NO",
"MP",
"UM",
"FM",
"MH",
"PW",
"PK",
"PA",
"PG",
"PY",
"PE",
"PH",
"PN",
"PL",
"PT",
"GW",
"TL",
"PR",
"QA",
"RE",
"RO",
"RU",
"RW",
"BL",
"SH",
"KN",
"AI",
"LC",
"MF",
"PM",
"VC",
"SM",
"ST",
"SA",
"SN",
"RS",
"SC",
"SL",
"SG",
"SK",
"VN",
"SI",
"SO",
"ZA",
"ZW",
"ES",
"SS",
"SD",
"EH",
"SR",
"SJ",
"SZ",
"SE",
"CH",
"SY",
"TJ",
"TH",
"TG",
"TK",
"TO",
"TT",
"AE",
"TN",
"TR",
"TM",
"TC",
"TV",
"UG",
"UA",
"MK",
"EG",
"GB",
"GG",
"JE",
"IM",
"TZ",
"US",
"VI",
"BF",
"UY",
"UZ",
"VE",
"WF",
"WS",
"YE",
"ZM"
]
},
"CurrencyDailyDataPoint": {
"required": [
"currencyId",
"date",
"value"
],
"type": "object",
"properties": {
"currencyId": {
"description": "ISO 4217 numeric currency code.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"date": {
"description": "Date of the data point.",
"$ref": "#/components/schemas/LocalDate"
},
"value": {
"type": "integer",
"description": "Value for the date.",
"format": "int64"
}
}
},
"CurrencyEnum": {
"enum": [
203,
208,
348,
352,
578,
752,
756,
826,
840,
946,
978,
985,
9001,
9002,
9003,
9004,
9005
],
"type": "integer",
"description": "ISO 4217 currency codes (fiat: numeric ISO 4217, crypto: 9XXX)\nAllowed values:\n - 203 = CZK (Czech Koruna)\n - 208 = DKK (Danish Krone)\n - 348 = HUF (Hungarian Forint)\n - 352 = ISK (Icelandic Krona)\n - 578 = NOK (Norwegian Krone)\n - 752 = SEK (Swedish Krona)\n - 756 = CHF (Swiss Franc)\n - 826 = GBP (Pound sterling)\n - 840 = USD (US Dollar)\n - 946 = RON (Romanian Leu)\n - 978 = EUR (Euro)\n - 985 = PLN (Polish Zloty)\n - 9001 = BTC (Bitcoin)\n - 9002 = ETH (Ethereum)\n - 9003 = USDT (Tether USD)\n - 9004 = USDC (USD Coin)\n - 9005 = LTC (Litecoin)\n",
"x-enum-varnames": [
"CZK",
"DKK",
"HUF",
"ISK",
"NOK",
"SEK",
"CHF",
"GBP",
"USD",
"RON",
"EUR",
"PLN",
"BTC",
"ETH",
"USDT",
"USDC",
"LTC"
]
},
"DailyDataPointOfint": {
"required": [
"date",
"value"
],
"type": "object",
"properties": {
"date": {
"description": "Date of the data point.",
"$ref": "#/components/schemas/LocalDate"
},
"value": {
"type": "integer",
"description": "Value for the date.",
"format": "int32"
}
}
},
"DailyDataPointOflong": {
"required": [
"date",
"value"
],
"type": "object",
"properties": {
"date": {
"description": "Date of the data point.",
"$ref": "#/components/schemas/LocalDate"
},
"value": {
"type": "integer",
"description": "Value for the date.",
"format": "int64"
}
}
},
"DocumentReference": {
"required": [
"frontFileId"
],
"type": "object",
"properties": {
"frontFileId": {
"maxLength": 255,
"type": "string",
"description": "Processor File ID for document front side"
},
"backFileId": {
"maxLength": 255,
"type": [
"null",
"string"
],
"description": "Processor File ID for document back side (optional for some documents)"
}
},
"description": "Reference to a verification document with front and back sides"
},
"DocumentReferencePayload": {
"type": "object",
"properties": {
"frontFileId": {
"type": [
"null",
"string"
],
"description": "File ID of the document front side."
},
"backFileId": {
"type": [
"null",
"string"
],
"description": "File ID of the document back side."
}
}
},
"DocumentTypeEnum": {
"enum": [
1,
2,
3,
4,
5,
6,
7
],
"type": "integer",
"description": "KYB document type.\nAllowed values:\n - 1 = Other (Document type not covered by the other categories.)\n - 2 = Id (Government-issued photo ID (driver's license, national ID card).)\n - 3 = Address (Proof of address, such as utility bill, bank statement, lease agreement)\n - 4 = Company (Company verification document, such article of incorporation, business license)\n - 5 = BankStatement (Proof of bank account possession.)\n - 6 = Passport (Passport (travel document with photo page).)\n - 7 = RecentFinancials (Recent financial statements (annual report, audited accounts).)\n",
"x-enum-varnames": [
"Other",
"Id",
"Address",
"Company",
"BankStatement",
"Passport",
"RecentFinancials"
]
},
"HeatmapCellResponse": {
"required": [
"dayOfWeek",
"hour",
"avgTransactions"
],
"type": "object",
"properties": {
"dayOfWeek": {
"type": "integer",
"description": "Day of week. 0 = Monday, 6 = Sunday.",
"format": "int32"
},
"hour": {
"type": "integer",
"description": "Hour of day in UTC. 0–23.",
"format": "int32"
},
"avgTransactions": {
"type": "number",
"description": "Average number of transactions for this day/hour bucket.",
"format": "double"
}
}
},
"IdentityPayload": {
"required": [
"legalName",
"businessTypeId",
"email",
"registrationNumber"
],
"type": "object",
"properties": {
"legalName": {
"type": "string",
"description": "Legal name of the merchant entity."
},
"businessTypeId": {
"description": "Type of business entity.",
"$ref": "#/components/schemas/BusinessTypeEnum"
},
"email": {
"type": "string",
"description": "Business email address."
},
"registrationNumber": {
"type": "string",
"description": "Company registration number."
},
"vatNumber": {
"type": [
"null",
"string"
],
"description": "VAT identification number."
},
"incorporationDate": {
"type": [
"null",
"string"
],
"description": "Date the company was incorporated.",
"format": "date"
}
}
},
"IFormFile": {
"type": "string",
"format": "binary"
},
"IndicativeFeeRateJson": {
"required": [
"feeAbsolute",
"feeRelative"
],
"type": "object",
"properties": {
"feeAbsolute": {
"type": "integer",
"format": "int64"
},
"feeRelative": {
"type": "integer",
"format": "int64"
}
}
},
"IndicativeRatesSnapshot": {
"type": "object",
"properties": {
"card": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CardIndicativeRatesJson"
}
]
},
"standard": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/IndicativeFeeRateJson"
}
]
}
}
},
"IndividualPayload": {
"type": "object",
"properties": {
"firstName": {
"type": [
"null",
"string"
],
"description": "First name."
},
"lastName": {
"type": [
"null",
"string"
],
"description": "Last name."
},
"phone": {
"type": [
"null",
"string"
],
"description": "Phone number."
},
"dateOfBirth": {
"type": [
"null",
"string"
],
"description": "Date of birth.",
"format": "date"
},
"nationalityCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Nationality country.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"placeOfBirthCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Country of birth.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"officialIdType": {
"oneOf": [
{
"type": "null"
},
{
"description": "Type of official identity document.",
"$ref": "#/components/schemas/OfficialIdTypeEnum"
}
]
},
"officialIdNumber": {
"type": [
"null",
"string"
],
"description": "Official identity document number."
},
"officialIdExpiryDate": {
"type": [
"null",
"string"
],
"description": "Expiry date of the official identity document.",
"format": "date"
},
"passportPlaceOfIssue": {
"type": [
"null",
"string"
],
"description": "Place of issue for passport."
},
"address": {
"oneOf": [
{
"type": "null"
},
{
"description": "Residential address.",
"$ref": "#/components/schemas/AddressObjectPayload"
}
]
},
"role": {
"oneOf": [
{
"type": "null"
},
{
"description": "Role(s) within the company.",
"$ref": "#/components/schemas/RolePayload"
}
]
},
"title": {
"type": [
"null",
"string"
],
"description": "Job title."
},
"ownershipPercentage": {
"type": [
"null",
"number"
],
"description": "Ownership percentage (0–100).",
"format": "double"
},
"verificationDocuments": {
"oneOf": [
{
"type": "null"
},
{
"description": "Identity verification documents.",
"$ref": "#/components/schemas/VerificationDocumentsPayload"
}
]
}
}
},
"Instant": {
"type": "string",
"description": "Instant in time",
"format": "date-time",
"example": "9999-12-31T23:59:59.999999999"
},
"IntegratorMerchantActivateResponse": {
"required": [
"isActive"
],
"type": "object",
"properties": {
"isActive": {
"type": "boolean",
"description": "Always true; confirms the merchant is now active."
}
}
},
"IntegratorMerchantActiveLocationsGetResponse": {
"required": [
"terminalId",
"latitude",
"longitude"
],
"type": "object",
"properties": {
"terminalId": {
"type": "string",
"description": "Terminal identifier.",
"format": "uuid"
},
"latitude": {
"type": "number",
"description": "Geographical latitude of the terminal.",
"format": "double"
},
"longitude": {
"type": "number",
"description": "Geographical longitude of the terminal.",
"format": "double"
},
"brand": {
"type": [
"null",
"string"
],
"description": "Terminal device brand."
},
"model": {
"type": [
"null",
"string"
],
"description": "Terminal device model."
}
}
},
"IntegratorMerchantBankAccountPrimaryPutRequest": {
"required": [
"bankAccountId"
],
"type": "object",
"properties": {
"bankAccountId": {
"type": "string",
"description": "Id of the bank account to mark primary.",
"format": "uuid"
}
}
},
"IntegratorMerchantBankAccountsGetResult": {
"required": [
"bankAccountId",
"iban",
"currencyId",
"beneficiaryName",
"isPrimary",
"createdAt",
"updatedAt"
],
"type": "object",
"properties": {
"bankAccountId": {
"type": "string",
"description": "Bank account identifier.",
"format": "uuid"
},
"iban": {
"type": "string",
"description": "IBAN."
},
"bic": {
"type": [
"null",
"string"
],
"description": "SWIFT/BIC code."
},
"currencyId": {
"description": "Settlement currency.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"beneficiaryName": {
"type": "string",
"description": "Beneficiary name on the bank account."
},
"isPrimary": {
"type": "boolean",
"description": "True if this account is the merchant's primary settlement destination."
},
"addressCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Beneficiary address country.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"addressCity": {
"type": [
"null",
"string"
],
"description": "Beneficiary address city."
},
"addressLine1": {
"type": [
"null",
"string"
],
"description": "Beneficiary address line 1."
},
"addressLine2": {
"type": [
"null",
"string"
],
"description": "Beneficiary address line 2."
},
"addressState": {
"type": [
"null",
"string"
],
"description": "Beneficiary address state/region."
},
"addressPostalCode": {
"type": [
"null",
"string"
],
"description": "Beneficiary address postal code."
},
"bankName": {
"type": [
"null",
"string"
],
"description": "Name of the bank that holds the account."
},
"bankCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Country in which the bank itself is registered.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"createdAt": {
"description": "Creation timestamp.",
"$ref": "#/components/schemas/Instant"
},
"updatedAt": {
"description": "Last update timestamp.",
"$ref": "#/components/schemas/Instant"
}
}
},
"IntegratorMerchantBankAccountsPostRequest": {
"required": [
"iban",
"currencyId",
"beneficiaryName"
],
"type": "object",
"properties": {
"iban": {
"maxLength": 34,
"minLength": 15,
"type": "string",
"description": "IBAN."
},
"bic": {
"maxLength": 11,
"minLength": 8,
"type": [
"null",
"string"
],
"description": "SWIFT/BIC code."
},
"currencyId": {
"description": "Settlement currency for this account.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"beneficiaryName": {
"maxLength": 255,
"minLength": 1,
"type": "string",
"description": "Beneficiary name on the bank account."
},
"addressCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Beneficiary address country.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"addressCity": {
"maxLength": 100,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Beneficiary address city."
},
"addressLine1": {
"maxLength": 255,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Beneficiary address line 1."
},
"addressLine2": {
"maxLength": 255,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Beneficiary address line 2."
},
"addressState": {
"maxLength": 100,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Beneficiary address state/region."
},
"addressPostalCode": {
"maxLength": 100,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Beneficiary address postal code."
},
"bankName": {
"maxLength": 255,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Name of the bank that holds the account."
},
"bankCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Country in which the bank itself is registered.",
"$ref": "#/components/schemas/CountryEnum"
}
]
}
}
},
"IntegratorMerchantBankAccountsPostResult": {
"required": [
"bankAccountId",
"iban",
"currencyId",
"beneficiaryName",
"isPrimary",
"createdAt",
"updatedAt"
],
"type": "object",
"properties": {
"bankAccountId": {
"type": "string",
"description": "Bank account identifier.",
"format": "uuid"
},
"iban": {
"type": "string",
"description": "IBAN."
},
"bic": {
"type": [
"null",
"string"
],
"description": "SWIFT/BIC code."
},
"currencyId": {
"description": "Settlement currency for this account.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"beneficiaryName": {
"type": "string",
"description": "Beneficiary name on the bank account."
},
"isPrimary": {
"type": "boolean",
"description": "True if this account is the merchant's primary settlement destination."
},
"addressCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Beneficiary address country.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"addressCity": {
"type": [
"null",
"string"
],
"description": "Beneficiary address city."
},
"addressLine1": {
"type": [
"null",
"string"
],
"description": "Beneficiary address line 1."
},
"addressLine2": {
"type": [
"null",
"string"
],
"description": "Beneficiary address line 2."
},
"addressState": {
"type": [
"null",
"string"
],
"description": "Beneficiary address state or region."
},
"addressPostalCode": {
"type": [
"null",
"string"
],
"description": "Beneficiary address postal code."
},
"bankName": {
"type": [
"null",
"string"
],
"description": "Name of the bank that holds the account."
},
"bankCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Country in which the bank itself is registered.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"createdAt": {
"description": "UTC timestamp when the bank account record was created.",
"$ref": "#/components/schemas/Instant"
},
"updatedAt": {
"description": "UTC timestamp when the bank account record was last updated.",
"$ref": "#/components/schemas/Instant"
}
}
},
"IntegratorMerchantCreateRequest": {
"required": [
"name",
"email"
],
"type": "object",
"properties": {
"name": {
"maxLength": 200,
"type": "string",
"description": "The name of the merchant."
},
"merchantToken": {
"maxLength": 100,
"type": [
"null",
"string"
],
"description": "Integrator-defined token used to activate POS terminals for this merchant; auto-generated if omitted, max 100 characters."
},
"email": {
"maxLength": 255,
"type": "string",
"description": "The email address of the merchant."
}
}
},
"IntegratorMerchantDeactivateResponse": {
"required": [
"isActive"
],
"type": "object",
"properties": {
"isActive": {
"type": "boolean",
"description": "Always false; confirms the merchant is now deactivated."
}
}
},
"IntegratorMerchantDocumentPostRequest": {
"required": [
"paymentProcessorId",
"documentType",
"frontFile"
],
"type": "object",
"properties": {
"paymentProcessorId": {
"description": "The payment processor to upload the document to.",
"$ref": "#/components/schemas/PaymentProcessorEnum"
},
"documentType": {
"description": "The type of verification document being uploaded.",
"$ref": "#/components/schemas/DocumentTypeEnum"
},
"frontFile": {
"description": "The front side of the document image file.",
"$ref": "#/components/schemas/IFormFile"
},
"backFile": {
"oneOf": [
{
"type": "null"
},
{
"description": "The back side of the document image file.",
"$ref": "#/components/schemas/IFormFile"
}
]
},
"relatedOfficialIdNumber": {
"type": [
"null",
"string"
],
"description": "Stakeholder's `official_id_number` when uploading an individual-bound\ndocument (e.g. Passport, Proof of address). Transient — never persisted. Ignored when\nnot applicable to the merchant's processor. Required when the document type is individual-bound."
},
"submitMerchant": {
"type": "boolean",
"description": "Set to `true` on the LAST upload of a submission batch to trigger the processor's\nKYC review. Defaults to `false`. Ignored when not applicable to the merchant's processor."
}
},
"description": "Request model for uploading verification documents to a payment processor."
},
"IntegratorMerchantDocumentPostResponse": {
"required": [
"frontFileId",
"uploadedAt"
],
"type": "object",
"properties": {
"frontFileId": {
"type": "string",
"description": "The payment processor's unique identifier for the front document file.",
"example": "file_1NqtHo2eZvKYlo2CZPg8Xt5h"
},
"backFileId": {
"type": [
"null",
"string"
],
"description": "The payment processor's unique identifier for the back document file (if provided).",
"example": "file_1NqtHp2eZvKYlo2CRTg9Xm3k"
},
"uploadedAt": {
"description": "UTC timestamp when the document was uploaded.",
"$ref": "#/components/schemas/Instant"
}
},
"description": "Response model returned after successfully uploading verification documents to a payment processor."
},
"IntegratorMerchantInvitePostRequest": {
"required": [
"email"
],
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of the person to invite."
}
}
},
"IntegratorMerchantInvitePostResponse": {
"required": [
"registrationUrl"
],
"type": "object",
"properties": {
"registrationUrl": {
"type": "string",
"description": "Registration URL to share with or email to the invitee."
}
}
},
"IntegratorMerchantKnownMccGetCardTypeResponse": {
"required": [
"cardType",
"rates"
],
"type": "object",
"properties": {
"cardType": {
"$ref": "#/components/schemas/PricingCardTypeEnum"
},
"rates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantKnownMccGetRateResponse"
}
}
}
},
"IntegratorMerchantKnownMccGetPaymentMethodResponse": {
"required": [
"paymentMethodId",
"cardTypes"
],
"type": "object",
"properties": {
"paymentMethodId": {
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"cardTypes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantKnownMccGetCardTypeResponse"
}
}
}
},
"IntegratorMerchantKnownMccGetRateResponse": {
"required": [
"currencyId",
"feeAbsolute",
"feeRelative"
],
"type": "object",
"properties": {
"currencyId": {
"type": "integer",
"format": "int32"
},
"feeAbsolute": {
"type": "integer",
"format": "int64"
},
"feeRelative": {
"type": "integer",
"format": "int64"
}
}
},
"IntegratorMerchantKnownMccGetResponse": {
"required": [
"mcc",
"paymentMethods"
],
"type": "object",
"properties": {
"mcc": {
"type": "string"
},
"paymentMethods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantKnownMccGetPaymentMethodResponse"
}
}
}
},
"IntegratorMerchantMccPricingRequestPostPaymentMethodRequest": {
"required": [
"paymentMethodId",
"expectedMonthlyVolume",
"currencyId"
],
"type": "object",
"properties": {
"paymentMethodId": {
"description": "Payment method to request pricing for.",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"expectedMonthlyVolume": {
"maximum": 9223372036854776000,
"minimum": 0,
"type": "integer",
"description": "Expected monthly transaction volume in minor currency units.",
"format": "int64"
},
"currencyId": {
"type": "integer",
"description": "Currency of the expected monthly volume.",
"format": "int32"
},
"avgDailyTransactionCount": {
"maximum": 2147483647,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Average daily transaction count; optional.",
"format": "int32"
}
}
},
"IntegratorMerchantMccPricingRequestPostPaymentMethodResponse": {
"required": [
"paymentMethodId",
"expectedMonthlyVolume",
"currencyId"
],
"type": "object",
"properties": {
"paymentMethodId": {
"description": "Payment method this rate applies to.",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"expectedMonthlyVolume": {
"type": "integer",
"description": "Expected monthly transaction volume in minor currency units, as submitted.",
"format": "int64"
},
"currencyId": {
"type": "integer",
"description": "Currency of the expected volume.",
"format": "int32"
},
"avgDailyTransactionCount": {
"type": [
"null",
"integer"
],
"description": "Average daily transaction count, if provided.",
"format": "int32"
},
"indicativeRates": {
"oneOf": [
{
"type": "null"
},
{
"description": "Indicative card rates; null if ops review is pending.",
"$ref": "#/components/schemas/IndicativeRatesSnapshot"
}
]
}
}
},
"IntegratorMerchantMccPricingRequestPostRequest": {
"required": [
"paymentMethods"
],
"type": "object",
"properties": {
"paymentMethods": {
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantMccPricingRequestPostPaymentMethodRequest"
},
"description": "At least one payment method for which to request indicative pricing."
}
}
},
"IntegratorMerchantMccPricingRequestPostResponse": {
"required": [
"pricingRequestId",
"status",
"requiresApproval",
"mcc",
"submittedAt",
"paymentMethods"
],
"type": "object",
"properties": {
"pricingRequestId": {
"type": "string",
"description": "Server-generated identifier for this pricing request.",
"format": "uuid"
},
"status": {
"description": "Current status of the pricing request (e.g., approved, pending, rejected).",
"$ref": "#/components/schemas/MerchantPricingRequestStatusEnum"
},
"requiresApproval": {
"type": "boolean",
"description": "True if this pricing request requires manual ops review before approval."
},
"mcc": {
"type": "string",
"description": "Merchant Category Code this quote was generated for."
},
"submittedAt": {
"description": "UTC timestamp when the pricing request was submitted.",
"$ref": "#/components/schemas/Instant"
},
"resolvedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "UTC timestamp when the request was approved or rejected; null if still pending.",
"$ref": "#/components/schemas/Instant"
}
]
},
"rejectionReason": {
"type": [
"null",
"string"
],
"description": "Human-readable reason for rejection; null if not rejected."
},
"paymentMethods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantMccPricingRequestPostPaymentMethodResponse"
},
"description": "Indicative rates per payment method."
}
}
},
"IntegratorMerchantMembersInvitePostRequest": {
"required": [
"email"
],
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address to invite."
}
}
},
"IntegratorMerchantMembersInvitePostResponse": {
"required": [
"inviteUrl"
],
"type": "object",
"properties": {
"inviteUrl": {
"type": "string",
"description": "Full invite URL sent in the email."
}
}
},
"IntegratorMerchantMembersInvitesGetResponse": {
"required": [
"inviteId",
"invitedEmail",
"createdAt",
"expiresAt"
],
"type": "object",
"properties": {
"inviteId": {
"type": "string",
"description": "Unique invite identifier.",
"format": "uuid"
},
"invitedEmail": {
"type": "string",
"description": "Email address the invite was sent to."
},
"createdAt": {
"description": "When the invite was created.",
"$ref": "#/components/schemas/Instant"
},
"expiresAt": {
"description": "When the invite token expires.",
"$ref": "#/components/schemas/Instant"
},
"usedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "When the invite was accepted, or null if still pending.",
"$ref": "#/components/schemas/Instant"
}
]
},
"inviteUrl": {
"type": [
"null",
"string"
],
"description": "Full invite URL sent in the email, or null for legacy hash-only invites."
}
}
},
"IntegratorMerchantOnboardingRequest": {
"required": [
"name",
"identity",
"address",
"business",
"kyb"
],
"type": "object",
"properties": {
"name": {
"maxLength": 200,
"type": "string",
"description": "The name of the merchant."
},
"merchantToken": {
"maxLength": 100,
"type": [
"null",
"string"
],
"description": "The merchant identifier provided by the integrator.\nIf not provided, a random token will be generated."
},
"identity": {
"description": "Legal identity information of the merchant.",
"$ref": "#/components/schemas/IdentityPayload"
},
"address": {
"description": "Registered address of the merchant.",
"$ref": "#/components/schemas/AddressPayload"
},
"business": {
"description": "Business profile of the merchant.",
"$ref": "#/components/schemas/BusinessPayload"
},
"kyb": {
"description": "Know Your Business (KYB) information.",
"$ref": "#/components/schemas/KybPayload"
}
}
},
"IntegratorMerchantOnboardingStatusResponse": {
"required": [
"submitted",
"processors"
],
"type": "object",
"properties": {
"submitted": {
"type": "boolean",
"description": "True if the merchant has submitted their onboarding profile."
},
"processors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProcessorStatus"
},
"description": "Onboarding status per payment processor registered for this merchant."
}
}
},
"IntegratorMerchantOnboardingValidateAddressRequest": {
"required": [
"line1",
"city",
"postalCode",
"countryId"
],
"type": "object",
"properties": {
"line1": {
"type": "string",
"description": "First line of the street address."
},
"line2": {
"type": [
"null",
"string"
],
"description": "Second line of the street address, if applicable."
},
"city": {
"type": "string",
"description": "City name."
},
"postalCode": {
"type": "string",
"description": "Postal or ZIP code."
},
"state": {
"type": [
"null",
"string"
],
"description": "State or region, if applicable."
},
"countryId": {
"description": "ISO country code.",
"$ref": "#/components/schemas/CountryEnum"
}
}
},
"IntegratorMerchantOnboardingValidateAddressResponse": {
"required": [
"valid",
"errors"
],
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "True if all address fields passed validation."
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationFieldError"
},
"description": "List of validation errors; empty when valid is true."
}
}
},
"IntegratorMerchantOnboardingValidateBusinessRequest": {
"required": [
"mcc",
"supportPhone",
"statementDescriptor"
],
"type": "object",
"properties": {
"mcc": {
"type": "string",
"description": "Four-digit Merchant Category Code (MCC)."
},
"url": {
"type": [
"null",
"string"
],
"description": "Public website URL of the business."
},
"productDescription": {
"type": [
"null",
"string"
],
"description": "Description of products or services; required if no website URL is provided."
},
"supportPhone": {
"type": "string",
"description": "Customer support phone number in E.164 format."
},
"statementDescriptor": {
"type": "string",
"description": "Text shown on customer bank statements (1–22 characters)."
},
"averageItemValue": {
"type": [
"null",
"integer"
],
"description": "Average transaction value in minor currency units.",
"format": "int64"
},
"expectedMonthlyTurnover": {
"type": [
"null",
"integer"
],
"description": "Expected monthly revenue in minor currency units.",
"format": "int64"
},
"numberOfEmployees": {
"type": [
"null",
"integer"
],
"description": "Number of employees at the business.",
"format": "int32"
},
"numberOfTerminals": {
"maximum": 9999,
"minimum": 1,
"type": [
"null",
"integer"
],
"description": "Number of POS terminals at this location (1–9999).",
"format": "int32"
},
"annualTurnover": {
"type": [
"null",
"integer"
],
"description": "Annual revenue in minor currency units.",
"format": "int64"
},
"balanceSheetTotal": {
"type": [
"null",
"integer"
],
"description": "Total balance sheet value in minor currency units.",
"format": "int64"
}
}
},
"IntegratorMerchantOnboardingValidateBusinessResponse": {
"required": [
"valid",
"errors"
],
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "True if all business fields passed validation."
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationFieldError"
},
"description": "List of validation errors; empty when valid is true."
}
}
},
"IntegratorMerchantOnboardingValidateIdentityRequest": {
"required": [
"legalName",
"businessTypeId",
"email",
"registrationNumber"
],
"type": "object",
"properties": {
"legalName": {
"type": "string",
"description": "Legal name of the business or individual account holder."
},
"businessTypeId": {
"description": "Type of business entity (e.g., individual, company).",
"$ref": "#/components/schemas/BusinessTypeEnum"
},
"email": {
"type": "string",
"description": "Contact email address."
},
"registrationNumber": {
"type": "string",
"description": "Official business registration number."
},
"vatNumber": {
"type": [
"null",
"string"
],
"description": "VAT registration number, if applicable."
},
"incorporationDate": {
"type": [
"null",
"string"
],
"description": "Date the business was legally incorporated (YYYY-MM-DD).",
"format": "date"
}
}
},
"IntegratorMerchantOnboardingValidateIdentityResponse": {
"required": [
"valid",
"errors"
],
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "True if all identity fields passed validation."
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationFieldError"
},
"description": "List of validation errors; empty when valid is true."
}
}
},
"IntegratorMerchantOnboardingValidateKybRequest": {
"type": "object",
"properties": {
"businessTypeId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Type of business entity; determines whether individual or company fields are required.",
"$ref": "#/components/schemas/BusinessTypeEnum"
}
]
},
"bankAccount": {
"oneOf": [
{
"type": "null"
},
{
"description": "Bank account details to validate.",
"$ref": "#/components/schemas/BankAccountPayload"
}
]
},
"individual": {
"oneOf": [
{
"type": "null"
},
{
"description": "Individual merchant data (sole trader / sole proprietor).",
"$ref": "#/components/schemas/IndividualPayload"
}
]
},
"company": {
"oneOf": [
{
"type": "null"
},
{
"description": "Company and personnel data for corporate merchants.",
"$ref": "#/components/schemas/CompanyPayload"
}
]
}
}
},
"IntegratorMerchantOnboardingValidateKybResponse": {
"required": [
"valid",
"errors"
],
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "True if all KYB fields passed validation."
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationFieldError"
},
"description": "List of validation errors; empty when valid is true."
}
}
},
"IntegratorMerchantOnboardingValidateReferenceIdRequest": {
"required": [
"referenceId"
],
"type": "object",
"properties": {
"referenceId": {
"type": "string",
"description": "Integrator-supplied reference id, checked against merchant token."
}
}
},
"IntegratorMerchantOnboardingValidateReferenceIdResponse": {
"required": [
"valid",
"errors"
],
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "True if the reference id is not already in use."
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationFieldError"
},
"description": "List of validation errors; empty when valid is true."
}
}
},
"IntegratorMerchantOnboardingValidationResponse": {
"required": [
"errors"
],
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"description": "List of validation errors that prevented merchant creation."
}
}
},
"IntegratorMerchantPaymentsGetResult": {
"required": [
"paymentId",
"paymentToken",
"paymentProcessorId",
"paymentMethodId",
"terminalId",
"locationId",
"requestedAmount",
"requestedCurrencyId",
"settlementAmount",
"settlementCurrencyId",
"statusId",
"createdAt"
],
"type": "object",
"properties": {
"paymentId": {
"type": "string",
"description": "Server-generated payment id.",
"format": "uuid"
},
"paymentToken": {
"type": "string",
"description": "Client-provided token that identifies a payment."
},
"paymentProcessorId": {
"description": "The payment processor to use (e.g., Stripe).",
"$ref": "#/components/schemas/PaymentProcessorEnum"
},
"paymentMethodId": {
"description": "The payment method to use (e.g., card, bank transfer).",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"terminalId": {
"type": "string",
"description": "Identifier of the terminal that processed the payment.",
"format": "uuid"
},
"locationId": {
"type": "string",
"description": "Identifier of the terminal location where payment happened.",
"format": "uuid"
},
"requestedAmount": {
"type": "integer",
"description": "Amount that the customer is requested to pay, in the smallest unit of requested currency.",
"format": "int64"
},
"requestedCurrencyId": {
"description": "Currency that will be charged to the customer.",
"examples": [
978
],
"$ref": "#/components/schemas/CurrencyEnum"
},
"settlementAmount": {
"type": "integer",
"description": "Amount the merchant will receive, in the smallest unit of the settlement currency.",
"format": "int64",
"example": 1000
},
"settlementCurrencyId": {
"description": "Numeric ISO 4217 code of the currency requested by merchant.",
"examples": [
978
],
"$ref": "#/components/schemas/CurrencyEnum"
},
"statusId": {
"description": "Payment status.",
"$ref": "#/components/schemas/StatusEnum"
},
"instrumentLabel": {
"type": [
"null",
"string"
],
"description": "Card brand or network token identifier (e.g., Visa, Mastercard)."
},
"instrumentIdentifier": {
"type": [
"null",
"string"
],
"description": "Last 4 digits of the card number, wallet address, or similar payment instrument identifier."
},
"createdAt": {
"description": "UTC timestamp when the payment was created.",
"$ref": "#/components/schemas/Instant"
},
"processedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "UTC timestamp when the payment was processed, if completed.",
"$ref": "#/components/schemas/Instant"
}
]
}
}
},
"IntegratorMerchantPricingRequestPaymentMethodResponse": {
"required": [
"paymentMethodId",
"expectedMonthlyVolume",
"currencyId"
],
"type": "object",
"properties": {
"paymentMethodId": {
"description": "Payment method this rate applies to.",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"expectedMonthlyVolume": {
"type": "integer",
"description": "Expected monthly transaction volume in minor currency units, as submitted.",
"format": "int64"
},
"currencyId": {
"type": "integer",
"description": "Currency of the expected volume.",
"format": "int32"
},
"avgDailyTransactionCount": {
"type": [
"null",
"integer"
],
"description": "Average daily transaction count, if provided.",
"format": "int32"
},
"indicativeRates": {
"oneOf": [
{
"type": "null"
},
{
"description": "Indicative card rates; null if ops review is pending.",
"$ref": "#/components/schemas/IndicativeRatesSnapshot"
}
]
}
}
},
"IntegratorMerchantPricingRequestPostPaymentMethodRequest": {
"required": [
"paymentMethodId",
"expectedMonthlyVolume",
"currencyId"
],
"type": "object",
"properties": {
"paymentMethodId": {
"description": "Payment method to request pricing for.",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"expectedMonthlyVolume": {
"maximum": 9223372036854776000,
"minimum": 0,
"type": "integer",
"description": "Expected monthly transaction volume in minor currency units.",
"format": "int64"
},
"currencyId": {
"type": "integer",
"description": "Currency of the expected monthly volume.",
"format": "int32"
},
"avgDailyTransactionCount": {
"maximum": 2147483647,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Average daily transaction count; optional.",
"format": "int32"
}
}
},
"IntegratorMerchantPricingRequestPostRequest": {
"required": [
"paymentMethods"
],
"type": "object",
"properties": {
"paymentMethods": {
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantPricingRequestPostPaymentMethodRequest"
},
"description": "At least one payment method for which to request indicative pricing."
}
}
},
"IntegratorMerchantPricingRequestResponse": {
"required": [
"pricingRequestId",
"status",
"requiresApproval",
"mcc",
"submittedAt",
"paymentMethods"
],
"type": "object",
"properties": {
"pricingRequestId": {
"type": "string",
"description": "Server-generated identifier for this pricing request.",
"format": "uuid"
},
"status": {
"description": "Current status of the pricing request (e.g., approved, pending, rejected).",
"$ref": "#/components/schemas/MerchantPricingRequestStatusEnum"
},
"requiresApproval": {
"type": "boolean",
"description": "True if this pricing request requires manual ops review before approval."
},
"mcc": {
"type": "string",
"description": "Merchant Category Code derived from the merchant's onboarding profile."
},
"submittedAt": {
"description": "UTC timestamp when the pricing request was submitted.",
"$ref": "#/components/schemas/Instant"
},
"resolvedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "UTC timestamp when the request was approved or rejected; null if still pending.",
"$ref": "#/components/schemas/Instant"
}
]
},
"rejectionReason": {
"type": [
"null",
"string"
],
"description": "Human-readable reason for rejection; null if not rejected."
},
"paymentMethods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantPricingRequestPaymentMethodResponse"
},
"description": "Indicative rates per payment method."
}
}
},
"IntegratorMerchantPricingRequestsGetResponse": {
"required": [
"pricingRequestId",
"status",
"requiresApproval",
"mcc",
"submittedAt",
"isActive",
"paymentMethods"
],
"type": "object",
"properties": {
"pricingRequestId": {
"type": "string",
"format": "uuid"
},
"status": {
"$ref": "#/components/schemas/MerchantPricingRequestStatusEnum"
},
"requiresApproval": {
"type": "boolean"
},
"mcc": {
"type": "string"
},
"submittedAt": {
"$ref": "#/components/schemas/Instant"
},
"resolvedAt": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/Instant"
}
]
},
"rejectionReason": {
"type": [
"null",
"string"
]
},
"isActive": {
"type": "boolean"
},
"paymentMethods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantPricingRequestPaymentMethodResponse"
}
}
}
},
"IntegratorMerchantProcessorGetResponse": {
"required": [
"paymentProcessorId",
"chargesEnabled",
"payoutsEnabled",
"pendingRequirements",
"pastDueRequirements",
"eventuallyDueRequirements",
"disabledReasonRequirements",
"updatedAt"
],
"type": "object",
"properties": {
"mcc": {
"type": [
"null",
"integer"
],
"description": "The Merchant Category Code (MCC) that classifies the business type.",
"format": "int32"
},
"url": {
"type": [
"null",
"string"
],
"description": "The public website URL of the merchant."
},
"productDescription": {
"type": [
"null",
"string"
],
"description": "Description of the products sold by the merchant."
},
"supportPhone": {
"type": [
"null",
"string"
],
"description": "Merchant customer support phone number."
},
"statementDescriptor": {
"type": [
"null",
"string"
],
"description": "The default text that appears on bank statements."
},
"bankAccount": {
"oneOf": [
{
"type": "null"
},
{
"description": "The bank account information where settlements will be deposited.",
"$ref": "#/components/schemas/BankAccountInformation"
}
]
},
"individual": {
"oneOf": [
{
"type": "null"
},
{
"description": "The personal information of the merchant if they are operating as an individual.",
"$ref": "#/components/schemas/PersonInformation"
}
]
},
"company": {
"oneOf": [
{
"type": "null"
},
{
"description": "The company information of the merchant if they are operating as a business entity.",
"$ref": "#/components/schemas/CompanyInformation"
}
]
},
"paymentProcessorId": {
"description": "The payment processor being queried.",
"$ref": "#/components/schemas/PaymentProcessorEnum"
},
"chargesEnabled": {
"type": "boolean",
"description": "True if charges are currently enabled for the account."
},
"payoutsEnabled": {
"type": "boolean",
"description": "True if payouts are currently enabled for the account."
},
"pendingRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requirements that processor reports as currently due."
},
"pastDueRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requirements that are past due, i.e. blocking or time‑critical."
},
"eventuallyDueRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requirements that will be eventually due, but are not blocking yet."
},
"disabledReasonRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requirements that are currently disabled (ex: for rejected capabilities)."
},
"requirementsDeadlineTimestamp": {
"oneOf": [
{
"type": "null"
},
{
"description": "Current deadline for providing missing requirements, if any.",
"$ref": "#/components/schemas/Instant"
}
]
},
"updatedAt": {
"description": "Timestamp of the last update to the stored processor merchant record.",
"$ref": "#/components/schemas/Instant"
}
}
},
"IntegratorMerchantProfileGetResponse": {
"type": "object",
"properties": {
"data": {
"oneOf": [
{
"type": "null"
},
{
"description": "Merchant profile data, `null` if not set.",
"$ref": "#/components/schemas/IntegratorMerchantProfileGetResponseData"
}
]
}
}
},
"IntegratorMerchantProfileGetResponseData": {
"required": [
"isActive"
],
"type": "object",
"properties": {
"isActive": {
"type": "boolean",
"description": "True if merchant is active, false if deactivated."
},
"email": {
"type": [
"null",
"string"
],
"description": "Merchant's email address."
},
"businessTypeId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Type of incorporation of the merchant.",
"$ref": "#/components/schemas/BusinessTypeEnum"
}
]
},
"legalName": {
"type": [
"null",
"string"
],
"description": "The legal name of the account holder or business."
},
"registrationNumber": {
"type": [
"null",
"string"
],
"description": "The registration number for the business."
},
"vatNumber": {
"type": [
"null",
"string"
],
"description": "VAT number of the business."
},
"incorporationDate": {
"type": [
"null",
"string"
],
"description": "Legal incorporation date of the merchant.",
"format": "date"
},
"mcc": {
"type": [
"null",
"string"
],
"description": "The Merchant Category Code (MCC) that classifies the business type."
},
"addressLine1": {
"type": [
"null",
"string"
],
"description": "The first line of the street address."
},
"addressLine2": {
"type": [
"null",
"string"
],
"description": "The second line of the street address."
},
"city": {
"type": [
"null",
"string"
],
"description": "The city name."
},
"postalCode": {
"type": [
"null",
"string"
],
"description": "Postal code."
},
"state": {
"type": [
"null",
"string"
],
"description": "The state name."
},
"countryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Country code.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"phone": {
"type": [
"null",
"string"
],
"description": "Merchant phone number."
},
"averageItemValue": {
"type": [
"null",
"integer"
],
"description": "Average transaction value in minor currency units.",
"format": "int64"
},
"expectedMonthlyTurnover": {
"type": [
"null",
"integer"
],
"description": "Expected monthly revenue in minor currency units.",
"format": "int64"
},
"businessModelDescription": {
"type": [
"null",
"string"
],
"description": "Description of the merchant's business model."
},
"numberOfEmployees": {
"type": [
"null",
"integer"
],
"description": "Number of employees at the business.",
"format": "int32"
},
"numberOfTerminals": {
"type": [
"null",
"integer"
],
"description": "Number of POS terminals at this location.",
"format": "int32"
},
"annualTurnover": {
"type": [
"null",
"integer"
],
"description": "Annual revenue in minor currency units.",
"format": "int64"
},
"balanceSheetTotal": {
"type": [
"null",
"integer"
],
"description": "Total balance sheet value in minor currency units.",
"format": "int64"
},
"statementDescriptor": {
"type": [
"null",
"string"
],
"description": "Text shown on customer bank statements (5–22 characters)."
}
}
},
"IntegratorMerchantProfileInitializeRequest": {
"required": [
"email",
"businessTypeId",
"legalName",
"registrationNumber",
"mcc",
"addressLine1",
"city",
"countryId"
],
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Merchant's email address."
},
"businessTypeId": {
"description": "Type of incorporation of the merchant.",
"$ref": "#/components/schemas/BusinessTypeEnum"
},
"legalName": {
"maxLength": 255,
"minLength": 1,
"type": "string",
"description": "The legal name of the account holder or business."
},
"registrationNumber": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "The registration number for the business."
},
"vatNumber": {
"maxLength": 50,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "VAT number of the business."
},
"incorporationDate": {
"type": [
"null",
"string"
],
"description": "Legal incorporation date of the merchant.",
"format": "date"
},
"mcc": {
"maxLength": 4,
"pattern": "^[0-9]{4}$",
"type": "string",
"description": "Merchant classification code of the business - 4-digit code."
},
"addressLine1": {
"maxLength": 255,
"minLength": 1,
"type": "string",
"description": "The first line of the street address."
},
"addressLine2": {
"maxLength": 255,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "The second line of the street address."
},
"city": {
"maxLength": 100,
"minLength": 1,
"type": "string",
"description": "The city name."
},
"postalCode": {
"maxLength": 100,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Postal code."
},
"state": {
"maxLength": 100,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "The state name."
},
"countryId": {
"description": "Country code.",
"$ref": "#/components/schemas/CountryEnum"
},
"phone": {
"maxLength": 20,
"type": [
"null",
"string"
],
"description": "Customer support phone number in E.164 format (e.g. +420123456789); optional."
},
"averageItemValue": {
"maximum": 9223372036854776000,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Expected average sale ticket, in EUR cents.",
"format": "int64"
},
"expectedMonthlyTurnover": {
"maximum": 9223372036854776000,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Expected gross monthly turnover, in EUR cents.",
"format": "int64"
},
"businessModelDescription": {
"maxLength": 32000,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Free-text description of the merchant's business activity."
},
"numberOfEmployees": {
"maximum": 2147483647,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Number of employees.",
"format": "int32"
},
"numberOfTerminals": {
"maximum": 9999,
"minimum": 1,
"type": [
"null",
"integer"
],
"description": "Number of POS terminals at this location (1–9999). Sent to Shift4 as pos_device.number_of_devices.",
"format": "int32"
},
"annualTurnover": {
"maximum": 9223372036854776000,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Annual turnover, in EUR cents.",
"format": "int64"
},
"balanceSheetTotal": {
"maximum": 9223372036854776000,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Balance sheet total, in EUR cents.",
"format": "int64"
},
"statementDescriptor": {
"maxLength": 22,
"minLength": 5,
"type": [
"null",
"string"
],
"description": "Statement descriptor shown on the cardholder's bank statement (5–22 characters)."
}
}
},
"IntegratorMerchantProfilePostStatusResponse": {
"required": [
"onboarded",
"paymentMethods"
],
"type": "object",
"properties": {
"onboarded": {
"type": "boolean",
"description": "True if merchant onboarding data was submitted."
},
"paymentMethods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PaymentMethodStatus"
},
"description": "Individual payment method statuses."
}
}
},
"IntegratorMerchantProfilePutStatusResponse": {
"required": [
"onboarded",
"paymentMethods"
],
"type": "object",
"properties": {
"onboarded": {
"type": "boolean",
"description": "True if merchant onboarding data was submitted."
},
"paymentMethods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PaymentMethodStatus"
},
"description": "Individual payment method statuses."
}
}
},
"IntegratorMerchantProfileUpdateRequest": {
"required": [
"email",
"businessTypeId",
"legalName",
"registrationNumber",
"mcc",
"addressLine1",
"city",
"countryId"
],
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Merchant's email address."
},
"businessTypeId": {
"description": "Type of incorporation of the merchant.",
"$ref": "#/components/schemas/BusinessTypeEnum"
},
"legalName": {
"maxLength": 255,
"minLength": 1,
"type": "string",
"description": "The legal name of the account holder or business."
},
"registrationNumber": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "The registration number for the business."
},
"vatNumber": {
"maxLength": 50,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "VAT number of the business."
},
"incorporationDate": {
"type": [
"null",
"string"
],
"description": "Legal incorporation date of the merchant.",
"format": "date"
},
"mcc": {
"maxLength": 4,
"pattern": "^[0-9]{4}$",
"type": "string",
"description": "Merchant classification code of the business - 4-digit code."
},
"addressLine1": {
"maxLength": 255,
"minLength": 1,
"type": "string",
"description": "The first line of the street address."
},
"addressLine2": {
"maxLength": 255,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "The second line of the street address."
},
"city": {
"maxLength": 100,
"minLength": 1,
"type": "string",
"description": "The city name."
},
"postalCode": {
"maxLength": 100,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Postal code."
},
"state": {
"maxLength": 100,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "The state name."
},
"countryId": {
"description": "Country code.",
"$ref": "#/components/schemas/CountryEnum"
},
"phone": {
"maxLength": 20,
"type": [
"null",
"string"
],
"description": "Merchant phone number."
},
"averageItemValue": {
"maximum": 9223372036854776000,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Expected average sale ticket, in EUR cents.",
"format": "int64"
},
"expectedMonthlyTurnover": {
"maximum": 9223372036854776000,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Expected gross monthly turnover, in EUR cents.",
"format": "int64"
},
"businessModelDescription": {
"maxLength": 32000,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Free-text description of the merchant's business activity."
},
"numberOfEmployees": {
"maximum": 2147483647,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Number of employees.",
"format": "int32"
},
"numberOfTerminals": {
"maximum": 9999,
"minimum": 1,
"type": [
"null",
"integer"
],
"description": "Number of POS terminals at this location (1–9999). Sent to Shift4 as pos_device.number_of_devices.",
"format": "int32"
},
"annualTurnover": {
"maximum": 9223372036854776000,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Annual turnover, in EUR cents.",
"format": "int64"
},
"balanceSheetTotal": {
"maximum": 9223372036854776000,
"minimum": 0,
"type": [
"null",
"integer"
],
"description": "Balance sheet total, in EUR cents.",
"format": "int64"
},
"statementDescriptor": {
"maxLength": 22,
"minLength": 5,
"type": [
"null",
"string"
],
"description": "Statement descriptor shown on the cardholder's bank statement (5–22 characters)."
}
}
},
"IntegratorMerchantRegisterProcessorMerchantRequest": {
"required": [
"paymentProcessorId"
],
"type": "object",
"properties": {
"paymentProcessorId": {
"description": "The payment processor to use (e.g., Stripe).",
"$ref": "#/components/schemas/PaymentProcessorEnum"
}
}
},
"IntegratorMerchantRegisterProcessorMerchantResponse": {
"required": [
"directManagementSupported"
],
"type": "object",
"properties": {
"directManagementSupported": {
"type": "boolean",
"description": "True if the processor supports API-based onboarding without requiring the merchant to visit an external URL."
},
"onboardingUrl": {
"type": [
"null",
"string"
],
"description": "URL for processor-specific onboarding. Null if direct management is supported."
}
}
},
"IntegratorMerchantsGetResponse": {
"required": [
"merchantId",
"merchantToken",
"name",
"onboarded",
"isActive"
],
"type": "object",
"properties": {
"merchantId": {
"type": "string",
"description": "Unique identifier of the merchant.",
"format": "uuid"
},
"merchantToken": {
"type": "string",
"description": "Token to pass to the terminal SDK when activating a POS device for this merchant."
},
"name": {
"type": [
"null",
"string"
],
"description": "Merchant name."
},
"email": {
"type": [
"null",
"string"
],
"description": "Admin / contact email stored on the merchant record."
},
"businessType": {
"oneOf": [
{
"type": "null"
},
{
"description": "Business type of the merchant.",
"$ref": "#/components/schemas/BusinessTypeEnum"
}
]
},
"city": {
"type": [
"null",
"string"
],
"description": "City where merchant is legally registered."
},
"country": {
"oneOf": [
{
"type": "null"
},
{
"description": "Country where merchant is legally registered.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"onboarded": {
"type": "boolean",
"description": "True if the merchant has completed their onboarding profile and is approved to accept payments."
},
"isActive": {
"type": "boolean",
"description": "True if merchant is active, false if deactivated."
}
}
},
"IntegratorMerchantShift4OfficialIdDto": {
"required": [
"personId",
"placeOfBirthCountryId",
"officialIdType",
"officialIdNumber"
],
"type": "object",
"properties": {
"personId": {
"type": "string",
"description": "Stakeholder identifier from the merchant's KYB onboarding profile.",
"format": "uuid"
},
"placeOfBirthCountryId": {
"description": "Country of birth.",
"$ref": "#/components/schemas/CountryEnum"
},
"officialIdType": {
"description": "One of: Passport / IdentityCard / DriverLicense / ResidencePermit / Asylum / Other.",
"$ref": "#/components/schemas/OfficialIdTypeEnum"
},
"officialIdNumber": {
"type": "string",
"description": "Document number printed on the official ID."
},
"officialIdExpiryDate": {
"oneOf": [
{
"type": "null"
},
{
"description": "Mandatory when OfficialIdTypeEnum IntegratorMerchantShift4OfficialIdDto.OfficialIdType = Passport.",
"$ref": "#/components/schemas/LocalDate"
}
]
},
"passportPlaceOfIssue": {
"type": [
"null",
"string"
],
"description": "Mandatory when OfficialIdTypeEnum IntegratorMerchantShift4OfficialIdDto.OfficialIdType = Passport."
}
},
"description": "Identity document for one KYB stakeholder."
},
"IntegratorMerchantShift4ProcessorRegisterPostRequest": {
"required": [
"officialIds"
],
"type": "object",
"properties": {
"officialIds": {
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorMerchantShift4OfficialIdDto"
},
"description": "Identity documents for all KYB stakeholders; one entry per person, matched by their PersonId from the onboarding profile."
}
},
"description": "Shift4 registration payload; contains identity documents for all KYB stakeholders."
},
"IntegratorMerchantShift4ProcessorRegisterPostResponse": {
"type": "object",
"properties": {
"crxRequestId": {
"type": [
"null",
"string"
],
"description": "Shift4-assigned correlation ID for this registration request."
},
"responseCode": {
"type": [
"null",
"string"
],
"description": "Shift4 response code; \"000\" indicates success."
},
"responseDescription": {
"type": [
"null",
"string"
],
"description": "Free-form description from Shift4 (when present)."
}
}
},
"IntegratorMerchantStatsGetResponse": {
"required": [
"monthlyRevenue",
"referralFeeBalance",
"lastReferralFeePayout",
"monthlyTransactions",
"byPaymentMethod",
"byOperatingSystem",
"dailyTransactions",
"dailyVolume",
"dailyReferralFee"
],
"type": "object",
"properties": {
"monthlyRevenue": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TotalRevenue"
},
"description": "Total monthly revenue."
},
"referralFeeBalance": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PayoutDetails"
},
"description": "Current referral fee balance pending payout."
},
"lastReferralFeePayout": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PayoutDetails"
},
"description": "Details of the last referral fee payout."
},
"monthlyTransactions": {
"description": "Monthly transaction statistics.",
"$ref": "#/components/schemas/TransactionStats"
},
"byPaymentMethod": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StatsByPaymentMethod"
},
"description": "Statistics broken down by payment method."
},
"byOperatingSystem": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StatsByOperatingSystem"
},
"description": "Statistics broken down by operating system."
},
"dailyTransactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DailyDataPointOfint"
},
"description": "Daily transaction counts."
},
"dailyVolume": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CurrencyDailyDataPoint"
},
"description": "Daily transaction volume."
},
"dailyReferralFee": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CurrencyDailyDataPoint"
},
"description": "Daily referral fee amounts."
}
}
},
"IntegratorMerchantStatsHeatmapGetResponse": {
"required": [
"matrix"
],
"type": "object",
"properties": {
"matrix": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HeatmapCellResponse"
},
"description": "Non-zero heatmap cells, ordered by dayOfWeek then hour."
}
}
},
"IntegratorMerchantStatsTerminalsGetResponse": {
"required": [
"terminals"
],
"type": "object",
"properties": {
"terminals": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TerminalStatResponse"
},
"description": "Per-terminal stats, including terminals with zero activity in the window."
}
}
},
"IntegratorMerchantStatusGetResponse": {
"required": [
"onboarded",
"paymentMethods"
],
"type": "object",
"properties": {
"onboarded": {
"type": "boolean",
"description": "True if the merchant has submitted their onboarding profile."
},
"paymentMethods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PaymentMethodStatus"
},
"description": "Individual payment method statuses."
}
}
},
"IntegratorMerchantTransactionReportDownloadGetResponse": {
"required": [
"url"
],
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Pre-signed S3 URL to download the transaction report. Valid for 15 minutes."
}
}
},
"IntegratorMerchantTransactionReportGetResponse": {
"required": [
"merchantTransactionReportId",
"merchantId",
"periodYear",
"periodMonth",
"currencyId",
"totalFee",
"netFee",
"vatRate",
"vatAmount",
"vatDate",
"reportNumber",
"merchantEmail",
"legalName",
"registrationNumber",
"countryId",
"city",
"addressLine1",
"postalCode",
"createdAt",
"paymentIds"
],
"type": "object",
"properties": {
"merchantTransactionReportId": {
"type": "string",
"format": "uuid"
},
"merchantId": {
"type": "string",
"format": "uuid"
},
"periodYear": {
"type": "integer",
"format": "int32"
},
"periodMonth": {
"type": "integer",
"format": "int32"
},
"currencyId": {
"$ref": "#/components/schemas/CurrencyEnum"
},
"totalFee": {
"type": "integer",
"description": "VAT-inclusive fee in minor currency units (what the merchant is charged).",
"format": "int64"
},
"netFee": {
"type": "integer",
"description": "Fee before VAT in minor currency units.",
"format": "int64"
},
"vatRate": {
"type": "integer",
"description": "VAT rate in basis points (e.g. 2100 = 21%).",
"format": "int32"
},
"vatAmount": {
"type": "integer",
"description": "VAT portion in minor currency units (totalFee − netFee).",
"format": "int64"
},
"vatDate": {
"$ref": "#/components/schemas/LocalDate"
},
"reportNumber": {
"type": "string",
"description": "Human-readable report number (e.g. TAP2026030001)."
},
"merchantName": {
"type": [
"null",
"string"
]
},
"merchantEmail": {
"type": "string"
},
"legalName": {
"type": "string"
},
"registrationNumber": {
"type": "string"
},
"vatNumber": {
"type": [
"null",
"string"
]
},
"countryId": {
"type": "integer",
"format": "int32"
},
"city": {
"type": "string"
},
"addressLine1": {
"type": "string"
},
"addressLine2": {
"type": [
"null",
"string"
]
},
"state": {
"type": [
"null",
"string"
]
},
"postalCode": {
"type": "string"
},
"createdAt": {
"$ref": "#/components/schemas/Instant"
},
"paymentIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "IDs of payments included in this transaction report."
}
}
},
"IntegratorMerchantTransactionReportsGetResponse": {
"required": [
"merchantTransactionReportId",
"merchantId",
"periodYear",
"periodMonth",
"currencyId",
"totalFee",
"netFee",
"vatRate",
"vatAmount",
"vatDate",
"reportNumber",
"createdAt"
],
"type": "object",
"properties": {
"merchantTransactionReportId": {
"type": "string",
"format": "uuid"
},
"merchantId": {
"type": "string",
"format": "uuid"
},
"periodYear": {
"type": "integer",
"format": "int32"
},
"periodMonth": {
"type": "integer",
"format": "int32"
},
"currencyId": {
"$ref": "#/components/schemas/CurrencyEnum"
},
"totalFee": {
"type": "integer",
"description": "VAT-inclusive fee in minor currency units (what the merchant is charged).",
"format": "int64"
},
"netFee": {
"type": "integer",
"description": "Fee before VAT in minor currency units.",
"format": "int64"
},
"vatRate": {
"type": "integer",
"description": "VAT rate in basis points (e.g. 2100 = 21%).",
"format": "int32"
},
"vatAmount": {
"type": "integer",
"description": "VAT portion in minor currency units (totalFee − netFee).",
"format": "int64"
},
"vatDate": {
"$ref": "#/components/schemas/LocalDate"
},
"reportNumber": {
"type": "string",
"description": "Human-readable report number (e.g. TAP2026030001)."
},
"createdAt": {
"$ref": "#/components/schemas/Instant"
}
}
},
"IntegratorMerchantUpdateProcessorMerchantRequest": {
"required": [
"mcc",
"paymentProcessorId",
"supportPhone",
"statementDescriptor"
],
"type": "object",
"properties": {
"mcc": {
"maxLength": 4,
"pattern": "^[0-9]{4}$",
"type": [
"null",
"string"
],
"description": "The Merchant Category Code (MCC) that classifies the business type."
},
"url": {
"maxLength": 2000,
"type": [
"null",
"string"
],
"description": "The public website URL of the merchant. Can be a website or a social media account.",
"format": "uri"
},
"productDescription": {
"maxLength": 2000,
"type": [
"null",
"string"
],
"description": "Description of the products sold by the merchant. Alternative if string? IntegratorMerchantUpdateProcessorMerchantRequest.Url is not available."
},
"bankAccount": {
"oneOf": [
{
"type": "null"
},
{
"description": "The bank account information where settlements will be deposited.",
"$ref": "#/components/schemas/BankAccountInformation"
}
]
},
"individual": {
"oneOf": [
{
"type": "null"
},
{
"description": "The personal information of the merchant if they are operating as an individual.",
"$ref": "#/components/schemas/PersonInformation"
}
]
},
"company": {
"oneOf": [
{
"type": "null"
},
{
"description": "The company information of the merchant if they are operating as a business entity.",
"$ref": "#/components/schemas/CompanyInformation"
}
]
},
"paymentProcessorId": {
"description": "The payment processor to use (e.g., Stripe).",
"$ref": "#/components/schemas/PaymentProcessorEnum"
},
"supportPhone": {
"maxLength": 20,
"type": "string",
"description": "Merchant customer support phone number."
},
"statementDescriptor": {
"maxLength": 22,
"type": "string",
"description": "The default text that appears on bank statements."
},
"final": {
"type": "boolean",
"description": "When true, indicates this is the final submission and a KYB email should be sent.\nWhen false or not provided, email is skipped."
}
},
"description": "Represents a request to update an existing merchant's information."
},
"IntegratorMerchantUpdateProcessorMerchantResponse": {
"required": [
"chargesEnabled",
"payoutsEnabled",
"pendingRequirements",
"pastDueRequirements",
"eventuallyDueRequirements",
"disabledReasonRequirements",
"summary"
],
"type": "object",
"properties": {
"processorMerchantId": {
"type": [
"null",
"string"
],
"description": "Processor merchant account identifier."
},
"chargesEnabled": {
"type": "boolean",
"description": "True if charges are currently enabled for the account."
},
"payoutsEnabled": {
"type": "boolean",
"description": "True if payouts are currently enabled for the account."
},
"pendingRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requirements that the processor reports as currently due."
},
"pastDueRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requirements that are past due, i.e. blocking or time‑critical."
},
"eventuallyDueRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requirements that will be eventually due, but are not blocking yet."
},
"disabledReasonRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requirements that are currently disabled (ex: for rejected capabilities)."
},
"requirementsDeadlineTimestamp": {
"oneOf": [
{
"type": "null"
},
{
"description": "Current deadline for providing missing requirements, if any.",
"$ref": "#/components/schemas/Instant"
}
]
},
"summary": {
"type": "string",
"description": "High‑level, human‑readable status summary (intended for logs / dashboards,\nnot for strict programmatic decisions)."
},
"isFullyRequirementsSatisfied": {
"type": "boolean",
"description": "True when there is no pending nor past‑due requirement."
},
"isOperational": {
"type": "boolean",
"description": "Indicates whether merchant is effectively \"live\": charges and payouts are enabled\nand no blocking requirements are present."
},
"stripeOnboardingUrl": {
"type": [
"null",
"string"
],
"description": "Redirect URL to the Stripe-hosted onboarding flow; present when Stripe requires additional information to activate\nthe account."
},
"submittedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "Timestamp when the merchant submitted their onboarding data to the processor.\nNull if the onboarding has not been submitted yet.",
"$ref": "#/components/schemas/Instant"
}
]
}
},
"description": "Processor account status and requirements returned after submitting merchant data."
},
"IntegratorOrganizationApiKeyGetResponse": {
"required": [
"tokens"
],
"type": "object",
"properties": {
"tokens": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenItem"
},
"description": "List of active API key tokens."
}
}
},
"IntegratorOrganizationApiKeyPostRequest": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string",
"description": "Human-readable label for the API key (1–64 characters, trimmed server-side)."
}
}
},
"IntegratorOrganizationApiKeyPostResponse": {
"required": [
"apiTokenId",
"token",
"name",
"createdAt"
],
"type": "object",
"properties": {
"apiTokenId": {
"type": "string",
"description": "Unique API token identifier.",
"format": "uuid"
},
"token": {
"type": "string",
"description": "The API key token value."
},
"name": {
"type": "string",
"description": "Human-readable label for the API key."
},
"createdAt": {
"type": "string",
"description": "UTC timestamp when the API key was created.",
"format": "date-time"
}
}
},
"IntegratorOrganizationBankAccountsGetResult": {
"required": [
"bankAccountId",
"iban",
"currencyId",
"createdAt",
"updatedAt"
],
"type": "object",
"properties": {
"bankAccountId": {
"type": "string",
"description": "Bank account identifier.",
"format": "uuid"
},
"iban": {
"type": "string",
"description": "IBAN."
},
"bic": {
"type": [
"null",
"string"
],
"description": "SWIFT/BIC code."
},
"bankName": {
"type": [
"null",
"string"
],
"description": "Name of the bank holding the account."
},
"accountHolderName": {
"type": [
"null",
"string"
],
"description": "Name of the account holder."
},
"currencyId": {
"description": "Settlement currency this account is used for.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"createdAt": {
"description": "Creation timestamp.",
"$ref": "#/components/schemas/Instant"
},
"updatedAt": {
"description": "Last update timestamp.",
"$ref": "#/components/schemas/Instant"
}
}
},
"IntegratorOrganizationBankAccountsPostRequest": {
"required": [
"iban",
"currencyId"
],
"type": "object",
"properties": {
"iban": {
"maxLength": 34,
"minLength": 0,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Za-z0-9]{1,30}$",
"type": "string",
"description": "IBAN."
},
"bic": {
"maxLength": 11,
"minLength": 0,
"pattern": "^[A-Za-z]{6}[A-Za-z0-9]{2}([A-Za-z0-9]{3})?$",
"type": [
"null",
"string"
],
"description": "SWIFT/BIC code."
},
"bankName": {
"maxLength": 255,
"minLength": 0,
"type": [
"null",
"string"
],
"description": "Name of the bank holding the account."
},
"accountHolderName": {
"maxLength": 255,
"minLength": 0,
"type": [
"null",
"string"
],
"description": "Name of the account holder."
},
"currencyId": {
"description": "Settlement currency this account is for.",
"$ref": "#/components/schemas/CurrencyEnum"
}
}
},
"IntegratorOrganizationBankAccountsPostResult": {
"required": [
"bankAccountId",
"iban",
"currencyId",
"createdAt",
"updatedAt"
],
"type": "object",
"properties": {
"bankAccountId": {
"type": "string",
"description": "Bank account identifier.",
"format": "uuid"
},
"iban": {
"type": "string",
"description": "IBAN."
},
"bic": {
"type": [
"null",
"string"
],
"description": "SWIFT/BIC code."
},
"bankName": {
"type": [
"null",
"string"
],
"description": "Name of the bank holding the account."
},
"accountHolderName": {
"type": [
"null",
"string"
],
"description": "Name of the account holder."
},
"currencyId": {
"description": "Settlement currency this account is used for.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"createdAt": {
"description": "Creation timestamp.",
"$ref": "#/components/schemas/Instant"
},
"updatedAt": {
"description": "Last update timestamp.",
"$ref": "#/components/schemas/Instant"
}
}
},
"IntegratorOrganizationConfigGetResponse": {
"required": [
"modeApplication",
"modePlugin",
"preferredPaymentProcessor"
],
"type": "object",
"properties": {
"modeApplication": {
"type": "boolean",
"description": "Whether the organization's SDK integration may run in standalone application mode."
},
"modePlugin": {
"type": "boolean",
"description": "Whether the organization's SDK integration may run in embedded plugin mode."
},
"preferredPaymentProcessor": {
"description": "Default payment processor applied when onboarding new merchants without an explicit processor selection.",
"$ref": "#/components/schemas/PaymentProcessorEnum"
}
}
},
"IntegratorOrganizationConfigPutRequest": {
"required": [
"preferredPaymentProcessor"
],
"type": "object",
"properties": {
"modeApplication": {
"type": [
"null",
"boolean"
],
"description": "Whether the organization's SDK integration may run in standalone application mode."
},
"modePlugin": {
"type": [
"null",
"boolean"
],
"description": "Whether the organization's SDK integration may run in embedded plugin mode."
},
"preferredPaymentProcessor": {
"description": "Preferred payment processor for this integrator. Required. Used as the default processor when a merchant\nis onboarded without an explicit processor selection.",
"$ref": "#/components/schemas/PaymentProcessorEnum"
}
}
},
"IntegratorOrganizationConfigPutResponse": {
"required": [
"modeApplication",
"modePlugin",
"preferredPaymentProcessor"
],
"type": "object",
"properties": {
"modeApplication": {
"type": "boolean",
"description": "Whether the organization's SDK integration may run in standalone application mode."
},
"modePlugin": {
"type": "boolean",
"description": "Whether the organization's SDK integration may run in embedded plugin mode."
},
"preferredPaymentProcessor": {
"description": "Preferred payment processor for this integrator. Used as the default processor when a merchant is\nonboarded without an explicit processor selection.",
"$ref": "#/components/schemas/PaymentProcessorEnum"
}
}
},
"IntegratorOrganizationGetResponse": {
"required": [
"organizationId",
"name",
"legalName",
"businessTypeId",
"registrationNumber",
"countryId",
"city",
"addressLine1",
"postalCode",
"email",
"settlementCurrencyId",
"invoicingEmail",
"isActive",
"canInitiatePaymentInCompanion",
"createdAt",
"updatedAt"
],
"type": "object",
"properties": {
"organizationId": {
"type": "string",
"description": "Unique organization identifier.",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Organization display name."
},
"legalName": {
"type": "string",
"description": "Legal name of the organization."
},
"businessTypeId": {
"description": "Type of incorporation.",
"$ref": "#/components/schemas/BusinessTypeEnum"
},
"registrationNumber": {
"type": "string",
"description": "Business registration number."
},
"vatNumber": {
"type": [
"null",
"string"
],
"description": "VAT number of the organization."
},
"countryId": {
"description": "Country code.",
"$ref": "#/components/schemas/CountryEnum"
},
"city": {
"type": "string",
"description": "City name."
},
"addressLine1": {
"type": "string",
"description": "Address line 1."
},
"addressLine2": {
"type": [
"null",
"string"
],
"description": "Address line 2."
},
"state": {
"type": [
"null",
"string"
],
"description": "State name."
},
"postalCode": {
"type": "string",
"description": "Postal code."
},
"email": {
"type": "string",
"description": "Contact email address."
},
"phone": {
"type": [
"null",
"string"
],
"description": "Contact phone number."
},
"settlementCurrencyId": {
"description": "Currency used for settlement payouts.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"invoicingEmail": {
"type": "string",
"description": "Email address used for sending invoices."
},
"themeUrl": {
"type": [
"null",
"string"
],
"description": "URL of the organization theme, or null if no theme is configured."
},
"isActive": {
"type": "boolean",
"description": "Whether the organization is active."
},
"canInitiatePaymentInCompanion": {
"type": "boolean",
"description": "True if terminals under this organization can initiate payments via the companion app; these payments are not tracked by the SDK."
},
"createdAt": {
"description": "UTC timestamp when the organization was created.",
"$ref": "#/components/schemas/Instant"
},
"updatedAt": {
"description": "UTC timestamp when the organization was last updated.",
"$ref": "#/components/schemas/Instant"
}
}
},
"IntegratorOrganizationInvoiceDownloadGetResponse": {
"required": [
"url"
],
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Pre-signed S3 URL to download the invoice. Valid for 15 minutes."
}
}
},
"IntegratorOrganizationInvoiceGetResponse": {
"required": [
"organizationInvoiceId",
"periodYear",
"periodMonth",
"currencyId",
"totalFee",
"netFee",
"vatRate",
"vatAmount",
"vatDate",
"invoiceNumber",
"orgName",
"orgLegalName",
"orgRegistrationNumber",
"orgEmail",
"countryId",
"city",
"addressLine1",
"postalCode",
"createdAt",
"paymentIds"
],
"type": "object",
"properties": {
"organizationInvoiceId": {
"type": "string",
"format": "uuid"
},
"periodYear": {
"type": "integer",
"format": "int32"
},
"periodMonth": {
"type": "integer",
"format": "int32"
},
"currencyId": {
"$ref": "#/components/schemas/CurrencyEnum"
},
"totalFee": {
"type": "integer",
"description": "VAT-inclusive fee in minor currency units (what the organization is charged).",
"format": "int64"
},
"netFee": {
"type": "integer",
"description": "Fee before VAT in minor currency units.",
"format": "int64"
},
"vatRate": {
"type": "integer",
"format": "int32"
},
"vatAmount": {
"type": "integer",
"description": "VAT portion in minor currency units (totalFee − netFee).",
"format": "int64"
},
"vatDate": {
"$ref": "#/components/schemas/LocalDate"
},
"paidAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "Null means unpaid.",
"$ref": "#/components/schemas/Instant"
}
]
},
"invoiceNumber": {
"type": "string",
"description": "Human-readable invoice number (e.g. TAP2026030001)."
},
"orgName": {
"type": "string"
},
"orgLegalName": {
"type": "string"
},
"orgRegistrationNumber": {
"type": "string"
},
"orgVatNumber": {
"type": [
"null",
"string"
]
},
"orgEmail": {
"type": "string"
},
"countryId": {
"type": "integer",
"format": "int32"
},
"city": {
"type": "string"
},
"addressLine1": {
"type": "string"
},
"addressLine2": {
"type": [
"null",
"string"
]
},
"state": {
"type": [
"null",
"string"
]
},
"postalCode": {
"type": "string"
},
"createdAt": {
"$ref": "#/components/schemas/Instant"
},
"paymentIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "IDs of payments included in this invoice batch."
}
}
},
"IntegratorOrganizationInvoicesGetResponse": {
"required": [
"organizationInvoiceId",
"periodYear",
"periodMonth",
"currencyId",
"totalFee",
"netFee",
"vatRate",
"vatAmount",
"vatDate",
"invoiceNumber",
"createdAt"
],
"type": "object",
"properties": {
"organizationInvoiceId": {
"type": "string",
"description": "Organization invoice identifier.",
"format": "uuid"
},
"periodYear": {
"type": "integer",
"description": "Year of the billing period.",
"format": "int32"
},
"periodMonth": {
"type": "integer",
"description": "Month of the billing period (1–12).",
"format": "int32"
},
"currencyId": {
"description": "Settlement currency ISO 4217 numeric code.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"totalFee": {
"type": "integer",
"description": "VAT-inclusive fee in minor currency units (what the organization is charged).",
"format": "int64"
},
"netFee": {
"type": "integer",
"description": "Fee before VAT in minor currency units.",
"format": "int64"
},
"vatRate": {
"type": "integer",
"description": "VAT rate in basis points (e.g. 2100 = 21%).",
"format": "int32"
},
"vatAmount": {
"type": "integer",
"description": "VAT portion in minor currency units (totalFee − netFee).",
"format": "int64"
},
"vatDate": {
"description": "Tax point date — last day of the billing period.",
"$ref": "#/components/schemas/LocalDate"
},
"paidAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "When the invoice was paid. Null means unpaid.",
"$ref": "#/components/schemas/Instant"
}
]
},
"invoiceNumber": {
"type": "string",
"description": "Human-readable invoice number (e.g. TAP2026030001)."
},
"createdAt": {
"description": "When the invoice was generated.",
"$ref": "#/components/schemas/Instant"
}
}
},
"IntegratorOrganizationPaymentGetCharge": {
"required": [
"chargeId",
"chargeToken",
"statusId",
"requestedAmount",
"requestedCurrencyId",
"settlementAmount",
"settlementCurrencyId",
"fxRate",
"createdAt"
],
"type": "object",
"properties": {
"chargeId": {
"type": "string",
"description": "Server-generated charge identifier.",
"format": "uuid"
},
"chargeToken": {
"type": "string",
"description": "Client-visible charge token."
},
"statusId": {
"description": "Charge status.",
"$ref": "#/components/schemas/StatusEnum"
},
"instrumentLabel": {
"type": [
"null",
"string"
],
"description": "Card brand, token network, or other instrument label."
},
"instrumentIdentifier": {
"type": [
"null",
"string"
],
"description": "PAN last 4, wallet address, or other instrument identifier."
},
"authorizationReference": {
"type": [
"null",
"string"
],
"description": "Authorization code, chain transaction ID, or similar processor reference."
},
"requestedAmount": {
"type": "integer",
"description": "Amount debited from the customer, in the smallest unit of requestedCurrencyId.",
"format": "int64"
},
"requestedCurrencyId": {
"description": "Numeric ISO 4217 code of the currency debited from the customer.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"settlementAmount": {
"type": "integer",
"description": "Amount credited to the merchant, in the smallest unit of settlementCurrencyId.",
"format": "int64"
},
"settlementCurrencyId": {
"description": "Numeric ISO 4217 code of the merchant settlement currency.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"fxRate": {
"type": "number",
"description": "FX rate applied to this charge.",
"format": "double"
},
"createdAt": {
"description": "UTC timestamp when this charge was created.",
"$ref": "#/components/schemas/Instant"
}
},
"description": "A charge attempt within a transaction."
},
"IntegratorOrganizationPaymentGetRefund": {
"required": [
"refundId",
"refundToken",
"statusId",
"refundReasonId",
"requestedAmount",
"requestedCurrencyId",
"settlementAmount",
"settlementCurrencyId",
"fxRate",
"createdAt"
],
"type": "object",
"properties": {
"refundId": {
"type": "string",
"description": "Server-generated refund identifier.",
"format": "uuid"
},
"refundToken": {
"type": "string",
"description": "Client-visible refund token."
},
"statusId": {
"description": "Refund status.",
"$ref": "#/components/schemas/StatusEnum"
},
"refundReasonId": {
"description": "Reason for the refund.",
"$ref": "#/components/schemas/RefundReasonEnum"
},
"requestedAmount": {
"type": "integer",
"description": "Amount refunded to the customer, in the smallest unit of requestedCurrencyId.",
"format": "int64"
},
"requestedCurrencyId": {
"description": "Numeric ISO 4217 code of the customer refund currency.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"settlementAmount": {
"type": "integer",
"description": "Amount deducted from the merchant, in the smallest unit of settlementCurrencyId.",
"format": "int64"
},
"settlementCurrencyId": {
"description": "Numeric ISO 4217 code of the merchant settlement currency.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"fxRate": {
"type": "number",
"description": "FX rate applied to this refund.",
"format": "double"
},
"authorizationReference": {
"type": [
"null",
"string"
],
"description": "Authorization code or processor reference for this refund, if available."
},
"referralFeeRefund": {
"type": [
"null",
"integer"
],
"description": "Integrator fee refunded, in the smallest unit of settlementCurrencyId.\nPopulated asynchronously after processor confirmation; null until then.",
"format": "int64"
},
"createdAt": {
"description": "UTC timestamp when the refund was created.",
"$ref": "#/components/schemas/Instant"
},
"processedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "UTC timestamp when the refund was processed, if applicable.",
"$ref": "#/components/schemas/Instant"
}
]
}
},
"description": "A refund issued against this payment."
},
"IntegratorOrganizationPaymentGetResult": {
"required": [
"paymentId",
"paymentToken",
"paymentProcessorId",
"paymentMethodId",
"terminalId",
"locationId",
"requestedAmount",
"requestedCurrencyId",
"settlementAmount",
"settlementCurrencyId",
"netAmount",
"totalApplicationFee",
"referralFee",
"statusId",
"merchantId",
"merchantName",
"createdAt",
"transactions",
"refunds"
],
"type": "object",
"properties": {
"paymentId": {
"type": "string",
"description": "Server-generated payment identifier.",
"format": "uuid"
},
"paymentToken": {
"type": "string",
"description": "Client-provided token that identifies the payment."
},
"paymentProcessorId": {
"description": "Payment processor used (e.g. Stripe).",
"$ref": "#/components/schemas/PaymentProcessorEnum"
},
"paymentMethodId": {
"description": "Payment method (e.g. Card, SepaIct).",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"terminalId": {
"type": "string",
"description": "Identifier of the terminal that initiated the payment.",
"format": "uuid"
},
"locationId": {
"type": "string",
"description": "Identifier of the location where payment occurred.",
"format": "uuid"
},
"requestedAmount": {
"type": "integer",
"description": "Amount requested from the customer, in the smallest unit of requestedCurrencyId.",
"format": "int64"
},
"requestedCurrencyId": {
"description": "Numeric ISO 4217 code of the currency debited from the customer.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"settlementAmount": {
"type": "integer",
"description": "Gross amount credited to the merchant before fees, in the smallest unit of settlementCurrencyId.",
"format": "int64"
},
"settlementCurrencyId": {
"description": "Numeric ISO 4217 code of the merchant settlement currency.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"netAmount": {
"type": "integer",
"description": "Net amount credited to the merchant after fees, in the smallest unit of settlementCurrencyId.\nEqual to settlementAmount - totalApplicationFee.",
"format": "int64"
},
"totalApplicationFee": {
"type": "integer",
"description": "Total platform fee deducted from settlementAmount, in the smallest unit of settlementCurrencyId.\nreferralFee is the integrator's share of this amount.",
"format": "int64"
},
"referralFee": {
"type": "integer",
"description": "Integrator's referral fee share, in the smallest unit of settlementCurrencyId.",
"format": "int64"
},
"statusId": {
"description": "Overall payment status.",
"$ref": "#/components/schemas/StatusEnum"
},
"terminalName": {
"type": [
"null",
"string"
],
"description": "Human-readable terminal name derived from the device (brand + model). Null if no device is assigned."
},
"locationName": {
"type": [
"null",
"string"
],
"description": "Name of the venue linked to the location. Null if no venue is linked."
},
"merchantId": {
"type": "string",
"description": "Identifier of the merchant that owns this payment.",
"format": "uuid"
},
"merchantName": {
"type": "string",
"description": "Display name of the merchant."
},
"createdAt": {
"description": "UTC timestamp when the payment was created.",
"$ref": "#/components/schemas/Instant"
},
"processedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "UTC timestamp when the payment reached a terminal status, if applicable.",
"$ref": "#/components/schemas/Instant"
}
]
},
"transactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentGetTransaction"
},
"description": "Ordered list of transaction attempts (oldest first). Multiple entries indicate retries."
},
"refunds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentGetRefund"
},
"description": "Refunds issued against this payment."
}
},
"description": "Full detail of a payment including its transaction history, charges, fees, and refunds."
},
"IntegratorOrganizationPaymentGetTransaction": {
"required": [
"transactionId",
"statusId",
"fxRate",
"createdAt",
"charges"
],
"type": "object",
"properties": {
"transactionId": {
"type": "string",
"description": "Server-generated transaction identifier.",
"format": "uuid"
},
"statusId": {
"description": "Transaction status.",
"$ref": "#/components/schemas/StatusEnum"
},
"referenceInfo": {
"type": [
"null",
"string"
],
"description": "Payment reference (e.g. bank transfer reference), if applicable."
},
"fxRate": {
"type": "number",
"description": "FX rate applied to this transaction (requestedCurrency → settlementCurrency).",
"format": "double"
},
"createdAt": {
"description": "UTC timestamp when this transaction was created.",
"$ref": "#/components/schemas/Instant"
},
"processedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "UTC timestamp when this transaction was successfully processed, if applicable.",
"$ref": "#/components/schemas/Instant"
}
]
},
"cancelledAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "UTC timestamp when this transaction was cancelled, if applicable.",
"$ref": "#/components/schemas/Instant"
}
]
},
"charges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentGetCharge"
},
"description": "Charge attempts within this transaction."
}
},
"description": "A single transaction attempt within a payment."
},
"IntegratorOrganizationPaymentMethodPutCardTypeRequest": {
"required": [
"region",
"holderType",
"scheme",
"enabled"
],
"type": "object",
"properties": {
"region": {
"$ref": "#/components/schemas/CardRegionEnum"
},
"holderType": {
"$ref": "#/components/schemas/CardHolderTypeEnum"
},
"scheme": {
"$ref": "#/components/schemas/CardSchemeEnum"
},
"enabled": {
"type": "boolean"
},
"referralFeeAbsolute": {
"type": [
"null",
"integer"
],
"description": "Referral fee absolute in cents. When omitted, the payment method-level value is used.",
"format": "int64"
},
"referralFeeRelative": {
"type": [
"null",
"integer"
],
"description": "Referral fee relative in basis points. When omitted, the payment method-level value is used.",
"format": "int64"
}
}
},
"IntegratorOrganizationPaymentMethodPutCardTypeResponse": {
"required": [
"region",
"holderType",
"scheme",
"enabled",
"referralFeeAbsolute",
"referralFeeRelative"
],
"type": "object",
"properties": {
"region": {
"$ref": "#/components/schemas/CardRegionEnum"
},
"holderType": {
"$ref": "#/components/schemas/CardHolderTypeEnum"
},
"scheme": {
"$ref": "#/components/schemas/CardSchemeEnum"
},
"enabled": {
"type": "boolean"
},
"referralFeeAbsolute": {
"type": "integer",
"format": "int64"
},
"referralFeeRelative": {
"type": "integer",
"format": "int64"
}
}
},
"IntegratorOrganizationPaymentMethodPutRequest": {
"required": [
"onboardingAllowed",
"referralFeeAbsolute",
"referralFeeRelative"
],
"type": "object",
"properties": {
"onboardingAllowed": {
"type": "boolean",
"description": "Indicates if onboarding of new merchants is allowed for this payment method."
},
"referralFeeAbsolute": {
"type": "integer",
"description": "Referral fee absolute in cents.",
"format": "int64"
},
"referralFeeRelative": {
"type": "integer",
"description": "Referral fee relative in basis points.",
"format": "int64"
},
"cardTypes": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentMethodPutCardTypeRequest"
},
"description": "Card category enable flags. Only valid when updating the Card payment method."
}
}
},
"IntegratorOrganizationPaymentMethodPutResponse": {
"required": [
"paymentMethodId",
"onboardingAllowed"
],
"type": "object",
"properties": {
"paymentMethodId": {
"description": "Identifier for the allowed payment method.",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"onboardingAllowed": {
"type": "boolean",
"description": "Indicates if onboarding of new merchants is allowed for this payment method."
},
"referralFeeAbsolute": {
"type": [
"null",
"integer"
],
"description": "Referral fee absolute in cents. Null for Card — fees are defined per card type.",
"format": "int64"
},
"referralFeeRelative": {
"type": [
"null",
"integer"
],
"description": "Referral fee relative in basis points. Null for Card — fees are defined per card type.",
"format": "int64"
},
"cardTypes": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentMethodPutCardTypeResponse"
},
"description": "Enabled card categories. Present only when PaymentMethodEnum IntegratorOrganizationPaymentMethodPutResponse.PaymentMethodId is Card."
}
}
},
"IntegratorOrganizationPaymentMethodsGetCardTypeResponse": {
"required": [
"region",
"holderType",
"scheme",
"enabled",
"referralFeeAbsolute",
"referralFeeRelative"
],
"type": "object",
"properties": {
"region": {
"$ref": "#/components/schemas/CardRegionEnum"
},
"holderType": {
"$ref": "#/components/schemas/CardHolderTypeEnum"
},
"scheme": {
"$ref": "#/components/schemas/CardSchemeEnum"
},
"enabled": {
"type": "boolean"
},
"referralFeeAbsolute": {
"type": "integer",
"format": "int64"
},
"referralFeeRelative": {
"type": "integer",
"format": "int64"
}
}
},
"IntegratorOrganizationPaymentMethodsGetResponse": {
"required": [
"paymentMethodId",
"onboardingAllowed"
],
"type": "object",
"properties": {
"paymentMethodId": {
"description": "Identifier for the allowed payment method.",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"onboardingAllowed": {
"type": "boolean",
"description": "Indicates if onboarding of new merchants is allowed for this payment method."
},
"referralFeeAbsolute": {
"type": [
"null",
"integer"
],
"description": "Referral fee absolute in cents. Null for Card — fees are defined per card type.",
"format": "int64"
},
"referralFeeRelative": {
"type": [
"null",
"integer"
],
"description": "Referral fee relative in basis points. Null for Card — fees are defined per card type.",
"format": "int64"
},
"cardTypes": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentMethodsGetCardTypeResponse"
},
"description": "Enabled card categories. Present only when PaymentMethodEnum IntegratorOrganizationPaymentMethodsGetResponse.PaymentMethodId is Card."
}
}
},
"IntegratorOrganizationPaymentMethodsPostCardTypeRequest": {
"required": [
"region",
"holderType",
"scheme",
"enabled",
"referralFeeAbsolute",
"referralFeeRelative"
],
"type": "object",
"properties": {
"region": {
"$ref": "#/components/schemas/CardRegionEnum"
},
"holderType": {
"$ref": "#/components/schemas/CardHolderTypeEnum"
},
"scheme": {
"$ref": "#/components/schemas/CardSchemeEnum"
},
"enabled": {
"type": "boolean"
},
"referralFeeAbsolute": {
"type": "integer",
"format": "int64"
},
"referralFeeRelative": {
"type": "integer",
"format": "int64"
}
}
},
"IntegratorOrganizationPaymentMethodsPostCardTypeResponse": {
"required": [
"region",
"holderType",
"scheme",
"enabled",
"referralFeeAbsolute",
"referralFeeRelative"
],
"type": "object",
"properties": {
"region": {
"$ref": "#/components/schemas/CardRegionEnum"
},
"holderType": {
"$ref": "#/components/schemas/CardHolderTypeEnum"
},
"scheme": {
"$ref": "#/components/schemas/CardSchemeEnum"
},
"enabled": {
"type": "boolean"
},
"referralFeeAbsolute": {
"type": "integer",
"format": "int64"
},
"referralFeeRelative": {
"type": "integer",
"format": "int64"
}
}
},
"IntegratorOrganizationPaymentMethodsPostRequest": {
"required": [
"paymentMethodId",
"onboardingAllowed"
],
"type": "object",
"properties": {
"paymentMethodId": {
"description": "Identifier for the allowed payment method.",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"onboardingAllowed": {
"type": "boolean",
"description": "Indicates if onboarding of new merchants is allowed for this payment method."
},
"referralFeeAbsolute": {
"type": [
"null",
"integer"
],
"description": "Referral fee absolute in cents. Required for non-Card payment methods; omit for Card.",
"format": "int64"
},
"referralFeeRelative": {
"type": [
"null",
"integer"
],
"description": "Referral fee relative in basis points. Required for non-Card payment methods; omit for Card.",
"format": "int64"
},
"cardTypes": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentMethodsPostCardTypeRequest"
},
"description": "Card categories with per-type referral fees. Required when adding the Card payment method."
}
}
},
"IntegratorOrganizationPaymentMethodsPostResponse": {
"required": [
"paymentMethodId",
"onboardingAllowed"
],
"type": "object",
"properties": {
"paymentMethodId": {
"description": "Identifier for the allowed payment method.",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"onboardingAllowed": {
"type": "boolean",
"description": "Indicates if onboarding of new merchants is allowed for this payment method."
},
"referralFeeAbsolute": {
"type": [
"null",
"integer"
],
"description": "Referral fee absolute in cents. Null for Card — fees are defined per card type.",
"format": "int64"
},
"referralFeeRelative": {
"type": [
"null",
"integer"
],
"description": "Referral fee relative in basis points. Null for Card — fees are defined per card type.",
"format": "int64"
},
"cardTypes": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/IntegratorOrganizationPaymentMethodsPostCardTypeResponse"
},
"description": "Enabled card categories. Present only when PaymentMethodEnum IntegratorOrganizationPaymentMethodsPostResponse.PaymentMethodId is Card."
}
}
},
"IntegratorOrganizationPaymentRefundPostRequest": {
"required": [
"refundReasonId"
],
"type": "object",
"properties": {
"amount": {
"type": [
"null",
"integer"
],
"description": "The amount to refund, in the smallest unit of the settlement currency.\nOmit to refund the full remaining amount.",
"format": "int64"
},
"refundReasonId": {
"description": "The reason for the refund.",
"$ref": "#/components/schemas/RefundReasonEnum"
}
},
"description": "Request body for initiating a refund."
},
"IntegratorOrganizationPaymentRefundPostResult": {
"required": [
"refundId",
"refundToken",
"statusId",
"refundReasonId",
"requestedAmount",
"requestedCurrencyId",
"settlementAmount",
"settlementCurrencyId",
"fxRate",
"createdAt"
],
"type": "object",
"properties": {
"refundId": {
"type": "string",
"description": "Server-generated refund identifier.",
"format": "uuid"
},
"refundToken": {
"type": "string",
"description": "Client-visible refund token."
},
"statusId": {
"description": "Refund status.",
"$ref": "#/components/schemas/StatusEnum"
},
"refundReasonId": {
"description": "Reason for the refund.",
"$ref": "#/components/schemas/RefundReasonEnum"
},
"requestedAmount": {
"type": "integer",
"description": "Amount refunded to the customer, in the smallest unit of requestedCurrencyId.",
"format": "int64"
},
"requestedCurrencyId": {
"description": "Numeric ISO 4217 code of the customer refund currency.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"settlementAmount": {
"type": "integer",
"description": "Amount deducted from the merchant, in the smallest unit of settlementCurrencyId.",
"format": "int64"
},
"settlementCurrencyId": {
"description": "Numeric ISO 4217 code of the merchant settlement currency.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"fxRate": {
"type": "number",
"description": "FX rate applied to this refund.",
"format": "double"
},
"authorizationReference": {
"type": [
"null",
"string"
],
"description": "Authorization code or processor reference for this refund, if available."
},
"referralFeeRefund": {
"type": [
"null",
"integer"
],
"description": "Integrator fee refunded, in the smallest unit of settlementCurrencyId.\nPopulated asynchronously after processor confirmation; null until then.",
"format": "int64"
},
"createdAt": {
"description": "UTC timestamp when the refund was created.",
"$ref": "#/components/schemas/Instant"
},
"processedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "UTC timestamp when the refund was processed, if applicable.",
"$ref": "#/components/schemas/Instant"
}
]
}
},
"description": "The newly created refund."
},
"IntegratorOrganizationPaymentsGetResult": {
"required": [
"paymentId",
"paymentToken",
"paymentProcessorId",
"paymentMethodId",
"terminalId",
"locationId",
"requestedAmount",
"requestedCurrencyId",
"settlementAmount",
"settlementCurrencyId",
"statusId",
"createdAt",
"merchantId",
"merchantName"
],
"type": "object",
"properties": {
"paymentId": {
"type": "string",
"description": "Server-generated payment id.",
"format": "uuid"
},
"paymentToken": {
"type": "string",
"description": "Client-provided token that identifies a payment."
},
"paymentProcessorId": {
"description": "The payment processor to use (e.g., Stripe).",
"$ref": "#/components/schemas/PaymentProcessorEnum"
},
"paymentMethodId": {
"description": "The payment method to use (e.g., card, bank transfer).",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"terminalId": {
"type": "string",
"description": "Identifier of the terminal that processed the payment.",
"format": "uuid"
},
"locationId": {
"type": "string",
"description": "Identifier of the terminal location where payment happened.",
"format": "uuid"
},
"requestedAmount": {
"type": "integer",
"description": "Amount that the customer is requested to pay, in the smallest unit of requested currency.",
"format": "int64"
},
"requestedCurrencyId": {
"description": "Currency that will be charged to the customer.",
"examples": [
978
],
"$ref": "#/components/schemas/CurrencyEnum"
},
"settlementAmount": {
"type": "integer",
"description": "Amount the merchant will receive, in the smallest unit of the settlement currency.",
"format": "int64",
"example": 1000
},
"settlementCurrencyId": {
"description": "Numeric ISO 4217 code of the currency requested by merchant.",
"examples": [
978
],
"$ref": "#/components/schemas/CurrencyEnum"
},
"statusId": {
"description": "Payment status.",
"$ref": "#/components/schemas/StatusEnum"
},
"instrumentLabel": {
"type": [
"null",
"string"
],
"description": "Card brand or network token identifier (e.g., Visa, Mastercard)."
},
"instrumentIdentifier": {
"type": [
"null",
"string"
],
"description": "Last 4 digits of the card number, wallet address, or similar payment instrument identifier."
},
"createdAt": {
"description": "UTC timestamp when the payment was created.",
"$ref": "#/components/schemas/Instant"
},
"processedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "UTC timestamp when the payment was processed, if completed.",
"$ref": "#/components/schemas/Instant"
}
]
},
"merchantId": {
"type": "string",
"description": "Unique identifier of the merchant which created the payment.",
"format": "uuid"
},
"merchantName": {
"type": "string",
"description": "Name of the merchant which created the payment."
}
}
},
"IntegratorOrganizationPaymentStatsGetResult": {
"required": [
"currencyId",
"amount"
],
"type": "object",
"properties": {
"currencyId": {
"description": "Currency id of the corresponding amount.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"amount": {
"type": "integer",
"description": "Total settled payment volume in minor currency units across all merchants for this currency.",
"format": "int64"
}
}
},
"IntegratorOrganizationPutRequest": {
"type": "object",
"properties": {
"name": {
"type": [
"null",
"string"
],
"description": "Updated organization name."
},
"settlementCurrencyId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Currency used for settlement payouts.",
"$ref": "#/components/schemas/CurrencyEnum"
}
]
},
"invoicingEmail": {
"type": [
"null",
"string"
],
"description": "Email address for invoices."
},
"iban": {
"maxLength": 34,
"minLength": 0,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Za-z0-9]{1,30}$",
"type": [
"null",
"string"
],
"description": "IBAN of the organization's settlement bank account."
},
"bic": {
"maxLength": 11,
"minLength": 0,
"pattern": "^[A-Za-z]{6}[A-Za-z0-9]{2}([A-Za-z0-9]{3})?$",
"type": [
"null",
"string"
],
"description": "SWIFT/BIC code of the organization's settlement bank account."
},
"bankName": {
"maxLength": 255,
"minLength": 0,
"type": [
"null",
"string"
],
"description": "Name of the bank holding the organization's settlement account."
},
"accountHolderName": {
"maxLength": 255,
"minLength": 0,
"type": [
"null",
"string"
],
"description": "Name of the account holder for the organization's settlement bank account."
}
}
},
"IntegratorOrganizationPutResponse": {
"type": "object",
"properties": {
"name": {
"type": [
"null",
"string"
],
"description": "Updated organization name."
},
"settlementCurrencyId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Currency used for settlement payouts.",
"$ref": "#/components/schemas/CurrencyEnum"
}
]
},
"invoicingEmail": {
"type": [
"null",
"string"
],
"description": "Email address for invoices."
},
"iban": {
"type": [
"null",
"string"
],
"description": "IBAN of the organization's settlement bank account."
},
"bic": {
"type": [
"null",
"string"
],
"description": "SWIFT/BIC code of the organization's settlement bank account."
},
"bankName": {
"type": [
"null",
"string"
],
"description": "Name of the bank holding the organization's settlement account."
},
"accountHolderName": {
"type": [
"null",
"string"
],
"description": "Name of the account holder for the organization's settlement bank account."
}
}
},
"IntegratorOrganizationStatsGetResponse": {
"required": [
"monthlyRevenue",
"referralFeeBalance",
"monthlyTransactions",
"byPaymentMethod",
"byBrand",
"byOperatingSystem",
"dailyTransactions",
"dailyVolume",
"dailyReferralFee",
"dailyOnboardedMerchants"
],
"type": "object",
"properties": {
"monthlyRevenue": {
"description": "Total monthly revenue.",
"$ref": "#/components/schemas/TotalRevenue"
},
"referralFeeBalance": {
"description": "Current referral fee balance pending payout.",
"$ref": "#/components/schemas/PayoutDetails"
},
"monthlyTransactions": {
"description": "Monthly transaction statistics.",
"$ref": "#/components/schemas/TransactionStats"
},
"byPaymentMethod": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StatsByPaymentMethod"
},
"description": "Statistics broken down by payment method."
},
"byBrand": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StatsByBrand"
},
"description": "Statistics broken down by card brand."
},
"byOperatingSystem": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StatsByOperatingSystem"
},
"description": "Statistics broken down by operating system."
},
"dailyTransactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DailyDataPointOfint"
},
"description": "Daily transaction counts."
},
"dailyVolume": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DailyDataPointOflong"
},
"description": "Daily transaction volume."
},
"dailyReferralFee": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DailyDataPointOflong"
},
"description": "Daily referral fee amounts."
},
"dailyOnboardedMerchants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DailyDataPointOfint"
},
"description": "Daily onboarded merchant counts."
}
}
},
"KybPayload": {
"type": "object",
"properties": {
"bankAccount": {
"oneOf": [
{
"type": "null"
},
{
"description": "Bank account details.",
"$ref": "#/components/schemas/BankAccountPayload"
}
]
},
"individual": {
"oneOf": [
{
"type": "null"
},
{
"description": "Individual owner details (sole trader / self-employed).",
"$ref": "#/components/schemas/IndividualPayload"
}
]
},
"company": {
"oneOf": [
{
"type": "null"
},
{
"description": "Company details.",
"$ref": "#/components/schemas/CompanyPayload"
}
]
}
}
},
"LastPayoutResponse": {
"required": [
"amount",
"currency",
"date"
],
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Payout amount in minor currency units.",
"format": "int64"
},
"currency": {
"description": "Payout currency.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"date": {
"description": "UTC timestamp when the payout was made.",
"$ref": "#/components/schemas/Instant"
}
}
},
"LocalDate": {
"type": "string",
"description": "Date without time",
"format": "date",
"example": "9999-12-3"
},
"MerchantAuthLoginRequest": {
"required": [
"merchantToken"
],
"type": "object",
"properties": {
"merchantToken": {
"type": "string",
"description": "Integrator's merchant identifier for which the authentication token will be issued."
},
"allowOnboarding": {
"type": [
"null",
"boolean"
],
"description": "`true` if the user can access and update onboarding and KYB information, can enroll new payment methods, and\ncan approve EULA on behalf of the merchant. Must be true for the first call to eanble the merchant to enroll at\nleast one payment method.\n`false` if the user is denied access to onboarding and can only use the payment method already enrolled to\nthis merchant.\nDefaults to `true` if not provided."
},
"employeeEmail": {
"type": [
"null",
"string"
],
"description": "Email of the employee using the terminal. Should be filled correctly when using Tap to Pay on iPhone to satisfy\nApple requirements."
}
}
},
"MerchantAuthLoginResponse": {
"required": [
"token"
],
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token for initializing terminal SDK.\nSecurely transport it to the mobile app SDK and immediately delete after usage."
}
}
},
"MerchantAuthRegisterRequest": {
"required": [
"email"
],
"type": "object",
"properties": {
"merchantToken": {
"maxLength": 128,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Merchant identifier which will be used to register merchant."
},
"merchantName": {
"maxLength": 128,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Human-readable name to identify the merchant in dashboard and reports."
},
"email": {
"type": "string",
"description": "Admin email of the merchant, used for login and critical communication."
}
}
},
"MerchantAuthRegisterResponse": {
"required": [
"merchantToken"
],
"type": "object",
"properties": {
"merchantToken": {
"maxLength": 128,
"minLength": 1,
"type": "string",
"description": "Merchant identifier used to register merchant."
}
}
},
"MerchantPricingRequestStatusEnum": {
"enum": [
1,
2,
3
],
"description": "Allowed values:\n - 1 = Pending (Awaiting resolution (ops review when requiresApproval is true).)\n - 2 = Approved (Approved — indicativeRates are final when requiresApproval was false at submission.)\n - 3 = Rejected (Rejected by Tapaya ops.)\n",
"x-enum-varnames": [
"Pending",
"Approved",
"Rejected"
]
},
"MoneyResponse": {
"required": [
"amount",
"currency"
],
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Amount in minor currency units.",
"format": "int64"
},
"currency": {
"description": "Currency.",
"$ref": "#/components/schemas/CurrencyEnum"
}
}
},
"OfficialIdTypeEnum": {
"enum": [
1,
2,
3,
4,
5,
6
],
"type": "integer",
"description": "Allowed values:\n - 1 = Passport (Passport travel document.)\n - 2 = IdentityCard (National identity card.)\n - 3 = DriverLicense (Driver's license.)\n - 4 = ResidencePermit (Residence permit.)\n - 5 = Asylum (Asylum seeker document.)\n - 6 = Other (Other official document.)\n",
"x-enum-varnames": [
"Passport",
"IdentityCard",
"DriverLicense",
"ResidencePermit",
"Asylum",
"Other"
]
},
"PaymentMethodEnum": {
"enum": [
1,
2,
3,
4
],
"type": "integer",
"description": "Allowed values:\n - 1 = Card (Card)\n - 2 = SepaIct (SEPA Instant Credit Transfer)\n - 3 = CertisCz (CERTIS Czech Instant Transfer)\n - 4 = Crypto (Cryptocurrency Transfer)\n",
"x-enum-varnames": [
"Card",
"SepaIct",
"CertisCz",
"Crypto"
]
},
"PaymentMethodStatus": {
"required": [
"method",
"processor",
"onboarded",
"allowed",
"ready",
"reason"
],
"type": "object",
"properties": {
"method": {
"description": "Payment method type (e.g., card, bank transfer).",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"processor": {
"description": "The payment processor to use.",
"$ref": "#/components/schemas/PaymentProcessorEnum"
},
"onboarded": {
"type": "boolean",
"description": "True if onboarding was sent to the processor."
},
"allowed": {
"type": "boolean",
"description": "True if payment method is allowed for this merchant."
},
"ready": {
"type": "boolean",
"description": "True if payment method can be used to create a transaction now."
},
"reason": {
"description": "Detailed reason for payment method status.",
"$ref": "#/components/schemas/PaymentMethodStatusEnum"
}
}
},
"PaymentMethodStatusEnum": {
"enum": [
1,
2,
3,
4,
5,
6,
7,
8
],
"type": "integer",
"description": "Allowed values:\n - 1 = Ok (No problem, payment method allowed)\n - 2 = KybRequired (KYB details are required for operation)\n - 3 = KybDueSoon (Additional KYB details should be filled in soon, but are not required now)\n - 4 = BlockedProcessor (Account blocked by the payment processor)\n - 5 = BlockedTapaya (Account blocked by Tapaya)\n - 6 = WaitingForKyb (Processor is waiting for KYB document submission)\n - 7 = WaitingForStakeholders (Processor is waiting for stakeholder data or verification)\n - 8 = PendingAcquirerApproval (Submitted to acquirer, pending their approval)\n",
"x-enum-varnames": [
"Ok",
"KybRequired",
"KybDueSoon",
"BlockedProcessor",
"BlockedTapaya",
"WaitingForKyb",
"WaitingForStakeholders",
"PendingAcquirerApproval"
]
},
"PaymentProcessorEnum": {
"enum": [
1,
2,
3,
4,
5
],
"type": "integer",
"description": "Allowed values:\n - 1 = Tapaya (Tapaya)\n - 2 = Stripe (Stripe)\n - 3 = Finbricks (Finbricks)\n - 4 = Confirmo (Confirmo)\n - 5 = SwitchioShift4 (Shift4)\n",
"x-enum-varnames": [
"Tapaya",
"Stripe",
"Finbricks",
"Confirmo",
"SwitchioShift4"
]
},
"PayoutDestinationResponse": {
"type": "object",
"properties": {
"bankAccountLast4": {
"type": [
"null",
"string"
],
"description": "Last 4 digits of the bank account number."
},
"bankName": {
"type": [
"null",
"string"
],
"description": "Name of the bank."
}
}
},
"PayoutDetails": {
"required": [
"amount",
"currencyId"
],
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Amount in minor currency units.",
"format": "int64"
},
"currencyId": {
"description": "ISO 4217 numeric currency code.",
"$ref": "#/components/schemas/CurrencyEnum"
}
}
},
"PayoutIntervalEnum": {
"enum": [
0,
1,
2,
3,
4
],
"type": "integer",
"description": "Allowed values:\n - 0 = Unknown (Interval could not be determined.)\n - 1 = Manual (Payouts are triggered manually.)\n - 2 = Daily (Payouts are sent daily.)\n - 3 = Weekly (Payouts are sent weekly.)\n - 4 = Monthly (Payouts are sent monthly.)\n",
"x-enum-varnames": [
"Unknown",
"Manual",
"Daily",
"Weekly",
"Monthly"
]
},
"PayoutMethodEnum": {
"enum": [
0,
1,
2
],
"type": "integer",
"description": "Allowed values:\n - 0 = Unknown (Method could not be determined.)\n - 1 = Standard (Standard payout timing.)\n - 2 = Instant (Expedited/instant payout.)\n",
"x-enum-varnames": [
"Unknown",
"Standard",
"Instant"
]
},
"PayoutScheduleResponse": {
"required": [
"interval",
"delayDays"
],
"type": "object",
"properties": {
"interval": {
"description": "Payout interval (e.g., daily, weekly, monthly).",
"$ref": "#/components/schemas/PayoutIntervalEnum"
},
"delayDays": {
"type": "integer",
"description": "Number of days delay before payout is sent.",
"format": "int32"
}
}
},
"PayoutStateResponse": {
"required": [
"balance",
"payoutSchedule",
"recentPayouts"
],
"type": "object",
"properties": {
"balance": {
"description": "Current processor balance.",
"$ref": "#/components/schemas/BalanceResponse"
},
"payoutSchedule": {
"description": "Configured payout schedule.",
"$ref": "#/components/schemas/PayoutScheduleResponse"
},
"destination": {
"oneOf": [
{
"type": "null"
},
{
"description": "Payout destination bank account details.",
"$ref": "#/components/schemas/PayoutDestinationResponse"
}
]
},
"recentPayouts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RecentPayoutResponse"
},
"description": "List of recent payouts."
},
"lastPayout": {
"oneOf": [
{
"type": "null"
},
{
"description": "Most recent payout details.",
"$ref": "#/components/schemas/LastPayoutResponse"
}
]
}
}
},
"PayoutStatusEnum": {
"enum": [
0,
1,
2,
3,
4,
5
],
"type": "integer",
"description": "Allowed values:\n - 0 = Unknown (Status could not be determined.)\n - 1 = Paid (Payout has been paid out.)\n - 2 = Pending (Payout is pending.)\n - 3 = InTransit (Payout is in transit to its destination.)\n - 4 = Failed (Payout failed.)\n - 5 = Canceled (Payout was canceled.)\n",
"x-enum-varnames": [
"Unknown",
"Paid",
"Pending",
"InTransit",
"Failed",
"Canceled"
]
},
"PersonInformation": {
"required": [
"email"
],
"type": "object",
"properties": {
"firstName": {
"maxLength": 100,
"type": [
"null",
"string"
],
"description": "The first name of the person."
},
"lastName": {
"maxLength": 100,
"type": [
"null",
"string"
],
"description": "The last name of the person."
},
"email": {
"maxLength": 255,
"type": "string",
"description": "The email address of the person. Always required."
},
"phone": {
"maxLength": 20,
"type": [
"null",
"string"
],
"description": "The phone number of the person.\n
\nRequired for Individual business type and Representative role."
},
"dateOfBirth": {
"type": [
"null",
"string"
],
"description": "The date of birth of the person.",
"format": "date"
},
"nationalityCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "The nationality of the person.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"address": {
"oneOf": [
{
"type": "null"
},
{
"description": "Person residence address.",
"$ref": "#/components/schemas/AddressInformation"
}
]
},
"placeOfBirthCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Country of birth. Used for Shift4 submission (converted to ISO 3166-1 alpha-3 at the connector boundary).",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"officialIdType": {
"oneOf": [
{
"type": "null"
},
{
"description": "Official ID type (Passport, ID Card, Driver's license). Used for Shift4 submission.",
"$ref": "#/components/schemas/OfficialIdTypeEnum"
}
]
},
"officialIdNumber": {
"type": [
"null",
"string"
],
"description": "Official document number. Used for Shift4 submission."
},
"officialIdExpiryDate": {
"type": [
"null",
"string"
],
"description": "Expiry date of the official ID. Required when OfficialIdTypeEnum? PersonInformation.OfficialIdType is `Passport`.",
"format": "date"
},
"passportPlaceOfIssue": {
"maxLength": 100,
"type": [
"null",
"string"
],
"description": "Place of issue of the passport. Required when OfficialIdTypeEnum? PersonInformation.OfficialIdType is `Passport`."
},
"role": {
"oneOf": [
{
"type": "null"
},
{
"description": "The role of the person within the organization.\n
\nRequired only for Company business type.",
"$ref": "#/components/schemas/PersonRole"
}
]
},
"title": {
"maxLength": 100,
"type": [
"null",
"string"
],
"description": "The title or designation of the person.\n
\nRequired for Representative and Director roles."
},
"ownershipPercentage": {
"type": [
"null",
"number"
],
"description": "The percentage of ownership the person has in the company. Required if IsOwner is true.",
"format": "double"
},
"verificationDocuments": {
"oneOf": [
{
"type": "null"
},
{
"description": "Verification documents for identity verification",
"$ref": "#/components/schemas/PersonVerificationDocuments"
}
]
}
},
"description": "Represents personal information about an individual, including their name, contact details,\ndate of birth, and address."
},
"PersonPayload": {
"required": [
"email"
],
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of the person."
},
"firstName": {
"type": [
"null",
"string"
],
"description": "First name."
},
"lastName": {
"type": [
"null",
"string"
],
"description": "Last name."
},
"phone": {
"type": [
"null",
"string"
],
"description": "Phone number."
},
"dateOfBirth": {
"type": [
"null",
"string"
],
"description": "Date of birth.",
"format": "date"
},
"nationalityCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Nationality country.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"placeOfBirthCountryId": {
"oneOf": [
{
"type": "null"
},
{
"description": "Country of birth.",
"$ref": "#/components/schemas/CountryEnum"
}
]
},
"officialIdType": {
"oneOf": [
{
"type": "null"
},
{
"description": "Type of official identity document.",
"$ref": "#/components/schemas/OfficialIdTypeEnum"
}
]
},
"officialIdNumber": {
"type": [
"null",
"string"
],
"description": "Official identity document number."
},
"officialIdExpiryDate": {
"type": [
"null",
"string"
],
"description": "Expiry date of the official identity document.",
"format": "date"
},
"passportPlaceOfIssue": {
"type": [
"null",
"string"
],
"description": "Place of issue for passport."
},
"address": {
"oneOf": [
{
"type": "null"
},
{
"description": "Residential address.",
"$ref": "#/components/schemas/AddressObjectPayload"
}
]
},
"role": {
"oneOf": [
{
"type": "null"
},
{
"description": "Role(s) within the company.",
"$ref": "#/components/schemas/RolePayload"
}
]
},
"title": {
"type": [
"null",
"string"
],
"description": "Job title."
},
"ownershipPercentage": {
"type": [
"null",
"number"
],
"description": "Ownership percentage (0–100).",
"format": "double"
},
"verificationDocuments": {
"oneOf": [
{
"type": "null"
},
{
"description": "Identity verification documents.",
"$ref": "#/components/schemas/VerificationDocumentsPayload"
}
]
}
}
},
"PersonRole": {
"required": [
"isOwner",
"isRepresentative",
"isDirector"
],
"type": "object",
"properties": {
"isOwner": {
"type": "boolean",
"description": "Individual owning 25% or more of a company."
},
"isRepresentative": {
"type": "boolean",
"description": "Person nominated to represent the organization. Must be a beneficial owner\n(person owning 25% or more of a company or having significant control over it)\nauthorized to sign for the company."
},
"isDirector": {
"type": "boolean",
"description": "Individual who is a member of the governing board of a company."
},
"isAuthorizedSignatory": {
"type": "boolean",
"description": "Designates the person as the merchant's authorized signatory for processor onboarding\nagreements."
}
},
"description": "Information about various roles a person can have within an organization."
},
"PersonVerificationDocuments": {
"type": "object",
"properties": {
"identityDocument": {
"oneOf": [
{
"type": "null"
},
{
"description": "Primary identity document (e.g., passport, driver's license)",
"$ref": "#/components/schemas/DocumentReference"
}
]
},
"additionalDocument": {
"oneOf": [
{
"type": "null"
},
{
"description": "Additional document for address verification",
"$ref": "#/components/schemas/DocumentReference"
}
]
}
},
"description": "Contains document references for person verification"
},
"PricingCardTypeEnum": {
"enum": [
1,
2,
3,
4,
5
],
"type": "integer",
"description": "Card interchange tier for MCC pricing lookup. Standard is used for non-card payment methods.\nAllowed values:\n - 1 = ConsumerEea (Consumer card, EEA issuer.)\n - 2 = ConsumerNonEea (Consumer card, non-EEA issuer.)\n - 3 = CommercialEea (Commercial card, EEA issuer.)\n - 4 = CommercialNonEea (Commercial card, non-EEA issuer.)\n - 5 = Standard (Non-card payment methods (SEPA, CertisCz, Crypto).)\n",
"x-enum-varnames": [
"ConsumerEea",
"ConsumerNonEea",
"CommercialEea",
"CommercialNonEea",
"Standard"
]
},
"ProcessorStatus": {
"required": [
"processorId",
"registered",
"chargesEnabled",
"payoutsEnabled",
"pastDueRequirements"
],
"type": "object",
"properties": {
"processorId": {
"description": "Payment processor this status applies to.",
"$ref": "#/components/schemas/PaymentProcessorEnum"
},
"processorMerchantId": {
"type": [
"null",
"string"
],
"description": "Merchant account identifier on the processor side; null if not yet registered."
},
"registered": {
"type": "boolean",
"description": "True if the merchant has been registered with this processor."
},
"chargesEnabled": {
"type": "boolean",
"description": "True if charges are currently enabled on this processor account."
},
"payoutsEnabled": {
"type": "boolean",
"description": "True if payouts are currently enabled on this processor account."
},
"pastDueRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requirements that are past-due and blocking the account; empty when none are due."
},
"rejectedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "Timestamp when onboarding was rejected by the processor.",
"$ref": "#/components/schemas/Instant"
}
]
},
"rejectedMsg": {
"type": [
"null",
"string"
],
"description": "Processor rejection message."
},
"registeredAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "Timestamp when merchant creation with this processor was last confirmed successful; null if not yet registered.",
"$ref": "#/components/schemas/Instant"
}
]
}
}
},
"PublicExceptionPayload": {
"required": [
"message",
"errorCode"
],
"type": "object",
"properties": {
"message": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"errors": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/ValidationFieldError"
}
}
}
},
"RecentPayoutResponse": {
"required": [
"id",
"amount",
"currency",
"status",
"method",
"created"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Processor payout identifier."
},
"amount": {
"type": "integer",
"description": "Payout amount in minor currency units.",
"format": "int64"
},
"currency": {
"description": "Payout currency.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"status": {
"description": "Current payout status.",
"$ref": "#/components/schemas/PayoutStatusEnum"
},
"arrivalDate": {
"oneOf": [
{
"type": "null"
},
{
"description": "Expected arrival date.",
"$ref": "#/components/schemas/Instant"
}
]
},
"method": {
"description": "Payout method (standard or instant).",
"$ref": "#/components/schemas/PayoutMethodEnum"
},
"created": {
"description": "UTC timestamp when the payout was created.",
"$ref": "#/components/schemas/Instant"
},
"failureCode": {
"type": [
"null",
"string"
],
"description": "Failure code if the payout failed."
},
"failureMessage": {
"type": [
"null",
"string"
],
"description": "Human-readable failure message."
}
}
},
"RefundReasonEnum": {
"enum": [
1,
2,
3,
4
],
"type": "integer",
"description": "Allowed values:\n - 1 = CustomerRequest (Refunded at the customer's request.)\n - 2 = Duplicate (Refunded because the charge was a duplicate of another transaction.)\n - 3 = Fraudulent (Refunded because the charge was identified as fraudulent.)\n - 4 = ExpiredCharge (Refunded because the authorization or charge had expired.)\n",
"x-enum-varnames": [
"CustomerRequest",
"Duplicate",
"Fraudulent",
"ExpiredCharge"
]
},
"RegistrationInvitesGetResponse": {
"required": [
"inviteId",
"invitedEmail",
"isOrgAdmin",
"createdAt",
"expiresAt",
"commissionProfileId"
],
"type": "object",
"properties": {
"inviteId": {
"type": "string",
"description": "Unique invite identifier.",
"format": "uuid"
},
"invitedEmail": {
"type": "string",
"description": "Email address the invite was sent to."
},
"isOrgAdmin": {
"type": "boolean",
"description": "Whether the invited user will become an org admin."
},
"createdAt": {
"description": "When the invite was created.",
"$ref": "#/components/schemas/Instant"
},
"expiresAt": {
"description": "When the invite token expires.",
"$ref": "#/components/schemas/Instant"
},
"usedAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "When the invite was accepted, or null if still pending.",
"$ref": "#/components/schemas/Instant"
}
]
},
"inviteUrl": {
"type": [
"null",
"string"
],
"description": "Full invite URL sent in the email, or null for legacy hash-only invites."
},
"commissionProfileId": {
"type": "string",
"description": "Commission profile assigned when this invite is completed.",
"format": "uuid"
}
}
},
"ReusableRegistrationInvitePostRequest": {
"required": [
"name",
"expiresAt"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name for the invite link."
},
"expiresAt": {
"description": "When the invite link stops working. Must be between 1 day and 2 months from now (inclusive).",
"$ref": "#/components/schemas/Instant"
},
"commissionProfileId": {
"type": [
"null",
"string"
],
"description": "Optional commission profile to assign when registrations complete via this link.\nWhen omitted, the organization default is used.",
"format": "uuid"
}
}
},
"ReusableRegistrationInvitesGetResponse": {
"required": [
"inviteId",
"name",
"registrationUrl",
"createdAt",
"expiresAt",
"commissionProfileId"
],
"type": "object",
"properties": {
"inviteId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"registrationUrl": {
"type": "string"
},
"createdAt": {
"$ref": "#/components/schemas/Instant"
},
"expiresAt": {
"$ref": "#/components/schemas/Instant"
},
"revokedAt": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/Instant"
}
]
},
"commissionProfileId": {
"type": "string",
"format": "uuid"
}
}
},
"RolePayload": {
"type": "object",
"properties": {
"isOwner": {
"type": "boolean",
"description": "Person owns at least 25% of company shares (UBO)."
},
"isDirector": {
"type": "boolean",
"description": "Member of company board of directors."
},
"isAuthorizedSignatory": {
"type": "boolean",
"description": "Person can legally sign contracts; at least one must be present."
},
"isRepresentative": {
"type": "boolean",
"description": "Primary contact of the company."
}
}
},
"SendRegistrationInvitePostRequest": {
"required": [
"email"
],
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address to send the registration / KYC link to."
},
"merchantToken": {
"maxLength": 128,
"minLength": 1,
"type": [
"null",
"string"
],
"description": "Optional merchant token of an existing shell merchant. When set, completing the invite\nonboards that merchant instead of creating a duplicate."
}
}
},
"SendRegistrationInvitePostResponse": {
"required": [
"registrationUrl"
],
"type": "object",
"properties": {
"registrationUrl": {
"type": "string",
"description": "Registration URL to share with or email to the invitee (also sent by email when delivery succeeds)."
}
}
},
"StatsByBrand": {
"required": [
"brand",
"count",
"volume"
],
"type": "object",
"properties": {
"brand": {
"type": "string",
"description": "Card brand (e.g. Visa, Mastercard)."
},
"count": {
"type": "integer",
"description": "Number of transactions with this brand.",
"format": "int32"
},
"volume": {
"type": "integer",
"description": "Total volume in minor currency units.",
"format": "int64"
}
}
},
"StatsByOperatingSystem": {
"required": [
"operatingSystem",
"currencyId",
"count",
"volume"
],
"type": "object",
"properties": {
"operatingSystem": {
"type": "string",
"description": "Operating system name."
},
"currencyId": {
"description": "ISO 4217 numeric currency code.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"count": {
"type": "integer",
"description": "Number of transactions from this operating system.",
"format": "int32"
},
"volume": {
"type": "integer",
"description": "Total volume in minor currency units.",
"format": "int64"
}
}
},
"StatsByPaymentMethod": {
"required": [
"paymentMethod",
"currencyId",
"count",
"volume"
],
"type": "object",
"properties": {
"paymentMethod": {
"description": "Payment method type.",
"$ref": "#/components/schemas/PaymentMethodEnum"
},
"currencyId": {
"description": "ISO 4217 numeric currency code.",
"$ref": "#/components/schemas/CurrencyEnum"
},
"count": {
"type": "integer",
"description": "Number of transactions with this payment method.",
"format": "int32"
},
"volume": {
"type": "integer",
"description": "Total volume in minor currency units.",
"format": "int64"
}
}
},
"StatusEnum": {
"enum": [
1,
2,
3,
4,
5,
6
],
"type": "integer",
"description": "Allowed values:\n - 1 = Pending (Transaction has been created but not yet finalized.)\n - 2 = Success (Transaction completed successfully.)\n - 3 = Cancelled (Transaction was cancelled before completion.)\n - 4 = Refunded (Transaction was refunded after completion.)\n - 5 = Failed (Transaction failed to complete.)\n - 6 = ActionNeeded (Transaction requires further customer action to complete.)\n",
"x-enum-varnames": [
"Pending",
"Success",
"Cancelled",
"Refunded",
"Failed",
"ActionNeeded"
]
},
"TerminalStatResponse": {
"required": [
"terminalId",
"label",
"transactionCount",
"volume",
"failureRate",
"lastSeenAt"
],
"type": "object",
"properties": {
"terminalId": {
"type": "string",
"description": "Terminal ID.",
"format": "uuid"
},
"label": {
"type": "string",
"description": "Human-readable label derived from device brand/model, or processor reader ID, or terminal ID."
},
"transactionCount": {
"type": "integer",
"description": "Total transaction count in the window (all statuses).",
"format": "int32"
},
"volume": {
"description": "Successful transaction volume in the window.",
"$ref": "#/components/schemas/TerminalVolumeResponse"
},
"failureRate": {
"type": "number",
"description": "Failure rate as a percentage (0–100) in the window. 0 if no transactions.",
"format": "double"
},
"lastSeenAt": {
"oneOf": [
{
"type": "null"
},
{
"description": "Most recent payment at this terminal (all-time). Null if terminal has never processed a payment.",
"$ref": "#/components/schemas/Instant"
}
]
}
}
},
"TerminalVolumeResponse": {
"required": [
"amount",
"currency"
],
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Amount in minor currency units.",
"format": "int64"
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code."
}
}
},
"TokenItem": {
"required": [
"apiTokenId",
"token",
"name",
"createdAt"
],
"type": "object",
"properties": {
"apiTokenId": {
"type": "string",
"description": "Unique API token identifier.",
"format": "uuid"
},
"token": {
"type": "string",
"description": "The API key token value."
},
"name": {
"type": "string",
"description": "Human-readable label for the API key."
},
"createdAt": {
"type": "string",
"description": "UTC timestamp when the API key was created.",
"format": "date-time"
}
}
},
"TotalRevenue": {
"required": [
"amount",
"currencyId"
],
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Total revenue amount in minor currency units.",
"format": "int64"
},
"currencyId": {
"description": "ISO 4217 numeric currency code.",
"$ref": "#/components/schemas/CurrencyEnum"
}
}
},
"TransactionStats": {
"required": [
"successful",
"failed"
],
"type": "object",
"properties": {
"successful": {
"type": "integer",
"description": "Number of successful transactions.",
"format": "int32"
},
"failed": {
"type": "integer",
"description": "Number of failed transactions.",
"format": "int32"
}
}
},
"ValidationError": {
"required": [
"step",
"field",
"message"
],
"type": "object",
"properties": {
"step": {
"type": "string",
"description": "Onboarding step where the error occurred (e.g. \"identity\", \"address\")."
},
"field": {
"type": "string",
"description": "Field name that failed validation."
},
"message": {
"type": "string",
"description": "Human-readable error message."
},
"code": {
"type": [
"null",
"string"
],
"description": "Machine-readable error code."
}
}
},
"ValidationFieldError": {
"required": [
"field",
"message"
],
"type": "object",
"properties": {
"field": {
"type": "string"
},
"message": {
"type": "string"
},
"code": {
"type": [
"null",
"string"
]
}
}
},
"VerificationDocumentsPayload": {
"type": "object",
"properties": {
"identityDocument": {
"oneOf": [
{
"type": "null"
},
{
"description": "Primary identity document (passport, national ID).",
"$ref": "#/components/schemas/DocumentReferencePayload"
}
]
},
"additionalDocument": {
"oneOf": [
{
"type": "null"
},
{
"description": "Additional supporting document.",
"$ref": "#/components/schemas/DocumentReferencePayload"
}
]
}
}
}
},
"securitySchemes": {
"ApiTokenScheme": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
}
},
"tags": [
{
"name": "Integrator/Merchant"
},
{
"name": "Integrator/Organization"
},
{
"name": "Merchant"
}
],
"externalDocs": {
"description": "Integration documentation",
"url": "https://docs.tapaya.com"
}
}