> 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 # Fire a case action POST https://api-sandbox.payabli.com/api/v2/cases/{uuid}/transitions Content-Type: application/json Fires a review action on a case, such as `Approve`, `Deny`, `Escalate`, or `RequestReview`. Assigning a case uses the dedicated assign endpoint, not this one. Firing an action that isn't valid for the case's current state returns `409`. Available to Enterprise Partners only. Reference: https://docs.payabli.com/developers/api-reference/caseManagement/transition-case ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: payabliApi-oas version: 1.0.0 paths: /v2/cases/{uuid}/transitions: post: operationId: Transition summary: Fire a case action description: | Fires a review action on a case, such as `Approve`, `Deny`, `Escalate`, or `RequestReview`. Assigning a case uses the dedicated assign endpoint, not this one. Firing an action that isn't valid for the case's current state returns `409`. Available to Enterprise Partners only. tags: - caseManagement parameters: - name: uuid in: path description: The case's UUID. required: true schema: type: string format: uuid responses: '200': description: The updated 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' '404': description: The case doesn't exist. content: application/json: schema: description: Any type '409': description: The action isn't permitted from the case's current state. content: application/json: schema: description: Any type '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/PayabliErrorBody' requestBody: content: application/json: schema: $ref: '#/components/schemas/TransitionCaseRequest' servers: - url: https://api-sandbox.payabli.com/api description: Sandbox - url: https://api.payabli.com/api description: Production components: schemas: CaseTrigger: type: string enum: - Submit - Verify - RequestReview - Assign - RequestResponse - Escalate - Approve - AutoApprove - RequestCompletion - Complete - Deny - Error description: > A transition action in the case state machine. `Assign` is fired through the dedicated assign endpoint, not the transitions endpoint. title: CaseTrigger BankReviewDecisionReason: type: string enum: - CreditDecline - FraudDecline - KybKycDecline - Withdrawn description: The reason a reviewer denied a case. Required only when denying. title: BankReviewDecisionReason TransitionCaseRequest: type: object properties: trigger: $ref: '#/components/schemas/CaseTrigger' reason: type: string description: The reason for the action. declineReason: oneOf: - $ref: '#/components/schemas/BankReviewDecisionReason' - type: 'null' description: >- The decline reason. Required when the trigger is `Deny`, and must be omitted otherwise. required: - trigger - reason description: A review action to fire on a case. title: TransitionCaseRequest 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 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 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 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 { "trigger": "Approve", "reason": "Account ownership confirmed with the merchant by phone." } ``` **Response** ```json { "uuid": "9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70", "state": "Approved", "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-15T12:15:00Z", "createdBy": 0, "assigneeId": 4238, "lastReviewedById": 4238, "stateHistory": [ { "uuid": "019f8100-1a2b-73c4-9d5e-6f7a8b9c0d1e", "caseUuid": "9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70", "fromState": "Assigned", "toState": "Approved", "ipAddress": "203.0.113.10", "triggeredBy": 4238, "reason": "Account ownership confirmed with the merchant by phone.", "createdAt": "2026-01-15T12:15:00Z", "triggeredByUser": { "id": 4238, "name": "Jordan Rivera" } } ], "attachments": [], "roomId": 96370, "metadata": { "verification": { "verificationResult": { "code": 5, "name": "RiskAlert", "description": "The suggested action is to further investigate the bank account and/or customer data for this inquiry due to a risk alert ." }, "accountResponseCode": { "code": 12, "name": "_1111", "description": "Account Verified – The account was found to be an open and valid checking account." }, "customerResponseCode": { "code": 3, "name": "CA21", "description": "The customer or business name data did not match gAuthenticate data." } }, "reviewDecision": null }, "org": { "id": 123, "name": "Example Partner Org" }, "paypoint": { "id": 3040, "name": "Gruzya Adventure Outfitters" }, "createdByUser": null, "assignee": { "id": 4238, "name": "Jordan Rivera" }, "lastReviewedBy": { "id": 4238, "name": "Jordan Rivera" } } ``` **SDK Code** ```typescript import { PayabliClient } from "@payabli/sdk-node"; async function main() { const client = new PayabliClient(); await client.caseManagement.transition("9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70", { trigger: "Approve", reason: "Account ownership confirmed with the merchant by phone.", }); } main(); ``` ```python from payabli import payabli client = payabli() client.case_management.transition( uuid_="9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70", trigger="Approve", reason="Account ownership confirmed with the merchant by phone.", ) ``` ```java package com.example.usage; import io.github.payabli.api.PayabliPayabliApiOasClient; import io.github.payabli.api.resources.casemanagement.requests.TransitionCaseRequest; import io.github.payabli.api.types.CaseTrigger; public class Example { public static void main(String[] args) { PayabliPayabliApiOasClient client = PayabliPayabliApiOasClient .builder() .build(); client.caseManagement().transition( "9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70", TransitionCaseRequest .builder() .trigger(CaseTrigger.APPROVE) .reason("Account ownership confirmed with the merchant by phone.") .build() ); } } ``` ```csharp using PayabliPayabliApiOas; using System.Threading.Tasks; namespace Usage; public class Example { public async Task Do() { var client = new PayabliPayabliApiOasClient(); await client.CaseManagement.TransitionAsync( "9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70", new TransitionCaseRequest { Trigger = CaseTrigger.Approve, Reason = "Account ownership confirmed with the merchant by phone." } ); } } ``` ```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.TransitionCaseRequest{ Trigger: payabli.CaseTriggerApprove, Reason: "Account ownership confirmed with the merchant by phone.", } client.CaseManagement.Transition( context.TODO(), "9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70", request, ) } ``` ```php caseManagement->transition( '9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70', new TransitionCaseRequest([ 'trigger' => CaseTrigger::Approve->value, 'reason' => 'Account ownership confirmed with the merchant by phone.', ]), ); ``` ```ruby require 'uri' require 'net/http' url = URI("https://api-sandbox.payabli.com/api/v2/cases/9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70/transitions") 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 \"trigger\": \"Approve\",\n \"reason\": \"Account ownership confirmed with the merchant by phone.\"\n}" response = http.request(request) puts response.read_body ``` ```swift import Foundation let headers = ["Content-Type": "application/json"] let parameters = [ "trigger": "Approve", "reason": "Account ownership confirmed with the merchant by phone." ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/v2/cases/9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70/transitions")! 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() ```