Standing Order Requests

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", // required
  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"
  },
  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",
}

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

Once the user has confirmed the details, they will be forwarded to the bank to login and authorise the standing the 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

Status

Description

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