API Reference

All requests need to set api-key to their peanut api key in their headers:

Header	Value
`api-key`	`YOUR_PEANUT_API_KEY`

Create a New Payment

POST https://api.peanut.to/charges

Request Body Parameters

Parameter	Type	Required	Description
`pricing_type`	string	Yes	Type of pricing. Options: `"fixed_price"`, `"no_price"`
`local_price`	object	Yes	Price information containing `amount` and `currency`
`local_price.amount`	string	Yes	The price amount as a string
`local_price.currency`	string	No	The currency code (currently only `"USD"` is supported)
`baseUrl`	string	No	Custom base URL for the payment page
`requestId`	string	No	Existing request ID to associate with this charge
`requestProps`	object	No	Payment request properties
`metadata`	object	No	Arbitrary additional data. Returned in webhook call
`redirect_url`	string	No	URL to redirect user after successful payment
`cancel_url`	string	No	URL to redirect user if payment is canceled

Example Request

javascript
const res = await fetch('https://api.peanut.to/charges', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json",
      'api-key': "YOUR_API_KEY"
    },
    body: JSON.stringify({
      pricing_type: "fixed_price",
      local_price: {
        amount: "13.37",
        currency: "USD"
      },
      redirect_url: "https://shopify.com/success",
      cancel_url: "https://shopify.com/cancel"
    })
});
const data = await res.json();

Example Response

Status Code: 201 Created

json
{
  "data": {
    "id": "4f77223g-f5be-5e6d-bcb3-443f29gf5f5g",
    "hosted_url": "<https://peanut.me/pay/4f77223g-f5be-5e6d-bcb3-443f29gf5f5g>",
    "created_at": "2024-11-28T06:45:23.034Z",
    "metadata": {
      "userId": "0x742d35"
    },
    "pricing_type": "fixed_price",
    "brand_color": "#122332",
    "brand_logo_url": "",
    "charge_kind": "WEB3",
    "code": "4f77223g-f5be-5e6d-bcb3-443f29gf5f5g",
    "collected_email": false,
    "organization_name": "",
    "payments": [],
    "pricing": {
      "local": {
        "amount": "13.37",
        "currency": "USD"
      },
      "settlement": {
        "amount": "13.37",
        "currency": "USD"
      }
    },
    "pwcb_only": false,
    "redirects": {
      "cancel_url": "",
      "success_url": "",
      "will_redirect_after_success": false
    },
    "timeline": [],
    "web3_retail_payments_enabled": true
  },
  "warnings": []
}

Error Responses

Status Code	Description
400	Bad Request - Invalid input parameters
500	Internal Server Error

Fetch a single charge

GET https://api.peanut.to/charges/{payment_id}

URL Parameters

Parameter	Type	Description
`chargeId`	string	The unique identifier of the charge

Response

Status Code: 200 OK

json
{
  "data": {
    "id": "4f77223g-f5be-5e6d-bcb3-443f29gf5f5g",
    "hosted_url": "<https://peanut.me/pay/4f77223g-f5be-5e6d-bcb3-443f29gf5f5g>",
    "created_at": "2024-11-28T06:45:23.034Z",
    "pricing_type": "fixed_price",
    "pricing": {
      "local": {
        "amount": "13.37",
        "currency": "USD"
      },
      "settlement": {
        "amount": "13.37",
        "currency": "USD"
      }
    },
    "payments": []
  },
  "warnings": []
}

Error Responses

Status Code	Description
404	Not Found - Charge not found

Example Request

javascript
const response = await fetch('<https://api.peanut.me/charges/4f77223g-f5be-5e6d-bcb3-443f29gf5f5g>', {
  method: 'GET',
  headers: {
    'api-key': 'YOUR_API_KEY'
  }
});
const data = await response.json();

Fetch all your charges

GET https://api.peanut.to/charges

Query Parameters

Parameter	Type	Description	Default
`limit`	number	Maximum number of charges to return (1-100)	25
`starting_after`	string	Cursor for pagination, starting after this charge ID	-
`ending_before`	string	Cursor for pagination, ending before this charge ID	-
`status`	string	Filter charges by status	-

Response

Status Code: 200 OK

json
{
  "data": [
    {
      "id": "4f77223g-f5be-5e6d-bcb3-443f29gf5f5g",
      "hosted_url": "<https://peanut.me/pay/4f77223g-f5be-5e6d-bcb3-443f29gf5f5g>",
      "created_at": "2024-11-28T06:45:23.034Z",
      "pricing_type": "fixed_price",
      "pricing": {
        "local": {
          "amount": "13.37",
          "currency": "USD"
        },
        "settlement": {
          "amount": "13.37",
          "currency": "USD"
        }
      },
      "payments": []
    }
  ],
  "pagination": {
    "has_more": false,
    "total": 1
  },
  "warnings": []
}

Example Request

javascript
const response = await fetch('<https://api.peanut.me/charges>', {
  method: 'GET',
  headers: {
    'api-key': 'YOUR_API_KEY'
  }
});
const data = await response.json();

Configure Payment Destination

POST https://api.peanut.to/api-keys/receiving-wallet

Parameter	Type	Description
`walletAddress`	string	Destination wallet address
`chainId`	number	Blockchain network ID
`tokenAddress`	string	Token contract address

Example Request

