Skip to main content

Create a purchase intent

You can create a purchase intent against a listing using the Phosphor public API. Public APIs do not require authentication with an api key in the header.

Issue a POST request to the purchase-intents endpoint.

POST https://public-api.phosphor.xyz/v1/purchase-intents
Example payload
{
  "provider": "STRIPE",
  "listing_id": "4e339560-5c6c-495a-bfe3-0a30e3519983",
  "quantity": 1,
  "buyer": {
    "email": "aaa@bbb.com",
    "eth_address": "0xa99d7eD4bb4E3EeFEd18a0269Be46Aa8C49Ab165"
  }
}

When using STRIPE as the payment provider, you can provide either email or eth_address. If you provide email, the platform will fulfill the sale through an email claim. If you provide eth_address, the platform will fulfill the sale through an on-chain transfer. If you provide both, the platform by default will send the items to the eth_address.

When you use MINT_VOUCHER as the payment provider, the platform only accepts an eth_address and will always fulfill the sale through a mint voucher.

When you use EMAIL_CLAIM as the payment provider, the platform only accepts an email and will always fulfill the sale through an email claim.

When you use ORGANIZATION as the payment provider, the platform only accepts an eth_address and will directly mint to the given address.

The endpoint returns different payload when you use a different payment provider. This payload contains essential information to complete the purchase.

Response when using STRIPE as the payment provider​

{
  "data": {
    "account_id": "stripe_connected_account_id",
    "client_secret": "pi_client_secret",
    "id": "6430cc30-016e-4ae1-b35b-a7e80a5112fb",
    "mode": "TEST",
    "provider_price": {
      "currency": "USD",
      "price": "25000"
    },
    "publishable_key": "platform_stripe_account_publishable_key"
  },
  "expires_at": "2023-01-26T12:21:15.280016",
  "id": "47b1e416-de8c-4fe8-9e1f-bd1389528104"
}
  • data:
    • account_id: Your organization Stripe account's ID.
    • client_secret: A unique identifier of the Stripe PaymentIntent. The platform communicates with Stripe through this unique identifier.
    • id: An internal ID by the platform for this Stripe payment session.
    • mode: Mode of your Stripe integration. See more on "TEST" and "LIVE" mode in payment providers.
    • provider_price: The price in the settlement currency, if the listing currency is different from the settlement currency accepted by the payment provider. See listing currencies for information on how the platform converts price.
    • publishable_key: The platform Stripe account's publishable key.
  • expires_at: The expiration of the payment session duration. Payments must be completed within this time frame.
  • id: An internal ID by the platform for this purchase intent.

When your organization set up Stripe integration on the Phosphor platform, it is integrated as the platform's connected account. When you set up Stripe context on your app, you must load Stripe with both the platform account's publishable_key and your own account's account_id. See the below example using Stripe.js

    export const StripeContext = ({ children }: any) => {
        const [stripePromise, setStripePromise] = useState<Promise<Stripe | null> | null>(null);

        useEffect(() => {
            if (!publishable_key || !account_id) {
            setStripePromise(null);
            } else {
            const stripePromise = loadStripe(publishable_key, {
                stripeAccount: account_id,
            });
            setStripePromise(stripePromise);
            }
        }, []);

        if (!stripePromise) {
            return <div>NoPromises</div>;
        }

        return <Elements stripe={stripePromise}>{children}</Elements>;
    };

You can then send payment to Stripe in the following way:

const { paymentIntent, error } = await stripe.confirmCardPayment(
  client_secret,
  {
    payment_method: {
      card: elements.getElement(CardElement),
    },
    receipt_email: buyer.email,
  },
);

Response when using MINT_VOUCHER as the payment provider​

{
  "data": {
    "contract": "0xC13Fc7A39000961847187Dbc042572319931Ca13",
    "minter": "0xa99D7eD4bB4E3EEFed18a0269bE46Aa8c49Ab165",
    "network_id": 59140,
    "signature": "0x6a7b1b4e9f8fa7d359a227a4c3b5885c2877b73e02d513a7ee8d4b28c569b063222afb06ba075b4bb69c6665b9aa1d1f1edc0c1487261eee5cb9fe4640bd21d61c",
    "voucher": {
      "net_recipient": "0xabf518e9B51D8DfD936E552d22B35Cfd8bDB48a5",
      "initial_recipient": "0xdf50409aBe6B503B3F6bA64E7e26e1312048A84E",
      "initial_recipient_amount": "0",
      "quantity": 1,
      "nonce": 1,
      "expiry": 1674740015,
      "price": "100000000000000000",
      "token_id": "11",
      "currency": "0x0000000000000000000000000000000000000000"
    }
  },
  "expires_at": "2023-01-26T13:33:35",
  "id": "3604184b-cb69-4783-8f58-ec291225c7d5"
}
  • data:
    • contract: The token contract for the collection. You must call this contract with the mint voucher params to redeem the voucher.
    • minter: The wallet address of the voucher owner. This is the buyer's ethereum address sent in the purchase intent.
    • network_id: The blockchain network for the items to redeem.
    • signature: A signature signed by the platform backend. When a minter tries to call the contract, the contract first validates that the voucher is valid and is being called by the right owner, then performs the mint.
    • voucher: The params that you must call the token contract with.
      • net_recipient: The payout address of your organization.
      • initial_recipient: The wallet address of the platform.
      • initial_recipient_amount: The platform fee.
      • quantity: How many items to mint in the voucher.
      • nonce: A way of accounting for how many vouchers a minter has redeemed.
      • expiry: Timestamp of the expiration of the voucher. After which, the voucher can no longer be redeemed.
      • price: Price of the items in wei or the currency's corresponding decimals. For ERC-20 tokens, this is usually 10e18.
      • token_id: The token id of the item to mint. If 0, the mint voucher is from a collection with EXTERNAL token_id_assignment_strategy. The platform will assign a token ID when it detects a mint.
      • currency: the currency address the voucher accepts. A 0x0 address means the voucher accepts ETH.
  • expires_at: The expiration of the payment session duration. Payments must be completed within this time frame.
  • id: An internal ID by the platform for this purchase intent.

Mint vouchers are internal constructs created by the Phosphor platform. They work with any collections deployed using the Phosphor's platform contracts.

To call the token contract with the mint voucher params, you will need a library that connects with a Web3Provider, such as ethers.js or wagmi.sh. You will also need the contract address, the mint voucher abi, and the function name you want to call, in this case, is mintWithVoucher. See more information on redeeming a mint voucher.

Response when using EMAIL_CLAIM as the payment provider​

{
  "data": "Your items will be sent to your email address. This could take up a few minutes to arrive.",
  "expires_at": "2023-01-26T14:53:32.169573",
  "id": "de80f06b-1af2-4666-be86-e249c8e9ac10"
}

EMAIL_CLAIM as a payment provider works only with free listings, and therefore, require no further actions to complete the purchase intent. The items will be directly sent to the buyer's mailbox. They can click on the "Claim" button in the email to complete the mint.

Response when using ORGANIZATION as the payment provider​

{
    "data": "Your items will be minted to your eth address. This could take up a few minutes to arrive.",
    "expires_at": "2024-02-23T03:59:55.012149+00:00",
    "id": "eb28482b-d33c-4b77-91ab-65a60192d4a8"
}
Last updated on