Simulate transaction status

Simulate transaction status changes a sandbox payout status.

For the step-by-step payout flows, see Testing payouts.

important

This request works in the sandbox only.

Endpoint

POST /api/v1/simulations/transactions/{systemReferenceNumber}/transition

Simulate transaction status changes a payout status.

Request

{
  "nextStatus": "RFI_REQUESTED",
  "requestInfoFor": "creditor_salaryStatement"
}

Parameters

Field	Required	Description
nextStatus	Yes	Status to apply. See the values below.
requestInfoFor	No	Information to request. If you omit it, the default is creditor_lastName.

nextStatus values

Status	Use
RFI_REQUESTED	Request more information
COMPLIANCE_COMPLETED	Mark compliance as approved
REJECTED	Reject the transaction. This status is permanent.
PAID	Mark the payout as paid
RETURN	Mark the payout as returned by the bank
EXPIRED	Mark the payout as expired

requestInfoFor

Omit requestInfoFor to use creditor_lastName.

{
  "nextStatus": "RFI_REQUESTED"
}

Set requestInfoFor when you need a specific item.

{
  "nextStatus": "RFI_REQUESTED",
  "requestInfoFor": "creditor_salaryStatement"
}

Party	Accepted values
Creditor (beneficiary)	creditor_firstName, creditor_address, creditor_bankName, creditor_passport, creditor_bankStatement, creditor_sourceOfFunds, creditor_others
Debtor (sender)	debtor_firstName, debtor_lastName, debtor_address, debtor_bankName, debtor_passport, debtor_bankStatement, debtor_sourceOfFunds, debtor_others

Valid transitions

From	To
ACTION_REQUIRED	RFI_REQUESTED
ACTION_REQUIRED	COMPLIANCE_COMPLETED
RFI_RESPONDED	COMPLIANCE_COMPLETED
RFI_RESPONDED	REJECTED
SENT_TO_BANK	PAID
SENT_TO_BANK	RETURN
PAID	RETURN
SCHEDULED	EXPIRED
AWAITING_FUNDS	EXPIRED

Response

A successful call returns HTTP 200.

{
  "message": "Status has been updated to PAID successfully"
}

An invalid transition returns HTTP 422.

{
  "errors": [
    {
      "code": "sim_invalid_next_status",
      "description": "Next Status allowed from current ACTION_REQUIRED is RFI_REQUESTED"
    }
  ]
}

Error codes

Code	Meaning	What to do
sim_invalid_system_reference_number	The transaction ID is invalid or does not exist	Confirm the payout was created
sim_invalid_next_status	The status transition is not allowed	Use a transition from the table above
unauthorized	The API key is missing or invalid	Check the x-api-key header
forbidden	The caller does not have permission	Contact Nium Support