Let customers pay your business

Confirm the arrangement before collecting

This guide describes ExampleCo reselling usage to its customers, with ExampleCo paying Modelvia for the service. A different arrangement where Modelvia invoices a customer directly must be configured during onboarding. Changing a payment-method setting does not change the seller, payee, invoice price or billing arrangement.

Square is a processor for an eligible issued invoice, not a second seller. Its configured merchant must match that invoice’s seller. Direct payment goes to the payee named by the invoice and is recorded only after staff verify receipt. Neither method changes who owes whom.

1. Agree to customer prices, commercial terms and spending limits before enabling billable usage. A displayed usage estimate is not an issued invoice.
2. Confirm your seller identity, tax treatment, customer billing details and invoice-close process with Modelvia onboarding.
3. For Square, have onboarding connect and verify the correct merchant and AUD location, configure webhook delivery, and confirm whether the environment is sandbox or live.
4. Choose payment methods and the allowed checkout surface. Test the complete invoice, payment and receipt journey for your configured account before offering it to customers.

Same-owner internal use should be configured as internal cost with client-funded usage. It must not create an invoice to yourself or a customer resale charge. Collecting a customer payment does not automatically settle your separate Modelvia service fees.

Choose how and where customers pay

As a client administrator, open Settings. Under How your customers pay, choose a method and save with MFA when prompted. Under Where your customers pay, choose your application, the Modelvia portal, both, or off.

Direct and both require plain-text instructions, up to 2,000 characters. Include the payee and how to find the payment details; do not add HTML or confidential information that every customer of your business should not see.

The checkout surface values are client_app, portal, both and off. Configure the surface in hosted Settings or through Modelvia onboarding; the client payment-settings API below changes methods and instructions only. Turning the offer off does not erase receipts or resolve an earlier checkout attempt.

Manage methods from your administration backend

Use your server-only client integration key. These settings affect all customers of your business, so expose changes only to authorized staff.

curl --fail-with-body "https://api.modelvia.dev/v1/client/payment-settings" \
  -H "Authorization: Bearer $MODELVIA_CLIENT_KEY"

The response contains clientId, version, customerPayment, squareConfigured and paymentMode. The mode is sandbox, live or disabled; it describes Square availability, not whether direct payments are allowed.

// POST /v1/client/payment-settings from your trusted administration backend.
// Use clientId and version from a fresh GET. Example values are fictional.
{
  "clientId": "exampleco",
  "version": 7,
  "customerPayment": {
    "methods": "both",
    "directInstructions": "Pay ExampleCo using the instructions on your invoice. Include the invoice number as your reference."
  }
}

Send exactly these three top-level fields. The client ID is an assertion of the business you are editing, not a way to select another business. A stale version or changed scope returns 409. Read the settings again, confirm the client, version and saved fields, and let the person review any conflict before saving again. After a lost response, read back persisted settings before reporting success or retrying.

Use the current invoice’s payment flags

Read /v1/client/customers/{customerId}/billing for issued invoices. Check the response’s client and customer IDs against the signed-in person’s stored binding. Use an invoice from that response and validate it again before an action.

Missing flags mean unavailable. Do not infer permission from collectionEnabled, a selected method, a positive amount or paid: false. Collection also depends on active accounts, invoice adjustments, surface choice and previous attempts. Never turn a current usage estimate into a payment request.

What a customer sees on each invoice line, and who used it, is covered in receipts, invoices and attribution.

Create a Square checkout and verify its outcome

Recheck the user’s permission, stored customer binding and invoice ownership in your backend. Protect your application’s payment action against cross-site requests. The invoice determines the seller, currency and amount; the browser must not supply a replacement amount.

# Server-side only, after checking your user, customer and invoice binding.
# This creates or reuses a payment link. Do not run it as a read-only test.
curl --fail-with-body -X POST \
  "https://api.modelvia.dev/v1/client/customers/$CUSTOMER_ID/invoices/$INVOICE_ID/checkout" \
  -H "Authorization: Bearer $MODELVIA_CLIENT_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'

For the resale arrangement in this guide, a successful response contains url, sessionId and mode (sandbox or live). Validate the response before opening the URL. Live links use HTTPS on square.link or checkout.square.site; sandbox links use the corresponding sandbox. hosts. Reject unexpected hosts, credentials or ports.

1. Persist an in-progress hold for this client, customer and invoice before sending the POST. Block another checkout, direct instructions and manual receipt entry while the result is unresolved. Preserve the hold across reloads.
2. On success, validate the expected Square response and open the checkout. A durable ready checkout can reuse its existing link; it does not restore the direct-payment option.
3. After a timeout, network error, malformed response or reconciliation error, keep the hold. An immediate read returning not_started, or no payment state, does not prove the original POST failed: it may still be in progress.
4. Read fresh invoice state. A confirmed paid receipt resolves the hold; a known ready checkout may resume the same Square link. Otherwise ask Modelvia support to reconcile the attempt before offering another payment path.

Do not automatically retry an unknown checkout or tell a customer to pay directly after an uncertain Square result. Returning from Square, closing its tab or seeing a success page does not mark an invoice paid; use the persisted receipt after verified webhook processing.

Record a payment your business has received

Customers pay ExampleCo using its instructions. An authorized staff member then verifies the actual receipt against the issued invoice. In hosted Billing, use Record payment received when it is available and complete MFA. A customer cannot mark their own invoice paid.

// POST /v1/client/customers/{customerId}/invoices/{invoiceId}/external-payment
// Staff-only, after verifying an actual full payment received by ExampleCo.
// Replace every example field with the verified statement and invoice values.
{
  "reference": "EXAMPLECO-STATEMENT-2026-09-001",
  "amountCents": "12500",
  "currency": "AUD",
  "receivedAt": "2026-09-23T01:15:00.000Z"
}

The amount must be a positive decimal string in cents and equal the full invoice total. Use a stable, unique statement reference for your business (1–200 characters, no control characters or angle brackets). receivedAt must be a non-future canonical ISO timestamp in UTC, including milliseconds.

Recording a receipt does not charge a customer, move money or automatically check a bank account. It appends a payment fact while the issued invoice document remains unchanged. The customer receives a limited receipt with source: external, invoice ID, amount, currency and settlement time; private statement references and staff identities are not included.

Validate the response or read the invoice again: require paid: true and an external receipt matching the invoice, amount and currency. Repeating the exact same receipt is idempotent. A different reference or changed receipt for an already paid invoice conflicts; do not invent a new reference to bypass it. Any Square attempt or later invoice adjustment can block recording and requires reconciliation.

Know what needs separate handling

• Automatic bank reconciliation and automatic “mark paid” updates are not provided by the external-payment route.
• Partial external payments and external-payment refunds are not supported by this API. Arrange reconciliation, credits or refunds with Modelvia support before changing the customer’s balance.
• Customer collection does not provide marketplace payouts, split settlements or automatic settlement of your own Modelvia service fees.
• Sandbox success does not establish live merchant readiness. Confirm the actual account’s invoice, delivery, webhook and authorized payment/refund workflow before launching collection.

Next: open Settings to review your current methods, surface and Square mode without creating a payment.