Setup Payments with your own license

🚧
For regulated clients only
To use this method of connecting with Bud you must be a licensed PISP. This requires a license from the FCA. If you wish to use Bud's license for this functionality please see our Setup payments guide here
If you have questions please contact us to confirm your status via the chatbot (bottom-right of screen 👉) or via a support request.

Below we’ll provide you with a step-by-step guide to help you integrate Bud’s Payment Initiation Service when using Bud as a Technical Service Provider (TSP). This means that Bud will be using your license (as a registered PISP) in order to provide a payment initiation service to your Customers. This will allow you to use your own interface to guide your users through payment initiation. Details of our coverage can be found here

Before starting

Before starting you’ll need:

to have provided your account manager with details requested during onboarding to allow Bud to register your Open Banking License with providers (ie banks);
a valid OAuth access token - for further details on how to authenticate to Bud’s APIs please see this guide;

View providers & check maintenance windows

The GET /v1/payments/providers endpoint (here) will allow you to view the available providers supported by Bud’s Payment Initiation service. Each provider object will contain a maintenance_window and maintenance_status fields. These can be used to check if a provider is currently (or soon to be) undergoing maintenance and may include a timescale for how long it will be in maintenance.

{
    "operation_id": "v1_payments_providers_get",
    "data": [
        {
					"provider": "Natwest",
					"display_name": "Natwest",
					"icon": "https://assets.thisisbud.com/openbanking/natwest-logo.jpg",
					"services": [
						"domestic-single-payment",
						"domestic-scheduled-payment",
						"domestic-standing-order"
					],
					"maintenance_status": "inactive",
					"maintenance_window": null,
					"country_code": "GBR",
					"implementation_type": "OpenbankingUK",
					"supported_currencies": [
						"GBP"
					],
					"required_actions": [
						"confirm_single_payment",
						"confirm_standing_order",
						"confirm_scheduled_payment"
					]
				},
        {
						"provider": "Monzo",
						"display_name": "Monzo",
						"icon": "https://assets.thisisbud.com/openbanking/monzo-logo.png",
						"services": [
							"domestic-single-payment",
							"domestic-scheduled-payment",
							"domestic-standing-order"
						],
						"maintenance_status": "inactive",
						"maintenance_window": null,
						"country_code": "GBR",
						"implementation_type": "OpenbankingUK",
						"supported_currencies": [
							"GBP"
						],
						"required_actions": [
							"confirm_single_payment",
							"confirm_standing_order",
							"confirm_scheduled_payment"
						]
				}
    ],
    "metadata": null
}

The provider field within the response body, e.g. “provider”: “Lloyds”, shows the name of the ASPSP that your Customers can connect to. Please note that the value of this provider field is the unique identifier for the corresponding ASPSP, and it is used elsewhere within Bud’s Payment Initiation APIs.

📘
What is a maintenance window?
A maintenance window is a period of time where the provider (ASPSP) will be making changes or improvements to their service. During this time the maintenance_status will be listed as active and your customers will be unable to make a payment from these providers. When the maintenance_window is over the provider will be available for payments again.

Configuring Callback URL(s)

Clients are required to configure their Callback URL(s) in order to receive event notifications regarding the status of different tasks. In terms of Payment Initiation Service flow, Bud will use your Callback URL to send requests detailing the status of your payment initiation. Full details around callbacks at Bud can be found here

There are three different webhooks available in regard to the payment flow:

Single payment status updated - This will fire when the status of a single payment has either succeeded or failed.
Standing order status updated - This will fire when the status of a standing order payment has either succeeded or failed.
Scheduled payment status updated - This will fire when the status of a scheduled payment has either succeeded or failed.

❗️
Please note that all of Bud's Callbacks are sent over TLS as standard. All webhooks are also signed, the public key to verify is included in the X-Signature header.

Callback URL set-up steps

The steps to set-up your Callback URL are as follows:

Log into the Bud Console (log in | sign up).
Navigate to Projects
Select the project that you would like to configure the callback for
There will be a header for Webhooks that will appear within the project
Select the edit icon next to Single payment status updated
Input your chosen URL into the text space provided.

The Callback URL specified will be used to notify you when Bud has completed (or failed) the payment with the relevant ASPSP.

Steps to initiate a single payment (Using your own user interface)

Using this method you will be required to create a user interface for your users to progress through the payment initiation flow. You will also be required to handle the redirect back from the users provider and therefore submit the authorisation codes to bud. If you would prefer to use a Bud managed interface please see the section below for details of this.

The steps to initiate a single payment are as follows:

The first step to initiate a single payment is to make a request to the Create Single Domestic Payment endpoint. Using the POST /v1/payments/single endpoint (here), you will need to specify a provider_redirect_url, provider (retrieved from the providers endpoint detailed above, value is provider within each object) and payment_details within the request payload e.g.

