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

Chooses the Open Payment PIS option

Clicks pay in the user interface

It's our backend's turn.

First, it's time for a payment order .

📘
Backend

Creates a new payment order

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

Receives the request from our backend

Saves the payment order

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

Receives the response from the Ping Payments API and saves the payment_order_id

Creates a new payment

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

Receives request from backend

Creates a payment request in the correct format for PIS

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

Receives request

Saves and readies the payment for processing

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

Receives response from the Ping payments API

Saves and updates information as needed in our database

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

Receives checkout URL from backend

Prompt a redirect to the Open Banking checkout via URL in the payer's client

Note: Iframing the checkout is possible

📘
Checkout

Payer will select their bank

Bank ID verification will start. If payer is on mobile, the Bank ID app will start automatically, otherwise a qr-code will display.

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

Finishes off the Payment

Sends updated payment status to the Ping Payments API

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

📘
Ping Payments API

Receives updated payment status

Updates and saves payment status of payment and payment order

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

Receives updated payment status

Saves updated payment status

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.