--- title: "Simulate a collection" method: POST path: "/collections/transfer/simulate" tags: ["Simulation (Sandbox only)"] --- # Simulate a collection `POST /collections/transfer/simulate` ## Request - Base URL: `https://sandboxapi.fincra.com` - URL: `https://sandboxapi.fincra.com/collections/transfer/simulate` - Auth: API key in header `api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Simulate an incoming collection to one of your existing Fincra virtual accounts. > **Sandbox only:** This operation is available through `https://sandboxapi.fincra.com`. It does not create a real transfer or move real funds. The `payee` must identify an existing virtual account belonging to your authenticated business in the same currency as the simulation. Use `accountNumber` for bank-account rails or `interacEmail` for CAD Interac collections. Replace the placeholder payee details in the examples before using **Try It**. The simulator always processes the collection as a virtual-account payment. You do not need to send a payment-method field. ### Simulation outcomes | Outcome | Request value | Response status | Webhook event | | --- | --- | --- | --- | | Successful | Any amount other than `999`, unless the RFI rule below applies | `successful` | `collection.successful` | | Failed | `amount: 999` | `failed` | `collection.failed` | | Request for information (RFI) | `amount` of `10000` or more for an additional virtual account in CAD, GBP, EUR, USD, ZAR or ZMW | `pending` | `collection.additional-info-requested` | > A `200` response with top-level `success: true` means the simulation request was processed. Always inspect `data.status` for the simulated transaction outcome. If you supply `reference`, Fincra returns it as `data.metadata.customerId`. The value in `data.reference` is the collection reference generated by Fincra. ## Request body - CollectionSimulationRequest - `amount` number, required: Amount to simulate. Use `999` to simulate a failed collection. For eligible additional virtual accounts, amounts of `10000` or more simulate an RFI flow. - `currency` 'NGN' | 'KES' | 'GHS' | 'GBP' | 'EUR' | 'USD' | 'UGX' | 'TZS' | 'ZAR' | 'ZMW' | 'CAD', required: Three-letter currency code for the collection being simulated. - `payer` union, required: A participant in the simulated collection. Provide exactly one of `accountNumber` or `interacEmail`. - object - `name` string, required: Name of the account holder or sender. - `accountNumber` string, required: Account number used for bank-account collection rails. - `interacEmail` string, email: Interac email alias used for CAD Interac collections. - `bankCode` string: Bank code, where applicable to the collection rail. - `bankName` string: Bank name, where applicable to the collection rail. - object - `name` string, required: Name of the account holder or sender. - `accountNumber` string: Account number used for bank-account collection rails. - `interacEmail` string, email, required: Interac email alias used for CAD Interac collections. - `bankCode` string: Bank code, where applicable to the collection rail. - `bankName` string: Bank name, where applicable to the collection rail. - `payee` union, required: A participant in the simulated collection. Provide exactly one of `accountNumber` or `interacEmail`. - object - `name` string, required: Name of the account holder or sender. - `accountNumber` string, required: Account number used for bank-account collection rails. - `interacEmail` string, email: Interac email alias used for CAD Interac collections. - `bankCode` string: Bank code, where applicable to the collection rail. - `bankName` string: Bank name, where applicable to the collection rail. - object - `name` string, required: Name of the account holder or sender. - `accountNumber` string: Account number used for bank-account collection rails. - `interacEmail` string, email, required: Interac email alias used for CAD Interac collections. - `bankCode` string: Bank code, where applicable to the collection rail. - `bankName` string: Bank name, where applicable to the collection rail. - `reference` string: Your identifier for the simulated customer or transaction. It is returned as `data.metadata.customerId`; Fincra generates `data.reference` separately. - `narration` string: Description of the simulated collection. It is returned in `data.description`. ## Response `200` The simulation was processed. Inspect `data.status` to determine the simulated transaction outcome. - CollectionSimulationResponse - `success` true, required: Indicates that Fincra processed the simulation request, not that the simulated collection succeeded. - `message` 'Collection processed successfully', required - `data` CollectionSimulationData, required - `_id` string, required: Internal collection identifier. Sandbox simulations may return an empty string. - `business` string, required: Fincra business ID associated with the virtual account. - `virtualAccount` string: Fincra ID of the virtual account receiving the simulated collection. - `virtualAccountType` string: Type of virtual account receiving the simulated collection. - `sessionId` string, uuid, required: Session identifier generated for the simulation. - `senderAccountName` string, nullable, required - `senderAccountNumber` string, nullable, required: Sender account number or Interac email, depending on the rail. - `senderBankName` string, nullable, required - `senderBankDetails` CollectionSimulationBankDetails, required - `bankName` string, nullable, required: Sender bank name. - `bankCode` string, nullable, required: Sender bank code. - `swiftCode` string, nullable, required: Sender bank SWIFT code, when available. - `bic` string, nullable, required: Sender bank BIC, when available. - `recipientAccountName` string, nullable, required - `recipientAccountNumber` string, nullable, required: Recipient account number or Interac email, depending on the rail. - `recipientBankName` string, nullable, required - `sourceCurrency` 'NGN' | 'KES' | 'GHS' | 'GBP' | 'EUR' | 'USD' | 'UGX' | 'TZS' | 'ZAR' | 'ZMW' | 'CAD', required: Three-letter currency code for the collection being simulated. - `destinationCurrency` 'NGN' | 'KES' | 'GHS' | 'GBP' | 'EUR' | 'USD' | 'UGX' | 'TZS' | 'ZAR' | 'ZMW' | 'CAD', required: Three-letter currency code for the collection being simulated. - `sourceAmount` number, required - `destinationAmount` number, required - `description` string, required - `amountReceived` number, required: Net amount received after applicable fees. - `fee` number, required: Fee calculated for the simulated collection. - `customerName` string, required - `settlementDestination` string, required - `status` 'successful' | 'failed' | 'pending', required: Simulated transaction outcome. This is independent of the top-level `success` field. - `initiatedAt` string, date-time, required - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `reference` string, uuid, required: Collection reference generated by Fincra. - `metadata` object: Metadata attached to the simulated collection. - `customerId` string: The value supplied in the request `reference` field. ## Other responses - `400`: The request payload is invalid. - `401`: The sandbox API key is missing or invalid. - `403`: The operation is unavailable outside the sandbox environment. - `404`: No virtual account belonging to the authenticated business matches the supplied payee and currency. ## Changes - **2026-11-03** `526b1509a02d`: 1 info - endpoint added [Operation history](https://skmtc.dev/fincra/apis/awesome-new-api/changes/collections/transfer/simulate/post.md) --- [API](https://skmtc.dev/fincra/apis/awesome-new-api.md) - [All operations](https://skmtc.dev/fincra/apis/awesome-new-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fincra/apis/awesome-new-api/revisions/526b1509a02d?raw)