Create a payment

Before a customer can pay, create a payment from your backend.

The payment represents the amount you want to collect and returns the URLs needed to continue the payment flow.

Request

Send the payment details from your backend to ICEPAY.

Your application should use its own order or payment identifier as the reference so you can match the ICEPAY payment to the corresponding order in your system.

For a typical online payment, also provide:

• redirectUrl to return the customer to your application after the payment flow.
• webhookUrl so ICEPAY can notify your backend when the payment changes.

Note

The redirectUrl is intended for returning the customer to your application.

Do not use the customer’s return to determine the final payment state. Process payment updates through your webhookUrl instead.

Successful payment creation returns HTTP 201 Created with the payment in the response body.

Payment identifiers

Identifier	Meaning	How to use it
Payment key (key)	The unique identifier generated by ICEPAY, such as pi-01j1ps8zf4jgnk0c3dnd477sp1. The Portal also calls this the checkout key.	Store it with your order and use it to retrieve, refund or forward the payment through the API.
Reference (reference)	Your own order or payment reference, supplied when you create the payment, such as ORD-16307.	Use it to match payments to records in your system. It is separate from the ICEPAY payment key.
Payment ID	An identifier shown in Portal payment details and reports.	Include it when discussing a payment with the ICEPAY team. For API operations, use the payment key returned in key.
Payment Account Reference (PAR)	Returned in paymentMethod.paymentAccountReference.	See the glossary entry for its meaning and availability.

Store the payment key

A successfully created payment contains a unique key, for example:

pi-01j1ps8zf4jgnk0c3dnd477sp1

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

You will need it when retrieving the payment and for operations such as refunds or payment forwarding.

Redirect the customer

Every successfully created payment contains a links.checkout URL.

Redirect the customer to this URL to let them choose a method on the ICEPAY Checkout Page.

For example:

https://checkout.icepay.com/checkout/pi-01j1ps8zf4jgnk0c3dnd477sp1

If you provide a payment method when creating the payment, the response may also contain links.direct. This URL takes the customer to the ICEPAY Payment Page or the selected method’s external payment page, bypassing payment-method selection on the ICEPAY Checkout Page.

Tip

If your application lets ICEPAY handle payment-method selection, use links.checkout. If your application supplies the payment method itself, use links.direct when it is returned. See Payment methods for how to control the payment method when creating a payment.

Payment expiry

Payments expire automatically if they are not completed.

expireAfter is an integer measured in minutes. By default, a payment remains open for 240 minutes (4 hours). For a different expiry period, provide expireAfter when creating the payment. For example, expireAfter: 60 means the payment expires after 60 minutes (1 hour). The maximum is 44,640 minutes (31 days).

This can be useful for payment flows where the customer may complete the payment later, such as when a checkout URL is included in an invoice or QR code.

What happens next

After redirecting the customer, payment processing takes place outside your application.

ICEPAY notifies your backend through the webhookUrl when the payment changes. Your webhook handler should use these notifications to keep the corresponding payment or order in your system synchronised.

Process webhooks

Receive payment updates from ICEPAY and keep your order status synchronised.