Payments API

Payments represent on-chain actions your customers can complete, whether that's paying for a product, minting an NFT, or depositing funds into your app. Your customers pay to an intent address using any coin on any chain, and the action gets completed on the destination chain.

Before you can make requests to the Daimo Pay API, you will need an API key. Contact us to get one.

The Payment Object

Attributes

Name
id
Type
string
Description
The unique ID of the payment.
Name
status
Type
string
Description
The status of the payment. Possible values are:
- payment_unpaid: The user has not paid yet.
- payment_started: The user has made a payment. Pending payment completion.
- payment_completed: The payment has been completed.
- payment_bounced: There was an error in the final transaction on the destination chain. The funds were refunded to the refund address specified during payment creation.
Name
createdAt
Type
timestamp
Description
Time at which the payment was created. Measured in seconds since the Unix epoch.
Name
display
Type
object
Description
- intent: Purpose of payment displayed to the user.
- paymentValue: The value of the payment denominated in currency displayed to the user.
- currency: The currency displayed to the user.
Name
externalId
Type
nullable string
Description
The external ID of the payment specified during payment creation. Each externalId is unique to a payment, and can be used to prevent accidentally creating duplicate payments.
Name
metadata
Type
nullable object
Description
Set of key-value pairs that attached during payment creation. This can be useful for storing additional information about the object in a structured format.
Name
source
Type
nullable object
Description
Describes the details of the source payment. Null if the user has not paid yet.
- payerAddress: The on-chain address of the payer.
- txHash: The transaction hash of the payment.
- chainId: The chain ID the user paid on.
- amountUnits: The amount of token the user paid as a precise decimal string (e.g. "1.00" for $1.00 USDC).
- tokenSymbol: The token symbol the user paid with.
- tokenAddress: The token address the user paid with.
Name
destination
Type
object
Description
Describes the details of the payment destination.
- destinationAddress: The on-chain address of the recipient account or contract.
- txHash: The transaction hash of the payment. Null if the payment has not been completed.
- chainId: The chain ID of the payment destination.
- amountUnits: The amount of token that will be received by destinationAddress as a precise decimal string (e.g. "1.00" for $1.00 USDC). Guaranteed that the address will receive exactly this amount.
- tokenSymbol: The token symbol received at the destination.
- tokenAddress: The token address received at the destination.
- calldata: The calldata to execute an arbitrary contract call if the recipient is a contract. If specified, we'll automatically make a token approval of amountUnits to the contract before executing the call.

{
  "id": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
  "status": "payment_completed",
  "createdAt": "1739554073",
  "display": {
    "intent": "Pay Daimoo",
    "paymentValue": "1.00",
    "currency": "USD"
  },
  "source": {
    "payerAddress": "0xFBfa6A0D1F44b60d7CCA4b95d5a2CfB15246DB0D",
    "txHash": "0xf975e462c8191d18ef970579814ebf68c83c45b4fa8984184f744f739285133b",
    "chainId": "10",
    "amountUnits": "1.00",
    "tokenSymbol": "USDC",
    "tokenAddress": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"
  },
  "destination": {
    "destinationAddress": "0x3a321372E8a9755cD2CA6114eB8dA32A14F8100b",
    "txHash": "0x8316f2dd90051333a6f879d7b15cacdf960535e56476a5300ad90c14377fa347",
    "chainId": "8453",
    "amountUnits": "1.00",
    "tokenSymbol": "DAI",
    "tokenAddress": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
    "calldata": "0x"
  },
  "externalId": "123",
  "metadata": {
    "mySystemId": "123",
    "name": "John Doe"
  },
}

POST/api/payment

Create a Payment

Create a new Payment. Once created, prompt your customers to pay through the hosted flow at the returned url.

If you are using the SDK, payments can be created from the SDK directly without interacting with the API.

Parameters

