Guides
Postman collections ↗Bud Console ↗

Setup payments

Suggest Edits

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 to the Bud Console
  2. Get API Keys and authenticated access
  3. Configure Callback URL (Optional)

📘

Check out Bud's payment coverage here


Configure Callback URL

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:

  1. Log in to the Bud developer console
  2. Navigate to Projects
  3. Select the project that you would like to configure the callback for
  4. Select Update for the webhook service you're interested in
  5. Input your URL into the text field

There are currently three different payment Callback URLs (webhooks) that you can subscribe to:

  1. Single payment status updated - used to provide an update to clients when the status of a single payment has either succeeded or failed.
  2. Standing order status updated - used to provide an update to clients when the status of a standing order payment has either succeeded or failed.
  3. Schedule payment status updated - used to provide an update to clients when the status of a scheduled payment has either succeeded or failed.

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

List Providers

You can call the GET v1/payments/providers endpoint (here) 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.

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.

{
  "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 POST v1/payments/single/bud-pay-url endpoint (here) 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 (a 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:

  • Call GET v1/payments/single/{payment_id} (here) to retrieve a payment status for a single payment using its 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": "MRS 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": "2022-02-02T12:29:33.428944815Z",
          "code": "CREATED",
          "message": "Payment created"
        },
        {
          "datetime": "2022-02-02T12:29:33.428944815Z",
          "code": "AWAITING_AUTH",
          "message": "Awaiting Authentication"
        },
        {
          "datetime": "2022-02-02T12:29:33.428944815Z",
          "code": "AUTHENTICATED",
          "message": "Authenticated; Confirming Funds"
        },
        {
          "datetime": "2022-02-02T12:29:33.428944815Z",
          "code": "FUNDS_CONFIRMED",
          "message": "Funds Confirmed; Awaiting Payment Initiation"
        },
        {
          "datetime": "2022-02-02T12:29:33.428944815Z",
          "code": "INITIATING",
          "message": "Initiating Payment"
        },
        {
          "datetime": "2022-02-02T12:29:33.428944815Z",
          "code": "ACCEPTED",
          "message": "Payment Order Accepted"
        },
        {
          "datetime": "2022-02-02T12:29:33.428944815Z",
          "code": "SETTLED",
          "message": "Payment Settlement Complete"
        }
        ]
		},
    "supplementary_status": {
      "payment_order": {
        "status": "AcceptedSettlementInProgress",
        "history": [
          {
            "datetime": "2022-02-02T12:29:37.628944815Z",
            "status": "Pending"
          },
          {
            "datetime": "2022-02-02T12:29:38.628944815Z",
            "status": "AcceptedSettlementInProgress"
          }
        ]
      },
      "consent": {
        "status": "Authorised",
        "history": [
          {
            "datetime": "2022-02-02T12:29:34.828944815Z",
            "status": "AwaitingAuthorisation"
          },
          {
            "datetime": "2022-02-02T12:29:35.028944815Z",
            "status": "Authorised"
          }
        ]
      },
      "confirmation_of_funds": {
        "status": "Available",
        "history": [
          {
            "datetime": "2022-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": "2022-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 single payment transaction is as follows:

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




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

Updated 10 months ago