❗️

This page and described flow are deprecated. You can now preselect cryptocurrency for a Payment Intent on the Create Payment Intent API call.

1. Get currencies available for the amount

Use the currency estimates endpoint to check availability for the currency to preselect.

📘

Note

This is a protected endpoint and the usage of your API Key is required.

Inspect the state of the currency you want to preselect and make sure its state is available. In case the currency is not available, it is advised to do not specify the currency so your customer can select from other available currencies.

2. Create a PaymentIntent

Use the Create PaymentIntent endpoint and send a payload with the required parameters and the quoteCurrency.

📘

Note

This is a protected endpoint and the usage of your API Key is required.

By default, if no cryptocurrency is preselected before the customer is redirected to Coinify's Payment Window, the customer will land on the Select Crypto screen, where they can choose from the list of available cryptocurrencies to complete the Payment Intent. See how to preselect a cryptocurrency.

3. Redirect your customer or Host your own Payment Window

3.1. Coinify Hosted Payment Window

Coinify provides a hosted checkout user interface which enables your customer to easily send the requested amount to the correct address and also choose from a variety of virtual currencies.

The URL to the Coinify hosted checkout user interface is returned in the successful response of the Create a PaymentIntent endpoint.

2.2. Self-hosted Payment Window

The PaymentIntent resource provides you with all the necessary data to build your own Payment Window around it and provide the UX/UI that is aligned with your brand.

Before you are able to create a quote for the customer, you need to create a customer and create a wallet for the customer.

After a successful creation of a PaymentIntent, Customer and Customer wallet, create a quote for the Payment Intent by passing the walletId and retrieve the PaymentIntent in the API response, and fetch the relevant payment information from the latest quote. All the created quotes can be found in the quotes object.

🚧

Important:

A Payment Intent will expire when the latest created quote expires! For optimal UX, do not re-use a previously crated quote. Always create a new one, even if there's an existing one for the same chosen currency!

4. Receive a Webhook notification (Callback event)

Coinify sends a callback notification to a webhook URL you provided once a PaymentIntent has been completed or failed.

If you are building a self-hosted payment window, you need to inform the customer about a successful or failed payment. The state and stateReason of a PaymentIntent are provided in the webhook events.

For more information on how to set up a webhook URL with Coinify and see the structure of the notifications read the Webhooks guide.

Validate the signature

Coinify includes a signature in the Header of each webhook notification request. For more information on validating the signatures, read the Webhooks guide.

❗️

Important

Never accept a payload before validating that the signature is correct.

Completed/Failed states

Based on the state received in a webhook notification you can determine whether the Payment Intent was successful or not and provide or reject the service/product to your end-user accordingly.

Once you receive a completed notification that contains the correct signature, the Payment Intent was successful and your merchant account has been credited.

Once you receive a failed notification that contains the correct signature, the PaymentIntent was not successful and your merchant account has not been credited.

Errors

This section describes the errors that can be thrown while creating a payment intent with currency preselection and their description.