Name
display*
Type
object
Description
Display settings for the payment page shown to the user.
- intent (string): Purpose of the payment. For example, "Pay", "Mint NFT", "Deposit", etc.
- orgLogo (string): Optional. URL to your organization's logo to display on the payment page.
- items (array): Optional. List of items being purchased. Each item has:
  - name (string): Name of the item
  - description (string): Description of the item
  - image (string): Optional URL to an image
  - price (string): Optional display price
  - priceDetails (string): Optional additional price details
- preferredChains (number[]): Optional. Chain IDs to display first when the user is selecting a payment option.
- preferredTokens (object[]): Optional. Specific tokens to display first. Takes precedence over preferredChains. Example: set to [{"chain": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}] to display Base USDC first.
- paymentOptions (string[]): Optional. Array of additional payment options to display to the user. The available options are Coinbase, Binance, Solana, RampNetwork, and ExternalChains. ExternalChains includes Bitcoin, Tron, Zcash, and non-EVM chains. Defaults to including all options.
- redirectUri (string): Optional. URL to redirect the customer to on successful payment completion.
Name
destination*
Type
object
Description
Payment recipient details.
- destinationAddress (string): Ethereum address of the recipient account or contract.
- chainId (number): Chain ID of the chain to receive payment on. We support Arbitrum (42161), Base (8453), Blast (81457), Binance Smart Chain (56), Ethereum L1 (1), Linea (59144), Optimism (10), Polygon PoS (137), and Worldchain (480).
- tokenAddress (string): Address of the token on the destination chain to receive payment in. To receive the chain's native token (ETH or MATIC), set to "0x0000000000000000000000000000000000000000"
- amountUnits (string): Controls the exact amount to receive. Must be a precise decimal string. (e.g. "1.00" for $1.00 USDC). Providing more decimals than the underlying token supports will result in an error.
- calldata (string): Optional. Calldata to execute an arbitrary contract call on the recipient address contract. If specified, we'll automatically make a token approval of amountUnits to the contract before executing the call. See the quickstart for example usage.
Name
externalId
Type
string
Description
Optional. Associate this payment with an external ID, such as your system's unique checkout or deposit ID. Returned in webhooks and API responses.
Multiple calls with the same externalId will return the same Payment object instead of creating new ones. This prevents accidentally creating duplicate payments.
Name
metadata
Type
object
Description
Optional. Attach key-value data to the payment object that persists across webhooks and API responses. For example, attach your system’s unique ID to simplify tracking, or store customer information with their payment.
You can specify up to 50 key-value pairs. Keys and values are stored as strings.

POST

/api/payment

curl --request POST 'https://pay.daimo.com/api/payment' \
--header 'Api-Key: <Your API key>' \
--data-raw '{
  "display": {
    "intent": "Pay Daimoo",
    "items": [
      {
        "name": "Milk",
        "description": "Get milk?",
        "image": "https://picsum.photos/200"
      }
    ],
    "preferredChains": [8453],
    "preferredTokens": [
      { "chain": 10, "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85" }
    ],
    "paymentOptions": ["Daimo", "Coinbase"],
    "redirectUri": "https://pay.daimo.com/"
  },
  "destination": {
    "destinationAddress": "<Your address>",
    "chainId": 10,
    "tokenAddress": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
    "amountUnits": "1.00"
  },
  "externalId": "123",
  "metadata": { "mySystemId": "123", "name": "John Doe" }
}'

Response

Name
id
Type
string
Description
Unique ID for the Payment.
Name
url
Type
string
Description
URL of the hosted payment page.
Name
payment
Type
object
Description
The newly created Payment object.

