Build with the API

This guide takes you through authentication, creating and retrieving payments, processing webhooks, issuing refunds, and other common payment operations.

Throughout this documentation, a customer is the person making the payment. This terminology is also used in API field names, SDK methods, and reporting columns, such as customer, WithCustomerEmail(), and CustomerName.

How the integration works

A typical payment starts in your backend and continues through ICEPAY Checkout.

1. Create a payment

   Create a payment from your backend with your own reference, the amount to collect, and the URLs ICEPAY can use during the payment flow.

2. Redirect the customer

   Send the customer to the checkout URL returned by ICEPAY.

   If you specified a payment method, the response may also contain a direct payment URL.

3. Let the customer complete the payment

   The customer completes the payment through ICEPAY or the selected payment provider.

4. Handle webhooks and the customer’s return

   ICEPAY sends payment updates to the webhookUrl supplied when you created the payment.

   Process these notifications on your backend and update the corresponding payment or order in your system.

   After the payment flow, the customer is returned to the redirectUrl supplied when you created the payment.

5. Retrieve the payment when needed

   Retrieve the payment from ICEPAY when your application needs to explicitly check its current state.

Note

Webhooks and the customer’s return happen independently and can arrive in either order. The customer may also close the page without returning.

Do not rely on the customer returning to your redirectUrl to determine whether a payment succeeded.

Payment updates should be processed independently by your backend.

API base URL

Send API requests to:

https://checkout.icepay.com/api

For example, creating a payment uses:

POST https://checkout.icepay.com/api/payments

Caution

All API requests should be made from your backend. Do not expose your ICEPAY Checkout API credentials in browser-side code.

Before you begin

Before building the integration, make sure you have:

• An ICEPAY Account for your company, with access through your ICEPAY User Account.
• A configured merchant.
• API credentials for the merchant you want to use.
• A backend capable of making HTTPS requests.
• A publicly reachable HTTPS endpoint for processing payment notifications.

New to ICEPAY?

If your ICEPAY Account or merchant is not configured yet, start with the Getting Started guide.

Payment state

Your application should keep its own order state synchronised with the payment state reported by ICEPAY.

Payment updates are received through webhooks. You can also retrieve a payment through the API when your application needs to explicitly check its current state.

For a detailed explanation of payment statuses and how a payment progresses, see the Payment lifecycle.

Next step

Before making your first API request, configure authentication for your ICEPAY merchant.

Set up authentication

Learn how to authenticate requests to the ICEPAY Checkout API using your merchant credentials.