Creating queued deferred transactions

If you have read about Queued Transactions and also Deferred Transactions you'll see that queued deferred transactions are a combination of both types. For more background information please see the Queued Deferred Transaction Overview, and for the API reference documentation that shows details of the JSON requests please see here.

The first steps with a QDTX is like deferred transactions - you need to create a forex rate group. Please see Fixed FX rates for more details.

Then you can create a QDTX by adding three elements to the API call - those being RequestedValueDate and (optionally) DateSearchMode and LatePaymentMode. These are all explained in the Queued Deferred Transaction Overview so if you are unclear about these values please review the documentation there.

Creating a QDTX is then just another call to the API...

POST api/deferredTransactionRequests

{
  "SendCurrency": "GBP",
  "SendValue": 1000,
  "Recipient": 
  {
    "Name": "Bilbo Baggins",
    "Country": "GB",
    "Currency": "GBP",
    "RecipientReference": "Testing",
    "Account": 
    {
      "AccountNumber": "12345678",
      "SortCode": "112244"
    }
  },
  RateGroupId: 1137418,
  RequestedValueDate: "2020-01-31"
}

Assuming everything validates OK you will receive a response from the API as follows...

{
  "DateSearchMode": "Backward",
  "Events": [],
  "LatePaymentMode": "Cancel",
  "Merchant": "Transfercorp UK Ltd",
  "Recipient": {
    "Country": "GB",
    "Currency": "GBP",
    "Name": "Bilbo Baggins",
    "RecipientReference": "Testing",
    "Type": "Person"
  },
  "RequestedValueDate": "2020-01-31",
  "Route": {
    "DestinationCurrency": {
      "Currency": "GBP",
      "Value": 1000.0
    },
    "ExchangeRate": 1.0,
    "QueuedUntil": "2020-01-30T00:00:00Z",
    "SourceCurrency": {
      "Currency": "GBP",
      "Value": 1000.0
    },
    "ValueDate": "2020-01-31"
  },
  "SendAccount": "Transfercorp UK Ltd GBP",
  "SendCurrency": "GBP",
  "SendValue": 1000.0,
  "Status": "PendingGrouping",
  "TransactionCreatedUTC": "2020-01-29T07:45:45.438924Z",
  "TransactionId": "a748030b-986b-4201-8b40-eb05abe81445",
  "TransactionRequestType": "Default"
}

The Status of the QDTX is PendingGrouping as we're waiting for you to group this transaction with zero or more associated transactions. You can create a DTX group by calling the API as follows...

POST api/deferredTransactionGroups

[
  "a748030b-986b-4201-8b40-eb05abe81445",
  ...
]

That will group the transaction(s) together and provide details of the group to you...

{
  "CreatedBy": "System",
  "CreatedOn": "2020-01-29T07:50:00.697Z",
  "Currency": "GBP",
  "DeferredTransactionGroupId": 51,
  "ExpiresOn": "2020-01-29T17:35:04.573Z",
  "ExportState": "Unnecessary",
  "MerchantId": 5,
  "MerchantName": "Transfercorp UK Ltd",
  "Name": "002TUK",
  "PayInAccount": {
    "Details": {
      "AccountNumber": "99988776",
      "SortCode": "112211"
    },
    "Name": "Barclays GBP"
  },
  "Status": "AwaitingLiquidity",
  "TotalAmount": 1000.00,
  "TotalFees": 0.0,
  "TotalPayment": 1000.00
}

Paying us!

The point of using deferred transactions is to allow us to calculate how much a given set of transactions will cost, and to then wait for you to pay us. In the above example, you would need to send us a TotalPayment of £1000, that needs to reach us by 2020-01-29 at 17:35 (note all times are in UTC), and the reference to use for this payment (such that we can attribute the incoming payment to the appropriate deferred transaction group) is 001TUK.

As you'll also notice, the DTX group provides bank account details for where the payment needs to be sent, such as the sort code and account number of a UK bank.

If you query a QDTX before payment you will find that the status is PendingPayment, and once the payment has been received, the status will change to Queued.

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/deferredTransactionRequests/{id}

{
  Status: "Cancelled"
}

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

Common Errors

A common error you will receive from trying to create a rate group is this...

{
  "Code": "NoDeferredMargin",
  "Message": "Your merchant account does not support locked FX rates for a period of 1 days.",
  "MoreInfo": "https://docs.vitessepsp.com/reference#section-nodeferredmargin"
}

All this means is that your merchant account has not been setup to permit you to create rate groups and deferred requests. In this case please contact our integration team and they can help set this feature up for your account.

Another common error is omitting the RateGroupId from the API call. The response will be as follows in this case...

{
  "Code": "InvalidRateGroup",
  "Message": "An invalid or expired RateGroupId was used.",
  "MoreInfo": "https://docs.vitessepsp.com/reference#section-invalidrategroup"
}