{
  "provider_redirect_url": "https://thisisbud.com",
  "provider": "BankOfBudOBUK",
  "payment_details": {
    "reference": "Test",
    "recipient": {
      "name": "Joe Bloggs",
      "type": "SortCodeAccountNumber",
      "account_number": "11223309876543"
    },
    "amount": {
      "value": "0.01",
      "currency": "GBP"
    },
    "sender": {
    	"name": "Alice Bloggs",
    	"user_id": "test-user"
    }
  }
}

This will initiate the process for generating an authorisation URL with the specified provider.

Direct your customer to the Providers Authorisation URL using the URL returned in the authorisation_url in the data object.

❗️
Please note that the returned URL returned as authorisation-url needs to be presented to the user within three hours for all providers. Once this expiration time has been reached, you will need to obtain a new URL for that customer by repeating step 1 above.

Having completed the authorisation flow with their provider your customer will then be redirected back to the specified provider_redirect_url provided in the Create Single Domestic Payment call. The provider will return a number of different parameters as both query parameters (delimited by ?) and fragment parameters (delimited by #).

❗️
Your callback endpoint needs to be able to accept both query parameters and fragment parameters. Most server side code does not support reading fragment parameters from a url so a javascript function may be required initially to combine these parameters.

All these parameters should be transposed into the body of a request to Submit Authorisation Codes POST v1/payments/authorisation-codes endpoint (here). This as a minimum needs to include a code and state value as below.

{  
	"code":"test_code",  
	"state":"9877da90-2b95-4b84-9b66-cee4d20c0b53"  
}

Please note this should be submitted for all responses.

On a successful submission, a final call to the Confirm Single Payment POST v1/payments/single/{payment_id}/confirm endpoint (here) will be required to trigger Bud to initiate the payment with the provider. The result of this payment will be pushed to your configured Callback URL. An example request payload within a callback of a successful payment initiation:

{  
    "data": {  
        "event": "payment.success",
				"payment_id": "9877da90-2b95-4b84-9b66-cee4d20c0b53",
				"service": "domestic-single-payment",
				"user_id": "test-user"
    }  
}

An example request payload within a callback of a failed payment initiation:

{  
    "data": {  
        "event": "payment.failure",
				"payment_id": "3aa5bc7b-8b61-420f-b6f2-41c0377bb631",
				"service": "domestic-single-payment",
				"user_id": "test-user"
    }  
}

Steps to initiate a single payment (Using a bud managed user interface)

This method uses a user interface managed by Bud. Therefore we handle providing a regulatory compliant interface to show to your users. We also handle the redirection back from the users provider to the Bud service. If would you prefer to have your own user interface please use the steps described in the section above.

The steps to initiate a single payment are as follows:

The first step to initiate a single payment is to make a request to the Create Single Domestic Payment endpoint. Using the POST /v1/payments/single endpoint (here), you will need to specify a redirect_url, provider (retrieved from the providers endpoint detailed above, value is provider within each object) and payment_details within the request payload e.g.

{
  "redirect_url": "https://thisisbud.com",
  "provider": "BankOfBudOBUK",
  "payment_details": {
    "reference": "Test",
    "recipient": {
      "name": "Joe Bloggs",
      "type": "SortCodeAccountNumber",
      "account_number": "11223309876543"
    },
    "amount": {
      "value": "0.01",
      "currency": "GBP"
    },
    "sender": {
    	"name": "Alice Bloggs",
    	"user_id": "test-user"
    }
  }
}

This will initiate the process for generating an authorisation URL with the specified provider.

Direct your customer to the Providers Authorisation URL using the URL returned in the authorisation_url in the data object.

❗️
Please note that the returned URL returned as authorisation-url needs to be presented to the user within three hours for all providers. Once this expiration time has been reached, you will need to obtain a new URL for that customer by repeating step 1 above.

Having completed the authorisation flow with their provider your customer will then be redirected back to the Bud managed interface. When this has been completed and the user confirms they will be redirected back to the url you specified in the redirect_url field.
The result of this payment will be pushed to your configured Callback URL. An example request payload within a callback of a successful payment initiation:

{  
    "data": {  
        "event": "payment.success",
				"payment_id": "9877da90-2b95-4b84-9b66-cee4d20c0b53",
				"service": "domestic-single-payment",
				"user_id": "test-user"
    }  
}

An example request payload within a callback of a failed payment initiation:

{  
    "data": {  
        "event": "payment.failure",
				"payment_id": "3aa5bc7b-8b61-420f-b6f2-41c0377bb631",
				"service": "domestic-single-payment",
				"user_id": "test-user"
    }  
}

Steps to retrieve status of a single payment

The steps to check the status of a single payment are below. This can be used to check the status of a payment and all events related to it:

To check the status of a single payment a request to the Retrieve Single Payment Status endpoint POST /v1/payments/single/{payment_id} (here) can be made using the payment_id value returned in step 1 of the Steps to initiate a single payment above. This endpoint will return the full status of the payment including the state and history of the payment. An example is below:

{
	"operation_id": "v1_payments_single_payment_id_get",
	"data": {
		"payment_id": "9877da90-2b95-4b84-9b66-cee4d20c0b53",
		"organisation_id": "9f5015ea-422b-41c9-8010-d0a16c922edc",
		"provider": "BankOfBudOBUK",
		"client_id": "8895ffd1-ff83-4881-b59b-c9acb4a4881d",
		"method": "FPS",
		"reference": "Test",
		"recipient": {
			"type": "SortCodeAccountNumber",
			"name": "Joe Bloggs",
			"account_number": "11223309876543"
		},
		"amount": {
			"value": "0.01",
			"currency": "GBP"
		},
		"sender": {
			"user_id": "test-user",
			"name": "Alice Bloggs",
			"provider": "BankOfBudOBUK"
		},
		"known_charges": {
			"recipient_charge": null,
			"sender_charge": {
				"charge": "0.00",
				"currency": "GBP",
				"bank_sends": "0.01",
				"total_cost": "0.01"
			}
		},
		"state": {
			"status_code": "SETTLED",
			"status_message": "Payment Settlement Complete",
			"history": [
				{
					"datetime": "2023-03-14T11:21:19.21441874Z",
					"code": "CREATED",
					"message": "Payment created"
				},
				{
					"datetime": "2023-03-14T11:21:19.443279829Z",
					"code": "AWAITING_AUTH",
					"message": "Awaiting Authentication"
				},
				{
					"datetime": "2023-03-14T11:21:25.685263945Z",
					"code": "AUTHENTICATED",
					"message": "Authenticated; Confirming Funds"
				},
				{
					"datetime": "2023-03-14T11:21:25.947803106Z",
					"code": "FUNDS_CONFIRMED",
					"message": "Funds Confirmed; Awaiting Payment Initiation"
				},
				{
					"datetime": "2023-03-14T11:21:40.190647092Z",
					"code": "INITIATING",
					"message": "Initiating Payment"
				},
				{
					"datetime": "2023-03-14T11:21:40.482492463Z",
					"code": "SETTLED",
					"message": "Payment Settlement Complete"
				}
			]
		},
		"supplementary_status": {
			"payment_order": {
				"status": "AcceptedSettlementCompleted",
				"history": [
					{
						"datetime": "2023-03-14T11:21:40.190647092Z",
						"status": "Created"
					},
					{
						"datetime": "2023-03-14T11:21:40.482492463Z",
						"status": "AcceptedSettlementCompleted"
					}
				]
			},
			"consent": {
				"status": "Consumed",
				"history": [
					{
						"datetime": "2023-03-14T11:21:19.443279829Z",
						"status": "AwaitingAuthorisation"
					},
					{
						"datetime": "2023-03-14T11:21:25.685263945Z",
						"status": "Authorised"
					},
					{
						"datetime": "2023-03-14T11:21:47.891258032Z",
						"status": "Consumed"
					}
				]
			},
			"confirmation_of_funds": {
				"status": "Available",
				"history": [
					{
						"datetime": "2023-03-14T11:21:25.947803106Z",
						"status": "Available"
					}
				]
			}
		},
		"errors": null,
		"created_at": "2023-03-14T11:21:19.21441874Z",
		"required_action": "confirm_single_payment",
		"required_actions": {
			"confirm_payment": true
		}
	}
}

Other payment types

To initiate either a Standing Order payment or a Scheduled payment the above guide for a single payment still applies but the endpoints to be used should be adjusted as below

Standing Order Payment

Create Standing Order - POST v1/payments/standing-order endpoint (here)

Confirm Standing Order - POST v1/payments/standing-order/{payment_id}/confirm endpoint (here)

Retrieve Standing Order Status - POST v1/payments/standing-order/{payment_id} endpoint (here)

Scheduled Payment

Create Scheduled Payment - POST v1/payments/scheduled endpoint (here)

Confirm Scheduled Payment - POST v1/payments/scheduled/{payment_id}/confirm endpoint (here)

Retrieve Scheduled Payment Status - POST v1/payments/scheduled/{payment_id} endpoint (here)

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.

Setup Payments with your own license

🚧
For regulated clients only

Before starting

View providers & check maintenance windows

📘
What is a maintenance window?

Configuring Callback URL(s)

❗️

Callback URL set-up steps

Steps to initiate a single payment (Using your own user interface)

❗️

❗️

Steps to initiate a single payment (Using a bud managed user interface)

❗️

Steps to retrieve status of a single payment

Other payment types

Standing Order Payment

Scheduled Payment

🚧For regulated clients only

Before starting

View providers & check maintenance windows

📘What is a maintenance window?

Configuring Callback URL(s)

❗️

Callback URL set-up steps

Steps to initiate a single payment (Using your own user interface)

❗️

❗️

Steps to initiate a single payment (Using a bud managed user interface)

❗️

Steps to retrieve status of a single payment

Other payment types

Standing Order Payment

Scheduled Payment

🚧
For regulated clients only

📘
What is a maintenance window?