Standing Orders

Creating new standing orders through the payments API

Scopes

Creating standing orders requires the standing_orders:create scope to be enabled on the API client

Claims

These are the values that can be passed into the moneyhub.getStandingOrderAuthorizeUrl method or the mh:standing_order claim within the id_token

{
  bankId: "Bank id to authorise payment from", // required
  payeeId: "Id of payee", // payeeId or payee required
  payee: { // payeeId or payee required
    accountNumber: "12345678",
    sortCode: "123456",
    name: "payee name"
  },
  payeeType: "Payee type [api-payee|mh-user-account]", // optional - defaults to api-payee
  payerId: "Id of payer", // required only if payerType is defined
  payerType: "Payer type [mh-user-account]", // required only if payerId is used
  reference: "The reference for standing order",
  frequency: {
    repeat: "The frequency to repeat the standing order [Daily,Weekly,Monthly]",
    day: "The number of the day of the repeating period to make the payment",
    week: "The number of the week of the repeating period to make the payment",
    onlyWorkDays: "Specifies whether the payment should only be made on working days",
    month: "The number of the month on which to repeat the payment",
    region: "The region for dates of quarterly payments"
  },
  numberOfPayments: "The number of payments to complete the standing order", // required if finalPaymentDate is not specified
  firstPaymentAmount: "Amount in pence to authorize payment",
  recurringPaymentAmount: "Amount in pence to authorize payment", // optional when it is the same as the first amount
  finalPaymentAmount: "Amount in pence to authorize payment", // optional when it is the same as the first amount
  currency: "The currency code for the standing order amount [GBP]",
  firstPaymentDate: "The date to make the first payment",
  recurringPaymentDate: "The date to make the first repeating payment",
  finalPaymentDate: "The date to make the final payment", // required if numberOfPayments is not specified
  state: "your state value",
  nonce: "your nonce value", // optional
  context: "Payment context [Other,BillPayment,PartyToParty]", // optional - defaults to PartyToParty
  claims: claimsObject, // optional
}
{
      payeeId: "14edab6d-7aed-4ed3-b01b-9592a5d539c6", // An API Payee
      bankId: "5233db2a04fe41dd01d3308ea92e8bd7", // Ozone bank
      reference: "Payments over 6 days",
      frequency: {
        repeat: "Daily"
      },
      firstPaymentAmount: 10000,
      recurringPaymentAmount: 3023,
      finalPaymentAmount: 1554,
      currency: "GBP",
      firstPaymentDate: "2021-03-16T00:00:00.000Z",
      recurringPaymentDate: "2021-03-17T00:00:00.000Z",
      finalPaymentDate: "2021-03-22T00:00:00.000Z",
      state: "foo",
      nonce: "bar",
}
{
      payeeId: "70c863f4-4840-4b98-babb-aeb8089eeba1", // An API Payee
      bankId: "5233db2a04fe41dd01d3308ea92e8bd7", // Ozone bank
      reference: "20 Pounds Monthly",
      frequency: {
        repeat: "Monthly",
        day: 30, // On the 30th of the month
      },
      numberOfPayments: 12,
      firstPaymentAmount: 2000,
      currency: "GBP",
      firstPaymentDate: "2021-03-16T00:00:00.000Z",
      state: "foo",
      nonce: "bar",
}

Frequency Examples

The frequency is mapped to Open Banking format as follows

FrequencyOB EquivalentDescription
{repeat: "Daily"}EvryDayEvery day
{repeat: "Daily", onlyWorkDays: true}EvryWorkgDayEvery working day
{repeat: "Daily", day: 15}IntrvlDay:15Every 15 Calendar day
{repeat: "Weekly", week: 1, day: 3}IntrvlWkDay:01:03Every week, on the 3rd day of the week
{repeat: "Weekly", week: 2, day: 3}IntrvlWkDay:02:03Every 2nd week, on the 3rd day of the week
{repeat: "Monthly", week: 2, day: 3}WkInMnthDay:02:03Every month, on the 2nd week of the month, and on the third day of the week
{repeat: "Monthly", day: 3}IntrvlMnthDay:01:03Every month, on the 3rd day
{repeat: "Monthly", month: 1, day: -1}IntrvlMnthDay:01:-01Every month, on the last day of the month
{repeat: "Monthly", month: 6, day: 15}IntrvlMnthDay:06:15Every 6th month, on the 15th day of the month

Further information on the Opening Banking format can be found here https://openbankinguk.github.io/read-write-api-site3/v3.1.10/resources-and-data-models/aisp/standing-orders.html#frequency-examples

Authorisation

To create a standing order you can generate an authorization URL using the Moneyhub API Client https://github.com/moneyhub/moneyhub-api-client#getstandingorderauthorizeurl

The end user should be directed to a consent page, showing the details of the standing order where they can confirm and consent

1016

Once the user has confirmed the details, they will be forwarded to the bank to login and authorise the standing order. The response this step is an authorisation code, which can be exchanged to complete the standing order setup
https://github.com/moneyhub/moneyhub-api-client#exchangecodefortokens

Status

When created the standing order will have one of these statuses. To refresh the status of a standing order it can be requested from the /standing-orders/:standingOrderId endpoint and checked with the updatedAt date

StatusDescription
InProgress The standing order is being authorised and has not yet been submitted to the bank
InitiationPending The payment order has been submitted to the bank and initiation is pending
InitiationFailed The initiation of the payment order has failed
InitiationCompleted The initiation of the payment order is complete
Cancelled Payment initiation has been successfully cancelled after having received a request for cancellation