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", // 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
Frequency | OB Equivalent | Description |
---|---|---|
{repeat: "Daily"} | EvryDay | Every day |
{repeat: "Daily", onlyWorkDays: true} | EvryWorkgDay | Every working day |
{repeat: "Daily", day: 15} | IntrvlDay:15 | Every 15 Calendar day |
{repeat: "Weekly", week: 1, day: 3} | IntrvlWkDay:01:03 | Every week, on the 3rd day of the week |
{repeat: "Weekly", week: 2, day: 3} | IntrvlWkDay:02:03 | Every 2nd week, on the 3rd day of the week |
{repeat: "Monthly", week: 2, day: 3} | WkInMnthDay:02:03 | Every month, on the 2nd week of the month, and on the third day of the week |
{repeat: "Monthly", day: 3} | IntrvlMnthDay:01:03 | Every month, on the 3rd day |
{repeat: "Monthly", month: 1, day: -1} | IntrvlMnthDay:01:-01 | Every month, on the last day of the month |
{repeat: "Monthly", month: 6, day: 15} | IntrvlMnthDay:06:15 | Every 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
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
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 |
Updated about 1 year ago