---
title: "Send document invite with payment request"
method: POST
path: "/document/{document_id}/invite"
---

# Send document invite with payment request

`POST /document/{document_id}/invite`

## Request

- Base URL: `https://api.signnow.com`
- URL: `https://api.signnow.com/document/{document_id}/invite`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/signnow/apis/signnow-api/docs/document/:document_id/invite/post.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint allows API users to send a document invite with a payment request. Recipients will be redirected to the payment page after completing the documents.

For more information, see the [Request payments guide](/docs/request-payments-guide).

> [!NOTE]
> To request a payment, users must either connect to the payment service individually or accept an invitation to an organization already connected to the payment service.

- To invite a user to an organization, see [Add members](/docs/organization/operations/post-v2-organizations-org-id-members). 

- To accept an invitation to an organization, the user can click the link they receive, or see [Accept invite to organization](/docs/organization/operations/post-v2-organizations-org-id-members-user-id-accept).

- To connect your organization to the payment service, see [Connect to merchant account](/docs/request-payments/operations/post-organizations-org-id-merchantaccount).

A payment request can be linked to a specific field (`calculated` type) or set as a fixed amount (`fixed`type).

This article lists only the parameters required for a payment request. For other field invite parameters, see [Send field invite](/docs/document-field-invite/operations/post-document-doc-id-invite).


<details>
<summary>Use additional attributes to customize the request</summary>

| Parameter | Description | Example |
| --- | --- | --- |
| `field_type` | Type of the field that sets the payment amount. Required if the request `type` is `calculated`. For a payment request invite, `filed_type` is `text_fields`. |<img src="/reference-assets/images/Request_payments/payment_request_field_name_type.png" alt="Field type"> |
| `field_name` | Name of the field that sets the payment amount. Used if the `type` is `calculated`. Can be found in the [Get document response](/docs/document/operations/get-document) (fields.name). | See the screenshot above.  |
| `type` | Defines how the payment amount is set. Allowed values: `fixed` (the amount is set in the amount field) and `calculated` (set using a document field).<br><br> Learn how to [add a payment request field](/docs/request-payments/operations/put-document-document-id). |<img src="/reference-assets/images/Request_payments/payment_request_type.png" alt="Payment type"> |
| `currency` | Payment currency in ISO format. |<img src="/reference-assets/images/Request_payments/payment_request_amount_currency.png" alt="Currency"> |
| `amount` | Amount of payment. Required if `type` is 'fixed'. | See the screenshot above. |

</details>

## Request body

- object
  - `to` object[], required: An array of objects with email addresses and settings for all recipients.
    - `role` string, required: Recipient's role. Can be found in the response to [Get document](/docs/document/operations/get-document) request (roles.name).
    - `email` string, required: Recipient's email address.
    - `payment_request` object: Payment request details.
      - `type` string, required: Defines how the payment amount is set. Possible values: `fixed` (the payment amount is set in the amount field) and `calculated` (the payment amount is set using a document field).
      - `amount` string: Payment amount. Required if `type` is `fixed`.
      - `currency` string, required: Payment currency in ISO format.
      - `field_id` string: ID of the field that sets the payment amount. Required if the request `type` is `calculated`. Can be found in the [Get document](/docs/document/operations/get-document) response (fields.id).
      - `merchants` string[], required: IDs of connected payment service accounts. Found in the [Get user](/docs/user/operations/get-user-info) response and [Get merchant account](/docs/request-payments/operations/get-organizations-org-id-merchantaccount-merchant-account-id) response.
      - `field_name` string: Name of the field that sets the payment amount. Used if the `type` is `calculated`. Can be found in the [Get document](/docs/document/operations/get-document) response (fields.name).
      - `field_type` string: Type of the field that sets the payment amount. Required if the request `type` is `calculated`. Allowed value is `text_fields`.
  - `from` string, required: Sender's email address.

## Response `200`

Successful response.

- object
  - `status` string: Result of the request. Always `success`.

## Other responses

- `400`: - `field_id` is empty or missing. - `field_type` is missing or incorrect. - `amount` is empty or missing. - `currency` is missing. - `type` is missing. - `merchants` is empty. - Merchant ID is incorrect.

---

[API](https://skmtc.dev/signnow/apis/signnow-api.md) - [All operations](https://skmtc.dev/signnow/apis/signnow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signnow/apis/signnow-api/revisions/1c9c30a6142b?raw)