> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md # Create bank account change POST https://api-sandbox.payabli.com/api/v2/cases/bank-account/{paypointId} Content-Type: application/json Creates a bank-account-change case for a paypoint. The account and routing numbers are validated and tokenized before the case is saved — the raw numbers are never stored or returned. The account holder name is taken from the paypoint's legal name. On success the case is created in `Submitted` and asynchronous verification starts. Available to both Platform and Enterprise Partners. Reference: https://docs.payabli.com/developers/api-reference/bankChanges/create-bank-account-change ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: payabliApi-oas version: 1.0.0 paths: /v2/cases/bank-account/{paypointId}: post: operationId: CreateBankAccountChange summary: Create bank account change description: | Creates a bank-account-change case for a paypoint. The account and routing numbers are validated and tokenized before the case is saved — the raw numbers are never stored or returned. The account holder name is taken from the paypoint's legal name. On success the case is created in `Submitted` and asynchronous verification starts. Available to both Platform and Enterprise Partners. tags: - caseManagement parameters: - name: paypointId in: path description: The paypoint's numeric identifier. required: true schema: type: integer format: int64 responses: '201': description: The created case content: application/json: schema: $ref: '#/components/schemas/CaseResponse' '400': description: Bad request / invalid data. content: application/json: schema: $ref: '#/components/schemas/PayabliErrorBody' '401': description: Unauthorized request. content: application/json: schema: $ref: '#/components/schemas/PayabliErrorBody' '403': description: Consent error. content: application/json: schema: $ref: '#/components/schemas/PayabliErrorBody' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/PayabliErrorBody' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBankAccountChangeCaseRequest' servers: - url: https://api-sandbox.payabli.com/api description: Sandbox - url: https://api.payabli.com/api description: Production components: schemas: caseManagement_BankAccountFunction: type: string enum: - Deposits - Withdrawals - DepositsAndWithdrawals - Remittances - RemittancesAndDeposits - RemittancesAndWithdrawals - RemittancesDepositsAndWithdrawals description: What the bank account is used for. `None` isn't accepted on a request. title: caseManagement_BankAccountFunction MoneyInService: type: string enum: - Ach - Card - Cloud - Device - Wallet - Cash - Check description: A Pay In service the bank account is used for. title: MoneyInService MoneyOutService: type: string enum: - Ach - VCard - Managed - Check - Rtp - Wire - Ghost description: A Pay Out service the bank account is used for. title: MoneyOutService BankAccountServices: type: object properties: moneyIn: type: array items: $ref: '#/components/schemas/MoneyInService' description: Pay In services the account is used for. moneyOut: type: array items: $ref: '#/components/schemas/MoneyOutService' description: Pay Out services the account is used for. description: >- The Pay In and Pay Out services the bank account applies to. Include at least one entry across the two lists. title: BankAccountServices CreateBankAccountChangeCaseRequest: type: object properties: nickname: type: string description: A label for the account. bankName: type: string description: The name of the bank. routingNumber: type: string description: The 9-digit bank routing number. accountNumber: type: string description: The bank account number (4 to 17 digits). accountType: type: string description: The account type. Must be `checking` or `savings`. bankAccountHolderType: type: string description: The account holder type. Must be `personal` or `business`. bankAccountFunction: $ref: '#/components/schemas/caseManagement_BankAccountFunction' services: $ref: '#/components/schemas/BankAccountServices' default: type: boolean description: Whether this is the default account for the selected services. scheduleFor: type: string format: date-time description: > When to run the change, as a UTC timestamp (trailing `Z`). Must be at least 1 hour and at most 30 days in the future. Omit to run as soon as the case is approved. required: - nickname - bankName - routingNumber - accountNumber - accountType - bankAccountHolderType - bankAccountFunction - services - default description: The bank account change to submit as a case. title: CreateBankAccountChangeCaseRequest CaseState: type: string enum: - Submitted - Verifying - PendingReview - Assigned - PendingResponse - Escalated - Approved - AutoApproved - PendingCompletion - Completed - Denied - Error description: > The state of a case in the bank-account-change lifecycle. `Completed` and `Denied` are terminal. title: CaseState CaseType: type: string enum: - BankAccountChange description: Bank account changes are currently the only supported case type. title: CaseType BankAccountChangeParametersType: type: string enum: - BankAccountChange description: The parameters type discriminator. title: BankAccountChangeParametersType BankAccountChangeParameters: type: object properties: type: $ref: '#/components/schemas/BankAccountChangeParametersType' description: The parameters type discriminator. nickname: type: string description: A label for the account. bankName: type: string description: The name of the bank. bankToken: type: string description: >- A vault token referencing the tokenized bank account. The raw account and routing numbers are never returned. accountType: type: string description: The account type, such as `Checking` or `Savings`. bankAccountHolderName: type: string description: The account holder's name, taken from the paypoint's legal name. bankAccountHolderType: type: string description: The account holder type, such as `personal` or `business`. bankAccountFunction: $ref: '#/components/schemas/caseManagement_BankAccountFunction' services: $ref: '#/components/schemas/BankAccountServices' default: type: boolean description: Whether this is the default account for the selected services. required: - type - nickname - bankName - bankToken - accountType - bankAccountHolderName - bankAccountHolderType - bankAccountFunction - services - default description: > The bank-account-change details stored on a case. The raw account and routing numbers are write-only and never appear here — only a vault token (`bankToken`) and non-sensitive details. title: BankAccountChangeParameters UserRef: type: object properties: id: type: integer format: int64 description: The user's numeric identifier. name: type: - string - 'null' description: The user's display name. Null when the name can't be resolved. required: - id - name description: A reference to a user, with the display name resolved when available. title: UserRef StateTransitionResponse: type: object properties: uuid: type: string format: uuid description: The transition's unique identifier. caseUuid: type: string format: uuid description: The case this transition belongs to. fromState: $ref: '#/components/schemas/CaseState' toState: $ref: '#/components/schemas/CaseState' ipAddress: type: - string - 'null' description: The IP address of the actor. Null for system transitions. triggeredBy: type: - integer - 'null' format: int64 description: >- The numeric id of the user who triggered the transition. Null for system transitions. reason: type: - string - 'null' description: The reason recorded for the transition. createdAt: type: string format: date-time description: When the transition occurred. triggeredByUser: oneOf: - $ref: '#/components/schemas/UserRef' - type: 'null' description: >- The resolved user who triggered the transition. Null for system transitions. required: - uuid - caseUuid - fromState - toState - ipAddress - triggeredBy - reason - createdAt - triggeredByUser description: A single entry in a case's state history. title: StateTransitionResponse AttachmentResponse: type: object properties: uuid: type: string format: uuid description: The attachment's identifier. caseUuid: type: string format: uuid description: The case the attachment belongs to. fileType: type: string description: The file's content type. filename: type: string description: The file's name. fileUrl: type: string description: A reference to the stored file. uploadedAt: type: string format: date-time description: When the file was uploaded. uploadedBy: type: string description: The id of the user who uploaded the file. uploadedByUser: oneOf: - $ref: '#/components/schemas/UserRef' - type: 'null' description: The resolved user who uploaded the file. Null when not enriched. required: - uuid - caseUuid - fileType - filename - fileUrl - uploadedAt - uploadedBy - uploadedByUser description: A file attached to a case. title: AttachmentResponse VerificationCode: type: object properties: code: type: integer description: The numeric result code. name: type: - string - 'null' description: The short code name. description: type: - string - 'null' description: A human-readable description of the result. required: - code - name - description description: >- A single bank-verification result code returned by the verification provider. title: VerificationCode BankVerificationMetadata: type: object properties: verificationResult: $ref: '#/components/schemas/VerificationCode' accountResponseCode: oneOf: - $ref: '#/components/schemas/VerificationCode' - type: 'null' description: The account-level verification code. Null when not returned. customerResponseCode: oneOf: - $ref: '#/components/schemas/VerificationCode' - type: 'null' description: The customer-level verification code. Null when not returned. required: - verificationResult - accountResponseCode - customerResponseCode description: The outcome of automatic bank account verification. title: BankVerificationMetadata BankReviewDecisionReason: type: string enum: - CreditDecline - FraudDecline - KybKycDecline - Withdrawn description: The reason a reviewer denied a case. Required only when denying. title: BankReviewDecisionReason ReviewDecisionMetadata: type: object properties: declineReason: oneOf: - $ref: '#/components/schemas/BankReviewDecisionReason' - type: 'null' description: The decline reason, when the case was denied. note: type: - string - 'null' description: A free-text note attached to the decision. required: - declineReason - note description: Details of a reviewer's decision, when one has been made. title: ReviewDecisionMetadata CaseMetadata: type: object properties: verification: oneOf: - $ref: '#/components/schemas/BankVerificationMetadata' - type: 'null' description: The verification outcome. Null until verification finishes. reviewDecision: oneOf: - $ref: '#/components/schemas/ReviewDecisionMetadata' - type: 'null' description: The reviewer's decision, when one has been made. required: - verification - reviewDecision description: >- Case metadata, populated as the case progresses. Null until verification completes. title: CaseMetadata OrgRef: type: object properties: id: type: integer format: int64 description: The organization's numeric identifier. name: type: string description: The organization's name. required: - id - name description: A reference to the organization that owns the case. title: OrgRef PaypointRef: type: object properties: id: type: integer format: int64 description: The paypoint's numeric identifier. name: type: string description: The paypoint's DBA name. required: - id - name description: A reference to the paypoint the case applies to. title: PaypointRef CaseResponse: type: object properties: uuid: type: string format: uuid description: The case's unique identifier. state: $ref: '#/components/schemas/CaseState' caseType: $ref: '#/components/schemas/CaseType' parameters: $ref: '#/components/schemas/BankAccountChangeParameters' orgId: type: integer format: int64 description: The organization that owns the case. paypointId: type: integer format: int64 description: The paypoint the case applies to. scheduleFor: type: - string - 'null' format: date-time description: When the change is scheduled to run. Null when not scheduled. createdAt: type: string format: date-time description: When the case was created. updatedAt: type: string format: date-time description: When the case was last updated. createdBy: type: integer format: int64 description: >- The numeric id of the user who created the case. `0` when created by a server-side integration. assigneeId: type: - integer - 'null' format: int64 description: The numeric id of the assigned reviewer. Null when unassigned. lastReviewedById: type: - integer - 'null' format: int64 description: The numeric id of the last reviewer. Null when not yet reviewed. stateHistory: type: array items: $ref: '#/components/schemas/StateTransitionResponse' description: The ordered history of state transitions. attachments: type: array items: $ref: '#/components/schemas/AttachmentResponse' description: Files attached to the case. roomId: type: - integer - 'null' format: int64 description: The id of the message room for the case. Null until provisioned. metadata: oneOf: - $ref: '#/components/schemas/CaseMetadata' - type: 'null' description: >- Case metadata, including the verification outcome. Null until verification completes. org: oneOf: - $ref: '#/components/schemas/OrgRef' - type: 'null' description: The resolved organization. Null when not enriched. paypoint: oneOf: - $ref: '#/components/schemas/PaypointRef' - type: 'null' description: The resolved paypoint. Null when not enriched. createdByUser: oneOf: - $ref: '#/components/schemas/UserRef' - type: 'null' description: >- The resolved creator. Null when created by a server-side integration or not enriched. assignee: oneOf: - $ref: '#/components/schemas/UserRef' - type: 'null' description: The resolved assigned reviewer. Null when unassigned. lastReviewedBy: oneOf: - $ref: '#/components/schemas/UserRef' - type: 'null' description: The resolved last reviewer. Null when not yet reviewed. required: - uuid - state - caseType - parameters - orgId - paypointId - scheduleFor - createdAt - updatedAt - createdBy - assigneeId - lastReviewedById - stateHistory - attachments - roomId - metadata - org - paypoint - createdByUser - assignee - lastReviewedBy description: A bank-account-change case. title: CaseResponse PayabliErrorBodyResponseData: type: object properties: explanation: type: string description: Human-readable explanation of what happened. todoAction: type: string description: Suggested resolution. description: Object with detailed error context. title: PayabliErrorBodyResponseData PayabliErrorBody: type: object properties: isSuccess: type: boolean description: Always `false` for error responses. responseCode: type: integer description: | Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses). responseText: type: string description: Error text describing what went wrong. responseData: $ref: '#/components/schemas/PayabliErrorBodyResponseData' description: Object with detailed error context. required: - isSuccess - responseText description: | Shape returned by every Payabli API error response. The `responseData` object carries human-readable error context. title: PayabliErrorBody ``` ## Examples **Request** ```json { "nickname": "Main Settlement Account", "bankName": "First National Bank", "routingNumber": "123456789", "accountNumber": "987654321", "accountType": "checking", "bankAccountHolderType": "business", "bankAccountFunction": "Deposits", "services": { "moneyIn": [ "Ach" ], "moneyOut": [ "Ach" ] }, "default": true } ``` **Response** ```json { "uuid": "9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70", "state": "Submitted", "caseType": "BankAccountChange", "parameters": { "type": "BankAccountChange", "nickname": "Main Settlement Account", "bankName": "First National Bank", "bankToken": "bnk_2b1c9e40f5a34c9a8f219e7c6b1a2d34", "accountType": "Checking", "bankAccountHolderName": "Gruzya Adventure Outfitters LLC", "bankAccountHolderType": "business", "bankAccountFunction": "Deposits", "services": { "moneyIn": [ "Ach" ], "moneyOut": [ "Ach" ] }, "default": true }, "orgId": 123, "paypointId": 3040, "scheduleFor": null, "createdAt": "2026-01-15T10:30:00Z", "updatedAt": "2026-01-15T10:30:00Z", "createdBy": 0, "assigneeId": null, "lastReviewedById": null, "stateHistory": [], "attachments": [], "roomId": null, "metadata": null, "org": { "id": 123, "name": "Example Partner Org" }, "paypoint": { "id": 3040, "name": "Gruzya Adventure Outfitters" }, "createdByUser": null, "assignee": null, "lastReviewedBy": null } ``` **SDK Code** ```typescript import { PayabliClient } from "@payabli/sdk-node"; async function main() { const client = new PayabliClient(); await client.caseManagement.createBankAccountChange(3040, { nickname: "Main Settlement Account", bankName: "First National Bank", routingNumber: "123456789", accountNumber: "987654321", accountType: "checking", bankAccountHolderType: "business", bankAccountFunction: "Deposits", services: { moneyIn: [ "Ach", ], moneyOut: [ "Ach", ], }, default: true, }); } main(); ``` ```python from payabli import payabli, BankAccountServices client = payabli() client.case_management.create_bank_account_change( paypoint_id=3040, nickname="Main Settlement Account", bank_name="First National Bank", routing_number="123456789", account_number="987654321", account_type="checking", bank_account_holder_type="business", bank_account_function="Deposits", services=BankAccountServices( money_in=[ "Ach" ], money_out=[ "Ach" ], ), default=True, ) ``` ```java package com.example.usage; import io.github.payabli.api.PayabliPayabliApiOasClient; import io.github.payabli.api.resources.casemanagement.requests.CreateBankAccountChangeCaseRequest; import io.github.payabli.api.types.BankAccountServices; import io.github.payabli.api.types.CaseManagementBankAccountFunction; import io.github.payabli.api.types.MoneyInService; import io.github.payabli.api.types.MoneyOutService; import java.util.Arrays; import java.util.Optional; public class Example { public static void main(String[] args) { PayabliPayabliApiOasClient client = PayabliPayabliApiOasClient .builder() .build(); client.caseManagement().createBankAccountChange( 3040L, CreateBankAccountChangeCaseRequest .builder() .nickname("Main Settlement Account") .bankName("First National Bank") .routingNumber("123456789") .accountNumber("987654321") .accountType("checking") .bankAccountHolderType("business") .bankAccountFunction(CaseManagementBankAccountFunction.DEPOSITS) .services( BankAccountServices .builder() .moneyIn( Optional.of( Arrays.asList(MoneyInService.ACH) ) ) .moneyOut( Optional.of( Arrays.asList(MoneyOutService.ACH) ) ) .build() ) .default_(true) .build() ); } } ``` ```csharp using PayabliPayabliApiOas; using System.Threading.Tasks; using System.Collections.Generic; namespace Usage; public class Example { public async Task Do() { var client = new PayabliPayabliApiOasClient(); await client.CaseManagement.CreateBankAccountChangeAsync( 3040L, new CreateBankAccountChangeCaseRequest { Nickname = "Main Settlement Account", BankName = "First National Bank", RoutingNumber = "123456789", AccountNumber = "987654321", AccountType = "checking", BankAccountHolderType = "business", BankAccountFunction = CaseManagementBankAccountFunction.Deposits, Services = new BankAccountServices { MoneyIn = new List(){ MoneyInService.Ach, } , MoneyOut = new List(){ MoneyOutService.Ach, } }, Default = true } ); } } ``` ```go package example import ( context "context" payabli "github.com/payabli/sdk-go" client "github.com/payabli/sdk-go/client" ) func do() { client := client.NewClient() request := &payabli.CreateBankAccountChangeCaseRequest{ Nickname: "Main Settlement Account", BankName: "First National Bank", RoutingNumber: "123456789", AccountNumber: "987654321", AccountType: "checking", BankAccountHolderType: "business", BankAccountFunction: payabli.CaseManagementBankAccountFunctionDeposits, Services: &payabli.BankAccountServices{ MoneyIn: []payabli.MoneyInService{ payabli.MoneyInServiceAch, }, MoneyOut: []payabli.MoneyOutService{ payabli.MoneyOutServiceAch, }, }, Default: true, } client.CaseManagement.CreateBankAccountChange( context.TODO(), int64(3040), request, ) } ``` ```php caseManagement->createBankAccountChange( 3040, new CreateBankAccountChangeCaseRequest([ 'nickname' => 'Main Settlement Account', 'bankName' => 'First National Bank', 'routingNumber' => '123456789', 'accountNumber' => '987654321', 'accountType' => 'checking', 'bankAccountHolderType' => 'business', 'bankAccountFunction' => CaseManagementBankAccountFunction::Deposits->value, 'services' => new BankAccountServices([ 'moneyIn' => [ MoneyInService::Ach->value, ], 'moneyOut' => [ MoneyOutService::Ach->value, ], ]), 'default' => true, ]), ); ``` ```ruby require 'uri' require 'net/http' url = URI("https://api-sandbox.payabli.com/api/v2/cases/bank-account/3040") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = 'application/json' request.body = "{\n \"nickname\": \"Main Settlement Account\",\n \"bankName\": \"First National Bank\",\n \"routingNumber\": \"123456789\",\n \"accountNumber\": \"987654321\",\n \"accountType\": \"checking\",\n \"bankAccountHolderType\": \"business\",\n \"bankAccountFunction\": \"Deposits\",\n \"services\": {\n \"moneyIn\": [\n \"Ach\"\n ],\n \"moneyOut\": [\n \"Ach\"\n ]\n },\n \"default\": true\n}" response = http.request(request) puts response.read_body ``` ```swift import Foundation let headers = ["Content-Type": "application/json"] let parameters = [ "nickname": "Main Settlement Account", "bankName": "First National Bank", "routingNumber": "123456789", "accountNumber": "987654321", "accountType": "checking", "bankAccountHolderType": "business", "bankAccountFunction": "Deposits", "services": [ "moneyIn": ["Ach"], "moneyOut": ["Ach"] ], "default": true ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/cases/bank-account/3040")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```