Creating deferred transactions

🔶
Legacy API. This topic describes our original API. If you are integrating with Vitesse, use Vitesse API instead.

Deferred transactions allow you to send us one or more transactions, group them together, and then pay for the whole set in one go. There is no need to hold funds on account with us as we hold the transactions until your funds show up. For background on deferred transactions, please see Deferred Transaction Overview, and for the API reference documentation that shows details of the JSON requests please see here.

In order to create a deferred transaction, it's first necessary to lock in the set of FX rates for a period of days. You do this by calling the Forex API and specifying this duration...

POST api/forex/1/GBP,EUR,AUD

You specify the duration in days (in the above this is one), and also specify which currencies you are interested in. This will return a martix of rates to you...

{
  "Currencies": [
    {
      "Code": "AUD",
      "Rates": [
        {
          "Code": "EUR",
          "Value": 0.5828298688
        },
        {
          "Code": "GBP",
          "Value": 0.4919405280
        }
      ]
    },
    {
      "Code": "EUR",
      "Rates": [
        {
          "Code": "AUD",
          "Value": 1.5484793220
        },
        {
          "Code": "GBP",
          "Value": 0.8018523529
        }
      ]
    },
    {
      "Code": "GBP",
      "Rates": [
        {
          "Code": "AUD",
          "Value": 1.8345713530
        },
        {
          "Code": "EUR",
          "Value": 1.1255189272
        }
      ]
    }
  ],
  "ExpiresOn": "2020-01-29T17:29:50.707Z",
  "RateGroupId": 1137418
}

The matrix returned provides you with the FX rate we will use when processing a given transaction. Please also refer to the full documentation on Fixed FX rates as that also describes other features of this API.

❗️
Important
Each rate group has an ExpiresOn value which defines exactly when this rate group will cease to be usable. If you attempt to post a transaction using an expired rate group, the API will return an error.

Now you have fixed your FX rates you can use them when creating a deferred transaction...

POST api/deferredTransactionRequests

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

Deferred transactions need to be grouped together - there may be one or more transactions in a group, the only caveat is that they must all be the same send currency. You can find all transactions that need to be grouped by calling the API as shown below...

GET api/deferredTransactionRequests

That will respond with a collection of any deferred transaction requests that need to be grouped.

{
  "Transactions": [
    {
      "CreatedOn": "2020-01-28T17:35:40.11Z",
      "DestinationCurrency": "GBP",
      "DestinationValue": 1000.00,
      "ExchangeRate": 1.0000000000,
      "ExpiresOn": "2020-01-29T17:35:04.573Z",
      "LatePaymentMode": "Cancel",
      "Location": "https://staging-api.vitessepsp.com/api/deferredtransactionrequests/c1363d1b-5df9-4eed-a5d5-45677924f3dd",
      "MerchantName": "Transfercorp UK Ltd",
      "SendAccountId": 339,
      "SourceCurrency": "GBP",
      "SourceValue": 1000.00,
      "Status": "PendingGrouping",
      "TransactionRequestId": "c1363d1b-5df9-4eed-a5d5-45677924f3dd"
    }
  ]
}

You can group requests together by calling the grouping API. You need to pass an array of the deferred transcation ID's to create the group...

POST api/deferredTransactionGroups

[
  "c1363d1b-5df9-4eed-a5d5-45677924f3dd",
  ...
]

That will verify that all transactions in the group are of the same currency, and that they are all currently ungrouped and also not expired. Assuming everything is OK you will receive a response as follows.

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

❗️
Important
A deferred transaction group may be made up of several transactions associated with different forex rate groups. The ExpiresOn time for the group is computed as the earliest expiration data of all transactions in the group - so if you had one transaction whose rate group expired at 2020-01-20 00:00, and another whose rate group expired at 2020-01-20 12:00, the expiration of the whole group, and the transactions within it, will be the earlier of these two times, 2020-01-20 00:00.
Once a DTX group has expired, all transactions within that group are cancelled.

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.

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"
}