Guides and tutorials

Integrate Bud's Payment TTP Flow

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 Third Party Provider (TPP). This means that you’ll be using Bud’s license (as a registered PISP) in order to provide a payment initiation service to your Customers. As a result, you have to use BudPay to allow your customers to process payments.

Prerequisites

Prior to using any of Bud’s APIs to initiate payments, clients must perform the following steps:

  1. Sign Up and Login to Bud's Developer Console

  2. Create and project and authenticate with Bud’s platform

  3. Configure Callback URL (Optional)

Clients are required to configure their Callback URL in order to receive event notifications regarding the status of different tasks. In terms of the Payment Initiation Service flow, Bud will use your Callback URL to send requests detailing the status of your payment initialisation.

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

  • Log into the Bud developer console

  • 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 Payment Status Updates

  • Input your chosen URL into the text space provided.

The Callback URL specified will be used to notify you detailing whether the payment in question was a success or not.

List Providers

The first step is to enable the Customer to select which bank provider also known as the Account Servicing Payment Service Provider (ASPSP) to initiate the payment from. You can either create the bank provider selection screen within your own UX, or rely on BudPay for this.

You can call the List Providers endpoint in order to retrieve all the ASPSPs that Bud currently supports along with useful information such as display name, maintenance windows, the provider brand icon and the payment services available.

{
"operation_id": "payment_providers_get",
"data": [
"provider": "BankOfBudOBUK",
"display_name": "Bank of Bud - Open Banking UK",
"icon": "https://assets.thisisbud.com/openbanking/bud-bank-logo.png",
"services": [
"domestic-single-payment"
"domestic-standing-order"
"domestic-scheduled-payment"
]
"maintenance_status": "inactive",
"maintenance_window": null,
"country_code": "GBR",
"implementation_type": "OpenbankingUK"
"supported_currencies": [
"GBP"
],
"required_actions": [
"confirm_single_payment"
"confirm_standing_order"
]
]
}

 

Initiate a payment via BudPay

Make a request to the BudPay URL endpoint to initiate a payment by providing the details including:

  • redirect_url - the destination to redirect the Customer to once the payment has been initiated

  • provider - optional depending on whether you want the bank selection to be pre-populated within the BudPay journey

  • reference - the payment reference

  • recipient - details of the recipient of the payment

    • type - the account number type (sort code and account number for UK or IBAN for EU payments)

    • name - of the recipient

    • account_number - sort code or IBAN as defined by the recipient type

  • sender - this is the entity and bank account that the payment will be sent from.

    • user_id - used to uniquely identify a user within your application

    • type - the account number type

    • name - of the sender

    • account_number - sender IBAN required for EU payments (if this field is required to make the EU payment but is not provided within the API request then the BudPay flow will ask the end user to confirm)

    • provider - The name (identifier) of the payment provider

  • amount - monetary value and associated currency

    • value - monetary unit of currency

    • currency - ISO 4217 currency code

Bud will return the payment id (unique identifier given to a payment transaction on Bud’s platform) along with the Bud Pay URL for the customer to authorise the payment, after a successful request. Store the payment id to query the state of the payment.

{
"operation_id": "v1_payments_domestic_single_post",
"data": {
"bud_pay_url": "https://payments-flow-sandbox.thisisbud.com/connect?nonce=pshNqbI9CBf6I1tLo4es7DFz0SlBBJGJjunElynMrINhbqEGccoXyBgeLHgnwcdrxG7xs31KSuWrH8V1e7yF5w",
"payment_id": "6b9b01dd-41fb-4d5c-af86-5e3b2d34849a"
}
}

 

Retrieve Payment Status

After the customer has authorised the payment and has been redirected back to your application you should query/confirm the status of the payment via one of the following methods:

  • Retrieve a payment status for a single payment id

  • Retrieve a paginated list of all payment status’ which can be filtered using header parameters including providers, status codes, dates range and amount range

{
"operation_id": "v1_payments_single_payment_id_get",
"data": {
"payment_id": "89f80199-1199-400e-9092-17208f6f39f5",
"organisation_id": "22f80199-1199-400e-9092-17208f6f39f0",
"client_id": "22f80199-1199-400e-9092-17208f6f39f0",
"method": "FPS",
"reference": "Rent",
"recipient": {
"type": "SortCodeAccountNumber",
"name": "MR TEST RECIPIENT",
"account_number": "01234501234567"
},
"amount": {
"value": "10.00",
"currency": "GBP"
},
"sender": {
"user_id": "client-defined-user-id",
"name": "MR TEST SENDER",
"provider": "Natwest"
},
"known_charges": {
"recipient_charge": {
"charge": "1.50",
"currency": "GBP",
"recipient_receives": "7.00"
},
"sender_charge": {
"charge": "1.50",
"currency": "GBP",
"bank_sends": "10.00",
"total_cost": "11.50"
}
},
"state": {
"status_code": "SETTLED",
"status_message": "Payment Settlement Complete",
"history": [
{
"datetime": "2020-02-02T12:29:33.428944815Z",
"code": "CREATED",
"message": "Payment created"
},
{
"datetime": "2020-02-02T12:29:33.428944815Z",
"code": "AWAITING_AUTH",
"message": "Awaiting Authentication"
},
{
"datetime": "2020-02-02T12:29:33.428944815Z",
"code": "AUTHENTICATED",
"message": "Authenticated; Confirming Funds"
},
{
"datetime": "2020-02-02T12:29:33.428944815Z",
"code": "FUNDS_CONFIRMED",
"message": "Funds Confirmed; Awaiting Payment Initiation"
},
{
"datetime": "2020-02-02T12:29:33.428944815Z",
"code": "INITIATING",
"message": "Initiating Payment"
},
{
"datetime": "2020-02-02T12:29:33.428944815Z",
"code": "ACCEPTED",
"message": "Payment Order Accepted"
},
{
"datetime": "2020-02-02T12:29:33.428944815Z",
"code": "SETTLED",
"message": "Payment Settlement Complete"
}
]
},
"supplementary_status": {
"payment_order": {
"status": "AcceptedSettlementInProgress",
"history": [
{
"datetime": "2020-02-02T12:29:37.628944815Z",
"status": "Pending"
},
{
"datetime": "2020-02-02T12:29:38.628944815Z",
"status": "AcceptedSettlementInProgress"
}
]
},
"consent": {
"status": "Authorised",
"history": [
{
"datetime": "2020-02-02T12:29:34.828944815Z",
"status": "AwaitingAuthorisation"
},
{
"datetime": "2020-02-02T12:29:35.028944815Z",
"status": "Authorised"
}
]
},
"confirmation_of_funds": {
"status": "Available",
"history": [
{
"datetime": "2020-02-02T12:29:35.028944815Z",
"status": "Available"
}
]
}
},
"required_action": null,
"errors": [
{
"code": "FAILED_FUNDS_CONFIRMATION",
"description": "The call to the provider to confirm funds returned an error"
}
],
"created_at": "2020-02-02T12:29:33.428944815Z"
},
"metadata": []
}


On completion of the payment flow, Bud will fetch the status of the payment. The result of this task will be pushed to your configured Callback URL. An example request payload within a callback of a successful payment transaction is follows:

{
"data": {
"event": "payment.success",
"payment_id": "89f80199-1199-400e-9092-17208f6f39f5",
"service": "domestic-single-payment",
"user_id": "22f80199-1199-400e-9092-17208f6f39f0",
}
}

Looking for more?

Get in touch with one of the team

Get started

Market coverage

All of our connections for account aggregation and payments

Get started

API Docs

Take a look at the resources available for our APIs.

API Docs