Redirect URLs

Send users to a specific website after a successful or cancelled purchase.

The <CrossmintPayButton> component offers two optional properties which can be used to redirect users to a website after a purchase:

• successCallbackURL redirects users to a given url after a successful transaction.
• failureCallbackURL redirects users to a given url after a failed transaction.

See example

<CrossmintPayButton
    projectId="yourProjectId"
    collectionId="yourCollectionId"
    environment="development"
    mintConfig={{
        type: "erc-721",
        totalPrice: "0.001",
        _quantity: "1",
    }}
    successCallbackURL="https://example.com/success"
    failureCallbackURL="https://example.com/failure"
/>

Whitelisting Domains

For security reasons, you must whitelist the URLs from the Domains tab on the console (staging, production).

Whitelisted domains must be https. This means you will not be able to whitelist localhost since it’s http

How to test if you don't have an https domain

A quick option is using ngrok to set one up. It’s free and takes five minutes. To get started:

1. Install the app (directions)

2. Open the terminal and enter ngrok http 3000. This assumes you’re using port 3000. Update the command accordingly if you’re using a different port.

3. Copy the URL in the Forwarding section: https://2fe4-98-145-150-44.ngrok-free.app in the screenshot below. This is the URL you will use to whitelist your domain.

4. Whitelist the ngrok domain on the the console.

To avoid having to whitelist a new domain every time you restart grok, you can get a static one using the following command: ngrok http --domain=YOUR_STATIC_SUBDOMAIN.ngrok-free.app 3000

Payloads

The redirect URL will contain a query parameter with format ?p=payload which contains an object with information about the outcome of the transaction. The payload will be a URL encoded JSON string. If you pass https://www.example.xyz/success as the successCallbackURL then you will be redirected to URL like the following:

https://www.example.xyz/success?p=%5B%7B"type"%3A"purchase.succeeded"%2C"status"%3A"success"%2C"walletAddress"%3A"0x41Bcfae8c5596C9d878d3457a5672e4EE5aA8206"%2C"clientId"%3A"36a6fd4c-899b-4fc0-84b4-126077b4f7bc"%2C"collectionId"%3A"36a6fd4c-899b-4fc0-84b4-126077b4f7bc"%2C"txId"%3A"0xa23fa2ae2b83aaa6898ae27ce05392765b00de9efd018cddeb5731629c364108"%2C"orderId"%3A"8a5d86d3-d059-4aac-86f5-4250b4c6eb64"%2C"projectId"%3A"42c43e55-f92d-4b25-bc99-d8309b6e1f38"%2C"contractAddress"%3A"0xFf42f3c7d771224b0251ECAE40aE26Efc686f05B"%2C"tokenId"%3A"2"%2C"tokenIds"%3A%5B"2"%5D%7D%5D

You can then extract and parse the payload from the redirect URL like so:

The exact structure of the payload can vary depending on the specific implementation and the transaction details. See below for details about the expected properties.

• Success Payload
• Failure Payload

• type: Payload type (purchase.succeeded).
• status: Transaction status ("success").
• walletAddress: Address to which the minting is done.
• passThroughArgs: Additional arguments passed through the transaction.
• clientId: The client identifier.
• collectionId: The collection identifier, same as clientId.
• txId: The transaction identifier.
• orderId: The order identifier associated with the transaction.
• projectId: The project identifier (if available).
• contractAddress: The contract address of the token contract (EVM only)
• mintHash: The mint hash of the token (Solana only)
• tokenId: The tokenId of the the transaction. (EVM only)
• tokenIds: An array of tokenIds to support transactions where multiple are purchased. (EVM only)

Testing the Failure Condition

It’s rather difficult to test the failure condition for two reasons. Firstly, Crossmint simulates the transaction before presenting the checkout to the user and if the simulation fails they will not be able to proceed with payment. If simulation is successful and payment proceeds, Crossmint will automatically retry until successful.

Any issues with credit card processing will be handled directly in the checkout form and will not result in creating the failure condition as the order is not actually submitted without a successful payment.

For primary sales, where the buyer is minting an NFT into existence, the only plausible failure conditions are:

• the contract sells out between simulation and payment completion
• some other contract error that couldn’t be detected in simulation (allowlist is updated between simulation and payment for example)

For secondary sales, it’s possible that another user buys the NFT for sale before the purchase completes.

If you really must test the failure condition you could open a checkout and allow simulation to complete. Then make a change in the contract such as pausing the sale. Then, after the contract sale is paused, you could submit payment. This should create the failure condition.