{
  "id": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
  "url": "https://pay.daimo.com/checkout?id=7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
  "payment": {
    "id": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
    "status": "payment_unpaid",
    "createdAt": "1739554073",
    "display": {
      "intent": "Pay Daimoo",
      "paymentValue": "1.00",
      "currency": "USD"
    },
    "source": null,
    "destination": {
      "destinationAddress": "0x3a321372E8a9755cD2CA6114eB8dA32A14F8100b",
      "txHash": null,
      "chainId": "8453",
      "amountUnits": "1.00",
      "tokenSymbol": "DAI",
      "tokenAddress": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
      "calldata": "0x"
    },
    "externalId": "123",
    "metadata": {
      "mySystemId": "123",
      "name": "John Doe"
    }
  }
}

Customization

Daimo Pay uses ConnectKit and offers the same theming and customization options. You can edit fonts, colors, and other styling via the theme and customTheme props. For detail, see the ConnectKit docs.

GET/api/payment/{id}

Retrieve a Payment by ID

Get the details of a previously created payment by its ID. The payment ID is returned in the response from the create payment endpoint. It's also included in the SDK event handlers and webhook payloads.

Parameters

Include the payment ID you want to retrieve in the URL path.

GET

/api/payment/{id}

curl --request GET 'https://pay.daimo.com/api/payment/{id}' \
--header 'Api-Key: <Your API key>'

Response

The Payment object corresponding to the payment ID.

{
  "id": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
  "status": "payment_completed",
  "createdAt": "1739554073",
  "display": {
    "intent": "Pay Daimoo",
    "paymentValue": "1.00",
    "currency": "USD"
  },
  "source": {
    "payerAddress": "0xFBfa6A0D1F44b60d7CCA4b95d5a2CfB15246DB0D",
    "txHash": "0xf975e462c8191d18ef970579814ebf68c83c45b4fa8984184f744f739285133b",
    "chainId": "10",
    "amountUnits": "1.00",
    "tokenSymbol": "USDC",
    "tokenAddress": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"
  },
  "destination": {
  "destinationAddress": "0x3a321372E8a9755cD2CA6114eB8dA32A14F8100b",
    "txHash": "0x8316f2dd90051333a6f879d7b15cacdf960535e56476a5300ad90c14377fa347",
    "chainId": "8453",
    "amountUnits": "1.00",
    "tokenSymbol": "DAI",
    "tokenAddress": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
    "calldata": "0x"
  },
  "externalId": "123",
  "metadata": {
    "mySystemId": "123",
    "name": "John Doe"
  }
}

GET/api/payment/external-id/{externalId}

Retrieve a Payment by External ID

Get the details of a previously created payment by the externalId specified during payment creation. externalId is unique to each payment so it can be used as a unique identifier to lookup a payment.

Parameters

Include the externalId you want to retrieve in the URL path.

GET

/api/payment/external-id/{externalId}

curl --request GET 'https://pay.daimo.com/api/payment/external-id/{externalId}' \
--header 'Api-Key: <Your API key>'

Response

The Payment object corresponding to the externalId. The externalId is unique to each payment so it can be used as a unique identifier to lookup a payment.

{
  "id": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
  "status": "payment_completed",
  "createdAt": "1739554073",
  "display": {
    "intent": "Pay Daimoo",
    "paymentValue": "1.00",
    "currency": "USD"
  },
  "source": {
    "payerAddress": "0xFBfa6A0D1F44b60d7CCA4b95d5a2CfB15246DB0D",
    "txHash": "0xf975e462c8191d18ef970579814ebf68c83c45b4fa8984184f744f739285133b",
    "chainId": "10",
    "amountUnits": "1.00",
    "tokenSymbol": "USDC",
    "tokenAddress": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"
  },
  "destination": {
    "destinationAddress": "0x3a321372E8a9755cD2CA6114eB8dA32A14F8100b",
    "txHash": "0x8316f2dd90051333a6f879d7b15cacdf960535e56476a5300ad90c14377fa347",
    "chainId": "8453",
    "amountUnits": "1.00",
    "tokenSymbol": "DAI",
    "tokenAddress": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
    "calldata": "0x"
  },
  "externalId": "123",
  "metadata": {
    "mySystemId": "123",
    "name": "John Doe"
  }
}