javascript
const res = await fetch('https://api.peanut.to/api-keys/receiving-wallet', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    walletAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    chainId: 10,
    tokenAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
  })
});

Configure Webhook

POST https://api.peanut.to/api-keys/charge-webhook

Endpoint	Type	Description
`url`	string	your receiving webhook URL

Example Request

javascript
const res = await fetch('https://api.peanut.to/api-keys/charge-webhook', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    url: 'https://shopify.com/webhook'
  })
});

Add a Payment to a Charge

Records a payment transaction for a specific charge.

Endpoint: POST /charges/:uuid/payments

Content-Type: application/json

URL Parameters

Parameter	Type	Description
`uuid`	string	The unique identifier of the charge

Request Body Parameters

Parameter	Type	Required	Description
`hash`	string	Yes	The transaction hash
`chainId`	string	Yes	The blockchain network ID
`tokenAddress`	string	Yes	The address of the token used for payment

Response

Status Code: 201 Created

json
{
  "uuid": "payment-uuid",
  "payerTransactionHash": "0x1234...",
  "payerChainId": "10",
  "paidTokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "requestCharge": {
    "uuid": "charge-uuid",
    "link": "<https://peanut.me/pay/charge-uuid>",
    "tokenAmount": "13.37",
    "tokenSymbol": "USDC"
  }
}

Error Responses

Status Code	Description
404	Not Found - Charge not found
409	Conflict - Transaction already used for payment
500	Internal Server Error

Request API

The Request API allows you to create and manage payment requests.

Create a New Request

Creates a new payment request for a specific recipient.

Endpoint: POST /requests

Content-Type: multipart/form-data

Request Body Parameters

Parameter	Type	Required	Description
`recipientAddress`	string	Yes	The recipient's Ethereum address
`chainId`	string	No	Blockchain network ID
`tokenAmount`	string	No	Amount of tokens requested
`tokenAddress`	string	No	Token contract address (for ERC20 tokens)
`tokenType`	string	No	Type of token
`tokenDecimals`	string	No	Number of decimal places for the token
`tokenSymbol`	string	No	Symbol of the token
`trackId`	string	No	Custom tracking identifier
`reference`	string	No	Reference information for the request
`attachment`	file	No	File attachment for the request

Response

Status Code: 201 Created

json
{
  "uuid": "request-uuid",
  "chainId": "10",
  "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "tokenAmount": "13.37",
  "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "tokenDecimals": 6,
  "tokenType": "erc20",
  "tokenSymbol": "USDC",
  "trackId": "custom-tracking-id",
  "reference": "Payment for services",
  "attachmentUrl": "<https://storage.example.com/request_attachment.pdf>",
  "createdAt": "2024-11-28T06:45:23.034Z",
  "updatedAt": "2024-11-28T06:45:23.034Z",
  "history": []
}

Get a Request by ID

Retrieves a specific payment request by its UUID.

Endpoint: GET /requests/:uuid

URL Parameters

Parameter	Type	Description
`uuid`	string	The unique identifier of the request

Response

Status Code: 200 OK

json
{
  "uuid": "request-uuid",
  "chainId": "10",
  "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "tokenAmount": "13.37",
  "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "tokenDecimals": 6,
  "tokenType": "erc20",
  "tokenSymbol": "USDC",
  "trackId": "custom-tracking-id",
  "reference": "Payment for services",
  "attachmentUrl": "<https://storage.example.com/request_attachment.pdf>",
  "createdAt": "2024-11-28T06:45:23.034Z",
  "updatedAt": "2024-11-28T06:45:23.034Z",
  "history": []
}

Error Responses

Status Code	Description
404	Not Found - Charge not found

Find a Request

Retrieves or creates a payment request based on query parameters.

Endpoint: GET /requests

Query Parameters

Parameter	Type	Required	Description
`recipient`	string	Yes	Recipient address, ENS name, or Peanut username
`tokenAmount`	string	No	Amount of tokens requested
`tokenAddress`	string	No	Token contract address
`chainId`	string	No	Blockchain network ID

Response

Status Code: 200 OK (existing request) or 201 Created (new request)

json
{
  "uuid": "request-uuid",
  "chainId": "10",
  "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "tokenAmount": "13.37",
  "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "tokenDecimals": 6,
  "tokenType": "erc20",
  "tokenSymbol": "USDC",
  "createdAt": "2024-11-28T06:45:23.034Z",
  "updatedAt": "2024-11-28T06:45:23.034Z",
  "history": []
}

Error Responses

Status Code	Description
404	Not Found - Charge not found

Request Charge API

Get a Request Charge

Retrieves a specific payment request charge.

Endpoint: GET /request-charges/:uuid

URL Parameters

Parameter	Type	Description
`uuid`	string	The unique identifier of the request charge

Response

Status Code: 200 OK

json
{
  "uuid": "charge-uuid",
  "link": "<https://peanut.me/pay/charge-uuid>",
  "tokenAmount": "13.37",
  "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "tokenDecimals": 6,
  "tokenType": "erc20",
  "tokenSymbol": "USDC",
  "chainId": "10",
  "createdAt": "2024-11-28T06:45:23.034Z",
  "requestLink": {
    "uuid": "request-uuid",
    "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }
}

Error Responses

Status Code	Description
404	Not Found - Charge not found