Using the Open Payments PIS Flow

This describes a typical happy path case.

Let's assume we run frontend and backend services that have an integration with the Ping Payments API. We provide several possible payment methods through Ping Payments, but the customer who is about to make a purchase wants to make an open banking payment through Open Payments payment initiation service (PIS).

Making a Purchase

Our customer or payer makes the purchase, and gets to the payment options.

📘

Payer

1. Chooses the Open Payment PIS option
2. Clicks pay in the user interface

It's our backend's turn.

First, it's time for a payment order .

📘

Backend

1. Creates a new payment order
2. Posts the new payment order to the Ping Payments API

Notes:

• The header of the request we send to the Ping payments API contains our tenant_id
• The body of the request we send to the Ping payments API contains a currency.

Create a payment order with the Payment Order endpoint.

The Ping Payments API starts working on our payment order,

📘

Ping Payments API

1. Receives the request from our backend
2. Saves the payment order
3. Sends a response to back to our backend

Note:

• A successful response from the Ping Payments API contains the payment_order_id of the new payment order.

🚧

Ping Payments recommends that you persist payment_order_ids in your backend

Now, it's time for the Payment object.

📘

Backend

1. Receives the response from the Ping Payments API and saves the payment_order_id
2. Creates a new payment
3. Posts the new payment to the Ping Payments API

Notes:

• Set open_payments as the payment provider property and pis as the payment method property
• Always include the payment_order_id of the new payment

Create a payment with the Payments endpoint.

🚧

Ping Payments recommends that you Include a valid status_callback_url in the payment

Your backend won't receive status updates on payments without a working status_callback_url.

Our part is done for now, and it's time for the Ping Payments API to get to work.

Making the Payment

Ping Payments API needs to send the Payment on to Open Payments.

📘

Ping Payments API

1. Receives request from backend
2. Creates a payment request in the correct format for PIS
3. Posts the payment request to Open Payments

Note: Any future updates to this payment will be sent as webhooks to the provided status_callback_url

It's time for Open Payments to do their part.

📘

Open Payments PIS

1. Receives request
2. Saves and readies the payment for processing
3. Returns a checkout URL

Now that the Ping Payments API has passed us the URL, it's time for our backend to take responsibility of the payment again.

📘

Backend

1. Receives response from the Ping payments API
2. Saves and updates information as needed in our database
3. Passes our payment status and checkout URL to frontend

Since our payer needs to know where and how to pay, our frontend has a little bit work left to do.

📘

Frontend

1. Receives checkout URL from backend
2. Prompt a redirect to the Open Banking checkout via URL in the payer's client

Note: Iframing the checkout is possible

📘

Checkout

1. Payer will select their bank
2. Bank ID verification will start. If payer is on mobile, the Bank ID app will start automatically, otherwise a qr-code will display.
3. Payer chooses which account to use in this payment and pays.

Finishing the Payment

Since the payer paid through the Open Payments page, they have the necessary information to finalize the Payment.

📘

Open Payments

1. Finishes off the Payment
2. Sends updated payment status to the Ping Payments API

The Ping Payments API is about to receive the updated payment status.

📘

Ping Payments API

1. Receives updated payment status
2. Updates and saves payment status of payment and payment order
3. Sends updated payment status to our backend via the status_callback_url

Once our backend receives the new payment status from the Ping Payments API, we too can finish off this purchase.

📘

Backend

1. Receives updated payment status
2. Saves updated payment status
3. Performs any actions we've decided on, such as updates to frontend for our pay to see or sends an email with a receipt

📘

Payer

Sees and reviews any information received from us, and is done with the purchase

Cancellation

In case the payer cancels the payment or if the payment fails for any reason there is a cancel_url and an error_url to be set in the payment initiation step.