---
title: "Add payment request field"
url: "https://docs.signnow.com/docs/request-payments/operations/put-document-document_id"
type: "endpoint"
section: "request-payments"
slug: "request-payments/operations/put-document-document_id"
method: "PUT"
path: "/document/{document_id}"
operation_id: "put-document-document_id"
authorization: "bearer"
---

# Add payment request field

`PUT /document/{document_id}`

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

> 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) - for European countries. Example: 8,100.00
- `824085fd04ce63b670b11b2e83457d59ac796a39` (currency amount format 2) - for the United States. Example: 8.100,60

> 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/document-field-invite/operations/post-field_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) - for European countries. Example: 8,100.00; `824085fd04ce63b670b11b2e83457d59ac796a39` (currency amount format 2) - for the United States. Example: 8.100,00. | <img src="/reference-assets/images/Request_payments/validator_payment_field.png" alt="Validator ID"> |

</details>

## Authorization

bearer

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_id` | string | Yes | Document ID. |

## Request Body

**Schema**

```json
{
  "type": "object",
  "required": [
    "fields"
  ],
  "properties": {
    "fields": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "x",
          "y",
          "width",
          "height",
          "type",
          "role"
        ],
        "properties": {
          "x": {
            "type": "number",
            "example": 358,
            "description": "A horizontal position of the field in pixels."
          },
          "y": {
            "type": "number",
            "example": 171,
            "description": "A vertical position of the field in pixels."
          },
          "name": {
            "type": "string",
            "example": "payment_field",
            "minLength": 1,
            "description": "A unique field name."
          },
          "role": {
            "type": "string",
            "example": "Signer 1",
            "minLength": 1,
            "description": "Recipient role assigned to the field."
          },
          "type": {
            "type": "string",
            "example": "text",
            "minLength": 1,
            "description": "Field type. For the payment request field, the `type` is `text`."
          },
          "width": {
            "type": "number",
            "example": 177,
            "description": "Field width in pixels."
          },
          "height": {
            "type": "number",
            "example": 50,
            "description": "Field height in pixels."
          },
          "required": {
            "type": "boolean",
            "description": "Indicates whether the field is required. The field **must** be set to required to use it for the payment request.\n\n"
          },
          "page_number": {
            "type": "number",
            "example": 0,
            "description": "The page number where the field will be placed. Page numbering starts at 0 (corresponding to page 1)."
          },
          "validator_id": {
            "type": "string",
            "example": "7ef095fd94ce63b670b52b2e83457d59ac796a39",
            "minLength": 1,
            "description": "A string that adds format validation. To use the field for the payment request, you **must** use the following validators:\n`7ef095fd94ce63b670b52b2e83457d59ac796a39` (currency amount format 1) - for European countries. Example: `8,100.00`;\n`824085fd04ce63b670b11b2e83457d59ac796a39` (currency amount format 2) - for the United States. Example: `8.100,00`\n"
          },
          "prefilled_text": {
            "type": "string",
            "example": "8100",
            "description": "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.\n\n",
            "x-stoplight": {
              "id": "u1mhkit828rse"
            }
          }
        }
      },
      "minItems": 1,
      "description": "Array of field objects to add to the document.",
      "uniqueItems": true
    }
  },
  "x-examples": {
    "example-1": {
      "fields": [
        {
          "x": 358,
          "y": 171,
          "name": "signature1",
          "role": "Signer 1",
          "type": "text",
          "width": 177,
          "height": 50,
          "required": true,
          "page_number": 0,
          "validator_id": "{{number_validator_id}}",
          "custom_defined_option": false
        }
      ],
      "elements": [],
      "client_timestamp": "timestamp"
    }
  }
}
```

**Example** (`example-1`)

```json
{
  "fields": [
    {
      "x": 358,
      "y": 171,
      "name": "payment_field",
      "role": "Signer 1",
      "type": "text",
      "width": 177,
      "height": 50,
      "required": true,
      "page_number": 0,
      "validator_id": "7ef095fd94ce63b670b52b2e83457d59ac796a39",
      "prefilled_text": "8100"
    }
  ]
}
```

## Responses

### 200

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

**Example** (`Success`)

```json
{
  "id": "2a4406b54049473fb709ed1191908eb6700fXXXX",
  "lines": [],
  "texts": [],
  "checks": [],
  "hyperlinks": [],
  "signatures": [],
  "attachments": [],
  "radiobuttons": []
}
```

**Example** (`Example 1`)

```json
{
  "id": "2a4406b54049473fb709ed1191908eb6700f7347",
  "lines": [],
  "texts": [],
  "checks": [],
  "hyperlinks": [],
  "signatures": [],
  "attachments": [],
  "radiobuttons": []
}
```

## Code Examples

> Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running.

### cURL

```bash
curl -X PUT \
  "https://api.signnow.com/document/{document_id}" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fields": [{"x": 358, "y": 171, "name": "payment_field", "role": "Signer 1", "type": "text", "width": 177, "height": 50, "required": true, "page_number": 0, "validator_id": "7ef095fd94ce63b670b52b2e83457d59ac796a39", "prefilled_text": "8100"}]}'
```

---
*Full reference: https://docs.signnow.com/docs/request-payments/operations/put-document-document_id*