Process Payment

Submits the payment for an order. For a crypto payment, send the transaction ID of the transfer. For an offramp order, that transfer is the stablecoin deposit that funds the fiat payout. When the order’s prepared transfer already carries a memo, Crossmint matches the deposit once the wallet broadcasts it, and this call only records the match sooner.

API scope required: orders.update or orders.create

Related: Offramp

POST /2022-06-09/orders/{orderId}/payment

cURL

Crypto Transaction

curl --request POST \
  --url https://staging.crossmint.com/api/2022-06-09/orders/{orderId}/payment \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "txId": "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060",
  "type": "crypto-tx-id"
}
'

201

{
  "lineItems": [
    {
      "chain": "base",
      "delivery": {
        "status": "awaiting-payment",
        "cashPickup": {
          "pickupCode": "1234567890"
        },
        "rail": "ach-us",
        "recipient": {
          "email": "[e-mail]",
          "locator": "email:[e-mail]:base",
          "walletAddress": "0x9fDA6b2C3e4d5e6F7a8B9c0D1e2F3a4B5c6D7e8F",
          "physicalAddress": {
            "city": "San Francisco",
            "country": "US",
            "line1": "123 Market St",
            "name": "Jane Doe",
            "postalCode": "94105",
            "line2": "Apt 4B",
            "state": "CA",
            "stateOrRegion": "CA"
          }
        }
      },
      "executionMode": "exact-in",
      "maxSlippageBps": "500",
      "metadata": {
        "description": "USDC Token",
        "imageUrl": "https://cryptologos.cc/logos/usd-coin-usdc-logo.svg",
        "name": "USDC",
        "collection": {
          "description": "Stablecoin issued by Circle, pegged 1:1 to the US dollar.",
          "imageUrl": "https://cryptologos.cc/logos/usd-coin-usdc-logo.svg",
          "name": "USD Coin"
        }
      },
      "quote": {
        "quantityRange": {
          "lowerBound": "9.95",
          "upperBound": "10.00"
        },
        "status": "valid",
        "charges": {
          "unit": {
            "amount": "1.00",
            "currency": "usd"
          },
          "crossmintFees": {
            "amount": "0.37",
            "currency": "usd"
          },
          "fees": {
            "amount": "0.47",
            "currency": "usd",
            "type": "exact"
          },
          "gas": {
            "amount": "0.10",
            "currency": "usd"
          },
          "networkFee": {
            "amount": "0.10",
            "currency": "usd"
          },
          "salesTax": {
            "amount": "0.84",
            "currency": "usd"
          },
          "shipping": {
            "amount": "4.99",
            "currency": "usd"
          },
          "transferFee": {
            "amount": "0.50",
            "currency": "usdc"
          }
        },
        "totalPrice": {
          "amount": "10.47",
          "currency": "usd"
        },
        "unavailabilityReason": {
          "code": "to",
          "message": "This item is sold out."
        }
      },
      "callData": {},
      "executionParams": {
        "amount": "10.47",
        "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "maxSlippageBps": "500",
        "mode": "exact-in"
      }
    }
  ],
  "locale": "en-US",
  "orderId": "b2959ca5-65e4-466a-bd26-1bd05cb4f837",
  "payment": {
    "currency": "usd",
    "method": "stripe-payment-element",
    "status": "awaiting-payment",
    "failureReason": {
      "code": "issuer_decline",
      "category": "authorization_decline",
      "developerMessage": "Generic issuer decline (do_not_honor). Do not retry automatically; ask the buyer to contact their bank.",
      "message": "Payment declined by your bank. Contact your bank or try a different payment method.",
      "retryPolicy": "contact_payment_provider"
    },
    "payer": {
      "deviceId": "8f3a1c2b9d4e5f60718293a4b5c6d7e8",
      "paymentMethodId": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
    },
    "preparation": {
      "chain": "base",
      "payerAddress": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
      "serializedTransaction": "0x02f8b0…",
      "transactionParameters": {
        "amount": "10470000",
        "memo": "b2959ca5-65e4-466a-bd26-1bd05cb4f837"
      }
    },
    "receiptEmail": "[e-mail]",
    "received": {
      "amount": "10.47",
      "chain": "base",
      "currency": "usd",
      "txId": "0x33be4e2d636a22b56cb28b858f682dd428c7f468367072e2711c09cdd42cf826"
    },
    "refunded": {
      "amount": "10.47",
      "chain": "base",
      "currency": "usd",
      "txId": "0x7c0a4f9e2b1d8c3a6e5f4b2d1c0a9e8f7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d"
    }
  },
  "phase": "payment",
  "quote": {
    "status": "valid",
    "exchangeRate": {
      "destinationCurrency": "mxn",
      "rate": "17.4523",
      "sourceCurrency": "usdc"
    },
    "expiresAt": "2024-01-15T10:30:00.000Z",
    "quotedAt": "2024-01-15T10:30:00.000Z",
    "totalPrice": {
      "amount": "10.47",
      "currency": "usd"
    }
  },
  "legal": {
    "requirements": [
      {
        "display": "show-checkbox",
        "type": "crossmint-terms-of-service",
        "url": "https://www.crossmint.com/legal/terms-of-service"
      }
    ],
    "shownBy": "crossmint"
  },
  "metadata": {
    "internalOrderId": "ORD-10042"
  }
}

Authorizations

apiKey & userJwtapiKeyorderClientSecret

X-API-KEY · string · header · required

API key required for authentication

Authorization · string · header · required

The end user's JWT, sent as Authorization: Bearer <JWT> together with a client-side API key. Validated against the project's external JWT configuration.

Path Parameters

orderId · string · required

The order ID, in UUID format. Create Order returns it as order.orderId.

Example:

"9c82ef99-617f-497d-9abb-fd355291681b"

Body

application/json

Wirex prefunded balance

Card or saved payment method

Crypto transaction

Bank transfer

Pay from a Wirex prefunded balance payment method.

paymentMethodId · string · required

ID of the Wirex prefunded balance payment method to pay with.

type · string · required

Allowed value: "wirex-prefunded"

Response

201

application/json

Payment submitted successfully. Returns the updated order.

lineItems · (Exact-in (fixed spend) · object | Exact-out (fixed quantity) · object)[] · required

Items in the order. Each line item has its own quote and delivery status.

Exact-in (fixed spend)

Exact-out (fixed quantity)

Show child attributes

locale · enum<string> · required

Locale for the checkout, in IETF BCP 47. It impacts the email receipt language. Ensure your UI is set to the same language as specified here. Throws an error if passed an invalid language.

Available options: Klingon, de-DE, en-US, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-PT, ru-RU, th-TH, tr-TR, uk-UA, vi-VN, zh-CN, zh-TW

Example:

"en-US"

orderId · string<uuid> · required

Unique ID of the order, in UUID format.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Example:

"b2959ca5-65e4-466a-bd26-1bd05cb4f837"

payment · object · required

Payment leg of the order. Read status to find the next action.

Show child attributes

phase · enum<string> · required

Current phase of the order lifecycle. quote: the quote is not final. payment: the order waits for the payment. delivery: the payment is received and delivery is in progress. completed: every line item is delivered.

Available options: completed, delivery, payment, quote

Example:

"payment"

quote · object · required

Quote for the whole order. Its values aggregate the line item quotes.

Show child attributes

legal · object

Terms that apply to the order. Absent from List Orders responses.

Show child attributes

metadata · object

Metadata that you sent when you created the order.

Show child attributes

Example:

{ "internalOrderId": "ORD-10042" }