{ "openapi": "3.0.0", "info": { "title": "GrailPay ACH API", "description": "API Documentation for moving funds via ACH using the GrailPay ACH API", "version": "2026.7.3.1" }, "servers": [ { "url": "https://api.grailpay.com", "description": "Production environment" }, { "url": "https://api-sandbox.grailpay.com", "description": "Sandbox environment" } ], "paths": { "/3p/api/v2/bank-accounts/validate": { "post": { "tags": [ "Bank Accounts", "Sunsetting" ], "summary": "Validate bank account and routing number ( SUNSETTING ) ", "description": "This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.", "operationId": "90011ab04f4c7e2d262cd935907844be", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreAccountValidationRequest" } } } }, "responses": { "200": { "description": "Successful Validation", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Validation processed successfully" }, "data": { "properties": { "uuid": { "type": "string" }, "account_number": { "type": "string" }, "routing_number": { "type": "string" }, "version": { "type": "string" }, "validity": { "type": "boolean" }, "validated_at": { "type": "string", "format": "date-time" }, "risk_score": { "type": "number", "nullable": true }, "confidence_level": { "type": "string", "nullable": true } }, "type": "object" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/users/{uuid}/bank-accounts": { "get": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Get all bank accounts for a user ( STABLE )", "description": "This API retrieves a list of all bank accounts associated with a business or person. The response includes details such as the account number, routing number, account holder's name, account type, and other relevant information.", "operationId": "aa53b1626c4d40ac8b45bf1b58a7e9bb", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/V2BankAccountResponse" }, "example": [ { "uuid": "f7a809c8-1987-4627-b1ab-885550cbbb5a", "user_uuid": "f7a809c8-1987-4627-b1ab-885550cbbb5a", "account_number": "12345678901234", "routing_number": "056008849", "account_name": "Jack Jones", "account_type": "savings", "aggregator_type": "manual", "created_at": "2023-10-16 16:19:42", "is_default": true }, { "uuid": "9abaa7dc-b31d-4fdf-b8a5-e62c8a582c9b", "user_uuid": "f7a809c8-1987-4627-b1ab-885550cbbb5a", "account_number": "1111222233330000", "routing_number": "011401533", "account_name": "Jack Jones", "account_type": "savings", "aggregator_type": "plaid", "created_at": "2023-11-29 13:31:48", "is_default": false } ] }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User not found" }, "data": { "type": "string", "example": null }, "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "properties": { "type": { "type": "string", "example": "client_error" }, "subType": { "type": "string", "example": "uuid_not_found" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "Bank Accounts", "Sunsetting" ], "summary": "Add a new bank account for a user ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "3c7f3c98a31812120bf7b1f038974204", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2AddBankAccountRequest" } } } }, "responses": { "200": { "description": "Bank account added successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Bank account added successfully" }, "data": { "$ref": "#/components/schemas/V2BankAccountResponse" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User delete in progress" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not found" }, "data": { "type": "string", "example": null }, "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "properties": { "type": { "type": "string", "example": "client_error" }, "subType": { "type": "string", "example": "uuid_not_found" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/bank-accounts/{aggregator_type}/{account_uuid}": { "delete": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Delete a bank account ( STABLE )", "description": "Deletes a bank account by its UUID and aggregator type.", "operationId": "bb462670bab153c5c2fe9f0d31b5c937", "parameters": [ { "name": "aggregator_type", "in": "path", "description": "The type of the bank aggregator", "required": true, "schema": { "type": "string", "enum": [ "plaid", "manual", "bank_link" ] } }, { "name": "account_uuid", "in": "path", "description": "The UUID of the bank account", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bank account deleted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Bank account deleted successfully" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User delete in progress" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Bank account not found" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/users/{uuid}/bank-accounts/{account_uuid}/balance": { "get": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Fetch the bank account balance ( STABLE )", "description": "Fetch the balance of a specific bank account for a user.", "operationId": "7d87d929ac9d7a1fa16bb5e7b0460fea", "parameters": [ { "$ref": "#/components/parameters/UserUuidPathParam" }, { "$ref": "#/components/parameters/BankAccountUuidPathParam" }, { "name": "billing_merchant_user_uuid", "in": "query", "description": "Billing Merchant User UUID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "billing_processor_mid", "in": "query", "description": "Billing Processor MID", "required": false, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "available_balance": { "description": "Available balance in the bank account", "type": "integer", "example": 25425 } }, "type": "object" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "404": { "description": "User Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserNotFound" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The bank account is not a valid provider." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "403": { "description": "Invalid account type", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "" }, "data": { "type": "string", "example": "Only a bank account connected through GrailPay's bank link widget can provide access to the account balance" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "406": { "description": "Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The requested billing merchant user uuid does not exist." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "503": { "description": "Failed to retrieve bank account balance", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "We are unable to fetch the account balance" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/bank-accounts/{aggregator_type}/{account_uuid}/history": { "get": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Fetch the transaction history for a bank account. ( STABLE )", "description": "Fetch a list of transactions for a bank account. This currently only works with accounts linked through the Bank Link SDK.", "operationId": "8b25d4591b8089f95e78e09e9a3f6756", "parameters": [ { "name": "aggregator_type", "in": "path", "description": "Bank Account Provider. Possible Values: bank_link. Supports both MoneyKit and Quiltt provider types.", "required": true, "schema": { "type": "string", "enum": [ "bank_link" ] } }, { "$ref": "#/components/parameters/BankAccountUuidPathParam" }, { "name": "page", "in": "query", "description": "Page number for page-based pagination. (MoneyKit only)", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page. (Both providers)", "required": false, "schema": { "type": "integer", "example": 15 } }, { "name": "start_date", "in": "query", "description": "Start date filter (Y-m-d format). Must be before or equal to end_date. (Both providers)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "end_date", "in": "query", "description": "End date filter (Y-m-d format). Must be after or equal to start_date. (Both providers)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-12-31" } }, { "name": "cursor", "in": "query", "description": "Cursor for cursor-based pagination. (Quiltt only)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction history fetched successfully. Response format varies by provider (Quiltt or MoneyKit).", "content": { "application/json": { "schema": { "oneOf": [ { "title": "MoneyKit Provider Response", "description": "Response when the bank account uses the MoneyKit provider. Uses page-based pagination.", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": null }, "data": { "properties": { "transactions": { "type": "array", "items": { "properties": { "transaction_id": { "type": "string", "example": "c7318ff7-257c-490e-8242-03a815b223b7" }, "account_id": { "type": "string", "example": "acc_6Tef269B6ZArSVpYrxtjBV" }, "amount": { "type": "number", "format": "float", "example": 384.05 }, "type": { "type": "string", "example": "debit" }, "currency": { "type": "string", "example": "USD" }, "date": { "type": "string", "example": "2023-02-16T00:00:00" }, "datetime": { "type": "string", "example": "2023-02-16T09:14:11" }, "description": { "type": "string", "example": "Regina's Mulberry" }, "raw_description": { "type": "string", "example": "Regina's Mulberry #1402 T48999-84" }, "pending": { "type": "boolean", "example": true }, "enrichment": { "properties": { "category": { "properties": { "value": { "type": "string", "example": "food_and_drink" }, "confidence": { "type": "integer", "example": 99 } }, "type": "object" }, "subcategory": { "properties": { "value": { "type": "string", "example": "coffee" }, "confidence": { "type": "integer", "example": 99 } }, "type": "object" }, "merchant": { "properties": { "id": { "type": "string", "example": "a0822a4f-a59b-4fc9-a768-d880da5bd090" }, "name": { "type": "string", "example": "Starbucks" }, "logo": { "type": "string", "example": "https://example.com/starbucks.png" }, "confidence": { "type": "integer", "example": 99 } }, "type": "object" }, "processor": { "properties": { "id": { "type": "string", "example": "a0822a4f-a59b-4fc9-a768-d880da5bd090" }, "name": { "type": "string", "example": "Square" }, "logo": { "type": "string", "example": "https://example.com/square.png" }, "confidence": { "type": "integer", "example": 99 } }, "type": "object" }, "recurrence": { "properties": { "frequency": { "type": "string", "example": "monthly" }, "next_predicted_date": { "type": "string", "example": "2024-08-03" } }, "type": "object" } }, "type": "object" }, "original_id": { "type": "string", "example": "" } }, "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 5 }, "total_items": { "type": "integer", "example": 50 }, "per_page": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" }, "errors": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, { "title": "Quiltt Provider Response", "description": "Response when the bank account uses the Quiltt (bank-link) provider. Uses cursor-based pagination.", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": null }, "data": { "properties": { "transactions": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "txn_abc123" }, "amount": { "type": "number", "format": "float", "example": -25.5 }, "currency_code": { "type": "string", "example": "USD" }, "date": { "type": "string", "format": "date", "example": "2024-06-15" }, "description": { "type": "string", "example": "Amazon Purchase" }, "entry_type": { "type": "string", "example": "DEBIT" }, "fees": { "type": "number", "format": "float", "example": null, "nullable": true }, "kind": { "type": "string", "example": "DEPOSITORY" }, "metadata": { "type": "object", "example": null, "nullable": true }, "price": { "type": "number", "format": "float", "example": null, "nullable": true }, "provider": { "type": "string", "example": "quiltt" }, "quantity": { "type": "number", "format": "float", "example": null, "nullable": true }, "status": { "type": "string", "example": "POSTED" }, "merchant_name": { "type": "string", "example": "Amazon", "nullable": true } }, "type": "object" } }, "pagination": { "properties": { "total_items": { "type": "integer", "example": 150 }, "page_size": { "type": "integer", "example": 15 }, "has_next_page": { "type": "boolean", "example": true }, "has_previous_page": { "type": "boolean", "example": false }, "start_cursor": { "type": "string", "example": "cursor_abc123", "nullable": true }, "next_cursor": { "type": "string", "example": "cursor_def456", "nullable": true } }, "type": "object" } }, "type": "object" }, "errors": { "type": "array", "items": { "type": "string" }, "example": null } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden - Multiple Reasons", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Unable to Fetch History", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "We are unable to retrieve the transaction history for this bank account." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, { "title": "Invalid Aggregator Type", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Only a bank account connected through GrailPay's bank link widget can provide access to the transaction history." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, { "title": "History Disabled", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Fetching transaction history from this bank account is disabled." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } ] } } } }, "404": { "description": "Bank Account Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The bank account was not found." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/businesses": { "post": { "tags": [ "Users", "Sunsetting" ], "summary": "Onboard a new Business or Merchant into the ACH application ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "7c551c8aa54cc5588db347b998a46df2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "kyb", "client_reference_id", "first_name", "last_name", "email", "phone", "business" ], "properties": { "kyb": { "type": "boolean", "example": true }, "client_reference_id": { "type": "string", "example": "123456" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "example": "test@example.org" }, "phone": { "type": "string", "example": "1234567890" }, "business": { "$ref": "#/components/schemas/Business" }, "business_owners": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessOwner" } }, "bank_account": { "$ref": "#/components/schemas/V2BankAccountRequest" }, "billing_merchant_user_uuid": { "type": "string", "format": "uuid", "example": "2bcf2ac3-38fc-4238-a638-4f092821fc27", "nullable": true }, "billing_processor_mid": { "type": "string", "example": "21245678932", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Business registered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2OnboardBusinessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error400" }, { "$ref": "#/components/schemas/Error400InvalidAcceptHeader" }, { "$ref": "#/components/schemas/Error400InvalidPlaidAccount" }, { "$ref": "#/components/schemas/Error400UnverifiedPlaidAccount" }, { "$ref": "#/components/schemas/Error400InvalidRoutingNumber" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401UnauthorizedProcessor" } ] } } } }, "409": { "description": "Idempotency Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error409" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null }, "errors": { "$ref": "#/components/schemas/BusinessValidationError" }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/users/{uuid}/kyb": { "post": { "tags": [ "Users", "Sunsetting" ], "summary": "Update Business KYB ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "7acac74adaf5357356a4a694430fe2f2", "parameters": [ { "$ref": "#/components/parameters/UserUuidPathParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBusinessKybRequest" } } } }, "responses": { "200": { "description": "Business Successfully updated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "The business KYB has been updated." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid token." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Only business users are allowed to update KYB." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not found." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "406": { "description": "Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The requested billing merchant user uuid does not exist." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "string", "example": null }, "errors": { "properties": { "first_name": { "type": "array", "items": { "type": "string", "example": "The tin is required." } } }, "type": "object" }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/merchants/{uuid}/billing": { "get": { "tags": [ "Billing", "Stable" ], "summary": "Get Billing by Merchant User UUID ( STABLE )", "description": "This retrieves a summary of all billed events for a specific merchant, providing comprehensive billing details to support seamless integration.", "operationId": "6fdcd5190b6f97e4184ab8e1c4ae9464", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the merchant user", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "description": "Start date for billing summary (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "End date for billing summary (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "summary": { "type": "array", "items": { "properties": { "billable_event": { "type": "string", "example": "Standard ACH" }, "total": { "type": "integer", "example": 1500 }, "total_occurrences": { "type": "integer", "example": 150 }, "amount_per_occurrence": { "type": "integer", "example": 10 } }, "type": "object" } } }, "type": "object" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The merchant was not found." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-payouts/business/{business_user_uuid}/{batch_payout_uuid}": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "Get Business Batch Payout ( STABLE )", "description": "This API retrieves the details of a business batch payout using the business user UUID and the unique batch payout UUID. The response provides comprehensive information about the payout, including the total amount and a detailed breakdown of the transactions.", "operationId": "bd558a7871e19f327103e3d8c3811064", "parameters": [ { "name": "business_user_uuid", "in": "path", "description": "UUID of the business user", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "batch_payout_uuid", "in": "path", "description": "UUID of the batch payout", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Business batch payout details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PayeeBatchPayoutResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Business not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Business Batch Payout not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-payouts/business/{business_user_uuid}": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "List Business Batch Payouts ( STABLE )", "description": "This API retrieves all business batch payouts associated with the business user UUID. The response provides comprehensive details about each payout, including the total amount and detailed information for each payout.", "operationId": "6636497d34f27fa34709aae413e5a625", "parameters": [ { "name": "business_user_uuid", "in": "path", "description": "UUID of the business user", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "description": "Filter by start date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "Filter by end date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort_order", "in": "query", "description": "Sort order ('oldest' or 'newest')", "required": false, "schema": { "type": "string", "enum": [ "oldest", "newest" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Business batch payouts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PayeeBatchPayoutsResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Business not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Parameters Received: startDate, endDate" }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "start_date": { "type": "array", "items": {}, "example": [ "The start date does not match the format Y-m-d.", "The start date must be a date before or equal to end date." ] }, "end_date": { "type": "array", "items": {}, "example": [ "The end date does not match the format Y-m-d.", "The end date must be a date after or equal to start date." ] }, "sort_order": { "type": "array", "items": {}, "example": [ "The selected sort order is invalid." ] }, "per_page": { "type": "array", "items": {}, "example": [ "The per page must be an integer.", "The per page must be at least 1.", "The per page may not be greater than 100." ] }, "page": { "type": "array", "items": {}, "example": [ "The page must be an integer.", "The page must be at least 1." ] } }, "type": "object" }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-payouts/merchant/{merchant_user_uuid}/{batch_payout_uuid}": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "Get Merchant Batch Payout ( STABLE )", "description": "This API retrieves the details of a merchant batch payout using the merchant user UUID and the unique batch payout UUID. The response provides comprehensive information about the payout, including the total amount and a detailed breakdown of the transactions.", "operationId": "8a10401810f70465a7e394ff50903da3", "parameters": [ { "name": "merchant_user_uuid", "in": "path", "description": "UUID of the merchant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "batch_payout_uuid", "in": "path", "description": "UUID of the batch payout", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Merchant batch payout details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PayeeBatchPayoutResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Merchant not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Merchant Batch Payout not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-payouts/merchant/{merchant_user_uuid}": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "List Merchant Batch Payouts ( STABLE )", "description": "This API retrieves all merchant batch payouts associated with the merchant user UUID. The response provides comprehensive details about each payout, including the total amount and detailed information for each individual payout.", "operationId": "aeb962faebd49755858be4c24fdc714b", "parameters": [ { "name": "merchant_user_uuid", "in": "path", "description": "UUID of the merchant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "description": "Filter by start date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "Filter by end date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort_order", "in": "query", "description": "Sort order ('oldest' or 'newest')", "required": false, "schema": { "type": "string", "enum": [ "oldest", "newest" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Merchant batch payouts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PayeeBatchPayoutsResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Merchant not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Parameters Received: startDate, endDate" }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "start_date": { "type": "array", "items": {}, "example": [ "The start date does not match the format Y-m-d.", "The start date must be a date before or equal to end date." ] }, "end_date": { "type": "array", "items": {}, "example": [ "The end date does not match the format Y-m-d.", "The end date must be a date after or equal to start date." ] }, "sort_order": { "type": "array", "items": {}, "example": [ "The selected sort order is invalid." ] }, "per_page": { "type": "array", "items": {}, "example": [ "The per page must be an integer.", "The per page must be at least 1.", "The per page may not be greater than 100." ] }, "page": { "type": "array", "items": {}, "example": [ "The page must be an integer.", "The page must be at least 1." ] } }, "type": "object" }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-payouts/person/{user_uuid}/{batch_payout_uuid}": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "Get Person Batch Payout ( STABLE )", "description": "This API retrieves the details of a person batch payout using the person user UUID and the unique batch payout UUID. The response provides comprehensive information about the payout, including the total amount and a detailed breakdown of the transactions.", "operationId": "566d68eb48fc4e125a4f0669ad7a8fdc", "parameters": [ { "name": "user_uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "batch_payout_uuid", "in": "path", "description": "UUID of the batch payout", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Person batch payout details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PayeeBatchPayoutResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Person not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Person Batch Payout not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-payouts/person/{user_uuid}": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "List Person Batch Payouts ( STABLE )", "description": "This API retrieves all person batch payouts associated with the person user UUID. The response provides comprehensive details about each payout, including the total amount and detailed information for each payout.", "operationId": "631ed6ab20bab3392e52db48c2c72c22", "parameters": [ { "name": "user_uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "description": "Filter by start date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "Filter by end date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort_order", "in": "query", "description": "Sort order ('oldest' or 'newest')", "required": false, "schema": { "type": "string", "enum": [ "oldest", "newest" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Person batch payouts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PayeeBatchPayoutsResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Person not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Parameters Received: startDate, endDate" }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "start_date": { "type": "array", "items": {}, "example": [ "The start date does not match the format Y-m-d.", "The start date must be a date before or equal to end date." ] }, "end_date": { "type": "array", "items": {}, "example": [ "The end date does not match the format Y-m-d.", "The end date must be a date after or equal to start date." ] }, "sort_order": { "type": "array", "items": {}, "example": [ "The selected sort order is invalid." ] }, "per_page": { "type": "array", "items": {}, "example": [ "The per page must be an integer.", "The per page must be at least 1.", "The per page may not be greater than 100." ] }, "page": { "type": "array", "items": {}, "example": [ "The page must be an integer.", "The page must be at least 1." ] } }, "type": "object" }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-payouts/processor/{batch_payout_uuid}": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "Get Processor Batch Payout ( STABLE )", "description": "This API retrieves the details of a processor batch payout using the unique batch payout UUID. The response provides comprehensive information about the payout, including the total amount and a detailed breakdown of the transactions.", "operationId": "0bfcc7b2d772e9b7ec1e466b863fa75a", "parameters": [ { "name": "batch_payout_uuid", "in": "path", "description": "UUID of the batch payout", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Processor batch payout details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2ProcessorBatchPayoutResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Processor Batch Payout not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-payouts/processor": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "List Processor Batch Payouts ( STABLE )", "description": "This API retrieves all batch payouts associated with the processor. The response provides comprehensive details for each payout, including the total amount and specific information for each payout.", "operationId": "0c5eef4a1ebb60e8503e7db16c78c22f", "parameters": [ { "name": "start_date", "in": "query", "description": "Filter by start date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "Filter by end date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort_order", "in": "query", "description": "Sort order ('oldest' or 'newest')", "required": false, "schema": { "type": "string", "enum": [ "oldest", "newest" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Processor batch payouts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2ProcessorBatchPayoutsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Parameters Received: startDate, endDate" }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "start_date": { "type": "array", "items": {}, "example": [ "The start date does not match the format Y-m-d.", "The start date must be a date before or equal to end date." ] }, "end_date": { "type": "array", "items": {}, "example": [ "The end date does not match the format Y-m-d.", "The end date must be a date after or equal to start date." ] }, "sort_order": { "type": "array", "items": {}, "example": [ "The selected sort order is invalid." ] }, "per_page": { "type": "array", "items": {}, "example": [ "The per page must be an integer.", "The per page must be at least 1.", "The per page may not be greater than 100." ] }, "page": { "type": "array", "items": {}, "example": [ "The page must be an integer.", "The page must be at least 1." ] } }, "type": "object" }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-payouts/{batch_payout_uuid}": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "Get Batch Payout ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.** This API retrieves the details of a specific batch payout using its unique batch payout UUID. The response provides comprehensive information about the payout, including the total amount and a breakdown of transactions grouped by payee.", "operationId": "be47e5b1b8a0964a5b353371eeb2ff44", "parameters": [ { "name": "batch_payout_uuid", "in": "path", "description": "UUID of the batch payout", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch payout details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BatchPayoutResponse" } }, "type": "object" } } } }, "404": { "description": "Batch payout not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch payout not found" }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-payouts": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "Get All Batch Payouts ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.** This API retrieves a list of all batch payouts. The response provides details for each payout, including the total amount and relevant timestamps. Pagination options are available to efficiently manage large datasets.", "operationId": "663e193fb79a925d1b026bc104649a11", "parameters": [ { "name": "start_date", "in": "query", "description": "Filter by start date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "Filter by end date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort_order", "in": "query", "description": "Sort order ('oldest' or 'newest')", "required": false, "schema": { "type": "string", "enum": [ "oldest", "newest" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Batch payouts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "batch_payouts": { "type": "array", "items": { "properties": { "batch_payout_uuid": { "type": "string", "format": "uuid", "example": "9bd53fe1-ac74-4e81-b6f2-be88b7c86a68" }, "amount": { "type": "number", "format": "float", "example": 10000 }, "date": { "type": "string", "format": "date-time", "example": "2024-04-18 01:00:20" }, "modality": { "properties": { "payment_rail": { "type": "string", "example": "fednow" }, "speed": { "type": "string", "example": "instant" } }, "type": "object" } }, "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 3 }, "total_items": { "type": "integer", "example": 30 }, "per_page": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "object", "example": null, "nullable": true } }, "type": "object" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unknown parameters: per_page, sort_order" }, "errors": { "type": "object", "additionalProperties": { "type": "string", "example": "Invalid value for per_page" } } }, "type": "object" } } } }, "404": { "description": "Batch payouts not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch payout not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-merchant-payouts/{batch_merchant_payout_uuid}": { "get": { "tags": [ "Payouts", "Stable" ], "summary": "Get Batch Merchant Payout ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**GrailPay enables merchants to receive a single batch payout per day, consolidating multiple transactions into one payout instead of processing individual transfers separately. This helps streamline payments and reduce transaction costs. ", "operationId": "2c6c00849cc41ba4f5d1d52a251be3db", "parameters": [ { "name": "batch_merchant_payout_uuid", "in": "path", "description": "UUID of the batch merchant payout", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9bd53fe1-ac74-4e81-b6f2-be88b7c86a68" } } ], "responses": { "200": { "description": "Batch merchant payout retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "ec0eb270-b656-4ffe-8799-66508ad48e18" }, "amount": { "type": "number", "format": "float", "example": 4400 }, "trace_id": { "type": "string", "example": "ach_11kt6v9715jp67t" }, "payout_status": { "type": "string", "example": "PAYOUT_COMPLETE" }, "transactions": { "type": "array", "items": { "properties": { "transaction_uuid": { "type": "string", "format": "uuid", "example": "9ccf5706-dff0-46c7-bf74-4e34dc998485" }, "amount": { "type": "number", "format": "float", "example": 4400 }, "transaction_fee": { "type": "number", "format": "float", "example": 0 }, "trace_id": { "type": "string", "example": "ach_11kt5sew15jj2dp" }, "capture_status": { "type": "string", "example": "CAPTURE_COMPLETE" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time", "example": "2025-02-16 14:15:15" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-02-18 14:15:15" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "object", "example": null, "nullable": true } }, "type": "object" } } } }, "404": { "description": "Batch merchant payout not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The batch merchant payout not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "object", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/users": { "get": { "tags": [ "Users", "Sunsetting" ], "summary": "Get All Users ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "14fe898be645615dd9ddde4c1da78f07", "parameters": [ { "name": "role", "in": "query", "description": "Filter users by role", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Filter users created after this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "Filter users created before this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "sort_order", "in": "query", "description": "Sort order (asc or desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of users per page", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Users retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/BusinessResponse" }, { "$ref": "#/components/schemas/PersonResponse" } ] } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 5 }, "total_items": { "type": "integer", "example": 50 }, "per_page": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unknown parameters: per_page, role" }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "string", "example": "Invalid value for per_page" } }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "Users", "Sunsetting" ], "summary": "Onboard a new Person into the ACH application ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "8b5aae9b3342dfb2d67304524b4da60b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_reference_id": { "type": "string", "example": "123456", "nullable": true }, "first_name": { "type": "string", "example": "John", "nullable": true }, "last_name": { "type": "string", "example": "Doe", "nullable": true }, "email": { "type": "string", "example": "test@example.org", "nullable": true }, "phone": { "type": "string", "example": "1234567890", "nullable": true }, "address": { "properties": { "line_1": { "type": "string", "example": "10554 W Quarles Ave", "nullable": true }, "city": { "type": "string", "example": "Littleton", "nullable": true }, "state": { "type": "string", "example": "CO", "nullable": true }, "zip": { "type": "string", "example": "80127", "nullable": true } }, "type": "object" }, "bank_account": { "$ref": "#/components/schemas/V2BankAccountRequest" }, "billing_merchant_user_uuid": { "type": "string", "format": "uuid", "example": "2bcf2ac3-38fc-4238-a638-4f092821fc27", "nullable": true }, "billing_processor_mid": { "type": "string", "example": "21245678932", "nullable": true }, "payout_type": { "type": "string", "example": "individual", "nullable": true, "enum": [ "batch", "individual" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Person registered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2OnboardPersonResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "string", "example": null }, "errors": { "properties": { "first_name": { "type": "array", "items": { "type": "string", "example": "The first name must be a string." } } }, "type": "object" }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-refunds": { "get": { "tags": [ "Refunds", "Stable" ], "summary": "Get All Batch Refunds ( STABLE )", "description": "This API retrieves a list of all batch refunds. The response provides details for each batch refund, including the total amount and relevant timestamps. Pagination options are available to efficiently manage large datasets.", "operationId": "83fd1801d91a8efd53e356094515a475", "parameters": [ { "name": "start_date", "in": "query", "description": "This parameter will filter the user's records based on the creation date of the batch refund.Date format: Y-m-d", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-03-01" } }, { "name": "end_date", "in": "query", "description": "This parameter will filter the user's records based on the creation date of the batch refund.Date format: Y-m-d", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-03-10" } }, { "name": "sort_order", "in": "query", "description": "Sorting order: 'oldest' for ascending, 'newest' for descending.", "required": false, "schema": { "type": "string", "example": "newest", "enum": [ "oldest", "newest" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination.", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page.", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Batch refunds retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRefundListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/batch-refunds/{batch_refund_uuid}": { "get": { "tags": [ "Refunds", "Stable" ], "summary": "Get Batch Refund ( STABLE )", "description": "This API retrieves the details of a specific batch refund using its unique batch refund UUID. The response provides comprehensive information about the refund, including the total amount and the associated transactions.", "operationId": "63ed85c2621b265ccf4b9a5c4b4ec278", "parameters": [ { "name": "batch_refund_uuid", "in": "path", "description": "UUID of the batch refund", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "$ref": "#/components/schemas/BatchRefundResponse" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "404": { "description": "Batch refund not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRefundNotFound" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/transactions": { "get": { "tags": [ "Transactions", "Sunsetting" ], "summary": "Get Transactions ( SUNSETTING )", "description": "This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.", "operationId": "5aa060d7d961b95ba524221445ac18a7", "parameters": [ { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer" } }, { "name": "start_date", "in": "query", "description": "Start date for filtering transactions", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "End date for filtering transactions", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort_order", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "enum": [ "newest", "oldest" ] } }, { "name": "payer_account_uuid", "in": "query", "description": "UUID of the payer account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "payer_account_aggregator_type", "in": "query", "description": "Aggregator type of the payer account (Required when payer_account_uuid is provided)", "required": false, "schema": { "type": "string" } }, { "name": "payee_account_uuid", "in": "query", "description": "UUID of the payee account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "payee_account_aggregator_type", "in": "query", "description": "Aggregator type of the payee account", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of transactions", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/V2TransactionResponse" } } }, "type": "object" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid parameters received" }, "data": { "type": "object", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/transactions/{uuid}": { "get": { "tags": [ "Transactions", "Sunsetting" ], "summary": "Get Transaction by UUID ( SUNSETTING )", "description": "This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.", "operationId": "ee52b4fd2a708352da760a353bfaca36", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the transaction", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction details", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "$ref": "#/components/schemas/V2TransactionResponse" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Transaction not found" }, "data": { "type": "object", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "Transactions", "Sunsetting" ], "summary": "Cancel a transaction ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "95e1494908c1987e546fd8bc8b2675a6", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the transaction to cancel", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Transaction canceled successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Transaction cancelled." }, "data": { "type": "object", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Trnasaction can not be cancelled", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "type": "string", "example": "A failed transaction cannot be cancelled." }, { "type": "string", "example": "This transaction has been cancelled previously." }, { "type": "string", "example": "A processed transaction cannot be cancelled." }, { "type": "string", "example": "Cancelling a transaction is not for instant ach transactions." } ] }, "data": { "type": "object", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Transaction not found" }, "data": { "type": "object", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v2/users/{uuid}": { "get": { "tags": [ "Users", "Sunsetting" ], "summary": "Get User ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "78d36f0a49ae471188d81e1fbae92d1e", "parameters": [ { "name": "uuid", "in": "path", "description": "User UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User details retrieved successfully", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BusinessResponse" }, { "$ref": "#/components/schemas/PersonResponse" } ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The user has not been found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "array", "items": { "type": "string" }, "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "Users", "Stable" ], "summary": "Deleting a User ( STABLE )", "description": "This API deletes a specific user from the system based on their unique user UUID.", "operationId": "92a24e030e4c373aa3318a0c883df936", "parameters": [ { "name": "uuid", "in": "path", "description": "User UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "User deletion is in process", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This user has been scheduled for deletion." }, "data": { "type": "array", "items": {}, "example": [] }, "errors": { "type": "string", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "The user has been deleted successfully." }, "data": { "type": "array", "items": {}, "example": [] }, "errors": { "type": "string", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The user has not been found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "array", "items": { "type": "string" }, "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/bank-accounts": { "get": { "tags": [ "Bank Accounts", "Stable" ], "summary": "List bank accounts for an entity. ( STABLE )", "description": "This endpoint retrieves a paginated list of bank accounts for a given entity. Supports filtering by account type, default status, provider, and account name. Supports sorting by created_at and account_name.", "operationId": "ec0c661bef93387bceecdbf34ee6cd06", "parameters": [ { "name": "filter[entity_uuid]", "in": "query", "description": "UUID of the entity (person or business) to list bank accounts for", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, { "name": "filter[account_type]", "in": "query", "description": "Filter by account type", "required": false, "schema": { "type": "string", "example": "checking", "enum": [ "checking", "savings" ] } }, { "name": "filter[is_default]", "in": "query", "description": "Filter by default account status", "required": false, "schema": { "type": "string", "example": "true", "enum": [ "true", "false" ] } }, { "name": "filter[provider]", "in": "query", "description": "Filter by provider type", "required": false, "schema": { "type": "string", "example": "manual", "enum": [ "manual", "plaid", "bank_link" ] } }, { "name": "filter[account_name]", "in": "query", "description": "Filter by account name (partial match)", "required": false, "schema": { "type": "string", "example": "Checking" } }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with - for descending order.", "required": false, "schema": { "type": "string", "example": "-created_at", "enum": [ "created_at", "-created_at", "account_name", "-account_name" ] } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Bank accounts retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "entity": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "type": { "type": "string", "example": "person" }, "person_uuid": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "nullable": true } }, "type": "object" }, "bank_accounts": { "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "provider_type": { "type": "string", "example": "bank_link" }, "aggregator_type": { "type": "string", "example": "bank_link" }, "account_number": { "type": "string", "example": "9876543210" }, "routing_number": { "type": "string", "example": "021000021" }, "account_name": { "type": "string", "example": "John Doe Checking" }, "account_type": { "type": "string", "example": "checking" }, "institution_name": { "type": "string", "example": "Chase", "nullable": true }, "aggregator": { "type": "string", "example": "mx", "nullable": true }, "is_default": { "type": "boolean", "example": true, "nullable": true }, "client_reference_id": { "type": "string", "example": "my-ref-123", "nullable": true }, "status": { "type": "string", "example": "connected", "nullable": true }, "timestamps": { "properties": { "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } }, "type": "object" } }, "type": "object" } }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3BankAccountValidationError" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Add a bank account to an entity. ( STABLE )", "description": "This endpoint allows for adding a new Bank Account to an entity (person or business) using their entity UUID. You can pass either Plaid information or account and routing information. You should never pass both.", "operationId": "7299e7b47155bef6795c0bef1f351f55", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "entity_uuid", "bank_account" ], "properties": { "entity_uuid": { "description": "UUID of the entity (person or business) to add the bank account to.", "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "client_reference_id": { "description": "Optional client reference ID for tracking purposes.", "type": "string", "example": "my-ref-123" }, "billing_processor_mid": { "description": "Optional billing processor MID.", "type": "string", "example": "12345678" }, "billing_merchant_uuid": { "description": "Optional billing merchant UUID.", "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" }, "person": { "description": "Use this object for name match account intelligence.", "properties": { "first_name": { "type": "string", "example": "Raj2" }, "last_name": { "type": "string", "example": "Last" } }, "type": "object" }, "bank_account": { "description": "Bank account details. Provide either Plaid details OR manual account/routing details, never both.", "oneOf": [ { "title": "Plaid Mode", "required": [ "plaid_account_id", "plaid_access_token" ], "properties": { "plaid_account_id": { "description": "Plaid account ID. Required when using Plaid.", "type": "string", "example": "vzeNDwK7KPIzDaqMq3Pn" }, "plaid_access_token": { "description": "Plaid access token. Required when using Plaid.", "type": "string", "example": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6" } }, "type": "object" }, { "title": "Manual Mode", "required": [ "account_number", "routing_number", "account_name", "account_type" ], "properties": { "account_number": { "description": "Bank account number. Max 17 characters. Required for manual entry.", "type": "string", "example": "1234567890123" }, "routing_number": { "description": "Bank routing number. Must be 9 digits. Required for manual entry.", "type": "string", "example": "021000021" }, "account_name": { "description": "Name on the bank account. Required for manual entry.", "type": "string", "example": "John Doe Checking" }, "account_type": { "description": "Type of bank account. Required for manual entry.", "type": "string", "example": "checking", "enum": [ "checking", "savings" ] } }, "type": "object" } ] }, "actions": { "description": "Optional actions to perform during bank account creation.", "properties": { "account_intelligence": { "description": "Account intelligence configuration.", "properties": { "version": { "description": "Account intelligence version. Required when account_intelligence object is present.", "type": "string", "example": "v3", "enum": [ "v1", "v2", "v3" ] }, "name_match": { "description": "Whether to perform name matching. Only available with version v3.", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Bank account successfully created.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Bank account added successfully." }, "data": { "properties": { "entity": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "type": { "type": "string", "example": "person" }, "person_uuid": { "description": "Only present when entity type is not person.", "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "type": "object" }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" }, "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "200": { "description": "Bank account already exists and was set as default.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This bank account already exists for this entity. We have attached it as the default bank account." }, "data": { "properties": { "entity": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "type": { "type": "string", "example": "person" } }, "type": "object" }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" }, "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "This entity is not available as they have been scheduled for deletion." }, { "example": "This entity is currently on hold and is unable to be modified." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3OnboardingValidationErrors" }, { "properties": {}, "type": "object" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/people/{uuid}/bank-accounts": { "post": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Add a new bank account to a person. ( STABLE )", "description": "This endpoint allows for adding a new Bank Account to the GrailPay ACH API Ecosystem. The only item that is required is the Bank Account object. When including the bank account, you can pass either Plaid information or account and routing information. You should never pass both.", "operationId": "382621bd16dd23255f6fb5245235a0cd", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the person", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "person": { "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" } }, "type": "object" }, "billing_merchant_uuid": { "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" }, "billing_processor_mid": { "type": "string", "example": "12345678" }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountObject" }, "actions": { "properties": { "account_intelligence": { "$ref": "#/components/schemas/V3AccountIntelligenceRequestObject" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "The response returned from a successful call to add a bank account.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "The bank account was created and attached successfully." }, "data": { "properties": { "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" }, "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "200": { "description": "The response returned from a successful call to add a bank account.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This bank account already exists for this person. We have attached it as the default bank account." }, "data": { "properties": { "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" }, "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No person was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "This person is not available as they have been scheduled for deletion." }, { "example": "This person is currently on hold and is unable to be modified." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3OnboardingValidationErrors" }, { "$ref": "#/components/schemas/V3PersonValidationError" }, { "properties": { "person.first_name": { "type": "object", "example": [ "The first name must be a string.", "The first name may not be greater than 56 characters." ] }, "person.last_name": { "type": "object", "example": [ "The last name must be a string.", "The last name may not be greater than 56 characters." ] }, "billing_merchant_uuid": { "type": "object", "example": [ "The billing merchant UUID must be a valid UUID.", "The billing merchant UUID does not exist.", "The billing merchant UUID is deleted and cannot be used for billing purposes." ] }, "billing_processor_mid": { "type": "object", "example": [ "The billing processor MID must be a string.", "The billing processor MID does not exist.", "The billing processor MID is deleted and cannot be used for billing purposes." ] }, "bank_account": { "type": "object", "example": [ "The bank account field is required.", "You cannot provide both plaid details and manual bank account fields.", "This person did not meet the confidence score threshold of 0.5 and has been rejected.", "Invalid plaid account ID or access token.", "The bank routing number is not valid." ] } }, "type": "object" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/bank-accounts/validate": { "post": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Validate a bank account's routing and account number. ( STABLE )", "description": "This endpoint allows for validating a Bank Account's routing and account number using GrailPay's Account Intelligence system.", "operationId": "77650b67f45408f8ec5d610ec96239d2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "person": { "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" } }, "type": "object" }, "bank_account": { "required": [ "account_number", "routing_number" ], "properties": { "account_number": { "type": "string", "example": "1111222233330000" }, "routing_number": { "type": "string", "example": "123456789" } }, "type": "object" }, "actions": { "properties": { "account_intelligence": { "$ref": "#/components/schemas/V3AccountIntelligenceRequestObject" } }, "type": "object" }, "billing_merchant_uuid": { "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" }, "billing_processor_mid": { "type": "string", "example": "12345678" } }, "type": "object" } } } }, "responses": { "200": { "description": "The response returned from a successful bank account validation.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Validation processed successfully" }, "data": { "properties": { "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3OnboardingValidationErrors" }, { "$ref": "#/components/schemas/V3PersonValidationError" }, { "properties": { "person.first_name": { "type": "object", "example": [ "The first name must be a string.", "The first name may not be greater than 56 characters.", "The first name field is required when name match is true." ] }, "person.last_name": { "type": "object", "example": [ "The last name must be a string.", "The last name may not be greater than 56 characters.", "The last name field is required when name match is true." ] } }, "type": "object" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/bank-accounts/{uuid}": { "get": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Show a bank account. ( STABLE )", "description": "This endpoint retrieves the details of a specific bank account by its UUID, including the associated entity information.", "operationId": "155c0871e6d5b16259c5e154f7b2862b", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the bank account", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "responses": { "200": { "description": "Bank account retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "The bank account was found successfully." }, "data": { "properties": { "entity": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "type": { "type": "string", "example": "person" }, "person_uuid": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "nullable": true } }, "type": "object" }, "bank_account": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "provider_type": { "type": "string", "example": "bank_link" }, "aggregator_type": { "type": "string", "example": "bank_link" }, "account_number": { "type": "string", "example": "9876543210" }, "routing_number": { "type": "string", "example": "021000021" }, "account_name": { "type": "string", "example": "John Doe Checking" }, "account_type": { "type": "string", "example": "checking" }, "institution_name": { "type": "string", "example": "Chase", "nullable": true }, "aggregator": { "type": "string", "example": "mx", "nullable": true }, "is_default": { "type": "boolean", "example": true, "nullable": true }, "client_reference_id": { "type": "string", "example": "my-ref-123", "nullable": true }, "status": { "type": "string", "example": "connected", "nullable": true }, "timestamps": { "properties": { "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No bank account was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Delete a bank account. ( STABLE )", "description": "This endpoint deletes a bank account by its UUID. The bank account must be eligible for deletion (no recent transaction activity within the configured period).", "operationId": "8dd66a43ca30cc96fc05dd01d1d9e632", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the bank account to delete", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "responses": { "200": { "description": "Bank account successfully deleted.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Bank account deleted successfully." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "This user is not available as they have been scheduled for deletion." }, { "example": "This user is not eligible for this action." }, { "example": "This bank account cannot be deleted because it has recent transaction activity within the last 70 days." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No bank account was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/bank-accounts/{uuid}/balance": { "get": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Fetch a bank account balance. ( STABLE )", "description": "This endpoint fetches the current balance of a bank account. Only available for bank-link (Quiltt/MoneyKit) provider accounts.", "operationId": "8c3f98d9b87452d7e6719d1f2c6af704", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the bank account", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "responses": { "200": { "description": "Bank account balance fetched successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "bank_account": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "provider_type": { "type": "string", "example": "bank_link" }, "aggregator_type": { "type": "string", "example": "bank_link" }, "account_number": { "type": "string", "example": "9876543210" }, "routing_number": { "type": "string", "example": "021000021" }, "account_name": { "type": "string", "example": "John Doe Checking" }, "account_type": { "type": "string", "example": "checking" }, "institution_name": { "type": "string", "example": "Chase", "nullable": true }, "aggregator": { "type": "string", "example": "mx", "nullable": true }, "is_default": { "type": "boolean", "example": true, "nullable": true }, "client_reference_id": { "type": "string", "example": "my-ref-123", "nullable": true }, "status": { "type": "string", "example": "connected", "nullable": true }, "timestamps": { "properties": { "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } }, "type": "object" } }, "type": "object" }, "balance": { "properties": { "available_balance": { "type": "number", "format": "float", "example": 1250.75, "nullable": true }, "current_balance": { "type": "number", "format": "float", "example": 1500, "nullable": true }, "currency": { "type": "string", "example": "USD", "nullable": true }, "last_updated_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z", "nullable": true } }, "type": "object" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No bank account was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Validation Errors", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "billing_merchant_uuid": { "type": "object", "example": [ "The billing merchant UUID must be a valid UUID.", "The billing merchant UUID does not exist.", "The billing merchant UUID is deleted and cannot be used for billing purposes." ] }, "billing_processor_mid": { "type": "object", "example": [ "The billing processor MID must be a string.", "The billing processor MID does not exist.", "The billing processor MID is deleted and cannot be used for billing purposes." ] } }, "type": "object" }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" }, { "title": "Invalid Provider", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The bank account is not a valid provider." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "Internal error while communicating with the requested bank" }, { "example": "Something went wrong on our side. Please contact support." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/bank-accounts/{uuid}/default": { "put": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Switch the default bank account. ( STABLE )", "description": "This endpoint sets a bank account as the default bank account for the entity. The bank account must be in a connected state for Quiltt/MoneyKit providers, and the entity must be approved and not scheduled for deletion.", "operationId": "c6a670c7331dc25c3def2a0c98f0c973", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the bank account to set as default", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "responses": { "200": { "description": "Default bank account switched successfully or already default.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "oneOf": [ { "example": "Default account is updated." }, { "example": "Provided account is already a default bank account." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "This entity is not available as they have been scheduled for deletion." }, { "example": "This entity is currently on hold and is unable to be modified." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No bank account was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/bank-accounts/{uuid}/history": { "get": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Fetch bank account transaction history. ( STABLE )", "description": "This endpoint fetches the transaction history for a bank account. Supports two providers: **Quiltt** (cursor-based pagination with advanced filtering) and **MoneyKit** (page-based pagination with basic date filtering). The available parameters and response format depend on the bank account's provider.", "operationId": "c16357b01c82188955fbb968e9e7004e", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the bank account. (Both providers)", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, { "name": "per_page", "in": "query", "description": "Number of records per page. Used as page size for MoneyKit and as first/page size for Quiltt cursor-based pagination. (Both providers)", "required": false, "schema": { "type": "integer", "example": 15 } }, { "name": "start_date", "in": "query", "description": "Start date filter (Y-m-d format). Must be before or equal to end_date. (Both providers)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "end_date", "in": "query", "description": "End date filter (Y-m-d format). Must be after or equal to start_date. (Both providers)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-12-31" } }, { "name": "page", "in": "query", "description": "Page number for page-based pagination. (MoneyKit only)", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "cursor", "in": "query", "description": "Cursor for cursor-based pagination. (Quiltt only)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction history fetched successfully. Response format varies by provider (Quiltt or MoneyKit).", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Quiltt Provider Response", "description": "Response when the bank account uses the Quiltt (bank-link) provider. Uses cursor-based pagination.", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "transactions": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "txn_abc123" }, "amount": { "type": "number", "format": "float", "example": -25.5 }, "currency_code": { "type": "string", "example": "USD" }, "date": { "type": "string", "format": "date", "example": "2024-06-15" }, "description": { "type": "string", "example": "Amazon Purchase" }, "entry_type": { "type": "string", "example": "DEBIT" }, "fees": { "type": "number", "format": "float", "example": null, "nullable": true }, "kind": { "type": "string", "example": "DEPOSITORY" }, "metadata": { "type": "object", "example": null, "nullable": true }, "price": { "type": "number", "format": "float", "example": null, "nullable": true }, "provider": { "type": "string", "example": "quiltt" }, "quantity": { "type": "number", "format": "float", "example": null, "nullable": true }, "status": { "type": "string", "example": "POSTED" }, "merchant_name": { "type": "string", "example": "Amazon", "nullable": true } }, "type": "object" } }, "pagination": { "properties": { "total_items": { "type": "integer", "example": 150 }, "page_size": { "type": "integer", "example": 15 }, "has_next_page": { "type": "boolean", "example": true }, "has_previous_page": { "type": "boolean", "example": false }, "start_cursor": { "type": "string", "example": "cursor_abc123", "nullable": true }, "next_cursor": { "type": "string", "example": "cursor_def456", "nullable": true } }, "type": "object" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" }, { "title": "MoneyKit Provider Response", "description": "Response when the bank account uses the MoneyKit provider. Uses page-based pagination.", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "transactions": { "type": "array", "items": { "properties": { "transaction_id": { "type": "string", "example": "txn_001" }, "amount": { "type": "number", "format": "float", "example": 150.75 }, "datetime": { "type": "string", "format": "date", "example": "2024-06-15" }, "original_description": { "type": "string", "example": "Coffee Shop" }, "pending": { "type": "boolean", "example": false }, "category": { "type": "string", "example": "Food", "nullable": true }, "transaction_type": { "type": "string", "example": "debit" }, "merchant_name": { "type": "string", "example": "Starbucks", "nullable": true } }, "type": "object" } }, "pagination": { "properties": { "currentPage": { "type": "integer", "example": 1 }, "totalPages": { "type": "integer", "example": 10 }, "totalItems": { "type": "integer", "example": 150 }, "pageSize": { "type": "integer", "example": 15 } }, "type": "object" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No bank account was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "We are unable to retrieve the transaction history." }, { "example": "Something went wrong on our side. Please contact support." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/bank-accounts/{uuid}/owners": { "get": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Get Bank Account Owners ( STABLE )", "description": "This endpoint returns the account owners of the bank account.", "operationId": "d4e32681a9d14d638f4b817a6a28d555", "parameters": [ { "name": "uuid", "in": "path", "description": "bank account UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9b97f121-a449-4b52-9f36-6c55f18394d6" } } ], "responses": { "200": { "description": "The response returned from a successful call to get bank account owners.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "owners": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "own_1331Ds7MrGmp8iCkEFFdmR" }, "names": { "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "middle_name": { "type": "string", "example": null, "nullable": true }, "full_name": { "type": "string", "example": "John Doe" } }, "type": "object" }, "emails": { "type": "array", "items": { "type": "string", "example": "john.doe@example.com" } }, "phone_numbers": { "type": "array", "items": { "type": "string", "example": "+12345678901" } }, "address": { "properties": { "line1": { "type": "string", "example": "123 Main St" }, "line2": { "type": "string", "example": null, "nullable": true }, "line3": { "type": "string", "example": null, "nullable": true }, "city": { "type": "string", "example": "Anytown" }, "state": { "type": "string", "example": "DE" }, "state_full": { "type": "string", "example": "Delaware" }, "postal_code": { "type": "string", "example": "12345" }, "country": { "type": "string", "example": "USA" }, "country_full": { "type": "string", "example": "United States of America" } }, "type": "object" } }, "type": "object" } } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This action is unauthorized." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No bank account was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/businesses": { "get": { "tags": [ "Users", "Stable" ], "summary": "Get All Businesses ( STABLE )", "description": "This endpoint provides a comprehensive list of all registered businesses, including essential details. Pagination options are available to efficiently manage large datasets.", "operationId": "ba480005cebe89606b2f65d95d3c2585", "parameters": [ { "name": "filter[uuid]", "in": "query", "description": "Filter by business UUID", "required": false, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, { "name": "filter[name]", "in": "query", "description": "Filter by business name", "required": false, "schema": { "type": "string", "example": "John Inc" } }, { "name": "sort", "in": "query", "description": "Sort by field (created_at, name). Prefix with '-' for descending order", "required": false, "schema": { "type": "string", "example": "-created_at" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15, "default": 15 } } ], "responses": { "200": { "description": "The response returned from a successful call to listing businesses.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "businesses": { "type": "array", "items": { "properties": { "business": { "$ref": "#/components/schemas/V3BusinessResponseObject" }, "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "relations": { "$ref": "#/components/schemas/V3PersonRelationResponseObject" } }, "type": "object" } } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" }, "meta": { "$ref": "#/components/schemas/V3ListingPaginationResponse" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "filter.uuid": { "type": "object", "example": [ "The business UUID must be a valid UUID." ] }, "filter.name": { "type": "object", "example": [ "The business name must be a string.", "The business name may not be greater than 255 characters." ] }, "sort": { "type": "object", "example": [ "The sort option must be one of the followings: created_at, -created_at, name, -name" ] }, "per_page": { "type": "object", "example": [ "The per page may not be greater than 200.", "The per page must be at least 1.", "The per page must be an integer." ] }, "page": { "type": "object", "example": [ "The page must be an integer.", "The page must be at least 1." ] } }, "type": "object" }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "Users", "Stable" ], "summary": "Onboard a new Business into the ACH application ( STABLE )", "description": "This endpoint allows for adding a new Business to the GrailPay ACH API Ecosystem. The only item that is required is the Bank Account object, but we strongly encourage that you supply as much information as possible. When including the bank account, you can pass either Plaid information or account and routing information. You should never pass both.", "operationId": "999c42d45d89d2db1aa6f3585c95a004", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_reference_id": { "type": "string", "example": "reference_12345" }, "billing_merchant_uuid": { "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" }, "billing_processor_mid": { "type": "string", "example": "12345678" }, "payout_type": { "type": "string", "example": "batch", "enum": [ "batch", "individual" ] }, "person": { "$ref": "#/components/schemas/V3PersonRequestObject" }, "business": { "$ref": "#/components/schemas/V3BusinessRequestObject" }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountObject" }, "actions": { "properties": { "account_intelligence": { "$ref": "#/components/schemas/V3AccountIntelligenceRequestObject" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "The response returned from a successful call to onboard a business.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This business was onboarded successfully." }, "data": { "properties": { "business": { "$ref": "#/components/schemas/V3BusinessResponseObject" }, "relations": { "properties": { "person": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, "type": "object" } }, "type": "object" }, "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3OnboardingValidationErrors" }, { "$ref": "#/components/schemas/V3PersonValidationError" }, { "$ref": "#/components/schemas/V3BusinessValidationError" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "There was a problem on the server and the action could not be completed. Please try again." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/businesses/{uuid}": { "get": { "tags": [ "Users", "Stable" ], "summary": "Get Business ( STABLE )", "description": "This endpoint will return detail of the business. When making a request to an API for a business's information, you typically need to provide a unique identifier UUID. The UUID is generated at the time of registration and is associated with the business's account.", "operationId": "d1c75dfe72809303cc7486abbf4b8d1b", "parameters": [ { "name": "uuid", "in": "path", "description": "business UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "responses": { "200": { "description": "The response returned from a successful call to get business.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "business": { "$ref": "#/components/schemas/V3BusinessResponseObject" }, "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "relations": { "$ref": "#/components/schemas/V3PersonRelationResponseObject" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No business was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This business is not available as they have been scheduled for deletion." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "patch": { "tags": [ "Users", "Stable" ], "summary": "Update a Business into the ACH application ( STABLE )", "description": "This endpoint allows for updating a Business to the GrailPay ACH API Ecosystem.", "operationId": "a176ef962d231a555656d062a2a9d693", "parameters": [ { "name": "uuid", "in": "path", "description": "business UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_reference_id": { "type": "string", "example": "reference_12345" }, "billing_merchant_uuid": { "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" }, "billing_processor_mid": { "type": "string", "example": "12345678" }, "payout_type": { "type": "string", "example": "batch", "enum": [ "batch", "individual" ] }, "person": { "$ref": "#/components/schemas/V3PersonRequestObject" }, "business": { "$ref": "#/components/schemas/V3BusinessRequestObject" }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountObject" }, "actions": { "properties": { "account_intelligence": { "$ref": "#/components/schemas/V3AccountIntelligenceRequestObject" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "The response returned from a successful call to update a business.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This business was updated successfully." }, "data": { "properties": { "business": { "$ref": "#/components/schemas/V3BusinessResponseObject" }, "relations": { "properties": { "person": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, "type": "object" } }, "type": "object" }, "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A business matching this UUID was not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This business is not available as they have been scheduled for deletion." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3OnboardingValidationErrors" }, { "$ref": "#/components/schemas/V3PersonValidationError" }, { "$ref": "#/components/schemas/V3BusinessValidationError" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "There was a problem on the server and the action could not be completed. Please try again." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/merchants": { "get": { "tags": [ "Users", "Stable" ], "summary": "Get All Merchants ( STABLE )", "description": "This endpoint provides a comprehensive list of all registered merchants, including essential details. Pagination options are available to efficiently manage large datasets.", "operationId": "e7ddae992283223ff98ce4cdea429ce6", "parameters": [ { "name": "filter[uuid]", "in": "query", "description": "Filter by merchant UUID", "required": false, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, { "name": "filter[name]", "in": "query", "description": "Filter by merchant name", "required": false, "schema": { "type": "string", "example": "John Inc" } }, { "name": "filter[tin]", "in": "query", "description": "Filter by EIN (TIN) number", "required": false, "schema": { "type": "string", "example": "123456789" } }, { "name": "sort", "in": "query", "description": "Sort by field (created_at, name). Prefix with '-' for descending order", "required": false, "schema": { "type": "string", "example": "-created_at" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15, "default": 15 } } ], "responses": { "200": { "description": "The response returned from a successful call to listing merchants.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "merchants": { "type": "array", "items": { "properties": { "merchant": { "$ref": "#/components/schemas/V3MerchantResponseObject" }, "beneficial_owners": { "type": "array", "items": { "$ref": "#/components/schemas/V3BeneficialOwnerResponseObject" } }, "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "relations": { "$ref": "#/components/schemas/V3PersonRelationResponseObject" } }, "type": "object" } } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" }, "meta": { "$ref": "#/components/schemas/V3ListingPaginationResponse" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "filter.uuid": { "type": "object", "example": [ "The merchant UUID must be a valid UUID." ] }, "filter.name": { "type": "object", "example": [ "The merchant name must be a string.", "The merchant name may not be greater than 255 characters." ] }, "filter.tin": { "type": "object", "example": [ "The EIN (TIN) number name must be a string.", "The EIN (TIN) number must consist of 9 digits." ] }, "sort": { "type": "object", "example": [ "The sort option must be one of the followings: created_at, -created_at, name, -name" ] }, "per_page": { "type": "object", "example": [ "The per page may not be greater than 200.", "The per page must be at least 1.", "The per page must be an integer." ] }, "page": { "type": "object", "example": [ "The page must be an integer.", "The page must be at least 1." ] } }, "type": "object" }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "Users", "Stable" ], "summary": "Onboard a new Merchant into the ACH application ( STABLE )", "description": "This endpoint allows for adding a new Merchant to the GrailPay ACH API Ecosystem.", "operationId": "dc8054b7f4b80775e0e4cf97eaf0f196", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_reference_id": { "type": "string", "example": "reference_12345" }, "billing_merchant_uuid": { "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" }, "billing_processor_mid": { "type": "string", "example": "12345678" }, "payout_type": { "type": "string", "example": "batch", "enum": [ "batch", "individual" ] }, "person": { "required": [ "first_name", "last_name", "email", "phone" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3PersonRequestObject" } ] }, "merchant": { "$ref": "#/components/schemas/V3MerchantRequestObject" }, "beneficial_owners": { "type": "array", "items": { "$ref": "#/components/schemas/V3BeneficialOwnerRequestObject" } }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountObject" }, "actions": { "properties": { "account_intelligence": { "$ref": "#/components/schemas/V3AccountIntelligenceRequestObject" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "The response returned from a successful call to onboard a merchant.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This merchant was onboarded successfully." }, "data": { "properties": { "merchant": { "$ref": "#/components/schemas/V3MerchantResponseObject" }, "beneficial_owners": { "type": "array", "items": { "$ref": "#/components/schemas/V3BeneficialOwnerResponseObject" } }, "relations": { "properties": { "person": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, "type": "object" } }, "type": "object" }, "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3OnboardingValidationErrors" }, { "$ref": "#/components/schemas/V3PersonValidationError" }, { "$ref": "#/components/schemas/V3MerchantValidationError" }, { "$ref": "#/components/schemas/V3BeneficialOwnerValidationError" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "There was a problem on the server and the action could not be completed. Please try again." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/merchants/{uuid}": { "get": { "tags": [ "Users", "Stable" ], "summary": "Get Merchant ( STABLE )", "description": "This endpoint will return detail of the merchant. When making a request to an API for a merchant's information, you typically need to provide a unique identifier UUID. The UUID is generated at the time of registration and is associated with the merchant's account.", "operationId": "c262225bb46c22d700bd9d78a6d1f8bb", "parameters": [ { "name": "uuid", "in": "path", "description": "merchant UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "responses": { "200": { "description": "The response returned from a successful call to get merchant.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "merchant": { "$ref": "#/components/schemas/V3MerchantResponseObject" }, "beneficial_owners": { "type": "array", "items": { "$ref": "#/components/schemas/V3BeneficialOwnerResponseObject" } }, "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "relations": { "$ref": "#/components/schemas/V3PersonRelationResponseObject" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No merchant was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This merchant is not available as they have been scheduled for deletion." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "patch": { "tags": [ "Users", "Stable" ], "summary": "Update a Merchant into the ACH application ( STABLE )", "description": "This endpoint allows for updating a Merchant to the GrailPay ACH API Ecosystem.", "operationId": "6680b96fb19eb86c8aea7805cbada282", "parameters": [ { "name": "uuid", "in": "path", "description": "merchant UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_reference_id": { "type": "string", "example": "reference_12345" }, "billing_merchant_uuid": { "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" }, "billing_processor_mid": { "type": "string", "example": "12345678" }, "payout_type": { "type": "string", "example": "batch", "enum": [ "batch", "individual" ] }, "person": { "required": [ "first_name", "last_name", "email", "phone" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3PersonRequestObject" } ] }, "merchant": { "$ref": "#/components/schemas/V3MerchantRequestObject" }, "beneficial_owners": { "type": "array", "items": { "$ref": "#/components/schemas/V3BeneficialOwnerRequestObject" } }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountObject" }, "actions": { "properties": { "account_intelligence": { "$ref": "#/components/schemas/V3AccountIntelligenceRequestObject" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "The response returned from a successful call to update a merchant.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This merchant was updated successfully." }, "data": { "properties": { "merchant": { "$ref": "#/components/schemas/V3MerchantResponseObject" }, "beneficial_owners": { "type": "array", "items": { "$ref": "#/components/schemas/V3BeneficialOwnerResponseObject" } }, "relations": { "properties": { "person": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, "type": "object" } }, "type": "object" }, "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A merchant matching this UUID was not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This merchant is not available as they have been scheduled for deletion." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3OnboardingValidationErrors" }, { "$ref": "#/components/schemas/V3PersonValidationError" }, { "$ref": "#/components/schemas/V3BusinessValidationError" }, { "$ref": "#/components/schemas/V3BeneficialOwnerValidationError" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "There was a problem on the server and the action could not be completed. Please try again." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/merchants/{uuid}/deactivate": { "post": { "tags": [ "Users", "Stable" ], "summary": "Deactivate a Merchant ( STABLE )", "description": "This endpoint allows for deactivating a Merchant in the GrailPay ACH API Ecosystem. The operation is idempotent: calling it on an already inactive merchant returns 200 and leaves state unchanged.", "operationId": "fd7adf2ef947515bd071a0ab67ffc342", "parameters": [ { "name": "uuid", "in": "path", "description": "merchant UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "reason": { "type": "string", "example": "The merchant requested deactivation.", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "The response returned from a successful call to deactivate a merchant.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This merchant has been deactivated and will no longer be able to transact." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3DeactivateMerchantValidationErrors" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No merchant was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This merchant is not available as they have been scheduled for deletion." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "There was a problem on the server and the action could not be completed. Please try again." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/merchants/{uuid}/activate": { "post": { "tags": [ "Users", "Stable" ], "summary": "Activate a Merchant ( STABLE )", "description": "This endpoint allows for activating a Merchant in the GrailPay ACH API Ecosystem. The operation is idempotent: calling it on an already active merchant returns 200 and leaves state unchanged.", "operationId": "f800ac42a34863bcf448d8400b33d6f7", "parameters": [ { "name": "uuid", "in": "path", "description": "merchant UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "responses": { "200": { "description": "The response returned from a successful call to activate a merchant.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This merchant has been reactivated and is able to transact." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This merchant is not available as they have been scheduled for deletion." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No merchant was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "There was a problem on the server and the action could not be completed. Please try again." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/payouts/standalone": { "post": { "tags": [ "Payouts" ], "summary": "Create a standalone payout", "description": "Creates a vendor standalone payout for an entity. Requires the vendor to have standalone payouts enabled and a pre-funded FBO account configured. Supports idempotency via Idempotency-Key header.", "operationId": "createStandalonePayout", "requestBody": { "description": "Standalone payout creation payload.", "required": true, "content": { "application/json": { "schema": { "required": [ "entity_uuid", "amount", "speed" ], "properties": { "entity_uuid": { "description": "UUID of the recipient entity (User or Merchant or Business). The default bank account will be used.", "type": "string", "format": "uuid", "example": "0ce7f879-0fc9-4d7d-8f40-b0cb89395351" }, "amount": { "description": "Payout amount in cents (e.g., 100 = $1.00)", "type": "integer", "format": "int64", "example": 100, "minimum": 1 }, "speed": { "description": "ACH processing speed. Standard = 1-2 business days, Fast = 2 hours, FedNow = immediate (if supported).", "type": "string", "example": "standard", "enum": [ "standard", "fast", "fednow" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Standalone payout successfully created", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "payout": { "$ref": "#/components/schemas/PayoutResource" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "This entity is currently on hold and is unable to be modified." }, { "example": "This entity is not available as it has been scheduled for deletion." }, { "example": "FedNow is not available on your account. Please contact support." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "019e738a-fda4-70bb-828d-5b517d43aa9f" } }, "type": "object" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "entity_uuid": { "type": "object", "example": [ "The entity uuid field is required.", "The entity uuid field must be a valid UUID.", "No bank account is connected to this entity UUID." ] }, "amount": { "type": "object", "example": [ "The amount field is required.", "The amount must be at least 10 cents." ] }, "speed": { "type": "object", "example": [ "The speed field is required.", "The speed must be one of the following: standard, fast, fednow" ] } }, "type": "object", "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "019e8c03-c60d-72a7-992f-10716cba48cf" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/people": { "get": { "tags": [ "Users", "Stable" ], "summary": "Get All People ( STABLE )", "description": "This endpoint provides a comprehensive list of all registered people, including essential details. Pagination options are available to efficiently manage large datasets.", "operationId": "38b563d2d762e16516d6e2f603607498", "parameters": [ { "name": "filter[uuid]", "in": "query", "description": "Filter by person UUID", "required": false, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, { "name": "filter[client_reference_id]", "in": "query", "description": "Filter by client reference ID", "required": false, "schema": { "type": "string", "example": "reference_12345" } }, { "name": "filter[first_name]", "in": "query", "description": "Filter by first name", "required": false, "schema": { "type": "string", "example": "John" } }, { "name": "filter[last_name]", "in": "query", "description": "Filter by last name", "required": false, "schema": { "type": "string", "example": "Doe" } }, { "name": "sort", "in": "query", "description": "Sort by field (created_at, first_name, last_name). Prefix with '-' for descending order", "required": false, "schema": { "type": "string", "example": "-created_at" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15, "default": 15 } } ], "responses": { "200": { "description": "The response returned from a successful call to listing people.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "people": { "type": "array", "items": { "properties": { "person": { "$ref": "#/components/schemas/V3PersonResponseObject" }, "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "relations": { "oneOf": [ { "$ref": "#/components/schemas/V3MerchantRelationResponseObject" }, { "$ref": "#/components/schemas/V3BusinessRelationResponseObject" }, { "example": null } ] } }, "type": "object" } } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" }, "meta": { "$ref": "#/components/schemas/V3ListingPaginationResponse" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "filter.uuid": { "type": "object", "example": [ "The person UUID must be a valid UUID." ] }, "filter.client_reference_id": { "type": "object", "example": [ "The client reference ID must be a string.", "The client reference ID may not be greater than 255 characters." ] }, "filter.first_name": { "type": "object", "example": [ "The first name must be a string.", "The first name may not be greater than 255 characters." ] }, "filter.last_name": { "type": "object", "example": [ "The last name must be a string.", "The last name may not be greater than 255 characters." ] }, "sort": { "type": "object", "example": [ "The sort option must be one of the followings: created_at, -created_at, first_name, -first_name, last_name, -last_name" ] }, "per_page": { "type": "object", "example": [ "The per page may not be greater than 200.", "The per page must be at least 1.", "The per page must be an integer." ] }, "page": { "type": "object", "example": [ "The page must be an integer.", "The page must be at least 1." ] } }, "type": "object" }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "Users", "Stable" ], "summary": "Onboard a new Person into the ACH application ( STABLE )", "description": "This endpoint allows for adding a new Person to the GrailPay ACH API Ecosystem. The only item that is required is the Bank Account object, but we strongly encourage that you supply as much information as possible. When including the bank account, you can pass either Plaid information or account and routing information. You should never pass both.", "operationId": "f60626f153fa21e572de57ce1c91fc4d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_reference_id": { "type": "string", "example": "reference_12345" }, "billing_merchant_uuid": { "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" }, "billing_processor_mid": { "type": "string", "example": "12345678" }, "payout_type": { "type": "string", "example": "batch", "enum": [ "batch", "individual" ] }, "person": { "$ref": "#/components/schemas/V3PersonRequestObject" }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountObject" }, "actions": { "properties": { "account_intelligence": { "$ref": "#/components/schemas/V3AccountIntelligenceRequestObject" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "The response returned from a successful call to onboard a person.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This person was onboarded successfully." }, "data": { "properties": { "person": { "$ref": "#/components/schemas/V3PersonResponseObject" }, "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3OnboardingValidationErrors" }, { "$ref": "#/components/schemas/V3PersonValidationError" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "There was a problem on the server and the action could not be completed. Please try again." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/people/{uuid}": { "get": { "tags": [ "Users", "Stable" ], "summary": "Get Person ( STABLE )", "description": "This endpoint will return detail of the person. When making a request to an API for a person's information, you typically need to provide a unique identifier UUID. The UUID is generated at the time of registration and is associated with the person's account.", "operationId": "47b283e94efa8d2a514c2c9ef98f6077", "parameters": [ { "name": "uuid", "in": "path", "description": "person UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "responses": { "200": { "description": "The response returned from a successful call to get person.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "person": { "$ref": "#/components/schemas/V3PersonResponseObject" }, "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "relations": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/V3MerchantRelationResponseObject" }, { "$ref": "#/components/schemas/V3BusinessRelationResponseObject" }, { "example": null } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No person was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This person is not available as they have been scheduled for deletion." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "patch": { "tags": [ "Users", "Stable" ], "summary": "Update a Person into the ACH application ( STABLE )", "description": "This endpoint allows for updating a Person to the GrailPay ACH API Ecosystem.", "operationId": "47c342b6509a1330c4e989b172997b71", "parameters": [ { "name": "uuid", "in": "path", "description": "person UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "client_reference_id": { "type": "string", "example": "reference_12345" }, "billing_merchant_uuid": { "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" }, "billing_processor_mid": { "type": "string", "example": "12345678" }, "payout_type": { "type": "string", "example": "batch", "enum": [ "batch", "individual" ] }, "person": { "$ref": "#/components/schemas/V3PersonRequestObject" }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountObject" }, "actions": { "properties": { "account_intelligence": { "$ref": "#/components/schemas/V3AccountIntelligenceRequestObject" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "The response returned from a successful call to update a person.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This person was updated successfully." }, "data": { "properties": { "person": { "$ref": "#/components/schemas/V3PersonResponseObject" }, "account_intelligence": { "oneOf": [ { "$ref": "#/components/schemas/V3AccountIntelligenceV3Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV2Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceV1Response" }, { "$ref": "#/components/schemas/V3AccountIntelligenceThresholdResponse" } ] } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A person matching this UUID was not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This person is not available as they have been scheduled for deletion." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3OnboardingValidationErrors" }, { "$ref": "#/components/schemas/V3PersonValidationError" } ] }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "There was a problem on the server and the action could not be completed. Please try again." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/refunds": { "get": { "tags": [ "Refunds", "Stable" ], "summary": "Get All Refunds ( STABLE )", "description": "This endpoint provides a paginated list of refunds visible to the authenticated user, with filtering and sorting options.", "operationId": "15ab8fb241a8a4e20e23f07b09932965", "parameters": [ { "name": "filter[uuid]", "in": "query", "description": "Filter by refund UUID", "required": false, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, { "name": "filter[status]", "in": "query", "description": "Filter by refund status", "required": false, "schema": { "type": "string", "example": "REFUND_COMPLETE", "enum": [ "REFUND_PENDING", "REFUND_CAPTURE_ACH_PENDING", "REFUND_ACH_PENDING", "REFUND_COMPLETE", "REFUND_FAILED", "REFUND_CANCELLED" ] } }, { "name": "filter[ach_id]", "in": "query", "description": "Filter by capture or refund ACH trace ID", "required": false, "schema": { "type": "string", "example": "ach_1331Ds7MrGmp8iCkEFFdmR" } }, { "name": "filter[r_code]", "in": "query", "description": "Filter by ACH return code", "required": false, "schema": { "type": "string", "example": "R01" } }, { "name": "filter[start_date]", "in": "query", "description": "Filter refunds created on or after this date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "filter[end_date]", "in": "query", "description": "Filter refunds created on or before this date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-12-31" } }, { "name": "filter[amount]", "in": "query", "description": "Filter by amount. Supports dynamic operators (e.g. filter[amount]=100, filter[amount]=>100, filter[amount]=<=500)", "required": false, "schema": { "type": "string", "example": ">=100" } }, { "name": "filter[transaction_uuid]", "in": "query", "description": "Filter by the parent transaction UUID", "required": false, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, { "name": "filter[merchant_uuid]", "in": "query", "description": "Filter by payee or payer merchant UUID", "required": false, "schema": { "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" } }, { "name": "sort", "in": "query", "description": "Sort by field (created_at, amount). Prefix with '-' for descending order", "required": false, "schema": { "type": "string", "example": "-created_at" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15, "default": 15 } } ], "responses": { "200": { "description": "The response returned from a successful call to listing refunds.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "refunds": { "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "client_reference_id": { "type": "string", "example": "reference_12345", "nullable": true }, "status": { "type": "string", "example": "REFUND_COMPLETE", "enum": [ "REFUND_PENDING", "REFUND_CAPTURE_ACH_PENDING", "REFUND_ACH_PENDING", "REFUND_COMPLETE", "REFUND_FAILED", "REFUND_CANCELLED" ] }, "amount": { "type": "number", "format": "float", "example": 100 }, "batch_uuid": { "type": "string", "format": "uuid", "example": null, "nullable": true }, "capture": { "properties": { "trace_id": { "type": "string", "example": "ach_1331Ds7MrGmp8iCkEFFdmR", "nullable": true }, "ach_timestamps": { "properties": { "created_at": { "type": "string", "example": "2024-06-25 13:57:03", "nullable": true }, "processed_at": { "type": "string", "example": "2024-06-26 13:57:03", "nullable": true }, "sent_at": { "type": "string", "example": "2024-06-26 14:57:03", "nullable": true }, "settled_at": { "type": "string", "example": "2024-06-27 13:57:03", "nullable": true }, "failed_at": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "type": "object" }, "payout": { "properties": { "trace_id": { "type": "string", "example": "ach_2442Ds7MrGmp8iCkEFFdmR", "nullable": true }, "ach_timestamps": { "properties": { "created_at": { "type": "string", "example": "2024-06-28 13:57:03", "nullable": true }, "processed_at": { "type": "string", "example": "2024-06-29 13:57:03", "nullable": true }, "sent_at": { "type": "string", "example": "2024-06-29 14:57:03", "nullable": true }, "settled_at": { "type": "string", "example": "2024-06-30 13:57:03", "nullable": true }, "failed_at": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "type": "object" }, "payor": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7b6f-a53b-06fca1f02095", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7d71-bb60-bda7b9a26d1a", "nullable": true }, "type": { "type": "string", "example": "merchant", "nullable": true }, "name": { "type": "string", "example": "John Doe", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "properties": { "aggregator_type": { "type": "string", "example": "manual" }, "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7a76-83bf-aecb05fcb8b3" }, "is_default": { "type": "boolean", "example": true }, "account_number": { "type": "string", "example": "********1234" }, "routing_number": { "type": "string", "example": "*****6789" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" } }, "type": "object" }, "payee": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7abd-8d2b-c233516fa461", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7cd8-8ef3-70162a383e1f", "nullable": true }, "type": { "type": "string", "example": "person", "nullable": true }, "name": { "type": "string", "example": "Nick Johns", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "properties": { "aggregator_type": { "type": "string", "example": "manual" }, "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7764-b1d7-c8fe44e4ba0f" }, "is_default": { "type": "boolean", "example": true }, "account_number": { "type": "string", "example": "********5468" }, "routing_number": { "type": "string", "example": "*****1142" }, "account_name": { "type": "string", "example": "Nick Johns" }, "account_type": { "type": "string", "example": "savings" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" } }, "type": "object" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" } } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" }, "meta": { "$ref": "#/components/schemas/V3ListingPaginationResponse" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "filter.uuid": { "type": "object", "example": [ "The refund UUID field must be a valid UUID." ] }, "filter.transaction_uuid": { "type": "object", "example": [ "The transaction UUID field must be a valid UUID." ] }, "filter.merchant_uuid": { "type": "object", "example": [ "The merchant UUID field must be a valid UUID." ] }, "filter.status": { "type": "object", "example": [ "The status field must be a string.", "The selected status is invalid." ] }, "filter.ach_id": { "type": "object", "example": [ "The ACH ID field must be a string.", "The ACH ID field must not be greater than 255 characters." ] }, "filter.r_code": { "type": "object", "example": [ "The ACH return code field must be a string.", "The ACH return code field must not be greater than 255 characters." ] }, "filter.amount": { "type": "object", "example": [ "The amount field must be a string.", "The amount field format is invalid." ] }, "filter.start_date": { "type": "object", "example": [ "The start date field must match the format Y-m-d.", "The start date field must be a date before or equal to end date." ] }, "filter.end_date": { "type": "object", "example": [ "The end date field must match the format Y-m-d.", "The end date field must be a date after or equal to start date." ] }, "sort": { "type": "object", "example": [ "The sort option field must be a string.", "The sort option must be one of the followings: created_at, -created_at, amount, -amount" ] }, "per_page": { "type": "object", "example": [ "The per page field must be an integer.", "The per page field must be at least 1.", "The per page field must not be greater than 200." ] }, "page": { "type": "object", "example": [ "The page field must be an integer.", "The page field must be at least 1." ] } }, "type": "object" }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/refunds/{uuid}": { "get": { "tags": [ "Refunds", "Stable" ], "summary": "Get Refund ( STABLE )", "description": "This endpoint returns the details of a single refund along with its parent transaction. The UUID is generated when the refund is created and is associated with the refund record.", "operationId": "fc4444653bc3cccf783d03b44d81124d", "parameters": [ { "name": "uuid", "in": "path", "description": "refund UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "responses": { "200": { "description": "The response returned from a successful call to get a refund.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Refund was found successfully." }, "data": { "properties": { "refund": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-75ed-abaa-8ce2c74aa42d" }, "client_reference_id": { "type": "string", "example": "reference_12345", "nullable": true }, "status": { "type": "string", "example": "REFUND_COMPLETE", "enum": [ "REFUND_PENDING", "REFUND_CAPTURE_ACH_PENDING", "REFUND_ACH_PENDING", "REFUND_COMPLETE", "REFUND_FAILED", "REFUND_CANCELLED" ] }, "amount": { "type": "number", "format": "float", "example": 100 }, "batch_uuid": { "type": "string", "format": "uuid", "example": null, "nullable": true }, "capture": { "properties": { "trace_id": { "type": "string", "example": "ach_11mnz9fy1mwkadc", "nullable": true }, "ach_timestamps": { "properties": { "created_at": { "type": "string", "example": "2024-06-25 13:57:03", "nullable": true }, "processed_at": { "type": "string", "example": "2024-06-26 13:57:03", "nullable": true }, "sent_at": { "type": "string", "example": "2024-06-26 14:57:03", "nullable": true }, "settled_at": { "type": "string", "example": "2024-06-27 13:57:03", "nullable": true }, "failed_at": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "type": "object" }, "payout": { "properties": { "trace_id": { "type": "string", "example": "ach_11mtphtz1q0r084", "nullable": true }, "ach_timestamps": { "properties": { "created_at": { "type": "string", "example": "2024-06-28 13:57:03", "nullable": true }, "processed_at": { "type": "string", "example": "2024-06-29 13:57:03", "nullable": true }, "sent_at": { "type": "string", "example": "2024-06-29 14:57:03", "nullable": true }, "settled_at": { "type": "string", "example": "2024-06-30 13:57:03", "nullable": true }, "failed_at": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "type": "object" }, "payor": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7b6f-a53b-06fca1f02095", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7d71-bb60-bda7b9a26d1a", "nullable": true }, "type": { "type": "string", "example": "merchant", "nullable": true }, "name": { "type": "string", "example": "John Doe", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "properties": { "aggregator_type": { "type": "string", "example": "manual" }, "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7a76-83bf-aecb05fcb8b3" }, "is_default": { "type": "boolean", "example": true }, "account_number": { "type": "string", "example": "********1234" }, "routing_number": { "type": "string", "example": "*****6789" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" } }, "type": "object" }, "payee": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7abd-8d2b-c233516fa461", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7cd8-8ef3-70162a383e1f", "nullable": true }, "type": { "type": "string", "example": "person", "nullable": true }, "name": { "type": "string", "example": "Nick Johns", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "properties": { "aggregator_type": { "type": "string", "example": "manual" }, "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7764-b1d7-c8fe44e4ba0f" }, "is_default": { "type": "boolean", "example": true }, "account_number": { "type": "string", "example": "********5468" }, "routing_number": { "type": "string", "example": "*****1142" }, "account_name": { "type": "string", "example": "Nick Johns" }, "account_type": { "type": "string", "example": "savings" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" } }, "type": "object" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" }, "transaction": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "client_reference_id": { "type": "string", "example": "reference_12345", "nullable": true }, "status": { "type": "string", "example": "TRANSACTION_COMPLETE", "nullable": true }, "currency": { "type": "string", "example": "USD" }, "trace_id": { "type": "string", "example": "ach_1331Ds7MrGmp8iCkEFFdmR", "nullable": true }, "amount": { "type": "number", "format": "float", "example": 100 }, "transaction_fee": { "type": "number", "format": "float", "example": 2.5, "nullable": true }, "payout_delay_days": { "type": "integer", "example": 2, "nullable": true }, "company_name": { "type": "string", "example": "Acme Inc", "nullable": true }, "description": { "type": "string", "example": "Payment for invoice #1234", "nullable": true }, "addenda": { "type": "string", "example": "INV-1234", "nullable": true }, "type": { "type": "string", "example": "DEBIT", "nullable": true }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "cancel_reason": { "type": "string", "example": null, "nullable": true }, "declined_reason": { "type": "string", "example": null, "nullable": true }, "payor": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7abd-8d2b-c233516fa461", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7cd8-8ef3-70162a383e1f", "nullable": true }, "type": { "type": "string", "example": "person", "nullable": true }, "name": { "type": "string", "example": "Nick Johns", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "properties": { "aggregator_type": { "type": "string", "example": "manual" }, "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7764-b1d7-c8fe44e4ba0f" }, "is_default": { "type": "boolean", "example": true }, "account_number": { "type": "string", "example": "********5468" }, "routing_number": { "type": "string", "example": "*****1142" }, "account_name": { "type": "string", "example": "Nick Johns" }, "account_type": { "type": "string", "example": "savings" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" } }, "type": "object" }, "payee": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7b6f-a53b-06fca1f02095", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7d71-bb60-bda7b9a26d1a", "nullable": true }, "type": { "type": "string", "example": "merchant", "nullable": true }, "name": { "type": "string", "example": "John Doe", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "properties": { "aggregator_type": { "type": "string", "example": "manual" }, "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7a76-83bf-aecb05fcb8b3" }, "is_default": { "type": "boolean", "example": true }, "account_number": { "type": "string", "example": "********1234" }, "routing_number": { "type": "string", "example": "*****6789" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" } }, "type": "object" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" }, "ach_timestamps": { "properties": { "created_at": { "type": "string", "example": "2024-06-25 13:57:03", "nullable": true }, "processed_at": { "type": "string", "example": "2024-06-26 13:57:03", "nullable": true }, "sent_at": { "type": "string", "example": "2024-06-26 14:57:03", "nullable": true }, "settled_at": { "type": "string", "example": "2024-06-27 13:57:03", "nullable": true }, "failed_at": { "type": "string", "example": null, "nullable": true }, "cancelled_at": { "type": "string", "example": null, "nullable": true }, "declined_at": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This action is unauthorized." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No refund was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/transactions": { "get": { "tags": [ "Transactions", "Stable" ], "summary": "Get All Transactions ( STABLE )", "description": "This endpoint provides a paginated list of transactions visible to the authenticated user, with filtering and sorting options.", "operationId": "30bcf3cbf8a796e444283b6d1f5f68e9", "parameters": [ { "name": "filter[uuid]", "in": "query", "description": "Filter by transaction UUID", "required": false, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, { "name": "filter[status]", "in": "query", "description": "Filter by transaction status", "required": false, "schema": { "type": "string", "example": "CAPTURE_COMPLETE", "enum": [ "CAPTURE_PENDING", "CAPTURE_ACH_PENDING", "CAPTURE_ACH_FAILED", "PAYOUT_PENDING_ACH", "IN_PAYOUT", "CANCELED", "CAPTURE_COMPLETE", "PAUSED", "AWAITING_CANCELLATION", "QUEUED", "DECLINED" ] } }, { "name": "filter[ach_id]", "in": "query", "description": "Filter by ACH trace ID", "required": false, "schema": { "type": "string", "example": "ach_1331Ds7MrGmp8iCkEFFdmR" } }, { "name": "filter[r_code]", "in": "query", "description": "Filter by ACH return code on the transaction or its payout", "required": false, "schema": { "type": "string", "example": "R01" } }, { "name": "filter[client_reference_id]", "in": "query", "description": "Filter by client reference ID (partial match)", "required": false, "schema": { "type": "string", "example": "reference_12345" } }, { "name": "filter[start_date]", "in": "query", "description": "Filter transactions created on or after this date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "filter[end_date]", "in": "query", "description": "Filter transactions created on or before this date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-12-31" } }, { "name": "filter[amount]", "in": "query", "description": "Filter by amount. Supports dynamic operators (e.g. filter[amount]=100, filter[amount]=>100, filter[amount]=<=500)", "required": false, "schema": { "type": "string", "example": ">=100" } }, { "name": "filter[merchant_uuid]", "in": "query", "description": "Filter by payee or payer merchant/business UUID", "required": false, "schema": { "type": "string", "format": "uuid", "example": "6a8fc154-1a50-483b-a690-fd1dfaf9408b" } }, { "name": "filter[person_uuid]", "in": "query", "description": "Filter by payee or payer person UUID", "required": false, "schema": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7d71-bb60-bda7b9a26d1a" } }, { "name": "sort", "in": "query", "description": "Sort by field (created_at, amount). Prefix with '-' for descending order", "required": false, "schema": { "type": "string", "example": "-created_at" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of records per page", "required": false, "schema": { "type": "integer", "example": 15, "default": 15 } } ], "responses": { "200": { "description": "The response returned from a successful call to listing transactions.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "transactions": { "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "client_reference_id": { "type": "string", "example": "reference_12345", "nullable": true }, "status": { "type": "string", "example": "CAPTURE_COMPLETE", "nullable": true }, "currency": { "type": "string", "example": "USD" }, "trace_id": { "type": "string", "example": "ach_1331Ds7MrGmp8iCkEFFdmR", "nullable": true }, "amount": { "type": "number", "format": "float", "example": 100 }, "transaction_fee": { "type": "number", "format": "float", "example": 2.5, "nullable": true }, "payout_delay_days": { "type": "integer", "example": 2, "nullable": true }, "company_name": { "type": "string", "example": "Acme Inc", "nullable": true }, "description": { "type": "string", "example": "Payment for invoice #1234", "nullable": true }, "addenda": { "type": "string", "example": "INV-1234", "nullable": true }, "type": { "type": "string", "example": "DEBIT", "nullable": true }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "cancel_reason": { "type": "string", "example": null, "nullable": true }, "declined_reason": { "type": "string", "example": null, "nullable": true }, "payor": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7b6f-a53b-06fca1f02095", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7d71-bb60-bda7b9a26d1a", "nullable": true }, "type": { "type": "string", "example": "merchant", "nullable": true }, "name": { "type": "string", "example": "John Doe", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "type": "object" }, "payee": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7abd-8d2b-c233516fa461", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7cd8-8ef3-70162a383e1f", "nullable": true }, "type": { "type": "string", "example": "person", "nullable": true }, "name": { "type": "string", "example": "Nick Johns", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "type": "object" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" }, "ach_timestamps": { "$ref": "#/components/schemas/V3AchTimestampsObject" } }, "type": "object" } } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" }, "meta": { "$ref": "#/components/schemas/V3ListingPaginationResponse" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This action is unauthorized." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "properties": { "filter.uuid": { "type": "object", "example": [ "The transaction UUID field must be a valid UUID." ] }, "filter.merchant_uuid": { "type": "object", "example": [ "The merchant UUID field must be a valid UUID." ] }, "filter.person_uuid": { "type": "object", "example": [ "The person UUID field must be a valid UUID." ] }, "filter.status": { "type": "object", "example": [ "The status field must be a string.", "The selected status is invalid." ] }, "filter.ach_id": { "type": "object", "example": [ "The ACH ID field must be a string.", "The ACH ID field must not be greater than 255 characters." ] }, "filter.r_code": { "type": "object", "example": [ "The ACH return code field must be a string.", "The ACH return code field must not be greater than 255 characters." ] }, "filter.client_reference_id": { "type": "object", "example": [ "The client reference ID field must be a string.", "The client reference ID field must not be greater than 255 characters." ] }, "filter.amount": { "type": "object", "example": [ "The amount field must be a string.", "The amount field format is invalid." ] }, "filter.start_date": { "type": "object", "example": [ "The start date field must match the format Y-m-d.", "The start date field must be a date before or equal to end date." ] }, "filter.end_date": { "type": "object", "example": [ "The end date field must match the format Y-m-d.", "The end date field must be a date after or equal to start date." ] }, "sort": { "type": "object", "example": [ "The sort option field must be a string.", "The sort option must be one of the followings: created_at, -created_at, amount, -amount" ] }, "per_page": { "type": "object", "example": [ "The per page field must be an integer.", "The per page field must be at least 1.", "The per page field must not be greater than 200." ] }, "page": { "type": "object", "example": [ "The page field must be an integer.", "The page field must be at least 1." ] } }, "type": "object" }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/transactions/{uuid}": { "get": { "tags": [ "Transactions", "Stable" ], "summary": "Get Transaction ( STABLE )", "description": "This endpoint returns the details of a single transaction along with its payout, refunds and clawback. The UUID is generated when the transaction is created and is associated with the transaction record.", "operationId": "3cca39c5ae839cbb1a3b615b2285f4fb", "parameters": [ { "name": "uuid", "in": "path", "description": "transaction UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "responses": { "200": { "description": "The response returned from a successful call to get a transaction.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Transaction was found successfully." }, "data": { "properties": { "transaction": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "client_reference_id": { "type": "string", "example": "reference_12345", "nullable": true }, "status": { "type": "string", "example": "CAPTURE_COMPLETE", "nullable": true }, "currency": { "type": "string", "example": "USD" }, "trace_id": { "type": "string", "example": "ach_1331Ds7MrGmp8iCkEFFdmR", "nullable": true }, "amount": { "type": "number", "format": "float", "example": 100 }, "transaction_fee": { "type": "number", "format": "float", "example": 2.5, "nullable": true }, "payout_delay_days": { "type": "integer", "example": 2, "nullable": true }, "company_name": { "type": "string", "example": "Acme Inc", "nullable": true }, "description": { "type": "string", "example": "Payment for invoice #1234", "nullable": true }, "addenda": { "type": "string", "example": "INV-1234", "nullable": true }, "type": { "type": "string", "example": "DEBIT", "nullable": true }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "cancel_reason": { "type": "string", "example": null, "nullable": true }, "declined_reason": { "type": "string", "example": null, "nullable": true }, "payor": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7b6f-a53b-06fca1f02095", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7d71-bb60-bda7b9a26d1a", "nullable": true }, "type": { "type": "string", "example": "merchant", "nullable": true }, "name": { "type": "string", "example": "John Doe", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "type": "object" }, "payee": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7abd-8d2b-c233516fa461", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7cd8-8ef3-70162a383e1f", "nullable": true }, "type": { "type": "string", "example": "person", "nullable": true }, "name": { "type": "string", "example": "Nick Johns", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "type": "object" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" }, "ach_timestamps": { "$ref": "#/components/schemas/V3AchTimestampsObject" } }, "type": "object" }, "payout": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-75ed-abaa-8ce2c74aa42d", "nullable": true }, "client_reference_id": { "type": "string", "example": "payout_ref_12345", "nullable": true }, "status": { "type": "string", "example": "PAYOUT_COMPLETE", "nullable": true }, "trace_id": { "type": "string", "example": "ach_2442Ds7MrGmp8iCkEFFdmR", "nullable": true }, "speed": { "type": "string", "example": "standard", "nullable": true }, "amount": { "type": "number", "format": "float", "example": 100 }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" }, "ach_timestamps": { "$ref": "#/components/schemas/V3AchTimestampsObject" } }, "type": "object", "nullable": true }, "refunds": { "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "client_reference_id": { "type": "string", "example": "refund_ref_12345", "nullable": true }, "status": { "type": "string", "example": "REFUND_COMPLETE" }, "amount": { "type": "number", "format": "float", "example": 50 }, "batch_uuid": { "type": "string", "format": "uuid", "example": null, "nullable": true }, "capture": { "properties": { "trace_id": { "type": "string", "example": "ach_2442Ds7MrGmp8iCkEFFdmR", "nullable": true }, "ach_timestamps": { "$ref": "#/components/schemas/V3AchTimestampsObject" } }, "type": "object" }, "payout": { "properties": { "trace_id": { "type": "string", "example": "ach_2442Ds7MrGmp8iCkEFFdmR", "nullable": true }, "ach_timestamps": { "$ref": "#/components/schemas/V3AchTimestampsObject" } }, "type": "object" }, "payer": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7abd-8d2b-c233516fa461", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7cd8-8ef3-70162a383e1f", "nullable": true }, "type": { "type": "string", "example": "person", "nullable": true }, "name": { "type": "string", "example": "Nick Johns", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "type": "object" }, "payee": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7b6f-a53b-06fca1f02095", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7d71-bb60-bda7b9a26d1a", "nullable": true }, "type": { "type": "string", "example": "merchant", "nullable": true }, "name": { "type": "string", "example": "John Doe", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "type": "object" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" } }, "clawback": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-75ed-abaa-8ce2c74aa42d", "nullable": true }, "status": { "type": "string", "example": "CLAWBACK_COMPLETE", "nullable": true }, "amount": { "type": "number", "format": "float", "example": 100 }, "clawback_type": { "type": "string", "example": "TRANSACTION", "nullable": true }, "payee": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7abd-8d2b-c233516fa461", "nullable": true }, "user_uuid": { "type": "string", "format": "uuid", "example": "019e0834-c96a-7cd8-8ef3-70162a383e1f", "nullable": true }, "type": { "type": "string", "example": "person", "nullable": true }, "name": { "type": "string", "example": "Nick Johns", "nullable": true }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "$ref": "#/components/schemas/V3BankAccountResponse" } }, "type": "object" }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "delay_days": { "type": "integer", "example": 2, "nullable": true }, "trace_id": { "type": "string", "example": "ach_2442Ds7MrGmp8iCkEFFdmR", "nullable": true }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" }, "ach_timestamps": { "$ref": "#/components/schemas/V3AchTimestampsObject" } }, "type": "object", "nullable": true } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidParameters400" }, { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } ] } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This action is unauthorized." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No transaction was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/transactions/{uuid}/pause": { "post": { "tags": [ "Transactions", "Stable" ], "summary": "Pause a transaction in the ACH application ( STABLE )", "description": "This endpoint allows to pause a transaction in the GrailPay ACH API Ecosystem.", "operationId": "6d96bf444c9ac9662a061d0b097fe547", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the transaction to pause.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "responses": { "200": { "description": "The response returned from a successful call to pause a transaction.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This transaction has been successfully paused." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "The payout for this transaction has already been created and it is not eligible to be paused." }, { "example": "This transaction has already been canceled and is not eligible to be paused." }, { "example": "This transaction has already failed and is not eligible to be paused." }, { "example": "This transaction is already paused." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No transaction was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/transactions/{uuid}/resume": { "post": { "tags": [ "Transactions", "Stable" ], "summary": "Resume a transaction in the ACH application ( STABLE )", "description": "This endpoint allows to resume a paused transaction in the GrailPay ACH API Ecosystem.", "operationId": "2ecb07bd1c26a607035ddf040f3376f4", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the transaction to resume.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "responses": { "200": { "description": "The response returned from a successful call to resume a transaction.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "The pause has been removed from this transaction and it will now process normally." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This transaction has not been paused, therefore it cannot be resumed." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No transaction was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorIdempotency409" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/transactions/{uuid}/cancel": { "delete": { "tags": [ "Transactions", "Stable" ], "summary": "Cancel a transaction in the ACH application ( STABLE )", "description": "This endpoint allows to cancel a transaction in the GrailPay ACH API Ecosystem.", "operationId": "9dc27221eac690253441292456a4a217", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the transaction to cancel.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "responses": { "200": { "description": "The response returned from a successful call to cancel a transaction.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "oneOf": [ { "example": "The transaction cancellation is currently being processed." }, { "example": "The transaction has been successfully canceled." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "400 - Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V3ErrorInvalidAcceptHeader400" } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "This transaction has already been failed and is not eligible to be canceled." }, { "example": "The payout for this transaction has already been created and it is not eligible to be canceled." }, { "example": "This transaction has already been canceled and cannot be canceled again." }, { "example": "This transaction is already in the process of being canceled and cannot be canceled again." } ] }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "404 - Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No transaction was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong on our side. Please contact support." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/api/v3/vendors/{uuid}/fbo": { "get": { "tags": [ "Vendors", "Stable" ], "summary": "Fetch vendor prefunded FBO account details ( STABLE )", "description": "Returns live account details and available balance for the authenticated vendor's prefunded FBO account. This endpoint is vendor-only and requires the API token to belong to the vendor identified by {uuid}. Account and routing numbers are returned unmasked because the vendor is viewing their own FBO account.", "operationId": "c64b459cec4ca14ba255f4636bf42c60", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the vendor", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } } ], "responses": { "200": { "description": "Vendor prefunded FBO account details retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "", "nullable": true }, "data": { "properties": { "vendor_uuid": { "description": "UUID of the vendor", "type": "string", "format": "uuid", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "name_on_account": { "description": "Account holder name on the prefunded FBO account", "type": "string", "example": "Test Account Holder" }, "account_number": { "description": "Unmasked account number for the vendor's prefunded FBO account", "type": "string", "example": "123456789" }, "routing_number": { "description": "Unmasked routing number for the vendor's prefunded FBO account", "type": "string", "example": "021214891" }, "bank_name": { "description": "Bank name associated with the account's routing number", "type": "string", "example": "Example Bank" }, "balance": { "description": "Available balance in integer cents", "type": "integer", "example": 1234567 }, "currency": { "type": "string", "example": "USD" }, "last_refreshed_at": { "description": "Timestamp when account data was fetched", "type": "string", "example": "2026-06-02 19:00:00" } }, "type": "object" }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "401": { "description": "401 - Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/V3ErrorInvalidToken401" }, { "$ref": "#/components/schemas/V3ErrorUnauthorized401" } ] } } } }, "403": { "description": "403 - Forbidden. Authenticated vendor does not match the vendor UUID in the route, or the token lacks the required ability.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This action is unauthorized." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "404 - Not Found. Vendor not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No vendor was found matching that UUID." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "422": { "description": "422 - No prefunded FBO account is configured for this vendor.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No prefunded FBO account is configured for this vendor." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "503": { "description": "503 - Service Unavailable. Bank is unavailable or the request timed out.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal error while communicating with the requested bank" }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/processor/api/v1/webhook": { "get": { "tags": [ "Webhooks", "Deprecated" ], "summary": "Get registered processor webhooks ( DEPRECATED )", "description": "*This Endpoint is deprecated. Deprecated APIs that are no longer supported and should be removed from your integration. Please use the Stable version for your integration.** Retrieve a list of registered webhooks for the authenticated user.", "operationId": "ea17fb5466ddf4b28bfe45ac2903dfcf", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "type": "array", "items": { "properties": { "event_name": { "type": "string", "example": "TransactionStarted" }, "webhook_url": { "type": "string", "example": "https://example.com/webhook" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-08-01 11:32:28" }, "updated_at": { "type": "string", "format": "date-time", "example": "2023-08-01 11:32:28" } }, "type": "object" }, "example": [ { "event_name": "TransactionStarted", "webhook_url": "https://example.com/webhook", "created_at": "2023-08-01 11:32:28", "updated_at": "2023-08-01 11:32:28" }, { "event_name": "TransactionCompleted", "webhook_url": "https://example.com/webhook", "created_at": "2023-08-01 11:32:28", "updated_at": "2023-08-01 11:32:28" } ] }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } } }, "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "Webhooks", "Deprecated" ], "summary": "Register Processor Webhook ( DEPRECATED )", "description": "*This Endpoint is deprecated. Deprecated APIs that are no longer supported and should be removed from your integration. Please use the Stable version for your integration.** Once registered, the webhook will be triggered by the GrailPay whenever a relevant event occurs, such as a transaction started, completed or failed. The webhook will then send a notification to the configured endpoint, which can be processed by the client application to perform additional actions or update relevant data.", "operationId": "19d231743f43cd383af5b03f3dd28c8b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RegisterWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook registered successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook registered successfully!" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookValidationErrorResponse" } } } } }, "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "Webhooks", "Deprecated" ], "summary": "De-register Processor Webhook ( DEPRECATED )", "description": "*This Endpoint is deprecated. Deprecated APIs that are no longer supported and should be removed from your integration. Please use the Stable version for your integration.** Once deregistered, the previously registered webhook will no longer be triggered by the GrailPay, and notifications will no longer be delivered to the configured endpoint.", "operationId": "90c06c3cd92b3e8e61c09a67630b9cea", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1DeRegisterWebhookRequest" } } } }, "responses": { "200": { "description": "Webhook de-registered successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook de-registered!" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookValidationErrorResponse" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/bank-account/{user_uuid}": { "get": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Get bank account details ( STABLE )", "description": "Retrieve the bank account details for a specific user.", "operationId": "6b4f744643d70e9db1c1dd606151b3b5", "parameters": [ { "name": "user_uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "uuid": { "type": "string", "example": "b1b9b3b0-0b3b-4b3b-8b3b-0b3b3b3b3b3b" }, "account_number": { "type": "string", "example": "1234567890" }, "routing_number": { "type": "string", "example": "123456789" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "aggregator_type": { "type": "string", "example": "plaid" }, "created_at": { "type": "string", "example": "2021-10-01 00:00:00" }, "is_default": { "type": "boolean", "example": true } }, "type": "object" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Linked account has expired", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Linked account has expired" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankUserNotFound" } } } } }, "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "Bank Accounts", "Sunsetting" ], "summary": "Add bank account. ( SUNSETTING )", "description": "Add a bank account for a specific user. **This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "b818f2802799c617fd6e3d50ac90e88f", "parameters": [ { "name": "user_uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AddBankAccountRequest" } } } }, "responses": { "200": { "description": "Bank account already exists", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "We found a matching bank account associated with your account." }, "data": { "properties": { "uuid": { "type": "string", "example": "019f0481-fc63-7a8b-9b6a-f0a8421a2121" }, "account_number": { "type": "string", "example": "1234567890" }, "routing_number": { "type": "string", "example": "123456789" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "aggregator_type": { "type": "string", "example": "manual" }, "created_at": { "type": "string", "example": "2021-10-01 00:00:00" }, "is_default": { "type": "boolean", "example": true } }, "type": "object" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "201": { "description": "Bank account has been added.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Bank account has been added." }, "data": { "properties": { "uuid": { "type": "string", "example": "b1b9b3b0-0b3b-4b3b-8b3b-0b3b3b3b3b3b" }, "account_number": { "type": "string", "example": "1234567890" }, "routing_number": { "type": "string", "example": "123456789" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "aggregator_type": { "type": "string", "example": "plaid" }, "created_at": { "type": "string", "example": "2021-10-01 00:00:00" }, "is_default": { "type": "boolean", "example": true } }, "type": "object" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid routing_number: 000000001. This routing number has an invalid check digit." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankUserNotFound" } } } }, "406": { "description": "Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The requested billing merchant user uuid does not exist." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "string", "example": null }, "errors": { "properties": { "account_number": { "type": "array", "items": { "type": "string", "example": "The account number is required." } } }, "type": "object" }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/bank-account/list/{user_uuid}": { "get": { "tags": [ "Bank Accounts", "Sunsetting" ], "summary": "Get all bank accounts for a user ( SUNSETTING )", "description": "This API retrieves a list of all bank accounts associated with a business or person. The response includes details such as the account number, routing number, account holder's name, account type, and other relevant information. **This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "26aad7e8195c69b4e90671beb920bb16", "parameters": [ { "name": "user_uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1BankAccountListSchema" }, "example": [ { "uuid": "f7a809c8-1987-4627-b1ab-885550cbbb5a", "account_number": "12345678901234", "routing_number": "056008849", "account_name": "Jack Jones", "account_type": "savings", "aggregator_type": "manual", "created_at": "2023-10-16 16:19:42", "is_default": true }, { "uuid": "9abaa7dc-b31d-4fdf-b8a5-e62c8a582c9b", "account_number": "1111222233330000", "routing_number": "011401533", "account_name": "Jack Jones", "account_type": "savings", "aggregator_type": "plaid", "created_at": "2023-11-29 13:31:48", "is_default": false } ] }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not found" }, "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "properties": { "type": { "type": "string", "example": "client_error" }, "subType": { "type": "string", "example": "uuid_not_found" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/bank-account/balance/{user_uuid}": { "post": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Get balance approval ( STABLE )", "description": "Retrieve the balance approval for a specific user.", "operationId": "e1b4c46d14e2bf6d6e685a76905da5ea", "parameters": [ { "name": "user_uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1GetBankAccountBalanceRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BalanceWithAmount" }, { "$ref": "#/components/schemas/BalanceWithApproval" } ] }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Account balance can not be accessed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Only a bank account connected through GrailPay's bank link widget can provide access to the account balance." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankUserNotFound" } } } }, "406": { "description": "Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The requested billing merchant user uuid does not exist." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "string", "example": null }, "errors": { "properties": { "amount": { "type": "array", "items": { "type": "string", "example": "The amount must be integer." } } }, "type": "object" }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/bank-account/switch/default/{user_uuid}": { "put": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Switch default bank account ( STABLE )", "description": "Switch default bank account", "operationId": "2fb93b4d8633f9794a8a6b1b4bbb0706", "parameters": [ { "name": "user_uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Switch default bank account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1SwitchBankAccountRequest" } } } }, "responses": { "200": { "description": "Default bank account updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Default account is updated!" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "404": { "description": "User was not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Default account is updated!" }, "data": { "type": "string", "example": "[]" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "409": { "description": "Same default account", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account is already set as default." }, "data": { "type": "string", "example": "[]" }, "errors": { "type": "string", "example": null }, "error_code": { "properties": { "type": { "type": "string", "example": "client_error" }, "sub_type": { "type": "string", "example": null } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/bank-account/user": { "post": { "tags": [ "Bank Accounts", "Stable" ], "summary": "Get User Details by bank account ( STABLE )", "description": "This API will return the details of the user associated with a specific bank account", "operationId": "a3584eaea5135ea2a0f3358ed223c861", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "bank_account": { "$ref": "#/components/schemas/GetUserDetailsRequest" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/V1BusinessResponse" }, { "$ref": "#/components/schemas/V1RegisterPersonResponse" } ] }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "User delete in progress", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This user is not available as they have been scheduled for deletion." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "404": { "description": "Bank account not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No bank account found with given details." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "properties": { "type": { "type": "string", "example": "client_error" }, "subType": { "type": "string", "example": "account_uuid_not_found" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/register/business": { "post": { "tags": [ "Users", "Deprecated" ], "summary": "Register a new business ( DEPRECATED )", "description": "**This Endpoint is deprecated. Deprecated APIs that are no longer supported and should be removed from your integration. Please use the Stable version for your integration.**", "operationId": "8b1fca9f286ff5db2817efdcce5b20df", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RegisterBusiness" } } } }, "responses": { "201": { "description": "Business registered successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "": { "properties": { "client_reference_id": { "type": "string", "example": "" }, "uuid": { "type": "string", "example": "401c79dd-d38c-4c3a-8edf-1afac5914d2d" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "name": { "type": "string", "example": "Jack Inc." }, "tin": { "type": "string", "example": "961862955" }, "user_status": { "type": "string", "example": "Approved|On Hold|Rejected" }, "kyb_status": { "type": "string", "example": "Approved|In Review|Failed|null" }, "kyb_rejected_reason": { "type": "string", "example": null }, "email": { "type": "string", "example": "" }, "phone": { "type": "string", "example": "" }, "payout_type": { "type": "string", "example": null } }, "type": "object" }, "address": { "properties": { "street_address": { "type": "string", "example": "20 Elmora Ave" }, "additional_address": { "type": "string", "example": "" }, "city": { "type": "string", "example": "Elizabeth" }, "state": { "type": "string", "example": "NJ" }, "country": { "type": "string", "example": "US" }, "zip": { "type": "string", "example": "07202" } }, "type": "object" }, "business_owners": { "properties": { "first_name": { "type": "string", "example": "Olive" }, "last_name": { "type": "string", "example": "Vein" }, "dob": { "type": "string", "example": "1996-05-04" }, "ssn9": { "type": "string", "example": "123456789" }, "address_line_1": { "type": "string", "example": "778 E Encore Dr" }, "city": { "type": "string", "example": "Hanford" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "93230" } }, "type": "object" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-06-03 15:58:44" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-06-04 18:30:30" }, "valid_account": { "type": "string", "example": null } }, "type": "object" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid routing_number: 000000001. This routing number has an invalid check digit." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "406": { "description": "Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The requested billing merchant user uuid does not exist." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "string", "example": null }, "errors": { "properties": { "first_name": { "type": "array", "items": { "type": "string", "example": "The first name must be a string." } } }, "type": "object" }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/user/kyb/{uuid}": { "post": { "tags": [ "Users", "Deprecated" ], "summary": "Update Business KYB ( DEPRECATED )", "description": "**This Endpoint is deprecated. Deprecated APIs that are no longer supported and should be removed from your integration. Please use the Stable version for your integration.**", "operationId": "54b1f88c0786d4b376a9fc1b03eb425a", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1UpdateBusinessKybRequest" } } } }, "responses": { "200": { "description": "Business Successfully updated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "The business KYB has been updated." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid token." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Only business users are allowed to update KYB." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not found." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "406": { "description": "Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The requested billing merchant user uuid does not exist." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "string", "example": null }, "errors": { "properties": { "first_name": { "type": "array", "items": { "type": "string", "example": "The tin is required." } } }, "type": "object" }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/processor/api/v1/batchpayout/{payout_uuid}": { "get": { "tags": [ "Payouts", "Sunsetting" ], "summary": "Fetch a Batch Payout ( Processor Only ) ( SUNSETTING )", "description": "**This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "e87afb402ab70227ffaca9143a40199e", "parameters": [ { "name": "payout_uuid", "in": "path", "description": "Payout UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9bd53fe1-ac74-4e81-b6f2-be88b7c86a68" } } ], "responses": { "200": { "description": "Batch payout details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPayoutResponse" } } } }, "404": { "description": "Batch payout not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch payout not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/register/person": { "post": { "tags": [ "Users", "Stable" ], "summary": "Onboard a new person ( DEPRECATED )", "description": "**This Endpoint is deprecated. Deprecated APIs that are no longer supported and should be removed from your integration. Please use the Stable version for your integration.*", "operationId": "4e6821d5a66192e6734d345b9c4efb04", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RegisterPersonRequest" } } } }, "responses": { "201": { "description": "Person registered successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/V1RegisterPersonResponse" }, { "properties": { "duplicate_uuids": { "type": "array", "items": { "type": "string" }, "example": null }, "valid_account": { "type": "boolean", "example": null } }, "type": "object" } ] } }, "type": "object" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid routing_number: 000000001. This routing number has an invalid check digit." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "406": { "description": "Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The requested billing merchant user uuid does not exist." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "string", "example": null }, "errors": { "properties": { "first_name": { "type": "array", "items": { "type": "string", "example": "The first name must be a string." } } }, "type": "object" }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/transactions/{transaction_uuid}/refunds": { "get": { "tags": [ "Refunds", "Sunsetting" ], "summary": "Get Transaction Refunds ( SUNSETTING )", "description": "This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.", "operationId": "dce69eeb9ea11d563c214d6a45d4d46d", "parameters": [ { "name": "transaction_uuid", "in": "path", "description": "Transaction UUID", "required": true, "schema": { "type": "string", "format": "uuid", "example": "9c2af585-9fea-4c47-ac12-e00f42943cd8" } } ], "responses": { "200": { "description": "Refunds retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundListResponse" } } } }, "404": { "description": "Transaction refunds not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Refunds not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/refunds/{refund_uuid}": { "get": { "tags": [ "Refunds", "Sunsetting" ], "summary": "Get Refund Details ( SUNSETTING )", "description": "This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.", "operationId": "0a6e136f79e4acc012c4c34259adb84e", "parameters": [ { "name": "refund_uuid", "in": "path", "description": "Refund UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Refund details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "transaction_uuid": { "type": "string", "format": "uuid", "example": "9c2af585-9fea-4c47-ac12-e00f42943cd8" }, "refund_uuid": { "type": "string", "format": "uuid", "example": "9c2b3589-160b-45a6-bbad-2694fdd8aeae" }, "amount": { "type": "number", "format": "float", "example": 10 }, "status": { "type": "string", "example": "REFUND_COMPLETE" }, "client_reference_id": { "type": "string", "example": "infiniRefundW@12", "nullable": true }, "payer_uuid": { "type": "string", "format": "uuid", "example": "4a9d2b92-55e6-4234-8732-a4296f73ee21", "nullable": true }, "payee_uuid": { "type": "string", "format": "uuid", "example": "7a70d56c-ee4d-43f1-9021-fc060fb4c460", "nullable": true }, "capture_delay_days": { "type": "integer", "example": 2 }, "payout_delay_days": { "type": "integer", "example": 5 }, "created_at": { "type": "string", "format": "datetime", "example": "2024-03-13T12:00:00Z" }, "updated_at": { "type": "string", "format": "datetime", "example": "2024-03-14T12:00:00Z" }, "failure_code": { "type": "string", "example": "R01", "nullable": true }, "failure_reason": { "type": "string", "example": "Insufficient Funds", "nullable": true } }, "type": "object" }, "errors": { "type": "string", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "404": { "description": "Refund not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Refund not found." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "array", "items": { "type": "string" }, "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/batchrefunds/{batch_refund_uuid}": { "get": { "tags": [ "Refunds", "Sunsetting" ], "summary": "Get Batch Refund ( SUNSETTING )", "description": "This API is processor specific and returns a list of refunds included in the specified batch. **This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "5d9fa6e0be1ff6e7ac5c676c3f4a03bc", "parameters": [ { "name": "batch_refund_uuid", "in": "path", "description": "UUID of the batch refund", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "$ref": "#/components/schemas/BatchRefundResponse" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "404": { "description": "Batch refund not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRefundNotFound" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/transaction": { "post": { "tags": [ "Transactions", "Stable" ], "summary": "Create a new transaction ( STABLE )", "description": "Once authenticated, the client application can send a request to create a new transaction by providing relevant details such as the payment amount, sender and receiver. GrailPay will then return a UUID, which serves as the unique identifier and can be used to fetch the details and status of the transaction. Please note that only one transaction can be created per request.", "operationId": "f96034804914c77cf08a89c767ec8be4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransaction" } } } }, "responses": { "201": { "description": "Transaction details", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "uuid": { "type": "string", "example": "9c330a70-84de-46c3-a380-70b34799b1d3" }, "payer_uuid": { "type": "string", "example": "7d021f9a-b5f4-4668-8d78-0f448f55f984" }, "payee_uuid": { "type": "string", "example": "ec82930a-b59e-4ed2-83dd-0f041bfa5baa" }, "transaction_status": { "type": "string", "example": "QUEUED" }, "currency": { "type": "string", "example": "USD" }, "amount": { "type": "integer", "example": 57163 }, "transaction_fee": { "type": "integer", "example": 0 }, "client_reference_id": { "type": "string", "example": "stageN5@123" }, "payout_delay_days": { "type": "integer", "example": 0 }, "company_name": { "type": "string", "example": "ABC Inc" }, "description": { "type": "string", "example": "ABC Pay" }, "addenda": { "type": "string", "example": "ABC Company Payment" }, "type": { "type": "string", "example": "api" }, "speed": { "type": "string", "example": "sameday" }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "batch_payout_id": { "type": "string", "example": null, "nullable": true }, "capture_status": { "type": "string", "example": "QUEUED", "nullable": true }, "payout_status": { "type": "string", "example": null, "nullable": true }, "clawback_status": { "type": "string", "example": null, "nullable": true }, "reverse_payout_status": { "type": "string", "example": null, "nullable": true }, "failure_code": { "type": "string", "example": null, "nullable": true }, "failure_reason": { "type": "string", "example": null, "nullable": true }, "cancel_reason": { "type": "string", "example": null, "nullable": true }, "payer_bank_account": { "properties": { "uuid": { "type": "string", "example": "9c3306a6-743f-4f8f-9a33-dcd081a06204" }, "aggregator_type": { "type": "string", "example": "manual" } }, "type": "object" }, "payee_bank_account": { "properties": { "uuid": { "type": "string", "example": "9c33090b-c0fb-42ce-9ad8-921665d15a90" }, "aggregator_type": { "type": "string", "example": "manual" } }, "type": "object" }, "trace_ids": { "properties": { "capture_trace_id": { "type": "string", "example": null, "nullable": true }, "payout_trace_id": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "type": "object" }, "errors": { "type": "string", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "To initiate a transaction, either the payer or the payee must undergo KYB verification." }, { "example": "The payer and payee must not be the same person." } ] }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "Merchant ABC Inc cannot process transactions due to compliance restrictions. Please use the V3 Fetch Merchant API endpoint to obtain more details about the failed compliance checks. Please contact support with any questions." }, { "example": "Transaction between the same bank account is prohibited." }, { "example": "This payer has been scheduled for deletion." }, { "example": "This payee has been scheduled for deletion." }, { "example": "Merchant ABC Inc has been deactivated and will no longer be able to transact." }, { "example": "This transaction could not be created because the John is currently On Hold due to a Sanctions Hit." }, { "example": "This transaction could not be created because the John is currently On Hold due to a fraud-related return." }, { "example": "The payer account has been put on hold. Please contact support." }, { "example": "The payee account has been put on hold. Please contact support." }, { "example": "Person-to-person transactions are not enabled." }, { "example": "To initiate a person-to-person transaction, the payee must have approved KYC verification." } ] }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "example": "The payer was not found." }, { "example": "The payee was not found." }, { "example": "No bank account found with given details of payer" }, { "example": "No bank account found with given details of payee" }, { "example": "The payer has not linked their bank account." }, { "example": "The payee has not linked their bank account." } ] }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "string", "example": null }, "errors": { "properties": { "amount": { "type": "object", "example": [ "The amount field is required.", "The amount must be at least 10 cents.", "You have exceeded your maximum transaction limit. Your limit is $70.00, and this transaction of $90.00 exceeds it, so the transaction was not created. Please contact our support." ] }, "payer_uuid": { "type": "object", "example": [ "The payer uuid field is required.", "The payer uuid field must be a valid UUID.", "The selected payer uuid is invalid." ] }, "payee_uuid": { "type": "object", "example": [ "The payee uuid field is required.", "The payee uuid field must be a valid UUID.", "The selected payee uuid is invalid." ] }, "processor_mid": { "type": "object", "example": [ "The processor mid field is required.", "The processor mid field must be a string." ] }, "speed": { "type": "object", "example": [ "The speed should be either standard or sameday." ] }, "source_bank_account.uuid": { "type": "object", "example": [ "The source bank account.uuid field must be a valid UUID.", "The source bank account.uuid field is required when source bank account is present." ] }, "source_bank_account.aggregator_type": { "type": "object", "example": [ "The selected source bank account.aggregator type is invalid.", "The source bank account.aggregator type field is required when source bank account is present." ] }, "destination_bank_account.uuid": { "type": "object", "example": [ "The destination bank account.uuid field must be a valid UUID.", "The destination bank account.uuid field is required when destination bank account is present." ] }, "destination_bank_account.aggregator_type": { "type": "object", "example": [ "The selected destination bank account.aggregator type is invalid.", "The destination bank account.aggregator type field is required when destination bank account is present." ] }, "transaction_fee": { "type": "object", "example": [ "The transaction fee field must not be greater than 500.", "The transaction fee field must be an integer." ] }, "company_name": { "type": "object", "example": [ "The company name field must not be greater than 16 characters." ] }, "description": { "type": "object", "example": [ "The description field must not be greater than 10 characters.", "The description field must be a string." ] }, "addenda": { "type": "object", "example": [ "The addenda field must not be greater than 80 characters.", "The addenda field must be a string." ] }, "client_reference_id": { "type": "object", "example": [ "The client reference id field must be a string." ] } }, "type": "object" }, "error_code": { "type": "string", "example": null }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/transaction/{uuid}": { "get": { "tags": [ "Transactions", "Sunsetting" ], "summary": "Get Transaction by UUID ( SUNSETTING )", "description": "When making a request to an API for a transaction's information, you typically need to provide a unique identifier UUID. The UUID is generated at the time of creating a transaction and is associated with the each transaction. **This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "ab695e39afb4b6787cff69d129b1e937", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the transaction", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction details", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "$ref": "#/components/schemas/V1TransactionResponse" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Transaction not found" }, "data": { "type": "object", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "Transactions", "Sunsetting" ], "summary": "Cancel a transaction ( SUNSETTING )", "description": "A transaction can only be canceled while in the CAPTURE_PENDING state. You can no longer cancel a transaction after the ACH capture process has begun. **This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "3de6f150a2a32338247e0576eadfea41", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the transaction to cancel", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Transaction canceled successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Trnasaction can not be cancelled", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "oneOf": [ { "type": "string", "example": "Your transaction cannot be cancelled now because it has already been cancelled." }, { "type": "string", "example": "Your transaction cannot be cancelled now because it has already been failed." }, { "type": "string", "example": "Your transaction can not be canceled now because it has already been processed." }, { "type": "string", "example": "Cancelling a transaction is not for instant ach transactions." } ] }, "data": { "type": "object", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Transaction not found" }, "data": { "type": "object", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/transaction/list": { "get": { "tags": [ "Transactions", "Sunsetting" ], "summary": "Get Transaction List ( SUNSETTING )", "description": "Get a list of transactions. **This Endpoint is Sunsetting and you should use the stable endpoint. Sunsetting APIs that are still supported but scheduled for deprecation.**", "operationId": "ca79263d4cbdc0814fc25b20757d9934", "parameters": [ { "name": "startDate", "in": "query", "description": "Filter transactions created after this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "description": "Filter transactions created before this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "description": "Number of transactions per page", "schema": { "type": "integer", "enum": [ "10", "20", "50", "100", "200" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "" }, "data": { "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/V1TransactionResponse" } }, "pagination": { "properties": { "totalItems": { "type": "integer", "example": 53 }, "pageSize": { "type": "integer", "example": 10 }, "currentPage": { "type": "integer", "example": 6 }, "totalPages": { "type": "integer", "example": 6 } }, "type": "object" } }, "type": "object" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Forbidden" }, "data": { "type": "object", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Transaction not found" }, "data": { "type": "object", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/transactions/{uuid}/refund": { "post": { "tags": [ "Refunds", "Stable" ], "summary": "Refund a transaction ( STABLE )", "description": "Once a transaction has been completed, this API can be used to issue a refund, thereby clawing back funds from the payee and transferring them back to the payor. An optional amount can be specified to either issue a partial refund or add additional fees to the original amount. If the amount is not specified, the total transaction amount is refunded.", "operationId": "d88ce5d80658c8999d1ca01633290d01", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the transaction to refund", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RefundTransactionRequest" } } } }, "responses": { "201": { "description": "Refund created", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "$ref": "#/components/schemas/V1RefundTransactionResponse" }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Transaction not found" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } } }, "security": [ { "ApiToken": [] } ] } }, "/3p/api/v1/webhook": { "get": { "tags": [ "Webhooks", "Stable" ], "summary": "Get registered webhooks ( STABLE )", "description": "Retrieve a list of registered webhooks for the authenticated user.", "operationId": "71449a2d892d7bb4362aeab26395ce42", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "type": "array", "items": { "properties": { "event_name": { "type": "string", "example": "TransactionStarted" }, "webhook_url": { "type": "string", "example": "https://example.com/webhook" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-08-01 11:32:28" }, "updated_at": { "type": "string", "format": "date-time", "example": "2023-08-01 11:32:28" } }, "type": "object" }, "example": [ { "event_name": "TransactionStarted", "webhook_url": "https://example.com/webhook", "created_at": "2023-08-01 11:32:28", "updated_at": "2023-08-01 11:32:28" }, { "event_name": "TransactionCompleted", "webhook_url": "https://example.com/webhook", "created_at": "2023-08-01 11:32:28", "updated_at": "2023-08-01 11:32:28" } ] }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } } }, "security": [ { "ApiToken": [] } ] }, "post": { "tags": [ "Webhooks", "Stable" ], "summary": "Register Webhook ( STABLE )", "description": "Registering a webhook via API call involves configuring a client application to receive notifications and updates from GrailPay. To enable notification related to transaction, you need to register webhook with sets of predefined Events.", "operationId": "ffad4d3dd269ae7a2b6cd12e5bac2256", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RegisterWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook registered successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook registered successfully!" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookValidationErrorResponse" } } } } }, "security": [ { "ApiToken": [] } ] }, "delete": { "tags": [ "Webhooks", "Stable" ], "summary": "De-register Webhook ( STABLE )", "description": "Deregistering a webhook via API involves removing a previously registered webhook configuration from the GrailPay. To disable notification related to particular transaction events, you need to de-register webhook with registered events name.", "operationId": "a9141fe6e6da5b72d879e19856392b7c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1DeRegisterWebhookRequest" } } } }, "responses": { "200": { "description": "Webhook de-registered successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook de-registered!" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error401Unauthorized" }, { "$ref": "#/components/schemas/Error401InvalidTokenStructure" }, { "$ref": "#/components/schemas/Error401InvalidTokenData" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403ForbiddenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookValidationErrorResponse" } } } } }, "security": [ { "ApiToken": [] } ] } } }, "components": { "schemas": { "CustomBankAccount": { "required": [ "account_number", "routing_number", "account_name", "account_type" ], "properties": { "account_number": { "type": "string", "example": "123456789" }, "routing_number": { "type": "string", "example": "123456789" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" } }, "type": "object" }, "PlaidAccount": { "required": [ "account_id", "access_token" ], "properties": { "account_id": { "type": "string", "example": "123456789" }, "access_token": { "type": "string", "example": "token123" } }, "type": "object" }, "V2BankAccountRequest": { "description": "Bank account can be either Plaid or Custom, not both", "oneOf": [ { "required": [ "custom" ], "properties": { "custom": { "$ref": "#/components/schemas/CustomBankAccount" } }, "type": "object" }, { "required": [ "plaid" ], "properties": { "plaid": { "$ref": "#/components/schemas/PlaidAccount" } }, "type": "object" } ] }, "Business": { "required": [ "name", "tin", "address" ], "properties": { "name": { "type": "string", "example": "John Incorporation" }, "tin": { "type": "string", "example": "123456789" }, "transaction_fee_percent": { "type": "number", "format": "float", "example": 2.5 }, "transaction_fee_fixed": { "type": "number", "format": "integer", "example": 100 }, "maximum_transaction_fee": { "type": "number", "format": "integer", "example": 1000 }, "payout_type": { "type": "string", "example": "individual", "nullable": true, "enum": [ "batch", "individual" ] }, "trading_name": { "type": "string", "example": "John Incorporation" }, "entity_type": { "type": "string", "example": "Sole Trader" }, "incorporation_date": { "type": "string", "example": "2024-02-02" }, "incorporation_state": { "type": "string", "example": "CO" }, "industry": { "type": "string", "example": "Nature of business" }, "industry_classification": { "properties": { "code_type": { "type": "string", "example": "SIC" }, "codes": { "type": "array", "items": { "type": "string", "example": "NAICS 42" } }, "description": { "type": "string", "example": "abcdefg" } }, "type": "object" }, "source_of_wealth": { "type": "string", "example": "2344" }, "source_of_funds": { "type": "string", "example": "skjdkd" }, "first_transaction_completed_at": { "type": "string", "example": "2024-05-02 16:14:25" }, "product_type": { "type": "string", "example": "financial" }, "registered_as_inactive": { "type": "boolean", "example": false }, "address_type": { "type": "string", "example": "Registered" }, "address": { "$ref": "#/components/schemas/Address" } }, "type": "object" }, "Address": { "required": [ "line_1", "city", "state", "zip" ], "properties": { "line_1": { "type": "string", "example": "10554 W Quarles Ave" }, "line_2": { "type": "string", "example": "Suite 123" }, "city": { "type": "string", "example": "Littleton" }, "state": { "type": "string", "example": "CO" }, "zip": { "type": "string", "example": "80127" } }, "type": "object" }, "BusinessOwner": { "required": [ "first_name", "last_name", "dob", "ssn9", "address", "email", "phone" ], "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Dew" }, "dob": { "type": "string", "example": "2023-04-11" }, "ssn9": { "type": "string", "example": "123456789" }, "address": { "$ref": "#/components/schemas/Address" }, "is_beneficial_owner": { "type": "boolean", "example": true }, "is_director": { "type": "boolean", "example": false }, "is_account_owner": { "type": "boolean", "example": false }, "is_share_holder": { "type": "boolean", "example": false }, "is_significant_control_person": { "type": "boolean", "example": false }, "ownership_percentage": { "type": "number", "format": "float", "example": 25 }, "email": { "type": "string", "example": "[email protected]" }, "phone": { "type": "string", "example": "2457856490" }, "occupation": { "type": "string", "example": "Co-founder" }, "first_transaction_completed_at": { "type": "string", "example": "2024-05-02 16:14:25" }, "product_type": { "type": "string", "example": "financial" } }, "type": "object" }, "Error400": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Parameters Received" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "Error400InvalidAcceptHeader": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid value provided for Accept header." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "Error400InvalidPlaidAccount": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid plaid account ID or access token." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "Error400UnverifiedPlaidAccount": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Plaid account ID couldn't be verified." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "Error400InvalidRoutingNumber": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid routing_number: 000000000. This routing number is invalid." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "Error401Unauthorized": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid token" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "Error401UnauthorizedProcessor": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This action is unauthorized." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "Error401InvalidTokenStructure": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid token format. The token should be in the following format: ID|TOKEN_VALUE. Example: 12345|abcdefg" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "UserNotFound": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The User was not found" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "Error401InvalidTokenData": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid token format. The ID in the token must be an integer. Example: 12345|abcdefg" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "Error403ForbiddenResponse": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied. Please use a secure (HTTPS) connection." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "Error409": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The request cannot be executed due to a detected conflict with a duplicate request." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": "server_error" } }, "type": "object" }, "Error500": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal server error occurred." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": "server_error" } }, "type": "object" }, "BusinessValidationError": { "properties": { "kyb": { "type": "object", "example": [ "The kyb field must be true or false." ] }, "client_reference_id": { "type": "object", "example": [ "The Client reference id must be a string.", "The Client reference id may not be greater than 255 characters." ] }, "payout_type": { "type": "object", "example": [ "The payout type must be a string.", "The payout type should be either individual or batch." ] }, "first_name": { "type": "object", "example": [ "The First name must be a string.", "The first name may not be greater than 56 characters.", "The First name field is required." ] }, "last_name": { "type": "object", "example": [ "The Last name must be a string.", "The last name may not be greater than 56 characters.", "The Last name field is required." ] }, "email": { "type": "object", "example": [ "The Email must be a valid email address.", "The Email field is required." ] }, "phone": { "type": "object", "example": [ "The Phone must be a string.", "Phone numbers should consist of 10 digits and should not contain the +1 prefix or any special characters.", "The Phone field is required." ] }, "business": { "type": "object", "example": [ "The business field is required." ] }, "business.name": { "type": "object", "example": [ "The Business name must be a string.", "The Business name may not be greater than 64 characters.", "The Business name field is required." ] }, "business.tin": { "type": "object", "example": [ "The Tin number must be a string.", "The Tin number must consist of 9 digit.", "The Tin number field is required." ] }, "business.trading_name": { "type": "object", "example": [ "The Business trading name must be a string.", "The Business trading name field is required." ] }, "business.entity_type": { "type": "object", "example": [ "The Entity type must be a string.", "The Entity type field is required." ] }, "business.incorporation_date": { "type": "object", "example": [ "The Incorporation date is not a valid date.", "The Incorporation date does not match the format Y-m-d.", "The Incorporation date field is required." ] }, "business.incorporation_state": { "type": "object", "example": [ "The Incorporation state must be a string.", "The Incorporation state must be valid US state.", "The Incorporation state field is required." ] }, "business.industry": { "type": "object", "example": [ "The Industry must be a string." ] }, "business.industry_classification.code_type": { "type": "object", "example": [ "The Industry classification code type must be a string.", "The Industry classification code type is required when industry classification is present." ] }, "business.industry_classification.codes": { "type": "object", "example": [ "The Industry classification codes is required when industry classification is present.", "The business.industry_classification.codes.0 must be a string." ] }, "business.industry_classification.description": { "type": "object", "example": [ "The Industry classification description must be a string.", "The Industry classification description is required when industry classification is present." ] }, "business.source_of_wealth": { "type": "object", "example": [ "The Source of wealth must be a string." ] }, "business.first_transaction_completed_at": { "type": "object", "example": [ "The First transaction completed date does not match the format Y-m-d H:i:s.", "The First transaction completed date must be a date before now." ] }, "business.address_type": { "type": "object", "example": [ "The Address type must be a string.", "The Address type field is required." ] }, "business.address": { "type": "object", "example": [ "The business.address field is required." ] }, "business.address.line_1": { "type": "object", "example": [ "The Business address line 1 must be a string.", "The Business address line 1 field is required." ] }, "business.address.line_2": { "type": "object", "example": [ "The Business address line 2 must be a string." ] }, "business.address.city": { "type": "object", "example": [ "The Business city name must be a string.", "The Business city name may not be greater than 56 characters.", "The Business city name field is required.", "The Business city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces." ] }, "business.address.state": { "type": "object", "example": [ "The Business state name must be a string.", "The Business state name may not be greater than 2 characters.", "The Business state name must be valid US state.", "The Business state name field is required." ] }, "business.address.zip": { "type": "object", "example": [ "The Business zip code must be a string.", "The Business zip code must consist of 5 digit.", "The Business zip code field is required." ] }, "business.transaction_fee_percent": { "type": "object", "example": [ "The Transaction fee percent must be a number.", "The Transaction fee percent may not be greater than 99.99.", "The Transaction fee percent must be at least 0." ] }, "business.maximum_transaction_fee": { "type": "object", "example": [ "The business maximum transaction fee must be an integer.", "The business maximum transaction fee must be at least 0." ] }, "business.transaction_fee_fixed": { "type": "object", "example": [ "The business transaction fee fixed must be an integer.", "The business transaction fee fixed must be at least 0." ] }, "bank_account.plaid": { "type": "object", "example": [ "If a bank account exists, Plaid should not be presented.", "The Plaid account id and access token is required." ] }, "bank_account.plaid.access_token": { "type": "object", "example": [ "The Plaid access token is required when plaid is present.", "The Plaid access token must be a string." ] }, "bank_account.plaid.account_id": { "type": "object", "example": [ "The Plaid account id is required when plaid is present.", "The Plaid account id must be a string." ] }, "bank_account.custom": { "type": "object", "example": [ "If a plaid account exists, Bank account should not be presented.", "The Bank account routing number, account number, name of account and account type is required." ] }, "bank_account.custom.account_number": { "type": "object", "example": [ "The Bank account number must be a string.", "The Bank account number may not be greater than 17 characters.", "The Bank account number is required when bank account is present." ] }, "bank_account.custom.routing_number": { "type": "object", "example": [ "The Bank routing number must be a number.", "The Bank routing number must consist of 9 digit", "The Bank routing number is required when bank account is present." ] }, "bank_account.custom.account_name": { "type": "object", "example": [ "The Bank account name must be a string.", "The Bank account name is required when bank account is present." ] }, "bank_account.custom.account_type": { "type": "object", "example": [ "The Bank account type must be a string.", "The Bank account type should be either savings or checking.", "The Bank account type is required when bank account is present." ] }, "bank_account.custom.validate_account_routing": { "type": "object", "example": [ "The Validate account and routing number field must be true or false." ] }, "billing_merchant_user_uuid": { "type": "object", "example": [ "The requested billing merchant user uuid does not exist.", "The Billing Merchant User UUID must be a valid UUID.", "The billing merchant is deleted and cannot be used for billing purposes." ] }, "billing_processor_mid": { "type": "object", "example": [ "The requested billing processor MID does not exist.", "The billing processor MID is deleted and cannot be used for billing purposes." ] }, "business_owners": { "type": "object", "example": [ "The Business owners field is required.", "The number of Business owners should not exceed 5" ] }, "business_owners.0.first_name": { "type": "object", "example": [ "The Business owner first name must be a string.", "The Business owner first name may not be greater than 56 characters.", "The Business owner first name field is required." ] }, "business_owners.0.last_name": { "type": "object", "example": [ "The Business owner last name must be a string.", "The Business owner last name may not be greater than 56 characters.", "The Business owner last name field is required." ] }, "business_owners.0.email": { "type": "object", "example": [ "The Business owner email must be a valid email address.", "The Business owner email field is required." ] }, "business_owners.0.phone": { "type": "object", "example": [ "The Business owner phone must be a string.", "The Business owner phone should consist of 10 digits without the +1 prefix.", "The Business owner phone field is required." ] }, "business_owners.0.dob": { "type": "object", "example": [ "The Business owner date of birth does not match the format Y-m-d.", "The Business owner date of birth field is required." ] }, "business_owners.0.ssn9": { "type": "object", "example": [ "The Business owner SSN must be a string.", "The ssn9 must consist of 9 digits.", "The Business owner SSN field is required.", "Social security numbers must adhere to the following constraints. The number may not begin with 000, the middle digits cannot be 00, and the ending digits cannot be 0000.", "Invalid ITIN: 4th and 5th digits should range from 50 to 65, 70 to 88, 90 to 92, and 94 to 99." ] }, "business_owners.0.address.line_1": { "type": "object", "example": [ "The Business owner address line 1 must be a string.", "The Business owner address line 1 field is required." ] }, "business_owners.0.address.line_2": { "type": "object", "example": [ "The Business owner address line 2 must be a string." ] }, "business_owners.0.address.city": { "type": "object", "example": [ "The Business owner city name must be a string.", "The Business owner city name may not be greater than 56 characters.", "The Business owner city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces.", "The Business owner city name field is required." ] }, "business_owners.0.address.state": { "type": "object", "example": [ "The Business owner state name must be a string.", "The Business owner state name may not be greater than 2 characters.", "The Business owner state name must be valid US state.", "The Business owner state name field is required." ] }, "business_owners.0.address.zip": { "type": "object", "example": [ "The Business owner zip code must be a string.", "The Business owner zip code must consist of 5 digit.", "The Business owner zip code field is required." ] }, "business_owners.0.is_beneficial_owner": { "type": "object", "example": [ "The Business owner is beneficial owner field must be true or false." ] }, "business_owners.0.is_director": { "type": "object", "example": [ "The Business owner is director field must be true or false." ] }, "business_owners.0.is_account_owner": { "type": "object", "example": [ "The Business owner is account owner field must be true or false." ] }, "business_owners.0.is_share_holder": { "type": "object", "example": [ "The Business owner is share holder field must be true or false." ] }, "business_owners.0.is_significant_control_person": { "type": "object", "example": [ "The Business owner is significant control person field must be true or false." ] }, "business_owners.0.occupation": { "type": "object", "example": [ "The Business owner occupation must be a string." ] }, "business_owners.0.ownership_percentage": { "type": "object", "example": [ "The Business owner ownership percentage must be a number.", "The Business owner ownership percentage must be between 0 and 100." ] }, "business_owners.0.first_transaction_completed_at": { "type": "object", "example": [ "The Business owner first transaction completed date does not match the format Y-m-d H:i:s.", "The Business owner first transaction completed date must be a date before now." ] }, "business_owners.0.product_type": { "type": "object", "example": [ "The Business owner product type must be a string." ] }, "business_owners.0.registered_as_inactive": { "type": "object", "example": [ "The Registered as inactive field must be true or false." ] } }, "type": "object" }, "V2OnboardBusinessResponse": { "title": "Business Response", "description": "Schema for a Business response", "properties": { "status": { "description": "Response status", "type": "boolean", "example": true }, "message": { "description": "Response message", "type": "string" }, "data": { "description": "Business data", "properties": { "client_reference_id": { "type": "string", "example": "company_45458" }, "uuid": { "type": "string", "example": "9d264b4a-006c-4d01-acd0-730e27784c59" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Dew" }, "email": { "type": "string", "example": "john.dew@example.com" }, "phone": { "type": "string", "example": "2457856490" }, "business": { "properties": { "name": { "type": "string", "example": "John Incorporation" }, "tin": { "type": "string", "example": "922454715" }, "address_type": { "type": "string", "example": "Registered" }, "address": { "properties": { "street_address": { "type": "string", "example": "10554 W Quarles Ave" }, "additional_address": { "type": "string", "example": "Suite 123" }, "city": { "type": "string", "example": "Littleton" }, "state": { "type": "string", "example": "CO" }, "country": { "type": "string", "example": "US" }, "zip": { "type": "string", "example": "80127" } }, "type": "object" }, "trading_name": { "type": "string", "example": "John Incorporation" }, "entity_type": { "type": "string", "example": "Sole Trader" }, "incorporation_date": { "type": "string", "format": "date", "example": "2024-02-02" }, "incorporation_state": { "type": "string", "example": "CO" }, "industry": { "type": "string", "example": "Nature of business" }, "industry_classification": { "properties": { "code_type": { "type": "string", "example": "SIC" }, "codes": { "type": "array", "items": { "type": "string" }, "example": [ "NAICS 42", "NAICS 45" ] }, "description": { "type": "string", "example": "NAICS" } }, "type": "object" }, "source_of_wealth": { "type": "string", "example": "2344" }, "source_of_funds": { "type": "string", "example": "Industry" }, "first_transaction_completed_at": { "type": "string", "format": "date-time", "example": "2024-05-02 16:14:25" }, "product_type": { "type": "string", "example": "financial" }, "registered_as_inactive": { "type": "boolean", "example": false }, "transaction_fee_percent": { "type": "number", "format": "float", "example": 2.5, "nullable": true }, "transaction_fee_fixed": { "type": "integer", "example": 100, "nullable": true }, "maximum_transaction_fee": { "type": "integer", "example": 1000, "nullable": true } }, "type": "object" }, "user_status": { "type": "string", "example": "APPROVED" }, "kyb_status": { "type": "string", "example": "APPROVED" }, "kyb_rejected_reason": { "type": "string", "example": null, "nullable": true }, "payout_type": { "type": "string", "example": "batch" }, "role": { "type": "string", "example": "business" }, "vendor_name": { "type": "string", "example": "Fintech" }, "business_owners": { "type": "array", "items": { "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Dew" }, "dob": { "type": "string", "format": "date", "example": "2023-04-11" }, "ssn9": { "type": "string", "example": "123456789" }, "address_line_1": { "type": "string", "example": "10554 W Quarles Ave" }, "address_line_2": { "type": "string", "example": "Suite 123" }, "city": { "type": "string", "example": "Littleton" }, "state": { "type": "string", "example": "CO" }, "zip": { "type": "string", "example": "80127" }, "is_beneficial_owner": { "type": "boolean", "example": true }, "is_director": { "type": "boolean", "example": false }, "is_account_owner": { "type": "boolean", "example": false }, "is_share_holder": { "type": "boolean", "example": false }, "is_significant_control_person": { "type": "boolean", "example": false }, "ownership_percentage": { "type": "number", "format": "float", "example": 25 }, "email": { "type": "string", "example": "john.dew@example.com" }, "phone": { "type": "string", "example": "2457856490" }, "nationality": { "type": "string", "example": "US" }, "occupation": { "type": "string", "example": "Co-founder" }, "first_transaction_completed_at": { "type": "string", "format": "date-time", "example": "2024-05-02 16:14:25" }, "product_type": { "type": "string", "example": "financial" } }, "type": "object" } }, "valid_account": { "type": "string", "example": "Valid" }, "bank_account": { "properties": { "risk": { "properties": { "confidence_score": { "type": "number", "format": "float", "example": "0.83", "nullable": true }, "threshold": { "type": "number", "format": "float", "example": "0.61", "nullable": true } }, "type": "object" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-10-02 14:06:14" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-10-02 14:06:17" } }, "type": "object" }, "errors": { "description": "Error details if any", "type": "object", "nullable": true }, "error_code": { "description": "Error code if any", "type": "string", "nullable": true } }, "type": "object" }, "V2OnboardPersonResponse": { "title": "Person Response", "description": "Schema for a person response", "properties": { "status": { "description": "Response status", "type": "boolean", "example": true }, "message": { "description": "Response message", "type": "string" }, "data": { "description": "User data", "properties": { "client_reference_id": { "description": "Client reference ID", "type": "string", "example": "company_45458" }, "uuid": { "description": "User UUID", "type": "string", "format": "uuid", "example": "9d264b4a-006c-4d01-acd0-730e27784c59" }, "first_name": { "description": "User first name", "type": "string", "example": "John" }, "last_name": { "description": "User last name", "type": "string", "example": "Dew" }, "email": { "description": "User email address", "type": "string", "format": "email", "example": "john.dew@example.com" }, "phone": { "description": "User phone number", "type": "string", "example": "2457856490" }, "user_status": { "description": "User status", "type": "string", "example": "APPROVED" }, "payout_type": { "description": "Payout Type", "type": "string", "example": "individual" }, "address": { "description": "User address details", "properties": { "street_address": { "description": "Street address", "type": "string", "example": "10554 W Quarles Ave" }, "city": { "description": "City", "type": "string", "example": "Littleton" }, "state": { "description": "State", "type": "string", "example": "CO" }, "country": { "description": "Country", "type": "string", "example": "US" }, "zip": { "description": "Zip code", "type": "string", "example": "80127" } }, "type": "object" }, "role": { "type": "string", "example": "Person" }, "vendor_name": { "description": "Vendor name", "type": "string", "example": "Fintech" }, "valid_account": { "type": "string", "example": "Valid" }, "bank_account": { "properties": { "risk": { "properties": { "confidence_score": { "type": "number", "format": "float", "example": "0.83", "nullable": true }, "threshold": { "type": "number", "format": "float", "example": "0.61", "nullable": true } }, "type": "object" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-10-02 14:06:14" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-10-02 14:06:17" } }, "type": "object" }, "errors": { "description": "Error details if any", "type": "object", "nullable": true }, "error_code": { "description": "Error code if any", "type": "string", "nullable": true } }, "type": "object" }, "V3BusinessRequestObject": { "title": "Business Request Object", "description": "Schema for a business request object", "properties": { "name": { "type": "string", "example": "Acme Inc." }, "trading_name": { "type": "string", "example": "Acme Corp" }, "address": { "oneOf": [ { "$ref": "#/components/schemas/V3AddressObject" } ], "nullable": true } }, "type": "object" }, "V3BusinessResponseObject": { "properties": { "uuid": { "type": "string", "example": "a77dbb10-3686-4caf-9acd-52b3cc455db2" }, "business_type": { "type": "string", "example": "business" }, "name": { "type": "string", "example": "Acme Inc." }, "trading_name": { "type": "string", "example": "Acme Corp" }, "payout_type": { "type": "string", "example": "batch" }, "client_reference_id": { "type": "string", "example": "reference_12345" }, "address": { "$ref": "#/components/schemas/V3AddressObject" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" }, "V3BusinessRelationResponseObject": { "properties": { "business": { "properties": { "uuid": { "type": "string", "example": "a77dbb10-3686-4caf-9acd-52b3cc455db2" } }, "type": "object" } }, "type": "object" }, "V3MerchantRequestObject": { "title": "Merchant Request Object", "description": "Schema for a merchant request object", "required": [ "name", "tin", "trading_name", "entity_type", "address" ], "properties": { "name": { "type": "string", "example": "Acme Inc." }, "tin": { "type": "string", "example": "123456789" }, "trading_name": { "type": "string", "example": "Acme Corp" }, "entity_type": { "type": "string", "example": "Sole Trader" }, "incorporation_date": { "type": "string", "format": "date", "example": "2024-02-02" }, "incorporation_state": { "type": "string", "example": "CO" }, "address_type": { "type": "string", "example": "Registered" }, "address": { "required": [ "line_1", "city", "state", "zip" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3AddressObject" } ] }, "transaction_fee_percent": { "type": "number", "format": "float", "example": 2.5 }, "transaction_fee_fixed": { "type": "number", "example": 100 }, "maximum_transaction_fee": { "type": "number", "example": 5000 } }, "type": "object" }, "V3BeneficialOwnerRequestObject": { "title": "Beneficial Owner Request Object", "description": "Schema for a beneficial owner request object", "required": [ "first_name", "last_name", "dob", "ssn9", "address", "is_beneficial_owner", "is_director", "is_significant_control_person", "email", "phone", "occupation" ], "properties": { "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "dob": { "type": "string", "format": "date", "example": "2023-04-11" }, "ssn9": { "type": "string", "example": "123456789" }, "address": { "required": [ "line_1", "city", "state", "zip" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/V3AddressObject" } ] }, "is_beneficial_owner": { "type": "boolean", "example": true }, "is_director": { "type": "boolean", "example": false }, "is_significant_control_person": { "type": "boolean", "example": false }, "ownership_percentage": { "type": "number", "format": "float", "example": 25 }, "email": { "type": "string", "example": "owner@test.com" }, "phone": { "type": "string", "example": "2457856490" }, "occupation": { "type": "string", "example": "Co-founder" } }, "type": "object" }, "V3MerchantResponseObject": { "properties": { "uuid": { "type": "string", "example": "c6bcfbbb-98ff-4d8b-a8f5-1559c3dcb718" }, "business_type": { "type": "string", "example": "merchant" }, "kyb_status": { "type": "string", "example": "IN_REVIEW" }, "kyb_rejected_reason": { "type": "string", "example": null }, "name": { "type": "string", "example": "Acme Inc." }, "tin": { "type": "string", "example": "123456789" }, "trading_name": { "type": "string", "example": "Acme Corp" }, "entity_type": { "type": "string", "example": "Sole Trader" }, "incorporation_date": { "type": "string", "example": "2024-02-02" }, "incorporation_state": { "type": "string", "example": "CO" }, "address_type": { "type": "string", "example": "Registered" }, "address": { "$ref": "#/components/schemas/V3AddressObject" }, "transaction_fee_percent": { "type": "number", "format": "float", "example": 2.5 }, "transaction_fee_fixed": { "type": "number", "example": 100 }, "maximum_transaction_fee": { "type": "number", "example": 5000 }, "payout_type": { "type": "string", "example": "batch" }, "client_reference_id": { "type": "string", "example": "reference_12345" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" }, "V3BeneficialOwnerResponseObject": { "properties": { "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "dob": { "type": "string", "example": "2023-04-11" }, "ssn9": { "type": "string", "example": "123456789" }, "address": { "$ref": "#/components/schemas/V3AddressObject" }, "is_beneficial_owner": { "type": "boolean", "example": true }, "is_director": { "type": "boolean", "example": false }, "is_significant_control_person": { "type": "boolean", "example": false }, "ownership_percentage": { "type": "number", "format": "float", "example": 25 }, "email": { "type": "string", "example": "owner@test.com" }, "phone": { "type": "string", "example": "2457856490" }, "occupation": { "type": "string", "example": "Co-founder" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" }, "V3MerchantRelationResponseObject": { "properties": { "merchant": { "properties": { "uuid": { "type": "string", "example": "c6bcfbbb-98ff-4d8b-a8f5-1559c3dcb718" } }, "type": "object" } }, "type": "object" }, "V3DeactivateMerchantValidationErrors": { "properties": { "reason": { "description": "Validation errors for the reason field.", "type": "array", "items": { "type": "string", "oneOf": [ { "example": "The reason must be a string." }, { "example": "The reason may not be greater than 255 characters." } ] } } }, "type": "object" }, "V3PersonRequestObject": { "title": "Person Request Object", "description": "Schema for a person request object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "2457856490" }, "address": { "$ref": "#/components/schemas/V3AddressObject" } }, "type": "object" }, "V3PersonResponseObject": { "properties": { "client_reference_id": { "type": "string", "example": "reference_12345" }, "status": { "type": "string", "example": "APPROVED" }, "uuid": { "type": "string", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" }, "payout_type": { "type": "string", "example": "batch" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Dew" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "2457856490" }, "address": { "$ref": "#/components/schemas/V3AddressObject" }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" }, "V3PersonRelationResponseObject": { "properties": { "person": { "properties": { "uuid": { "type": "string", "example": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e" } }, "type": "object" } }, "type": "object" }, "V3AddressObject": { "properties": { "line_1": { "type": "string", "example": "10554 W Quarles Ave" }, "line_2": { "type": "string", "example": "Suite 123", "nullable": true }, "city": { "type": "string", "example": "Littleton" }, "state": { "type": "string", "example": "CO" }, "zip": { "type": "string", "example": "80127" } }, "type": "object" }, "V3TimestampsObject": { "properties": { "created_at": { "type": "string", "example": "2024-06-25 13:57:03" } }, "type": "object" }, "V3BankAccountObject": { "properties": { "plaid_account_id": { "type": "string", "nullable": true }, "plaid_access_token": { "type": "string", "nullable": true }, "account_number": { "type": "string", "example": "9876543210" }, "routing_number": { "type": "string", "example": "021000021" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking", "enum": [ "checking", "savings" ] } }, "type": "object" }, "V3AccountIntelligenceRequestObject": { "required": [ "version" ], "properties": { "version": { "type": "string", "example": "v3", "enum": [ "v1", "v2", "v3" ] }, "name_match": { "type": "boolean", "example": true, "nullable": true } }, "type": "object" }, "V3AccountIntelligenceV3Response": { "properties": { "confidence_score": { "type": "number", "format": "float", "example": 0.81 }, "decisioning_insights": { "properties": { "account_duplicate": { "type": "boolean", "example": false }, "days_since_first_seen": { "type": "integer", "example": -1 }, "days_since_last_transaction": { "type": "integer", "example": -1 }, "has_negative_transactions": { "type": "boolean", "example": false }, "has_paid_transactions": { "type": "boolean", "example": false }, "has_positive_transactions": { "type": "boolean", "example": true }, "name_match": { "type": "string", "example": "yes" }, "phone_number_present": { "type": "boolean", "example": false }, "valid_routing_number": { "type": "boolean", "example": true }, "name_match_score": { "type": "integer", "example": 0 }, "taxpayer_number_match": { "type": "string", "example": "not_available" } }, "type": "object" }, "version": { "type": "string", "example": "v3" } }, "type": "object" }, "V3AccountIntelligenceV2Response": { "properties": { "confidence_score": { "type": "number", "format": "float", "example": 0.81 }, "confidence_level": { "type": "string", "example": "very high", "enum": [ "very low", "low", "medium", "high", "very high" ] }, "version": { "type": "string", "example": "v2" } }, "type": "object" }, "V3AccountIntelligenceV1Response": { "properties": { "validity": { "type": "string", "example": "valid", "enum": [ "valid", "invalid", "not_validated" ] }, "version": { "type": "string", "example": "v1" } }, "type": "object" }, "V3AccountIntelligenceThresholdResponse": { "properties": { "confidence_score": { "type": "number", "format": "float", "example": 0.81 }, "threshold": { "type": "number", "format": "float", "example": 0.6 }, "confidence_level": { "type": "string", "example": "very high", "enum": [ "very low", "low", "medium", "high", "very high" ] }, "version": { "type": "string", "example": "v2" } }, "type": "object" }, "V3ListingPaginationResponse": { "properties": { "current_page": { "type": "number", "example": 1 }, "from": { "type": "number", "example": 1 }, "last_page": { "type": "number", "example": 25 }, "links": { "type": "array", "items": { "type": "object" } }, "per_page": { "type": "number", "example": 15 }, "to": { "type": "number", "example": 15 }, "total": { "type": "number", "example": 370 } }, "type": "object" }, "V3BankAccountResponse": { "properties": { "aggregator_type": { "type": "string", "example": "manual" }, "provider_type": { "type": "string", "example": "manual" }, "uuid": { "type": "string", "format": "uuid", "example": "9b97f121-a449-4b52-9f36-6c55f18394d6" }, "is_default": { "type": "boolean", "example": true }, "account_number": { "type": "string", "example": "9876543210" }, "routing_number": { "type": "string", "example": "021000021" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "institution_name": { "type": "string", "example": "CITIZENS BANK NATIONAL ASSOCIATION", "nullable": true }, "aggregator": { "type": "string", "example": "Citizens Bank", "nullable": true }, "client_reference_id": { "type": "string", "example": null, "nullable": true }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object" }, "V3AchTimestampsObject": { "properties": { "created_at": { "type": "string", "example": "2024-06-25 13:57:03", "nullable": true }, "processed_at": { "type": "string", "example": "2024-06-26 13:57:03", "nullable": true }, "sent_at": { "type": "string", "example": "2024-06-26 14:57:03", "nullable": true }, "settled_at": { "type": "string", "example": "2024-06-27 13:57:03", "nullable": true }, "failed_at": { "type": "string", "example": null, "nullable": true }, "cancelled_at": { "type": "string", "example": null, "nullable": true }, "declined_at": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "V3ErrorInvalidParameters400": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Parameters Received" }, "data": { "type": "string", "example": null, "nullable": true }, "errors": { "type": "string", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" }, "V3ErrorInvalidAcceptHeader400": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid value provided for Accept header." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" }, "V3ErrorInvalidToken401": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid token." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" }, "V3ErrorUnauthorized401": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This action is unauthorized." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" }, "V3ErrorIdempotency409": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The request cannot be executed due to a detected conflict with a duplicate request." }, "data": { "type": "object", "example": null, "nullable": true }, "errors": { "type": "object", "example": null, "nullable": true }, "request_id": { "type": "string", "format": "uuid", "example": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2" } }, "type": "object" }, "V3OnboardingValidationErrors": { "properties": { "client_reference_id": { "type": "object", "example": [ "The client reference ID must be a string.", "The client reference ID may not be greater than 255 characters." ] }, "billing_merchant_uuid": { "type": "object", "example": [ "The billing merchant UUID must be a valid UUID.", "The billing merchant UUID does not exist.", "The billing merchant UUID is deleted and cannot be used for billing purposes." ] }, "billing_processor_mid": { "type": "object", "example": [ "The billing processor MID must be a string.", "The billing processor MID does not exist.", "The billing processor MID is deleted and cannot be used for billing purposes." ] }, "bank_account": { "type": "object", "example": [ "You cannot provide both plaid details and manual bank account fields.", "This person did not meet the confidence score threshold of 0.5 and has been rejected.", "Invalid plaid account ID or access token.", "The bank routing number is not valid." ] }, "bank_account.plaid_account_id": { "type": "object", "example": [ "The plaid account ID is required when plaid account details is present.", "The plaid account ID must be a string." ] }, "bank_account.plaid_access_token": { "type": "object", "example": [ "The plaid access token is required when plaid account details is present.", "The plaid access token must be a string." ] }, "bank_account.account_number": { "type": "object", "example": [ "The bank account number is required when any manual bank account field is provided.", "The bank account number must be a string.", "The bank account number may not be greater than 17 characters." ] }, "bank_account.routing_number": { "type": "object", "example": [ "The bank routing number is required when any manual bank account field is provided.", "The bank routing number must be 9 digits." ] }, "bank_account.account_name": { "type": "object", "example": [ "The bank account name is required when any manual bank account field is provided.", "The bank account name must be a string.", "The bank account name may not be greater than 255 characters." ] }, "bank_account.account_type": { "type": "object", "example": [ "The bank account type is required when any manual bank account field is provided.", "The bank account type must be one of the followings: savings, checking" ] }, "actions.account_intelligence": { "type": "object", "example": [ "The person first and last name are required when name match is true.", "Name Match is only available when using Account Intelligence Version 3. Please update your request and try again." ] }, "actions.account_intelligence.version": { "type": "object", "example": [ "The version is required when account intelligence is present.", "The version must be a string.", "The version must be one of the followings: v1, v2, v3" ] }, "actions.account_intelligence.name_match": { "type": "object", "example": [ "The name match field must be true or false." ] } }, "type": "object" }, "V3PersonValidationError": { "properties": { "person.first_name": { "type": "object", "example": [ "The first name must be a string.", "The first name may not be greater than 56 characters." ] }, "person.last_name": { "type": "object", "example": [ "The last name must be a string.", "The last name may not be greater than 56 characters." ] }, "person.email": { "type": "object", "example": [ "The email must be a valid email address." ] }, "person.phone": { "type": "object", "example": [ "The phone must be a string.", "Phone numbers should consist of 10 digits and should not contain the +1 prefix or any special characters." ] }, "person.address.line_1": { "type": "object", "example": [ "The address line 1 is required when address is present.", "The address line 1 must be a string.", "The address line 1 may not be greater than 255 characters." ] }, "person.address.line_2": { "type": "object", "example": [ "The address line 2 must be a string.", "The address line 2 may not be greater than 255 characters." ] }, "person.address.city": { "type": "object", "example": [ "The city name is required when address is present.", "The city name must be a string.", "The city name may not be greater than 56 characters.", "The city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces." ] }, "person.address.state": { "type": "object", "example": [ "The state is required when address is present.", "The state must be a string.", "The state may not be greater than 2 characters.", "The state must be valid US state." ] }, "person.address.zip": { "type": "object", "example": [ "The zip code is required when address is present.", "The zip code must be a string.", "The zip code must consist of 5 digit." ] } }, "type": "object" }, "V3BusinessValidationError": { "properties": { "business.name": { "type": "object", "example": [ "The name must be a string.", "The name may not be greater than 255 characters." ] }, "business.trading_name": { "type": "object", "example": [ "The trading name must be a string.", "The trading name may not be greater than 255 characters." ] }, "business.address.line_1": { "type": "object", "example": [ "The address line 1 is required when address is present.", "The address line 1 must be a string.", "The address line 1 may not be greater than 255 characters." ] }, "business.address.line_2": { "type": "object", "example": [ "The address line 2 must be a string.", "The address line 2 may not be greater than 255 characters." ] }, "business.address.city": { "type": "object", "example": [ "The city name is required when address is present.", "The city name must be a string.", "The city name may not be greater than 56 characters.", "The city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces." ] }, "business.address.state": { "type": "object", "example": [ "The state is required when address is present.", "The state must be a string.", "The state may not be greater than 2 characters.", "The state must be valid US state." ] }, "business.address.zip": { "type": "object", "example": [ "The zip code is required when address is present.", "The zip code must be a string.", "The zip code must consist of 5 digit." ] } }, "type": "object" }, "V3MerchantValidationError": { "properties": { "merchant.name": { "type": "object", "example": [ "The name field is required.", "The name must be a string.", "The name may not be greater than 255 characters." ] }, "merchant.tin": { "type": "object", "example": [ "The EIN (TIN) number field is required.", "The EIN (TIN) number must be a string.", "The EIN (TIN) number must consist of 9 digits." ] }, "merchant.trading_name": { "type": "object", "example": [ "The trading name field is required.", "The trading name must be a string.", "The trading name may not be greater than 255 characters." ] }, "merchant.entity_type": { "type": "object", "example": [ "The entity type field is required.", "The entity type must be a string.", "The entity type may not be greater than 255 characters." ] }, "merchant.incorporation_date": { "type": "object", "example": [ "The incorporation date is not a valid date.", "The incorporation date does not match the format Y-m-d." ] }, "merchant.incorporation_state": { "type": "object", "example": [ "The incorporation state must be a string.", "The incorporation state must be valid US state." ] }, "merchant.transaction_fee_percent": { "type": "object", "example": [ "The transaction fee percent must be a number.", "The transaction fee percent must be between 0 and 99.99.", "The transaction fee percent field must have 0-2 decimal places." ] }, "merchant.transaction_fee_fixed": { "type": "object", "example": [ "The transaction fee fixed must be at least 0.", "The transaction fee fixed must be an integer." ] }, "merchant.maximum_transaction_fee": { "type": "object", "example": [ "The maximum transaction fee must be at least 0.", "The maximum transaction fee must be an integer." ] }, "merchant.address_type": { "type": "object", "example": [ "The address type must be a string.", "The address type may not be greater than 255 characters." ] }, "merchant.address": { "type": "object", "example": [ "The address field is required." ] }, "merchant.address.line_1": { "type": "object", "example": [ "The address line 1 field is required.", "The address line 1 must be a string.", "The address line 1 may not be greater than 255 characters." ] }, "merchant.address.line_2": { "type": "object", "example": [ "The address line 2 must be a string.", "The address line 2 may not be greater than 255 characters." ] }, "merchant.address.city": { "type": "object", "example": [ "The city name field is required.", "The city name must be a string.", "The city name may not be greater than 56 characters.", "The city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces." ] }, "merchant.address.state": { "type": "object", "example": [ "The state field is required.", "The state must be a string.", "The state may not be greater than 2 characters.", "The state must be valid US state." ] }, "merchant.address.zip": { "type": "object", "example": [ "The zip code field is required.", "The zip code must be a string.", "The zip code must consist of 5 digit." ] } }, "type": "object" }, "V3BeneficialOwnerValidationError": { "properties": { "beneficial_owners": { "type": "object", "example": [ "The beneficial owners field is required.", "The beneficial owners may not have more than 5 items." ] }, "beneficial_owners.0.first_name": { "type": "object", "example": [ "The first name field is required.", "The first name must be a string.", "The first name may not be greater than 255 characters." ] }, "beneficial_owners.0.last_name": { "type": "object", "example": [ "The last name field is required.", "The last name must be a string.", "The last name may not be greater than 255 characters." ] }, "beneficial_owners.0.dob": { "type": "object", "example": [ "The date of birth field is required.", "The date of birth is not a valid date.", "The date of birth does not match the format Y-m-d." ] }, "beneficial_owners.0.ssn9": { "type": "object", "example": [ "The ssn9 field is required.", "The ssn9 must be a string.", "The ssn9 must consist of 9 digits.", "Social security numbers must adhere to the following constraints. The number may not begin with 000, the middle digits cannot be 00, and the ending digits cannot be 0000.", "Invalid ITIN: 4th and 5th digits should range from 50 to 65, 70 to 88, 90 to 92, and 94 to 99." ] }, "beneficial_owners.0.is_beneficial_owner": { "type": "object", "example": [ "The is beneficial owner field is required.", "The is beneficial owner must be true or false." ] }, "beneficial_owners.0.is_director": { "type": "object", "example": [ "The is director field is required.", "The is director must be true or false." ] }, "beneficial_owners.0.is_significant_control_person": { "type": "object", "example": [ "The is significant control person field is required.", "The is significant control person must be true or false." ] }, "beneficial_owners.0.ownership_percentage": { "type": "object", "example": [ "The ownership percent must be a number." ] }, "beneficial_owners.0.email": { "type": "object", "example": [ "The email field is required.", "The email must be a valid email address." ] }, "beneficial_owners.0.phone": { "type": "object", "example": [ "The phone field is required.", "The phone must be a string.", "Phone numbers should consist of 10 digits and should not contain the +1 prefix or any special characters." ] }, "beneficial_owners.0.occupation": { "type": "object", "example": [ "The occupation field is required.", "The occupation must be a string.", "The occupation may not be greater than 255 characters." ] }, "beneficial_owners.0.address": { "type": "object", "example": [ "The address field is required." ] }, "beneficial_owners.0.address.line_1": { "type": "object", "example": [ "The address line 1 field is required.", "The address line 1 must be a string.", "The address line 1 may not be greater than 255 characters." ] }, "beneficial_owners.0.address.line_2": { "type": "object", "example": [ "The address line 2 must be a string.", "The address line 2 may not be greater than 255 characters." ] }, "beneficial_owners.0.address.city": { "type": "object", "example": [ "The city name field is required.", "The city name must be a string.", "The city name may not be greater than 56 characters.", "The city name field only accepts letters (a-z, A-Z), numbers (0-9), hyphens (-), periods (.), apostrophes ('), and spaces." ] }, "beneficial_owners.0.address.state": { "type": "object", "example": [ "The state field is required.", "The state must be a string.", "The state may not be greater than 2 characters.", "The state must be valid US state." ] }, "beneficial_owners.0.address.zip": { "type": "object", "example": [ "The zip code field is required.", "The zip code must be a string.", "The zip code must consist of 5 digit." ] } }, "type": "object" }, "PayoutResource": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "a1e52556-7b0e-40d1-a787-9af5df215a57" }, "client_reference_id": { "type": "string", "example": "StandalonePayout_22778_1780055459", "nullable": true }, "entity": { "properties": { "type": { "type": "string", "example": "person", "nullable": true }, "uuid": { "type": "string", "format": "uuid", "example": "a182280a-a732-44cf-90b4-0b05b7aa86e8", "nullable": true } }, "type": "object" }, "type": { "type": "string", "example": "standalone" }, "status": { "type": "string", "example": "PAYOUT_ACH_PENDING" }, "trace_id": { "type": "string", "example": "ach_11n1jzd31sgr9xd", "nullable": true }, "speed": { "type": "string", "example": "standard", "nullable": true }, "amount": { "type": "integer", "example": 100 }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "payout_failure_reason": { "type": "string", "example": null, "nullable": true }, "modality": { "properties": { "payment_rail": { "type": "string", "example": "ach" }, "speed": { "type": "string", "example": "standard" } }, "type": "object" }, "payee": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "a182280a-a732-44cf-90b4-0b05b7aa86e8" }, "user_uuid": { "type": "string", "format": "uuid", "example": "a182280a-9fe1-4f32-b055-4fd298c8c3ff" }, "type": { "type": "string", "example": "merchant" }, "name": { "type": "string", "example": "MarkTestV3" }, "processor_mid": { "type": "string", "example": null, "nullable": true }, "bank_account": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019e406b-9664-71e7-9277-be2e0d2f6155" }, "aggregator_type": { "type": "string", "example": "bank_link" }, "provider_type": { "type": "string", "example": "bank_link" }, "account_name": { "type": "string", "example": "Spending" }, "account_type": { "type": "string", "example": "checking", "enum": [ "checking", "savings" ] }, "account_number": { "type": "string", "example": "******1680" }, "routing_number": { "type": "string", "example": "*****0021" }, "institution_name": { "type": "string", "example": "Mock Test Bank", "nullable": true }, "aggregator": { "type": "string", "example": "MOCK", "nullable": true }, "is_default": { "type": "boolean", "example": true }, "client_reference_id": { "type": "string", "example": "bus_123456781", "nullable": true }, "status": { "type": "string", "example": "connected", "nullable": true }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" } }, "type": "object", "nullable": true } }, "type": "object", "nullable": true }, "timestamps": { "$ref": "#/components/schemas/V3TimestampsObject" }, "ach_timestamps": { "$ref": "#/components/schemas/V3AchTimestampsObject" } }, "type": "object" }, "V3BankAccountValidationError": { "properties": { "entity_uuid": { "type": "object", "example": [ "The entity UUID field is required.", "The entity UUID must be a valid UUID.", "No entity was found matching that UUID." ] }, "filter.entity_uuid": { "type": "object", "example": [ "The entity UUID field is required.", "The entity UUID must be a valid UUID." ] }, "filter.account_type": { "type": "object", "example": [ "The account type must be one of the followings: checking, savings" ] }, "filter.provider": { "type": "object", "example": [ "The provider must be one of the followings: manual, plaid, bank_link" ] }, "per_page": { "type": "object", "example": [ "The per_page field must be an integer.", "The per_page field must be at least 1.", "The per_page field must not be greater than 100." ] }, "page": { "type": "object", "example": [ "The page field must be an integer.", "The page field must be at least 1." ] }, "cursor": { "type": "object", "example": [ "The cursor field must be a string." ] }, "start_date": { "type": "object", "example": [ "The start_date field must match the format Y-m-d." ] }, "end_date": { "type": "object", "example": [ "The end_date field must match the format Y-m-d." ] } }, "type": "object" }, "BatchRefundResponse": { "properties": { "total": { "type": "number", "example": "100" }, "refund_uuid": { "type": "array", "items": { "properties": { "refund_uuid": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "transaction_uuid": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "amount": { "type": "number", "example": "100" }, "client_reference_id": { "type": "string", "example": "123e4567" }, "capture_delay_days": { "type": "integer", "example": "1" }, "payout_delay_days": { "type": "integer", "example": "1" } }, "type": "object" } } }, "type": "object" }, "BatchRefundNotFound": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Batch refund not found" }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "BankUserNotFound": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User not found." }, "data": { "type": "string", "example": null }, "errors": { "type": "string", "example": null }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "BalanceWithAmount": { "properties": { "available_balance": { "type": "integer", "example": 1000 } }, "type": "object" }, "BalanceWithApproval": { "properties": { "approval": { "type": "boolean", "example": true } }, "type": "object" }, "RefundListResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "total": { "type": "integer", "example": 50 }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } } }, "type": "object" }, "errors": { "type": "object", "nullable": true }, "error_code": { "type": "string", "nullable": true } }, "type": "object" }, "Refund": { "properties": { "transaction_uuid": { "type": "string", "format": "uuid", "example": "9c2af585-9fea-4c47-ac12-e00f42943cd8" }, "refund_uuid": { "type": "string", "format": "uuid", "example": "9c2b3589-160b-45a6-bbad-2694fdd8aeae" }, "amount": { "type": "integer", "example": 50 }, "status": { "type": "string", "example": "REFUND_COMPLETE" }, "client_reference_id": { "type": "string", "example": "infiniRefundW@12", "nullable": true }, "payer_uuid": { "type": "string", "format": "uuid", "example": "4a9d2b92-55e6-4234-8732-a4296f73ee21", "nullable": true }, "payee_uuid": { "type": "string", "format": "uuid", "example": "7a70d56c-ee4d-43f1-9021-fc060fb4c460", "nullable": true }, "capture_delay_days": { "type": "integer", "example": 2 }, "payout_delay_days": { "type": "integer", "example": 5 }, "created_at": { "type": "string", "format": "datetime", "example": "2024-04-18 01:00:20" }, "updated_at": { "type": "string", "format": "datetime", "example": "2024-04-18 02:30:45" }, "failure_code": { "type": "string", "example": "R01", "nullable": true }, "failure_reason": { "type": "string", "example": "Insufficient funds", "nullable": true } }, "type": "object" }, "V1BusinessResponse": { "properties": { "client_reference_id": { "type": "string", "example": "" }, "uuid": { "type": "string", "example": "401c79dd-d38c-4c3a-8edf-1afac5914d2d" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "name": { "type": "string", "example": "Jack Inc." }, "tin": { "type": "string", "example": "961862955" }, "user_status": { "type": "string", "example": "Approved|On Hold|Rejected" }, "kyb_status": { "type": "string", "example": "Approved|In Review|Failed|null" }, "kyb_rejected_reason": { "type": "string", "example": null }, "email": { "type": "string", "example": "" }, "phone": { "type": "string", "example": "" }, "address": { "properties": { "street_address": { "type": "string", "example": "20 Elmora Ave" }, "additional_address": { "type": "string", "example": "" }, "city": { "type": "string", "example": "Elizabeth" }, "state": { "type": "string", "example": "NJ" }, "country": { "type": "string", "example": "US" }, "zip": { "type": "string", "example": "07202" } }, "type": "object" }, "business_owners": { "properties": { "first_name": { "type": "string", "example": "Olive" }, "last_name": { "type": "string", "example": "Vein" }, "dob": { "type": "string", "example": "1996-05-04" }, "ssn9": { "type": "string", "example": "123456789" }, "address_line_1": { "type": "string", "example": "778 E Encore Dr" }, "city": { "type": "string", "example": "Hanford" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "93230" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-06-03 15:58:44" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-06-04 18:30:30" } }, "type": "object" }, "V1RegisterPersonResponse": { "properties": { "client_reference_id": { "type": "string", "example": "" }, "uuid": { "type": "string", "example": "401c79dd-d38c-4c3a-8edf-1afac5914d2d" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "example": "" }, "phone": { "type": "string", "example": "" }, "status": { "type": "string", "example": "Approved|On Hold|Rejected" }, "payout_type": { "type": "string", "example": "individual|batch" }, "address": { "properties": { "street_address": { "type": "string", "example": "20 Elmora Ave" }, "additional_address": { "type": "string", "example": "" }, "city": { "type": "string", "example": "Elizabeth" }, "state": { "type": "string", "example": "NJ" }, "country": { "type": "string", "example": "US" }, "zip": { "type": "string", "example": "07202" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-06-03 15:58:44" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-06-04 18:30:30" } }, "type": "object" }, "V1RefundTransactionResponse": { "properties": { "uuid": { "type": "string", "example": "d1b3b3b0-7b3b-4b3b-8b3b-3b3b3b3b3b3b" }, "transaction_uuid": { "type": "string", "example": "d1b3b3b0-7b3b-4b3b-8b3b-3b3b3b3b3b3b" }, "amount": { "type": "number", "format": "float", "example": 100 }, "status": { "type": "string", "example": "REFUND_PENDING" }, "client_reference_id": { "type": "string", "example": "123456" }, "created_at": { "type": "string", "format": "date-time", "example": "2021-09-01 12:00:00" } }, "type": "object" }, "WebhookValidationErrorResponse": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "data": { "type": "string", "example": null }, "errors": { "properties": { "event_names.0": { "type": "array", "items": { "type": "string", "example": "The selected webhook event TransactionStarted1 is invalid." } } }, "type": "object" }, "error_code": { "type": "string", "example": null } }, "type": "object" }, "V2AddBankAccountRequest": { "properties": { "plaid": { "properties": { "access_token": { "type": "string", "example": "access-token" }, "account_id": { "type": "string", "example": "account-id" } }, "type": "object" }, "custom": { "properties": { "account_number": { "type": "string", "example": "12345678901234567" }, "routing_number": { "type": "integer", "example": 123456789 }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "validate_account_routing": { "type": "boolean", "example": true } }, "type": "object" }, "account_details": { "type": "object" }, "billing_merchant_user_uuid": { "type": "string", "example": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" }, "billing_processor_mid": { "type": "string", "example": "1213121313" } }, "type": "object" }, "V2GetBankAccountBalanceRequest": { "properties": { "billing_merchant_user_uuid": { "type": "string", "format": "uuid" }, "billing_processor_mid": { "type": "string", "maxLength": 255 } }, "type": "object" }, "StoreAccountValidationRequest": { "required": [ "account_number", "routing_number", "version" ], "properties": { "account_number": { "type": "string", "example": "1234567890123456" }, "routing_number": { "type": "string", "example": "123456789" }, "version": { "type": "integer", "enum": [ "1", "2" ] }, "billing_merchant_user_uuid": { "description": "(optional) The UUID of the merchant user to be billed for this account validation.", "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "billing_processor_mid": { "description": "(optional) The processor MID to be billed for this account validation.", "type": "string", "example": "123456789" } }, "type": "object" }, "UpdateBusinessKybRequest": { "required": [ "first_name", "last_name", "email", "phone", "business", "address" ], "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "example": "" }, "phone": { "type": "string", "example": "" }, "business": { "required": [ "name", "tin" ], "properties": { "name": { "type": "string", "example": "Business Name" }, "tin": { "type": "string", "example": "123456789" }, "trading_name": { "type": "string", "example": "Business Trading Name" }, "entity_type": { "type": "string", "example": "" }, "incorporation_date": { "type": "string", "example": "2021-01-01" }, "incorporation_state": { "type": "string", "example": "CO" }, "industry": { "type": "string", "example": "" }, "industry_classification": { "properties": { "code_type": { "type": "string", "example": "" }, "codes": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "example": "" } }, "type": "object" }, "source_of_wealth": { "type": "string", "example": "" }, "source_of_funds": { "type": "string", "example": "" }, "first_transaction_completed_at": { "type": "string", "example": "2021-01-01 00:00:00" }, "product_type": { "type": "string", "example": "" }, "registered_as_inactive": { "type": "boolean", "example": false }, "address_type": { "type": "string", "example": "" }, "address": { "required": [ "line_1", "city", "state", "zip" ], "properties": { "line_1": { "type": "string", "example": "123 Main St" }, "line_2": { "type": "string", "example": "Apt 1" }, "city": { "type": "string", "example": "Denver" }, "state": { "type": "string", "example": "CO" }, "zip": { "type": "string", "example": "80202" } }, "type": "object" } }, "type": "object" }, "billing_merchant_user_uuid": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "billing_processor_mid": { "type": "string", "example": "1234567890" } }, "type": "object" }, "V1AddBankAccountRequest": { "properties": { "plaid": { "properties": { "access_token": { "type": "string", "example": "access-token" }, "account_id": { "type": "string", "example": "account-id" } }, "type": "object" }, "custom": { "properties": { "account_number": { "type": "string", "example": "12345678901234567" }, "routing_number": { "type": "integer", "example": 123456789 }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "validate_account_routing": { "type": "boolean", "example": true } }, "type": "object" }, "billing_merchant_user_uuid": { "type": "string", "example": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" }, "billing_processor_mid": { "type": "string", "example": "1213121313" } }, "type": "object" }, "V1RegisterBusiness": { "properties": { "should_do_kyb": { "type": "boolean", "example": "false" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "integer", "example": "abc@abc.com" }, "phone": { "type": "integer", "example": null }, "client_reference_id": { "type": "string", "example": null }, "billing_merchant_user_uuid": { "type": "string", "example": "9c330a70-84de-46c3-a380-70b34799b1d3" }, "business": { "properties": { "name": { "type": "string", "example": "Jack Inc." }, "tin": { "type": "string", "example": "961862955" }, "payout_type": { "type": "string", "example": "batch" } }, "type": "object" }, "address": { "properties": { "line_1": { "type": "string", "example": "20 Elmora Ave" }, "line_2": { "type": "string", "example": "" }, "city": { "type": "string", "example": "Elizabeth" }, "state": { "type": "string", "example": "NJ" }, "zip": { "type": "string", "example": "07202" } }, "type": "object" }, "business_owners": { "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "dob": { "type": "string", "example": "1996-05-04" }, "ssn9": { "type": "string", "example": "123456789" }, "address_line_1": { "type": "string", "example": "778 E Encore Dr" }, "city": { "type": "string", "example": "Hanford" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "93230" } }, "type": "object" }, "bank_account": { "properties": { "plaid": { "properties": { "access_token": { "type": "string", "example": "NJ" }, "account_id": { "type": "string", "example": "07202" } }, "type": "object" }, "custom": { "properties": { "account_number": { "type": "string", "example": "12345678901234" }, "routing_number": { "type": "string", "example": "056008849" }, "account_name": { "type": "string", "example": "Jack Jones" }, "account_type": { "type": "string", "example": "checking" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "V1DeRegisterWebhookRequest": { "required": [ "event_names" ], "properties": { "webhook_url": { "type": "array", "items": { "type": "string", "format": "url", "example": "https://example.com/webhook" }, "example": [ "https://example.com/webhook", "https://example.com/webhook-example" ] }, "event_names": { "type": "array", "items": { "type": "string", "example": "TransactionStarted" }, "example": [ "TransactionStarted", "TransactionFailed" ] } }, "type": "object" }, "V1GetBankAccountBalanceRequest": { "properties": { "amount": { "type": "integer", "minimum": 1 }, "billing_merchant_user_uuid": { "type": "string", "format": "uuid" }, "billing_processor_mid": { "type": "string", "maxLength": 255 } }, "type": "object" }, "GetUserDetailsRequest": { "required": [ "bank_account" ], "properties": { "bank_account": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "aggregator_type": { "type": "string", "enum": [ "plaid", "manual", "banklink" ] } }, "type": "object" } }, "type": "object" }, "V1RegisterPersonRequest": { "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "integer", "example": "abc@abc.com" }, "phone": { "type": "integer", "example": null }, "client_reference_id": { "type": "string", "example": null }, "billing_merchant_user_uuid": { "type": "string", "example": "9c330a70-84de-46c3-a380-70b34799b1d3" }, "billing_processor_mid": { "type": "string", "example": "34234244333" }, "payout_type": { "type": "string", "example": "batch" }, "address": { "properties": { "line_1": { "type": "string", "example": "20 Elmora Ave" }, "line_2": { "type": "string", "example": "" }, "city": { "type": "string", "example": "Elizabeth" }, "state": { "type": "string", "example": "NJ" }, "zip": { "type": "string", "example": "07202" } }, "type": "object" }, "bank_account": { "properties": { "plaid": { "properties": { "access_token": { "type": "string", "example": "NJ" }, "account_id": { "type": "string", "example": "07202" } }, "type": "object" }, "custom": { "properties": { "account_number": { "type": "string", "example": "12345678901234" }, "routing_number": { "type": "string", "example": "056008849" }, "account_name": { "type": "string", "example": "Jack Jones" }, "account_type": { "type": "string", "example": "checking" }, "validate_account_routing": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "V1RefundTransactionRequest": { "required": [ "amount" ], "properties": { "amount": { "description": "Amount to refund", "type": "integer", "example": 100 }, "client_reference_id": { "description": "Client reference id", "type": "string", "example": "123456" } }, "type": "object" }, "V1RegisterWebhookRequest": { "required": [ "event_names", "webhook_url" ], "properties": { "event_names": { "type": "array", "items": { "type": "string", "example": "TransactionCompleted" }, "example": [ "TransactionCompleted", "TransactionFailed" ] }, "webhook_url": { "type": "array", "items": { "type": "string", "example": "https://example.com/webhook/transaction" }, "example": [ "https://example.com/webhook/transaction", "https://testexample.com/webhook/transaction" ] } }, "type": "object" }, "V1SwitchBankAccountRequest": { "required": [ "account_uuid", "aggregator_type" ], "properties": { "account_uuid": { "type": "string", "format": "uuid" }, "aggregator_type": { "type": "string", "enum": [ "plaid", "manual", "bank_link" ] } }, "type": "object" }, "CreateTransaction": { "properties": { "payer_uuid": { "type": "string", "example": "9c330a70-84de-46c3-a380-70b34799b1d3" }, "payee_uuid": { "type": "string", "example": "9c330a70-84de-46c3-a380-70b34799b1d3" }, "processor_mid": { "type": "string", "example": "234234234" }, "amount": { "type": "integer", "example": "100" }, "transaction_fee": { "type": "integer", "example": "1.2" }, "client_reference_id": { "type": "string", "example": "adsssd" }, "speed": { "type": "string", "example": "fast" }, "company_name": { "type": "string", "example": "Company-1" }, "description": { "type": "string", "example": "lladsdf asldfs" }, "addenda": { "type": "string", "example": "" }, "source_bank_account": { "properties": { "uuid": { "type": "string", "example": "9c330a70-84de-46c3-a380-70b34799b1d3" }, "aggregator_type": { "type": "string", "enum": [ "plaid", "manual", "bank_link" ] } }, "type": "object" }, "destination_bank_account": { "properties": { "uuid": { "type": "string", "example": "9c330a70-84de-46c3-a380-70b34799b1d3" }, "aggregator_type": { "type": "string", "enum": [ "plaid", "manual", "bank_link" ] } }, "type": "object" } }, "type": "object" }, "V1UpdateBusinessKybRequest": { "required": [ "business", "address" ], "properties": { "business": { "required": [ "name", "tin" ], "properties": { "name": { "type": "string", "example": "Business Name" }, "tin": { "type": "string", "example": "123456789" } }, "type": "object" }, "address": { "required": [ "line_1", "city", "state", "zip" ], "properties": { "line_1": { "type": "string", "example": "123 Main St" }, "line_2": { "type": "string", "example": "Apt 1" }, "city": { "type": "string", "example": "Denver" }, "state": { "type": "string", "example": "CO" }, "zip": { "type": "string", "example": "80202" } }, "type": "object" }, "billing_merchant_user_uuid": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "billing_processor_mid": { "type": "string", "example": "1234567890" } }, "type": "object" }, "BatchPayoutResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "total": { "type": "integer", "example": 4400 }, "direction": { "type": "string", "example": "credit" }, "modality": { "properties": { "payment_rail": { "type": "string", "example": "fednow" }, "speed": { "type": "string", "example": "instant" } }, "type": "object" }, "payee_id": { "type": "array", "items": { "properties": { "payee_id": { "type": "string", "format": "uuid", "example": "0cda5458-660f-4f12-9447-e432da2f959c" }, "total": { "type": "integer", "example": 4400 }, "transactions": { "type": "array", "items": { "properties": { "transaction_id": { "type": "string", "format": "uuid", "example": "9ccf5706-dff0-46c7-bf74-4e34dc998485" }, "client_reference_id": { "type": "string", "example": "typesetting" }, "amount": { "type": "integer", "example": 4400 } }, "type": "object" } } }, "type": "object" } } }, "type": "object" }, "errors": { "type": "string", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "V2PayeeBatchPayoutsResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "batch_payouts": { "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "9bd53fe1-ac74-4e81-b6f2-be88b7c86a68" }, "amount": { "type": "number", "format": "integer", "example": 4400 }, "trace_id": { "type": "string", "example": "ach_11kt6v9715jp67t" }, "payout_status": { "type": "string", "example": "PAYOUT_COMPLETE" }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "failure_reason": { "type": "string", "example": null, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2025-02-17 11:15:15" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-02-18 17:15:15" } }, "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 2 }, "total_items": { "type": "integer", "example": 12 }, "per_page": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" }, "errors": { "type": "string", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "V2ProcessorBatchPayoutsResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "batch_payouts": { "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "9bd53fe1-ac74-4e81-b6f2-be88b7c86a68" }, "amount": { "type": "number", "format": "integer", "example": 4400 }, "trace_id": { "type": "string", "example": "ach_11kt6v9715jp67t" }, "payout_status": { "type": "string", "example": "PAYOUT_COMPLETE" }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "failure_reason": { "type": "string", "example": null, "nullable": true }, "modality": { "properties": { "payment_rail": { "type": "string", "example": "fednow" }, "speed": { "type": "string", "example": "instant" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-02-17 11:15:15" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-02-18 17:15:15" } }, "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 2 }, "total_items": { "type": "integer", "example": 12 }, "per_page": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" }, "errors": { "type": "string", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "V1BankAccountListSchema": { "properties": { "uuid": { "type": "string", "example": "b1b9b3b0-0b3b-4b3b-8b3b-0b3b3b3b3b3b" }, "account_number": { "type": "string", "example": "1234567890" }, "routing_number": { "type": "string", "example": "123456789" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "aggregator_type": { "type": "string", "example": "plaid" }, "created_at": { "type": "string", "example": "2021-10-01 00:00:00" }, "is_default": { "type": "boolean", "example": true } }, "type": "object" }, "V1TransactionResponse": { "properties": { "uuid": { "type": "string", "example": "9c330a70-84de-46c3-a380-70b34799b1d3" }, "payer_uuid": { "type": "string", "example": "7d021f9a-b5f4-4668-8d78-0f448f55f984" }, "payee_uuid": { "type": "string", "example": "ec82930a-b59e-4ed2-83dd-0f041bfa5baa" }, "transaction_status": { "type": "string", "example": "PAYOUT_COMPLETE" }, "currency": { "type": "string", "example": "USD" }, "amount": { "type": "integer", "example": 57163 }, "transaction_fee": { "type": "integer", "example": 0 }, "client_reference_id": { "type": "string", "example": "stageN5@123" }, "payout_delay_days": { "type": "integer", "example": 0 }, "company_name": { "type": "string", "example": "a-z, A-Z, 12-'3." }, "description": { "type": "string", "example": null, "nullable": true }, "addenda": { "type": "string", "example": null, "nullable": true }, "type": { "type": "string", "example": "api" }, "spped": { "type": "string", "example": "sameday" }, "processor_mid": { "type": "string", "example": "123131123" }, "batch_payout_id": { "type": "string", "example": "78e84f6a-c36e-4c9e-86bf-6ff4a492be90" }, "capture_status": { "type": "string", "example": "CAPTURE_COMPLETE" }, "payout_status": { "type": "string", "example": "PAYOUT_COMPLETE" }, "clawback_status": { "type": "string", "example": null, "nullable": true }, "reverse_payout_status": { "type": "string", "example": null, "nullable": true }, "failure_code": { "type": "string", "example": null, "nullable": true }, "failure_reason": { "type": "string", "example": null, "nullable": true }, "cancel_reason": { "type": "string", "example": null, "nullable": true }, "payer_bank_account": { "properties": { "uuid": { "type": "string", "example": "9c3306a6-743f-4f8f-9a33-dcd081a06204" }, "aggregator_type": { "type": "string", "example": "bank_link" } }, "type": "object" }, "payee_bank_account": { "properties": { "uuid": { "type": "string", "example": "9c33090b-c0fb-42ce-9ad8-921665d15a90" }, "aggregator_type": { "type": "string", "example": "bank_link" } }, "type": "object" }, "payout_ach_return_code": { "type": "string", "format": "date-time", "example": "R01" }, "payout_failure_reason": { "type": "string", "format": "date-time", "example": "Insufficient funds" }, "trace_ids": { "properties": { "capture_trace_id": { "type": "string", "example": "ach_92lhg3vbf76qxzp" }, "payout_trace_id": { "type": "string", "example": "ach_57ytkdw84mncxvq" }, "reverse_payout_trace_id": { "type": "string", "example": "" }, "refunds": { "type": "array", "items": { "properties": { "refund_uuid": { "type": "string", "example": "" }, "refund_capture_trace_id": { "type": "string", "example": "" }, "refund_payout_trace_id": { "type": "string", "example": "" } }, "type": "object" } } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-06-03 15:58:44" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-06-04 18:30:30" } }, "type": "object" }, "V2PayeeBatchPayoutResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "ec0eb270-b656-4ffe-8799-66508ad48e18" }, "amount": { "type": "number", "format": "integer", "example": 4400 }, "trace_id": { "type": "string", "example": "ach_11kt6v9715jp67t" }, "payout_status": { "type": "string", "example": "PAYOUT_COMPLETE" }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "failure_reason": { "type": "string", "example": null, "nullable": true }, "transactions": { "type": "array", "items": { "properties": { "transaction_uuid": { "type": "string", "format": "uuid", "example": "9ccf5706-dff0-46c7-bf74-4e34dc998485" }, "amount": { "type": "number", "format": "integer", "example": 2200 }, "transaction_fee": { "type": "number", "format": "integer", "example": 0 }, "trace_id": { "type": "string", "example": "ach_11kt5sew15jj2dp" }, "capture_status": { "type": "string", "example": "CAPTURE_COMPLETE" }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "failure_reason": { "type": "string", "example": null, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2025-02-15 12:15:15" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-02-16 14:15:15" } }, "type": "object" } }, "vendor_name": { "type": "string", "example": "Vendor-1" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-02-17 11:15:15" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-02-18 17:15:15" } }, "type": "object" }, "errors": { "type": "string", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "V2ProcessorBatchPayoutResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "ec0eb270-b656-4ffe-8799-66508ad48e18" }, "amount": { "type": "number", "format": "integer", "example": 4400 }, "trace_id": { "type": "string", "example": "ach_11kt6v9715jp67t" }, "payout_status": { "type": "string", "example": "PAYOUT_COMPLETE" }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "failure_reason": { "type": "string", "example": null, "nullable": true }, "modality": { "properties": { "payment_rail": { "type": "string", "example": "fednow" }, "speed": { "type": "string", "example": "instant" } }, "type": "object" }, "transactions": { "type": "array", "items": { "properties": { "transaction_uuid": { "type": "string", "format": "uuid", "example": "9ccf5706-dff0-46c7-bf74-4e34dc998485" }, "amount": { "type": "number", "format": "integer", "example": 2200 }, "transaction_fee": { "type": "number", "format": "integer", "example": 0 }, "trace_id": { "type": "string", "example": "ach_11kt5sew15jj2dp" }, "capture_status": { "type": "string", "example": "CAPTURE_COMPLETE" }, "ach_return_code": { "type": "string", "example": null, "nullable": true }, "failure_reason": { "type": "string", "example": null, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2025-02-15 12:15:15" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-02-16 14:15:15" } }, "type": "object" } }, "vendor_name": { "type": "string", "example": "Vendor-1" }, "created_at": { "type": "string", "format": "date-time", "example": "2025-02-17 11:15:15" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-02-18 17:15:15" } }, "type": "object" }, "errors": { "type": "string", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "BusinessResponse": { "title": "Business Response", "description": "Schema for a Business response", "properties": { "client_reference_id": { "type": "string", "example": "company_45458" }, "uuid": { "type": "string", "example": "9d264b4a-006c-4d01-acd0-730e27784c59" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Dew" }, "email": { "type": "string", "example": "john.dew@example.com" }, "phone": { "type": "string", "example": "2457856490" }, "business": { "properties": { "name": { "type": "string", "example": "John Incorporation" }, "tin": { "type": "string", "example": "922454715" }, "address_type": { "type": "string", "example": "Registered" }, "address": { "properties": { "street_address": { "type": "string", "example": "10554 W Quarles Ave" }, "city": { "type": "string", "example": "Littleton" }, "state": { "type": "string", "example": "CO" }, "country": { "type": "string", "example": "US" }, "zip": { "type": "string", "example": "80127" } }, "type": "object" }, "trading_name": { "type": "string", "example": "John Incorporation" }, "entity_type": { "type": "string", "example": "Sole Trader" }, "incorporation_date": { "type": "string", "format": "date", "example": "2024-02-02" }, "incorporation_state": { "type": "string", "example": "CO" }, "industry": { "type": "string", "example": "Nature of business" }, "industry_classification": { "properties": { "code_type": { "type": "string", "example": "SIC" }, "codes": { "type": "array", "items": { "type": "string" }, "example": [ "NAICS 42", "NAICS 45" ] }, "description": { "type": "string", "example": "NAICS" } }, "type": "object" }, "source_of_wealth": { "type": "string", "example": "2344" }, "source_of_funds": { "type": "string", "example": "Industry" }, "first_transaction_completed_at": { "type": "string", "format": "date-time", "example": "2024-05-02 16:14:25" }, "product_type": { "type": "string", "example": "financial" }, "registered_as_inactive": { "type": "boolean", "example": false }, "transaction_fee_percent": { "type": "number", "format": "float", "example": 25, "nullable": true }, "transaction_fee_fixed": { "type": "integer", "example": 500, "nullable": true }, "maximum_transaction_fee": { "type": "integer", "example": 500, "nullable": true } }, "type": "object" }, "user_status": { "type": "string", "example": "APPROVED" }, "kyb_status": { "type": "string", "example": "APPROVED" }, "kyb_rejected_reason": { "type": "string", "example": null, "nullable": true }, "payout_type": { "type": "string", "example": "batch" }, "role": { "type": "string", "example": "business" }, "vendor_name": { "type": "string", "example": "Fintech" }, "business_owners": { "type": "array", "items": { "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Dew" }, "dob": { "type": "string", "format": "date", "example": "2023-04-11" }, "ssn9": { "type": "string", "example": "123456789" }, "address_line_1": { "type": "string", "example": "10554 W Quarles Ave" }, "city": { "type": "string", "example": "Littleton" }, "state": { "type": "string", "example": "CO" }, "zip": { "type": "string", "example": "80127" }, "is_beneficial_owner": { "type": "boolean", "example": true }, "is_director": { "type": "boolean", "example": false }, "is_account_owner": { "type": "boolean", "example": false }, "is_share_holder": { "type": "boolean", "example": false }, "is_significant_control_person": { "type": "boolean", "example": false }, "ownership_percentage": { "type": "number", "format": "float", "example": 25 }, "email": { "type": "string", "example": "john.dew@example.com" }, "phone": { "type": "string", "example": "2457856490" }, "nationality": { "type": "string", "example": "US" }, "occupation": { "type": "string", "example": "Co-founder" }, "first_transaction_completed_at": { "type": "string", "format": "date-time", "example": "2024-05-02 16:14:25" }, "product_type": { "type": "string", "example": "financial" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-10-02 14:06:14" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-10-02 14:06:17" } }, "type": "object" }, "PersonResponse": { "title": "Person Response", "description": "Schema for a person response", "properties": { "status": { "description": "Response status", "type": "boolean" }, "message": { "description": "Response message", "type": "string" }, "data": { "description": "User data", "properties": { "client_reference_id": { "description": "Client reference ID", "type": "string" }, "uuid": { "description": "User UUID", "type": "string", "format": "uuid" }, "first_name": { "description": "User first name", "type": "string" }, "last_name": { "description": "User last name", "type": "string" }, "email": { "description": "User email address", "type": "string", "format": "email" }, "phone": { "description": "User phone number", "type": "string" }, "user_status": { "description": "User status", "type": "string" }, "payout_type": { "description": "Payout Type", "type": "string" }, "address": { "description": "User address details", "properties": { "street_address": { "description": "Street address", "type": "string" }, "city": { "description": "City", "type": "string" }, "state": { "description": "State", "type": "string" }, "country": { "description": "Country", "type": "string" }, "zip": { "description": "Zip code", "type": "string" } }, "type": "object" }, "role": { "description": "User role", "type": "string" }, "vendor_name": { "description": "Vendor name", "type": "string" }, "created_at": { "description": "User creation date", "type": "string", "format": "date-time" }, "updated_at": { "description": "User last update date", "type": "string", "format": "date-time" } }, "type": "object" }, "errors": { "description": "Error details if any", "type": "object", "nullable": true }, "error_code": { "description": "Error code if any", "type": "string", "nullable": true } }, "type": "object" }, "V2TransactionResponse": { "properties": { "uuid": { "type": "string", "example": "9c330a70-84de-46c3-a380-70b34799b1d3" }, "payer_uuid": { "type": "string", "example": "7d021f9a-b5f4-4668-8d78-0f448f55f984" }, "payee_uuid": { "type": "string", "example": "ec82930a-b59e-4ed2-83dd-0f041bfa5baa" }, "processor_mid": { "type": "string", "example": "123131123" }, "batch_payout_id": { "type": "string", "example": "de880c41-5a9e-4c93-b9fe-252a61125258" }, "transaction_status": { "type": "string", "example": "PAYOUT_COMPLETE" }, "capture_status": { "type": "string", "example": "CAPTURE_COMPLETE" }, "payout_status": { "type": "string", "example": "PAYOUT_COMPLETE" }, "clawback_status": { "type": "string", "example": null, "nullable": true }, "reverse_payout_status": { "type": "string", "example": null, "nullable": true }, "currency": { "type": "string", "example": "USD" }, "amount": { "type": "integer", "example": 57163 }, "transaction_fee": { "type": "integer", "example": 0 }, "client_reference_id": { "type": "string", "example": "stageN5@123" }, "payout_delay_days": { "type": "integer", "example": 0 }, "company_name": { "type": "string", "example": "Company-1" }, "description": { "type": "string", "example": null, "nullable": true }, "addenda": { "type": "string", "example": null, "nullable": true }, "type": { "type": "string", "example": "api" }, "ach_return_code": { "type": "string", "example": "R01" }, "cancel_reason": { "type": "string", "example": null, "nullable": true }, "speed": { "type": "string", "example": "sameday" }, "failure_code": { "type": "string", "example": "R01", "nullable": true }, "failure_reason": { "type": "string", "example": "Insufficient funds", "nullable": true }, "payer_bank_account": { "properties": { "uuid": { "type": "string", "example": "9c3306a6-743f-4f8f-9a33-dcd081a06204" }, "aggregator_type": { "type": "string", "example": "bank_link" } }, "type": "object" }, "payee_bank_account": { "properties": { "uuid": { "type": "string", "example": "9c33090b-c0fb-42ce-9ad8-921665d15a90" }, "aggregator_type": { "type": "string", "example": "bank_link" } }, "type": "object" }, "payout_ach_return_code": { "type": "string", "format": "string", "example": "R01" }, "payout_failure_reason": { "type": "string", "format": "string", "example": "Insufficient funds" }, "vendor_name": { "type": "string", "format": "string", "example": "Vendor-1" }, "trace_ids": { "properties": { "capture_trace_id": { "type": "string", "example": "ach_92lhg3vbf76qxzp" }, "payout_trace_id": { "type": "string", "example": "ach_57ytkdw84mncxvq" }, "reverse_payout_trace_id": { "type": "string", "example": "" }, "refunds": { "type": "array", "items": { "properties": { "refund_uuid": { "type": "string", "example": "" }, "refund_capture_trace_id": { "type": "string", "example": "" }, "refund_payout_trace_id": { "type": "string", "example": "" } }, "type": "object" } }, "clawback_trace_id": { "type": "string", "example": "" } }, "type": "object" }, "created_at": { "type": "string", "format": "string", "example": "2024-06-03 15:58:44" }, "updated_at": { "type": "string", "format": "string", "example": "2024-06-04 18:30:30" } }, "type": "object" }, "BatchRefundListResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "" }, "data": { "properties": { "batch_refunds": { "type": "array", "items": { "properties": { "batch_refund_uuid": { "type": "string", "format": "uuid", "example": "9bd53fe1-ac74-4e81-b6f2-be88b7c86a68" }, "amount": { "type": "integer", "example": 10000 }, "date": { "type": "string", "format": "datetime", "example": "2024-04-18 01:00:20" } }, "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 3 }, "total_items": { "type": "integer", "example": 30 }, "per_page": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" }, "errors": { "type": "string", "example": null, "nullable": true }, "error_code": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "V2BankAccountResponse": { "properties": { "uuid": { "type": "string", "example": "12345678-1234-1234-1234-123456789012" }, "user_uuid": { "type": "string", "example": "12345678-1234-1234-1234-123456789012" }, "account_number": { "type": "string", "example": "12345678901234567" }, "routing_number": { "type": "string", "example": "123456789" }, "account_name": { "type": "string", "example": "John Doe" }, "account_type": { "type": "string", "example": "checking" }, "aggregator_type": { "type": "string", "example": "manual" }, "created_at": { "type": "string", "example": "2021-09-01 00:00:00" }, "is_default": { "type": "boolean", "example": true } }, "type": "object" } }, "parameters": { "UserUuidPathParam": { "name": "uuid", "in": "path", "description": "UUID of the user", "required": true, "schema": { "type": "string", "format": "uuid" } }, "BankAccountUuidPathParam": { "name": "account_uuid", "in": "path", "description": "UUID of the bank account", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "securitySchemes": { "ApiToken": { "type": "http", "description": "Token-based authentication using Authorization: Bearer provided by the GrailPay Support Team.", "bearerFormat": "Token", "scheme": "bearer" } } }, "tags": [ { "name": "Users", "description": "API Endpoints used for the onboarding and managing People, Businesses, and Merchants." }, { "name": "Transactions", "description": "API Endpoints used for creating and managing transactions." }, { "name": "Payouts", "description": "API Endpoints used for fetching payout information." }, { "name": "Refunds", "description": "API Endpoints used for creating and retrieving refunds." }, { "name": "Bank Accounts", "description": "API Endpoints used for adding and managing bank accounts." }, { "name": "Webhooks", "description": "API Endpoints used for registering and de-registering webhooks." }, { "name": "Billing", "description": "API Endpoints used for retrieving billing information." }, { "name": "Stable", "description": "Stable, up-to-date APIs that are recommended for current integration." }, { "name": "Sunsetting", "description": "Sunsetting APIs that are still supported but scheduled for deprecation." }, { "name": "Deprecated", "description": "Deprecated APIs that are no longer supported and should be removed." }, { "name": "Vendors", "description": "Vendors" } ] }