Tipping

Enable tipping with preset configurations and free-form tipping during the checkout process.

Tipping presets for payment links allow you to set multiple options to display to customers during the checkout process. Tipping presets can be a percentage of the total, or a dollar amount, such as 10%, 15%, and 20%, or $1.00, $1.50, and $2.00. When choosing preset percentages, you must choose whether the calculations are based on the pre-tax or post-tax amount.

For percentage presets, you can also choose whether the tip amount is calculated on the pre-tax or post-tax amount.

Enable tipping

Tipping is enabled through creating a transfer configuration. By default, tipping is disabled. Additionally, if choosing preset percentages, you must set whether the tip is calculated on the pre-tax or post-tax amount.

curl -X POST "https://api.moov.io/accounts/{accountID}/transfer-config" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.04.00" \
  -d '{\n    "tipPresets": {\n      "calculationBasis": "pre-tax",\n      "percentageOptions": [\n        5,\n        15,\n        25\n      ]\n    }\n}'

curl -X POST "https://api.moov.io/accounts/{accountID}/transfer-config" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.04.00" \
  -d '{\n    "tipPresets": {\n      "currency": "USD",\n      "fixedAmountOptions": [\n        { \n          "currency": "USD", \n          "valueDecimal": "1.00" \n        },\n        { \n          "currency": "USD", \n          "valueDecimal": "2.00" \n        },\n        { \n          "currency": "USD", \n          "valueDecimal": "5.00" \n        }\n      ]\n    }\n}'

If a tip amount is selected at checkout, it's added to the total amount to be charged. The breakdown of different charges will be on the receipt sent to the customer:

• Subtotal: $10.00
• Sales tax: $1.00
• Tip: $2.50
• Total: $13.50

Once tipping presets are configured, you can enable tipping within payment links.

Manage tipping presets

Retrieve the transfer configuration for an account.

curl -X GET "https://api.moov.io/accounts/{accountID}/transfer-config" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.04.00" \

Update tipping presets

You can update the following tipping preset options:

• Preset type (percentage or fixed amount)
• Preset options
• Calculation basis (pre-tax or post-tax)

curl -X PUT "https://api.moov.io/accounts/{accountID}/transfer-config" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.04.00" \
  -d '{\n    "tipPresets": {\n      "fixedAmountOptions": [\n        { \n          "currency": "USD", \n          "valueDecimal": "5.00" \n        },\n        { \n          "currency": "USD", \n          "valueDecimal": "10.00" \n        },\n        { \n          "currency": "USD", \n          "valueDecimal": "15.00" \n        }\n\t\t]\n    }\n}'

Create transfer

In addition to tipping presets with payment links, you can create a basic transfer with a tip. In the transfers request, add a tip amount to amountDetails. The tip must be the same currency as the amount.

The amount is the total payment, which is the base price + tip. In the example below, the amount.value represents a base price of $349.00 with a tip of $20.00, totaling $549.00.

 1curl -X POST "https://api.moov.io/accounts/{accountID}/transfers" \
 2  -H "Authorization: Bearer {token}" \
 3  -H "X-Moov-Version: v2026.04.00" \
 4  -d '{\n 5    "source": {\n 6      "paymentMethodID": "9506dbf6-4208-44c3-ad8a-e4431660e1f2"\n 7    },\n 8    "destination": {\n 9      "paymentMethodID": "3f9969cf-a1f3-4d83-8ddc-229a506651cf"\n10    },\n11    "amount": {\n12      "currency": "USD",\n13      "value": 54900\n14    },\n15    "amountDetails": {\n16      "tip": {\n17        "currency": "USD",\n18        "valueDecimal": "20.00"\n19      }\n20    },\n21    "description": "Transfer from card to wallet",\n22    "metadata": {\n23      "optional": "metadata"\n24    }\n25}'