Worldline / Payment IQ

The Ping Payments™ integration with PaymentIQ offers secure card payments through a known and well-tested payments solution.


Using the PaymentIQ 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 a card payment through PaymentIQ.

Making a Purchase

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

📘

Payer

  1. Chooses the PaymentIQ card option
  2. Clicks pay in the user interface

Preparing for Payment

The payer has committed to a purchase, and our frontend is ready to start the payment process.

📘

Frontend

Passes the request for a new payment and all the customer and purchase information to backend

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 Payment IQ as the payment method in the 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

The Ping Payments API needs to send the Payment on to PaymentIQ.

📘

Ping Payments API

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

Note: PaymentIQ offers callback functionality via a webhook, much like the Ping Payments API. The Ping Payments API will receive status updates to the payment, and will be able to pass those on to our backend.

It's time for PaymentIQ to do their part.

📘

PaymentIQ

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

The Ping Payments API is about to receive the response from PaymentIQ.

📘

Ping Payments API

  1. Receives the response from PaymentIQ
  2. Saves info
  3. Returns a response containing the checkout URL from PaymentIQ to our backend

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 Payment IQ checkout URL in the payer's client

It wouldn't be a purchase unless someone pays, so here comes the payer.

📘

Payer

  1. Reviews the purchase on the checkout page
  2. Enters card info and other details
  3. Clicks pay

Finishing the Payment

Since the payer paid through the Payment IQ page, PaymentIQ has the necessary information to finalize the Payment.

📘

PaymentIQ

  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