FIfincra
Simulation (Sandbox only)

Simulate a collection

Changed on

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

OutcomeRequest valueResponse statusWebhook event
SuccessfulAny amount other than 999, unless the RFI rule below appliessuccessfulcollection.successful
Failedamount: 999failedcollection.failed
Request for information (RFI)amount of 10000 or more for an additional virtual account in CAD, GBP, EUR, USD, ZAR or ZMWpendingcollection.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.

post/collections/transfer/simulate

Request

Request body

amountnumber 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.

referencestring

Your identifier for the simulated customer or transaction. It is returned as data.metadata.customerId; Fincra generates data.reference separately.

narrationstring

Description of the simulated collection. It is returned in data.description.

Example request

{
  "amount": 1000,
  "currency": "NGN",
  "payer": {
    "name": "Kora Tumaini",
    "accountNumber": "0123456789",
    "interacEmail": "kora.tumaini@example.com",
    "bankCode": "058",
    "bankName": "Guaranty Trust Bank"
  },
  "payee": {
    "name": "Kora Tumaini",
    "accountNumber": "0123456789",
    "interacEmail": "kora.tumaini@example.com",
    "bankCode": "058",
    "bankName": "Guaranty Trust Bank"
  },
  "reference": "kora-ngn-success-20260829",
  "narration": "NGN collection simulation"
}

Response

The simulation was processed. Inspect data.status to determine the simulated transaction outcome.

successtrue required

Indicates that Fincra processed the simulation request, not that the simulated collection succeeded.

message'Collection processed successfully' required

Example response

{
  "data": {
    "business": "65f1c9ef838af8cda0211d9d",
    "virtualAccount": "65f1ca2e838af8cda0211e02",
    "virtualAccountType": "additional",
    "sessionId": "0124cf97-143b-4354-a7a1-3d00887f7ba7",
    "senderAccountName": "Kora Tumaini",
    "senderAccountNumber": "0123456789",
    "senderBankName": "Guaranty Trust Bank",
    "recipientAccountName": "Example Trading Limited",
    "recipientAccountNumber": "0001234567",
    "recipientBankName": "Example Bank",
    "sourceCurrency": "NGN",
    "destinationCurrency": "NGN",
    "sourceAmount": 1000,
    "destinationAmount": 1000,
    "description": "NGN collection simulation",
    "amountReceived": 986,
    "fee": 13.999999999999998,
    "customerName": "Kora Tumaini",
    "settlementDestination": "wallet",
    "status": "successful",
    "initiatedAt": "2026-08-29T17:35:00.698Z",
    "createdAt": "2026-08-29T17:35:00.725Z",
    "updatedAt": "2026-08-29T17:35:00.725Z",
    "reference": "0c05c977-2fd6-46f4-9272-5f4a60ef1e1b",
    "metadata": {
      "customerId": "kora-ngn-success-20260829"
    }
  }
}

Changes