Payments API

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

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.
  • 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 call data 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.
  • 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.

{
  "id": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
  "status": "payment_completed",
  "createdAt": "1739554073",
  "display": {
    "intent": "Checkout",
  },
  "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"
  },
  "metadata": {
    "mySystemId": "123",
    "name": "John Doe"
  },
}
POST/api/payment

Create a Payment

Create a new Payment.

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", "Deposit", etc.
    • orgLogo (string): Optional. URL to your organization's logo to display on the payment page.
    • 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 AllExchanges, Coinbase, Binance, Lemon, AllPaymentApps (desktop only), Venmo, CashApp, MercadoPago, Revolut, Wise, Zelle. 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. See supported chains.
    • 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.
  • Name
    refundAddress*
    Type
    string
    Description

    Required fallback refund address. Must be valid on all supported networks.

  • 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": "Checkout",
    "preferredChains": [8453],
    "preferredTokens": [
      { "chain": 10, "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85" }
    ],
    "paymentOptions": ["Coinbase","Venmo","Cashapp"],
    "redirectUri": "https://pay.daimo.com/"
  },
  "destination": {
    "destinationAddress": "<Your address>",
    "chainId": 10,
    "tokenAddress": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
    "amountUnits": "1.00"
  },
  "refundAddress": "<Your refund address>",
  "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": "Checkout",
    },
    "source": null,
    "destination": {
      "destinationAddress": "0x3a321372E8a9755cD2CA6114eB8dA32A14F8100b",
      "txHash": null,
      "chainId": "8453",
      "amountUnits": "1.00",
      "tokenSymbol": "DAI",
      "tokenAddress": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
      "callData": "0x"
    },
    "metadata": {
      "mySystemId": "123",
      "name": "John Doe"
    }
  }
}
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": "Checkout",
  },
  "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"
  },
  "metadata": {
    "mySystemId": "123",
    "name": "John Doe"
  }
}

Was this page helpful?