Skip to main content

Set up required endpoints

Feature for managed partners only

This is a feature intended for managed partners. If you are not a managed partner and would like to become one, please reach out to us on our #dev-discussion channel on Discord.

If you are a managed partner, your partner success manager needs to set up a commercial partnership with MoonPay for you. Please reach out to them to facilitate this.

In order to implement this NFT primary sale card checkout feature, you need to complete the following:

  1. Establish a commercial partnership with MoonPay (your partner success manager will facilitate this for you)
  2. Set up and register with Immutable X with the required endpoints

How to set up and register endpoints

1. Create endpoints

You are required to provide the following endpoints:

  1. Trigger the mint: An endpoint to mint the asset once payment has been confirmed with MoonPay
  2. Get asset info: An endpoint to get information about the minted asset and render the checkout

Triggering the mint endpoint

Headers required:

NameDescription
IMX-Signature - How to validate thisSignature to confirm that the request was made by Immutable X
IMX-Timestamp - How to generate thisTimestamp header to validate IMX-Signature

Request body:

PropertyTypeDescription
offer_idStringThe ID of the offer provided for the NFT to be minted
contract_addressStringSmart contract address of the NFT
userStringUser that the NFT will be minted for (will become the NFT's owner)
wallet_addressStringWallet address that will receive the payment, in crypto (from MoonPay), for the minted NFT
external_transaction_idString (UUID)Unique Immutable X transaction ID that can be used to get information about the transaction

Response:

PropertyTypeDescrtiption
contract_addressStringSmart contract address of the NFT
token_idStringToken ID (as specified by the NFT smart contract) of the minted asset
tx_idIntegerMinting transaction ID - see mintTokens response

Example:

Request: POST /mint
headers: {
"IMX-Signature": "5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd",
"IMX-Timestamp": "1492774577"
}

data: {
"offer_id": "string",
"contract_address": "string",
"user": "string",
"wallet_address": "string",
"external_transaction_id": "string(UUID)",
}

Status: 200
Response: {
"contract_address": "string",
"token_id": "string",
"tx_id": 0
}
Error on mint

If minting fails, please provide a response with the error code and message.

Response: {
"code": "number", // the error code
"message": "string", // the error message
"details": "string" // the error details
}

Get asset info endpoint

This endpoint will be used to get information about the asset to be minted using trigger mint endpoint.

Response:

PropertyTypeDescription
offer_idStringThe ID of the offer provided for the NFT to be minted
contract_addressStringSmart contract address of the NFT
nameStringToken name to be rendered at checkout
collectionStringCollection name to be rendered at checkout
image_urlStringURL where the image to be displayed for the minted asset is hosted
price_currency_codeStringCurrency of the amount to be paid. Choose from: "ETH" or "USDC"
priceStringAmount of the currency required to mint the token
seller_addressStringWallet address that will receive the payment, in crypto (from MoonPay), for the minted NFT

Example:

Example Request: GET /:contract_address/:offer_id

Status: 200
Response: {
"offer_id": "123",
"contract_address": "0xacb3...",
"name": "SiShinylver Card Pack",
"collection": "Gods Unchained",
"image_url": "https://images.godsunchained.com/cardpack-images--marketing/256/mortal--neutral--shiny--legendary.png",
"price": "125.29",
"price_currency_code": "USD",
"seller_address": "0xacb3...",
}
Unavailable offer

If an offer is unavailable, a response should return 404 - Not Found.

Status: 404
Response: {
"code": "404", // the error code
"message": "Missing offer", // the error message
"details": "The offer id {offer_id} is not a valid offer for purchase" // the error details
}

2. Register with Immutable X using created endpoints

When you've set up the endpoints required in the previous step, please register with Immutable X using the registerNftPrimarySalesContract API endpoint.

After registration, Immutable X will send you a webhook key that will be used to validate the signature when initiating mint requests.

3. How to validate the IMX-Signature

Generate a signed_payload by concatenating the following:

  • IMX-Timestamp header
  • The character .
  • JSON payload of the message to be signed

Example:

const payload = JSON.stringify({
offer_id: '1',
contract_address: '0x23a...',
user: '0x8b1...',
wallet_address: '0x11a...',
external_transaction_id: '00000000-0000-0000-aaaa-0000a000aa00',
});

const signed_payload = imx_timestamp_header_value + '.' + payload;

You will then need to compute an HMAC with the SHA-256 hash function using the webhook key that we provided when you registered the endpoints with Immutable X for the signed_payload and use it to compare the signature in the header:

import crypto from 'crypto-js';

const generatedSignature = crypto
.HmacSHA256(signed_payload, webhookKey)
.toString();

More information

Main flow diagram:

NFT Checkout Primary Main flow

Technical flow diagram:

NFT Checkout Primary By Fiat Technical flow