---
title: "Add payment request field"
method: PUT
path: "/document/{document_id}"
---

# Add payment request field

`PUT /document/{document_id}`

## Request

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

This endpoint allows API users to add a payment request field to a document.

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

> [!NOTE]
> The payment request field is a text field with a specific validator ID. You can only add one payment request field to your invite.

For payment requests with field values, you must use the following validator IDs:

- `7ef095fd94ce63b670b52b2e83457d59ac796a39` (currency amount format 1) - comma for thousands, dot for decimals. Example: `8,100.00`
- `824085fd04ce63b670b11b2e83457d59ac796a39` (currency amount format 2) - dot for thousands, comma for decimals. Example: `8.100,00`

> [!NOTE]
> To request payment from the recipient, you have to [connect to the payment service](/docs/request-payments/operations/post-organizations-org-id-merchantaccount) and send a [signature invite with a payment request](/docs/request-payments/operations/post-document-document-id-invite). The recipient will be asked to pay the amount you specified once they’ve completed the document.

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

| Parameter | Description | Example |
| --- | --- | --- |
| `type` | Field type. For the payment request field, the `type` is `text`. |<img src="/reference-assets/images/Request_payments/payment_field_type_name.png" alt="Payment field type"> |
| `name` | Name of the payment field. | See the screenshot above.  |
| `validator_id` | A string that adds format validation. To use the field for the payment request, you must use the following validators: `7ef095fd94ce63b670b52b2e83457d59ac796a39` (currency amount format 1) - comma for thousands, dot for decimals. Example: `8,100.00`; `824085fd04ce63b670b11b2e83457d59ac796a39` (currency amount format 2) - dot for thousands, comma for decimals. Example: `8.100,00`. | <img src="/reference-assets/images/Request_payments/validator_payment_field.png" alt="Validator ID"> |

</details>

## Request body

- object
  - `fields` object[], required: Array of field objects to add to the document.
    - `x` number, required: A horizontal position of the field in pixels.
    - `y` number, required: A vertical position of the field in pixels.
    - `name` string: A unique field name.
    - `role` string, required: Recipient role assigned to the field.
    - `type` string, required: Field type. For the payment request field, the `type` is `text`.
    - `width` number, required: Field width in pixels.
    - `height` number, required: Field height in pixels.
    - `required` boolean: Indicates whether the field is required. The field **must** be set to required to use it for the payment request.
    - `page_number` number: The page number where the field will be placed. Page numbering starts at 0 (corresponding to page 1).
    - `validator_id` string: A string that adds format validation. To use the field for the payment request, you **must** use the following validators: `7ef095fd94ce63b670b52b2e83457d59ac796a39` (currency amount format 1) - comma for thousands, dot for decimals. Example: `8,100.00`; `824085fd04ce63b670b11b2e83457d59ac796a39` (currency amount format 2) - dot for thousands, comma for decimals. Example: `8.100,00`
    - `prefilled_text` string: The amount in the specified format shown in the field when the signer opens the document. For the payment request field, only numbers should be used.

## Response `200`

Returns ID of the updated document with a payment request field in case of successful response.

- object
  - `id` string: ID of the document.
  - `lines` object[]: Line elements on the document.
  - `texts` object[]: Text elements on the document.
  - `views` unknown[]: View elements on the document.
    - unknown
  - `checks` object[]: Checkmark elements on the document.
  - `hyperlinks` object[]: Hyperlink elements on the document.
  - `signatures` object[]: Signature elements on the document.
  - `attachments` object[]: Attachment elements on the document.
  - `radiobuttons` object[]: Radio button elements on the document.

## Other responses

- `400`: * Wrong, expired, or missing token. * The document doesn't exist. * The document belongs to another user. * The request body isn't valid JSON. * `fields` isn't an array. * A field has no `type` or an unsupported `type`. * A required field property, such as `role` or `x`, is missing. * `page_number` points to a page the document doesn't have. * `validator_id` doesn't match any validator. * `prefilled_text` doesn't match the field's validator. * A coordinate or size is out of range, for example `x` is less than `0` or `width` is less than `1`.

---

[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)