Forward payment funds

Payment forwarding lets you transfer part of the funds from a payment to another ICEPAY merchant.

This can be useful for platforms or marketplaces where part of a customer’s payment needs to be transferred to another party.

Payment Forwarding must be enabled

Payment Forwarding is an additional ICEPAY product and must be activated for your account before you can use it.

Contact the ICEPAY team if you want to use Payment Forwarding.

Before forwarding a payment

A payment can only be forwarded after ICEPAY has received and matched the funds.

Before creating a forward, make sure:

• the original payment was processed in Live mode;
• the payment has a financialStatus of cleared;
• the amount you want to forward is available on the payment;
• the recipient is a valid ICEPAY merchant.

Any refunds or previous forwards can affect the amount that is still available to forward.

Tip

You can check the current financialStatus by retrieving the payment.

ICEPAY can also notify your webhook when the financial status changes, so you do not need to repeatedly check the payment.

Payment key

To create a forward, use the unique payment key returned when the original payment was created.

For example:

pi-01j1ps8zf4jgnk0c3dnd477sp1

The forward is created against this payment.

Request

Send the forwarding details to ICEPAY.

Specify the ICEPAY merchant that should receive the funds in recipient.id.

The amount uses the same currency as the original payment, so only the amount value needs to be provided.

Use the forward reference to associate the transfer with a record in your own system.

Store the forward key

A successfully created forward has its own unique key, separate from the original payment key.

For example:

pf-01j1sr38kspvq2z5xek20y565w

Store this key with the forward in your system.

It allows you to identify the forward when processing subsequent payment updates.

Forward status

A forward can have the following statuses:

Status	Description
pending	The forward has been accepted but is still being processed.
completed	The forward has been completed.
failed	The forward could not be completed.

Most forwards can complete immediately once the funds are available, but some payment methods may require additional processing time.

Process forward updates

If a forward is initially pending, ICEPAY sends an update to the webhookUrl of the original payment when its status changes.

The payment payload contains a forwards array with the forwards associated with that payment.

Use the forward key to match each update to the corresponding forward in your system.

Tip

Your existing payment webhook handler can also process forwarding updates.

Check the forwards array when receiving a payment update and synchronise the corresponding forward records in your system.

Continue with the API

Back to the overview

Return to the Checkout API integration overview.