In the dynamic environment of online transactions, managing the responses and callbacks from payment links is a critical component of the integration with Ping Payments. This chapter provides an essential guide to understanding and handling the various statuses of payment links. You will learn how to interpret the callback responses effectively, track payment statuses, and integrate these updates into your system for a seamless transaction process. This guide is designed to ensure you can maintain consistent transaction flow and handle post-payment actions with confidence, and focused on when you're using Ping Payments Checkout.
Overview
Efficiently handling responses and callbacks is a crucial aspect of integrating with Ping Payments. When a payment link's status changes, Ping Payments sends a callback to the specified URL on the payment_link_status_callback_url-property of the Create a payment Link payload, providing essential information about the status of the payment link. Understanding and properly managing these callbacks ensures seamless transaction processing and aids in maintaining accurate transaction records.
Callback Body Example
Here’s an example of a typical callback body:
{
"payment_link_id": "a25cdd3b-f95f-4861-87e4-1ca0a6be748e",
"status": "COMPLETED",
"occured_at": "2024-01-16T14:24:29.105356Z"
}
- payment_link_id
The unique identifier of the payment link. - occured_at
Timestamp indicating when the status change occurred. - status
The current status of the payment link.
Payment Link Status Descriptions
| Status | Description |
|---|---|
CREATED | The payment link is created but has not been used by any payer. |
COMPLETED | The payment link has been paid, either through the Ping Payments checkout or by an invoice payment. |
EXPIRED | The payment link is too old to process. |
CANCELLED | The payment link has been cancelled. This can be done by tenants using the Cancel Payment Link endpoint. |
Following Up on Payment Link Status
Each COMPLETED payment link is associated with a payment_id. To retrieve this payment_id, use the Fetch a Full Representation of a Payment Link endpoint. This payment_id is crucial for getting individual payment details associated with the payment link.
Understanding Callbacks
No Reporting of Failed or Pending Attempts
It's important to note that payment links do not report failed attempts or pending attempts. Such detailed tracking requires building your own checkout directly against the Ping Payments API.
The purpose of the Ping Payments Checkout is to abstract away these details so you as an integrator only have to worry about if the payment link in itself has the right status, and all of the failed attempts or pending attempts are only a concern to Ping as a provider of this checkout service. Meaning less integration to do, and more focus on your product instead!
1:1 Ratio with Payment Orders
Typically, a payment order is associated with one payment link. Once a payment link reaches the COMPLETED status, it will have exactly one payment_id linked to it. This is the critical moment for the callback processing. As a tenant, you should update your system accordingly and be prepared to CLOSEthe payment order if no more payment links or payments are expected to be added to it.
Post-Completion Actions
SPLIT and SETTLE
After a payment link is completed, actions like SPLIT and SETTLE are performed against the main Payments API, just as any other payment order. As a tenant, even if you utilize the Ping Payments Links API and the Ping Payments Checkout, you still need to integrate with the main Payments API for these actions.
Key Takeaway
Effectively managing callbacks and understanding the status of payment links are integral to the transaction process with Ping Payments. Ensuring that your system is updated based on these callbacks will maintain transaction integrity and streamline your payment processing workflow.
As mentioned, as an integrator, you can always also poll the status of your Payment Link to keep your system up to date by using theFetch a Full Representation of a Payment Link endpoint.