Introduction

File Payments allow customers to upload a payment file that significantly streamlines financial transactions. By consolidating multiple transaction instructions into a single file, this process facilitates the efficient transfer of funds between bank accounts, simplifying and automating the management of numerous payments.

The implementation consists of two main steps:

File upload: This step involves submitting the payment file to the system, setting the foundation for further processing.
Consent creation: This step involves establishing a file-payment-consent, which authorizes the PISP to proceed with initiating the payment as intended.

Scope Requirements

To utilise file payments, your API client must have the necessary authorisation scopes enabled. To have these scopes set up, please reach out to your Moneyhub contact. Below is a list of the required scopes and their corresponding actions:

Name	Action	Required
`pay_file_consent:create`	Create a file-payment-consent	Yes
`pay_file_consent:read`	Read a file-payment-consent	Yes

File Upload

There are currently two ways in which you can upload file payments:

By uploading the raw file payment document, which you can find the documentation for here.
By uploading the file payment data, which you can find the documentation for here.

In both cases you will receive an id as part of the response which you will be able to use to create a file-payment-consent.

Consent Creation

Claims

To create a file-payment-consent, ensure you pass these claim values within the mh:file_payment claim within id_token.

Key	Description	Required
`payFileId`	ID of the file payment obtained during file upload	Yes

Authorisation

You can initiate a file-payment-consent by running the following request:

curl -X POST "https://identity.moneyhub.co.uk/request" \
-H "Content-Type: application/x-www-form-urlencoded" \
-F "client_id=YOUR_CLIENT_ID" \
-F "redirect_uri=YOUR_REDIRECT_URI" \
-F "response_type=YOUR_RESPONSE_TYPE" \
-F "state=YOUR_STATE_VALUE" \
-F "nonce=YOUR_NONCE_VALUE" \
-F "scope=pay_file_consent:create openid id:OPEN_ID_VALUE" \
-F "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
-F "client_assertion=SIGNED_JWT" \
-F "claims=$(echo -n '{
  "id_token": {
    "mh:con_id": {
      "essential": "true"
    },
    "mh:file_payment": {
      "essential": "true",
      "value": {
       "payFileId": "PAY_FILE_ID"
      }
    }
  }
}' | jq -c)"

Then direct the end user to a consent page with file-payment-consent details, where they can confirm and create the file-payment-consent with the chosen ASPSP.

Consent status

After creation, the file-payment-consent will have one of these statuses:

Status	Description
AwaitingUpload	The file for the consent resource is awaiting upload.
AwaitingAuthorisation	The file payment consent has the file uploaded and is awaiting PSU authorisation.
Rejected	The file payment consent was rejected by the bank. This is a final status.
Authorised	The file payment consent has been authorised. This is a final status.
Consumed	The consented action has been successfully completed. This does not reflect the status of the consented action.

To check and refresh the status of a file-payment-consent, make a GET /pay-file-consents/{payFileConsentId} request.

The status may change over time due to various factors and timelines specific to each ASPSP. We recommend periodically checking the status until it reaches a final stage (Rejected or Authorised), to stay informed about updates from the ASPSP.

The payFileCreated webhook notifies you when a file payment consent has been created.

Retrieving All Consents

To view all file-payment-consents, you can make a GET /pay-file-consents request without specifying an id parameter.

File Payment Consents