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
- Chooses the PaymentIQ card option
- 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
- 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 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
- Receives request from backend
- Creates a payment request in the correct format for PaymentIQ
- 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
- Receives request
- Saves and readies the payment for processing
- Returns a checkout URL
The Ping Payments API is about to receive the response from PaymentIQ.
Ping Payments API
- Receives the response from PaymentIQ
- Saves info
- 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
- 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 Payment IQ checkout URL in the payer's client
It wouldn't be a purchase unless someone pays, so here comes the payer.
Payer
- Reviews the purchase on the checkout page
- Enters card info and other details
- Clicks pay
Finishing the Payment
Since the payer paid through the Payment IQ page, PaymentIQ has the necessary information to finalize the Payment.
PaymentIQ
- 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