Creating queued transactions

Queued transactions (also known as QTX) are those that are held by our system and then released at a later date, such that the payment will arrive on (or as near to as possible) a specific date. For background on queued transactions, please see Queued Transaction Overview, and for the API reference documentation that shows details of the JSON requests please see here.

To create a queued transaction, you can add the RequestedValueDate and DateSearchMode parameters to a regular immediate transaction call...

POST api/transactionRequests

{
  SendValue: 100.00,
  SendCurrency: "EUR",
  Recipient: {
    Name: "B BAGGINS",
    RecipientReference: "Testing",
    Country: "GB",
    Currency: "GBP",
    Account: {
      SortCode: "112233",
      AccountNumber: "22233445"
    }
  },
  RequestedValueDate: '2020-01-31',
  DateSearchMode: 'Backward'
}

This says "Send €100 to be received on the 31st January 2020, and if that is a working day or holiday, search backwards to find the next closest woking day".

Backward is unsurprisingly the default for the search direction, so it can be omitted - people usually want to be paid early if their payment will not show up on the exact day due to working day constraints. If you wish however you can set this value to Forward and we'll look ahead for the next working day.

Assuming that the TX validates OK and that the rquested value date is achievable, the API will respond with details of the transaction...

{
  "DateSearchMode": "Backward",
  "Events": [
  ],
  "LatePaymentMode": "Cancel",
  "Merchant": "Transfercorp UK Ltd",
  "Recipient": {
    "Country": "GB",
    "Currency": "GBP",
    "Name": "B BAGGINS",
    "RecipientReference": "Testing",
    "Type": "Person"
  },
  "RequestedValueDate": "2020-01-31",
  "Route": {
    "DestinationCurrency": {
      "Currency": "GBP",
      "Value": 84.4
    },
    "ExchangeRate": 0.8440551083,
    "QueuedUntil": "2020-01-30T00:00:00Z",
    "SourceCurrency": {
      "Currency": "EUR",
      "Value": 100.0
    },
    "ValueDate": "2020-01-31"
  },
  "SendAccount": "Transfercorp UK Ltd EUR",
  "SendCurrency": "EUR",
  "SendValue": 100.0,
  "Status": "Queued",
  "TransactionCreatedUTC": "2020-01-28T17:06:48.6055471Z",
  "TransactionId": "bcef29ca-3a0b-48cf-82d9-1c7c2579ba36",
  "TransactionRequestType": "Default"
}

The response provides the ValueDate, which is when we expect the recipient to receive their payment. Also note that the status is Queued, and it will be in this state until midnight on 30th January 2020.

Cancelling a QTX

A queued transaction can be cancelled - as long as it's before the QueuedUntil date. To cancel a queued transaction you make a request as follows...

PUT api/transactionRequests/{id}

{
  Status: "Cancelled"
}

The response will be a 202 Accepted if the queue request is valid.

Common Errors

With queued transactions the most common errors you are likely to see are as follows.

Requested Value Date too soon

This error is returned when we don't have enough time to process the transaction before the requested value date - we often have a lead time of a day (sometimes more) to get a payment to a given country, so if you receive this you are basically asking for the impossible.

{
  "Code": "RequestedValueDateTooSoon",
  "Message": "We cannot honour the requested value date as with holidays/weekends, bank lead time and our lead time the payment will not arrive in time.",
  "MoreInfo": "https://docs.vitessepsp.com/reference#section-requestedvaluedatetoosoon"
}

Requested Value Date too distant

This is the opposite of the above - you have asked us to queue a transaction longer than the period we permit for this...

{
  "Code": "RequestedValueDateTooDistant",
  "Message": "The selected currency only permits requested value dates of up to 7 days.",
  "MoreInfo": "https://docs.vitessepsp.com/reference#section-requestedvaluedatetoodistant"
}

You will see in the above that the permitted duration is returned as part of the API response.