Retrieve a payment

Retrieve a payment when your application needs to explicitly check its current state.

A common use case is when the customer returns to your application after completing or cancelling the payment flow.

When to retrieve a payment

When the customer returns to your redirectUrl, you can retrieve the payment once to confirm its current state before showing the appropriate result to the customer.

For example, you can use the response to decide whether to show:

• a payment confirmation;
• a pending payment message;
• an expired or cancelled payment message.

Note

Do not use the Retrieve a payment endpoint to continuously monitor payments.

For ongoing payment updates, use webhooks. ICEPAY sends a notification whenever the payment state changes.

Payment key

To retrieve a payment, use the unique key returned when the payment was created.

For example:

pi-01j1ps8zf4jgnk0c3dnd477sp1

Store this key with the corresponding order or payment in your system when you create the payment.

Request

Send the payment key as part of the request URL.

Use the payment state

The response contains the latest information available for the payment, including its status and financialStatus.

Use the payment state to determine what should happen in your application, but keep the state stored in your system synchronised through webhooks.

For a detailed explanation of the available states, see the Payment lifecycle.

Tip

The webhook payload and the response from retrieving a payment contain the same payment information.

This allows your application to process the payment state consistently regardless of whether it was received through a webhook or retrieved explicitly.

Payment Account Reference (PAR)

The paymentMethod.paymentAccountReference field contains the Payment Account Reference (PAR).

For example, a completed card payment contains the following response excerpt:

{
  "status": "completed",
  "paymentMethod": {
    "type": "card",
    "paymentAccountReference": "WCJ205PL1SMPX85WGKNBY89HNZ38J"
  }
}

Next step

If your application displays payment methods before creating the payment, retrieve the payment methods available for your merchant.

Payment methods

Retrieve the payment methods available for your merchant and use them when creating a payment.