1
Order Creation or Update
Your application determines recipient info for the buyer. It can be an email wallet or wallet address. Create or
update an order with this info to proceed to next step.
2
API Response
The API response returned from create/update order call(s) will include a
payment.preparation
object that your
application uses to render the Stripe payment element.3
Render Stripe Payment Element
Use the
stripePublishableKey
and stripeClientSecret
returned in the API response to render the credit card
checkout form.4
User Completes Payment
The buyer completes checkout via credit card.
5
Poll for Status
Your application will poll the GET order status and update the UI as the order progresses to the next phase.
During the initial
quote
phase of the order the payment status will be requires-quote
.awaiting-payment
, which indicates that the order is ready to be paid.
See below the full list of possible statuses:
Payment Status | Explanation |
---|---|
requires-quote | still in the quote phase |
awaiting-payment | ready to submit payment |
completed | order is in the delivery or order completion phase |
completed with payment.refunded | payment was completed but has been refunded |
Render the Stripe Payment Element
When the order is ready to accept payment, the API response will include anorder.payment.preparation
object, which contains two important properties to render the payment element. These properties are named: stripePublishableKey
and stripeClientSecret
. You can use these with the Stripe Payment Element package to collect the user’s credit card payment.
Example response
Example response
The
key
property on the Elements
component is important to re-render the payment element if either the
stripeClientSecret
or stripePublishableKey
change, as these fields can't be 'live' updatedHandle Payment Confirmation
The Stripe Payment Element does not handle submitting the payment, so you will also need to create your own submit button. First, at the top of the file, update the import for@stripe/react-stripe-js
to be:
SubmitButton
component with the following code:
order.payment.preparation
in order to see the live Payment Element).
Poll for Status Updates
After making the payment via whichever payment method, you'll need to poll the Get Order API to check on the delivery status and present this info to your user. Refer to the complete get order API reference here.GET
https://staging.crossmint.com/api/2022-06-09/orders/<orderId>
Handling Refunded Payments
When polling for order status, you may encounter a situation wherepayment.status
is completed
but the order also contains a payment.refunded
property. This indicates that the payment was initially successful but has since been refunded.
payment.refunded
object includes the following fields:
amount
: The amount that was refundedcurrency
: The currency of the refundtxId
: The on-chain transaction ID the refund was sent inchain
: The blockchain where the refund transaction occurred
- Display an appropriate message to the user indicating that their payment was refunded
- Provide the transaction ID (
txId
) so users can verify the refund on-chain - Prevent any further actions related to the order (such as delivery expectations)
- Provide options for the user to place a new order if desired