Payment Links

MoneyHash Payment Links are hosted, branded checkout pages tied to a specific customer and a list of items. You generate a unique URL via the API (or dashboard), share it, and the customer completes payment - no frontend required.

Each link automatically applies your account's brand settings (logo, name, colors) and incorporates any configured taxes into the final amount. The link is scoped to a single MoneyHash customer, so only that customer can complete the purchase.

Branding: Payment links inherit your account's logo, brand name, and colors automatically - no extra configuration needed.

Dashboard: You can also create and manage payment links directly in the MoneyHash dashboard without writing any code.

When to use

Payment links are the right tool when you need to collect payment without building a checkout flow yourself.

Use case	Why payment links fit
Selling products or services without a website	No frontend required - the hosted page handles everything
Invoicing individual customers	Link is customer-scoped; only the intended recipient can pay
Collecting donations	Adjustable quantity lets customers choose their amount
Subscription or one-time payments via messaging	Share the URL over email, WhatsApp, or social media
Prototyping a checkout flow	No integration code needed for early validation

How to create a payment link via API

Step 1 - Authenticate

All requests require your API key passed in the X-Api-Key header, or an access_token as a query parameter.

See the Programmatic Access page for how to generate sandbox and live API keys and attach them to your requests.

Step 2 - Create or retrieve a customer

Payment links are scoped to a specific customer. Create one via POST /api/v1.1/customers/ and note the returned UUID. If the customer already exists, retrieve their UUID from the dashboard or the List Customers endpoint.

See the Customers API page for a complete request/response example.

Step 3 - Call the Create Payment Link endpoint

  POST
  /api/v1.4/payment_links/

Send a POST request to /api/v1.4/payment_links/ with the customer UUID, a list of items, currency, and quantity_type.

Request

{
  "customer": "5f9e2c1a-8b3d-4e6f-9a2b-1c3d4e5f6a7b",
  "name": "Invoice #1042",
  "description": "Consulting services — June 2026",
  "currency": "USD",
  "quantity_type": "FIXED",
  "items": [
    {
      "name": "Consulting hours",
      "unit_price": "150.00",
      "quantity": 4
    },
    {
      "name": "Setup fee",
      "unit_price": "50.00",
      "quantity": 1
    }
  ]
}

Step 4 - Retrieve the URL from the response

The response body contains a url field - this is the shareable payment link. The initial status is PENDING.

Step 5 - Share the link

Copy the URL and distribute it via email, SMS, WhatsApp, or any other channel. The customer does not need a MoneyHash account.

Step 6 - Monitor status

  GET
  /api/v1.4/payment_links/{payment_link_id}/status/

Pull GET /api/v1.4/payment_links/{payment_link_id}/status/ or listen for webhooks to track the link from PENDING → PAID (or EXPIRED).

Response

{
  "status": {
    "code": 200,
    "message": "success",
    "errors": []
  },
  "data": {
    "id": "wA9eY9m",
    "status": "PAID",
    "url": "https://pay.moneyhash.io/wA9eY9m",
    "customer": "5f9e2c1a-8b3d-4e6f-9a2b-1c3d4e5f6a7b",
    "currency": "USD",
    "amount": "650.00",
    "paid_at": "2026-07-10T14:32:07+00:00"
  }
}

Quantity types

The quantity_type parameter controls whether customers can change item quantities at checkout.

Value	Behavior
`FIXED`	Quantities are locked. Customers pay exactly the amounts you set.
`ADJUSTABLE`	Customers choose quantity per item, up to a maximum of 99.

Setting up taxes

Taxes are applied automatically based on your account settings. To configure them:

Go to Settings → Accounts in the MoneyHash dashboard.
Select the account you want to update.
Set Tax Number (fixed amount) and/or Taxes (percentage rate).

Payment link lifecycle

Common errors & troubleshooting

Status	Error	Likely cause	Fix
`400`	Invalid Customer Token	The customer UUID does not exist in your account.	Create the customer first via `POST /api/v1.4/customers/` and use the returned UUID.
`400`	This field is required	A required field (`name`, `description`, `currency`, `items`, or `quantity_type`) was omitted.	Check the request body and ensure all required fields are present.
`400`	Invalid items format	`items` is not a valid array, or an item is missing `name`, `unit_price`, or `quantity`.	Ensure each item object has all three fields. `unit_price` must be a decimal string, e.g. `"10.00"`.
`401`	Authentication credentials were not provided	The `X-Api-Key` header or `access_token` query param is missing.	Add `X-Api-Key: YOUR_KEY` to every request.
`401`	Invalid API key	The key format is correct but does not match any active key on this account.	Verify the key in the MoneyHash dashboard. Use sandbox keys for test mode, live keys for production.
`404`	Not found	The `payment_link_id` in the URL does not exist or belongs to a different account.	Double-check the ID returned at creation. IDs are case-sensitive (`wA9eY9m` ≠ `wa9ey9m`).

Debugging checklist

Confirm you are using the correct environment - sandbox API keys will not work against the production base URL and vice versa.
Check status.errors in the response body - it often contains field-level validation details.
Ensure unit_price is sent as a string with up to 2 decimal places (e.g. "10.00"), not a raw number.
If tax amounts look wrong, review your Tax Number and Taxes settings under Settings → Accounts.
If the customer cannot open the link, confirm the link's status is still PENDING - expired links return no payment UI.

Still stuck? Reach out via the MoneyHash dashboard support widget or email your account team with the full response body including status.errors.