Payment flows

To understand the various Payments Hub API operations and how they work together to manage the full life-cycle of a payment, this document describes the most commonly used payment scenarios ("payment flows").

Each payment has two main actors: the payer who sends the money, and the beneficiary who receives the money. As an example, this document describes payments occurring in a standard commercial relationship between a merchant and a customer, where the customer (payer) wants to make a payment to purchase goods or services from the merchant (beneficiary). However, Payments Hub can be used by all kinds of payers to send money to all kinds of beneficiaries.

The standard commercial relationship uses 5 basic payment flows:

• The customer can initiate 3 of the payment flows:

  • First of all, if the customer wants to make a purchase, they can initiate the main payment flow by creating a payment. This action also initiates the incoming payment flow for the merchant. These are the only payment flows needed, if the merchant can provide the goods or service, and the customer is happy with what they receive.

  • After making the payment, if the customer notices that they have made a mistake in the payment details, they can initiate the payment cancellation flow to cancel their original payment and make a new one with the correct details.

• The merchant can also initiate 2 payment flows:

  • If the merchant receives a payment they cannot provide the goods or service for, they can initiate a payment return flow. For example, if the customer pays for something the merchant currently cannot provide, or if the customer accidentally makes the payment for the same service twice, this flow sends the customer's money back to them.

  • If the customer is unsatisfied with the goods or service they received, and for any reason wants to return the items and receive a refund, the merchant can initiate a payment refund flow to return part or all of the customer's original payment.

Main payment flow

The main payment flow is used to create a payment.

The customer creates the payment in a financial institution that they have an account with, and the financial institution uses Payments Hub to initiate the payment. The payment is then processed through clearing houses and potentially other intermediaries, until it reaches the merchant's bank account.

During this process, the customer's financial institution can query Payments Hub for the status of the payment, to track its progress.

The following diagram shows the main payment flow when using Payments Hub.

To facilitate creating payments, Payments Hub uses the ISO20022 pacs.008.001.08 message version as part of the POST /pacs008/v08 API operation. The pacs.008.001.08 message contains all the details needed by Payments Hub to create the payment, such as the payment amount and the customer's and merchant's bank account details.

When the customer's financial institution queries Payments Hub for the status of the payment, it uses the GET /pacs002/v10/{paymentsHubId} API operation and receives an ISO20022 pacs.002.001.10 message containing the payment status.

For more information on creating payments with the Payments Hub API, see pacs.008 and pacs.002 - related tutorials.

Incoming payment flow

The incoming payment flow is identical to the main payment flow, but happens from the perspective of the merchant receiving the payment instead of the customer sending the payment.

The customer follows the main payment flow to send the payment to the merchant. For the merchant, the incoming payment flow starts when their financial institution receives a notification informing them of the incoming payment.

The merchant's financial institution can use the information included in the notification to query Payments Hub for the payment information, such as the amount and who has sent it.

The following diagram shows the incoming payment flow when using Payments Hub.

When the merchant's financial institution queries Payments Hub for the payment information, it uses the GET /pacs008/v08/{paymentsHubId} API operation and receives an ISO20022 pacs.008.01.08 message containing the payment information.

For more information on receiving incoming payments with the Payments Hub API, see pacs.008 related tutorials. For information on notifications, see Notifications.

Payment cancellation flow

Cancelling a payment means that the customer who created the payment wants to undo their action. In today's fast world, however, payments reach their beneficiaries in no time, usually well before the customer realizes that a mistake has been made. And money that has once reached the beneficiary's financial institution cannot simply be moved back without that institution's approval. As a result, the payment cancellation flow only works for non-immediate payment schemes.

In the payment cancellation flow, the customer contacts their financial institution to ask for a cancellation. If their institution has already initiated the original payment, they must initiate a payment cancellation in Payments Hub. Payments Hub forwards the cancellation request to the payment scheme-specific service that batches payment requests, and if the batch that they payment belongs to has not yet been sent, the payment is returned to the customer's bank account. If the payment has been sent already, the payment scheme-specific service notifies Payments Hub that the cancellation request is rejected. To get their money back, the customer must contact the beneficiary directly and ask them to initiate the payment return flow. For information on the payment return flow, see the Payment return flow section.

During the cancellation process, the customer's financial institution can query Payments Hub for the status of the cancellation.

The following diagram shows the payment cancellation flow when using Payments Hub.

To facilitate the cancellation of payments, Payments Hub uses the ISO20022 camt.056.001.08 message version as part of the POST /camt056/v08 API operation. The camt.056.001.08 message contains all the details needed by Payments Hub to initiate the cancellation, such as the reason for the cancellation.

If the payment scheme-specific service rejects the cancellation, it notifies Payments Hub with the ISO20022 camt.029.001.09 message. When the customer's financial institution queries Payments Hub for the status of the cancellation, it uses the GET /camt029/v09/{paymentsHubId} API operation and receives the same camt.029.001.09 message containing the cancellation status.

For more information on cancelling payments with the Payments Hub API, see camt.056 and camt.029 - related tutorials.

Payment return flow

Returning a payment restores the funds of the original payments to the customer. Unlike in the payment refund flow, the funds are returned in full.

In the payment return flow, the merchant contacts their financial institution to ask them to return a payment to the customer, and the financial institution uses Payments Hub to return the payment. The payment is then processed in the reverse to how it was created with the main payment flow until it is returned to the customer's bank account.

The merchant's financial institution can query Payments Hub for the status of the return during the return process.

The following diagram shows the payment return flow when using the Payments Hub API.

To facilitate payment returns, Payments Hub uses the ISO20022 pacs.004.001.08 message version as part of the POST /pacs004/v08 API operation. The pacs.004.001.08 message contains all the details needed by Payments Hub to create the payment return, such as the customer's bank account details.

When the customer's financial institution queries Payments Hub for the status of the return, it uses the GET /pacs002/v10/{paymentsHubId} API operation and receives an ISO20022 pacs.002.001.10 message containing the payment return status.

For more information on returning payments with the Payments Hub API, see pacs.004 and pacs.002 - related tutorials.

Payment refund flow

Refunding a payment reverses the original payment and returns part of the funds to the customer. The Payments Hub API allows the merchant to determine the refund amount so long as it is less than the original payment. If the full amount is required, the payment return flow must be used instead. If required, the merchant can issue multiple refunds for the same payment which can total the full amount of the original payment.

In the payment refund flow, the customer requests a refund from the merchant. The merchant contacts their financial institution to ask them to refund the payment to the customer, and the financial institution uses Payments Hub to refund the payment. The payment is then processed in the reverse to how it was created with the main payment flow until it is returned to the customer's bank account.

During this process, the merchant's financial institution can query Payments Hub for the status of the return, to track its progress.

The following diagram shows the payment refund flow when using the Payments Hub API.

To facilitate payment refunds, Payments Hub uses the ISO20022 pacs.007.001.08 message version as part of the POST /pacs007/v08 API operation. The pacs.007.001.08 message contains all the details needed by Payments Hub to refund the payment, such as the refund amount and the customer's bank account details.

When the merchant's financial institution queries Payments Hub for the status of the refund, it uses the GET /pacs002/v10/{paymentsHubId} API operation and receives an ISO20022 pacs.002.001.10 message containing the refund status.

For more information on refunding payments with the Payments Hub API, see pacs.007 and pacs.002 - related tutorials.