> For the complete documentation index, see [llms.txt](https://docs.shadowcipher.in/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shadowcipher.in/endpoints/initiate-transaction.md).

# Start a signing transaction

Start a signing transaction for a PDF or a template and get the signing link.

<mark style="color:blue;">`POST`</mark> `/api/oauth/initiateTxn`

Creates a transaction and returns a `signing_url`. Redirect the signer's browser to that URL to open the signing page.

## Headers

| Header          | Value                   |
| --------------- | ----------------------- |
| `Authorization` | `Bearer <access_token>` |
| `Content-Type`  | `application/json`      |

## Request body

| Field            | Type                   | Required                        | Description                                                                                                                                                                                                             |
| ---------------- | ---------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reference_no`   | string (max 100)       | Yes                             | Your own reference for this document. It is echoed back and shown on the signing page.                                                                                                                                  |
| `signer_name`    | string (max 100)       | Yes                             | Shown on the signature placeholder ("Signed by ...").                                                                                                                                                                   |
| `return_url`     | string (URI, max 1000) | Yes                             | The `http(s)` URL the signer is sent back to, with `txn_no`, `reference_no` and `status`.                                                                                                                               |
| `file_type`      | string                 | No                              | `PDF` (default) or `TEMPLATES`. Case-insensitive.                                                                                                                                                                       |
| `document`       | string (base64)        | When `file_type` is `PDF`       | The PDF to sign, base64-encoded. Maximum 10 MB decoded.                                                                                                                                                                 |
| `template_id`    | string                 | When `file_type` is `TEMPLATES` | ID of an active template assigned to your client.                                                                                                                                                                       |
| `signature_type` | integer or integer\[]  | No                              | One or more signature type IDs from [List signature types](https://docs.shadowcipher.in/endpoints/signature-types.md). Only these are offered to the signer. If omitted, every type assigned to your client is offered. |
| `page`           | string                 | No                              | Page for the signature: `first` (default), `last`, or a page number such as `"3"`.                                                                                                                                      |
| `position`       | string                 | No                              | Where the signature goes on that page. Default `top-right`. See below.                                                                                                                                                  |

### Positions

|            | Left          | Center          | Right          |
| ---------- | ------------- | --------------- | -------------- |
| **Top**    | `top-left`    | `top-center`    | `top-right`    |
| **Middle** | `middle-left` | `middle-center` | `middle-right` |
| **Bottom** | `bottom-left` | `bottom-center` | `bottom-right` |

### PDF or template

{% tabs %}
{% tab title="PDF" %}
Send the file in `document`. The `signing_url` opens the signing page directly.

```json
{
  "reference_no": "INV-2026-0042",
  "file_type": "PDF",
  "document": "JVBERi0xLjQK...",
  "signer_name": "Abhishek",
  "return_url": "https://partner.example.com/signing/callback",
  "signature_type": [1, 2],
  "page": "last",
  "position": "bottom-right"
}
```

{% endtab %}

{% tab title="Template" %}
Send `template_id` instead of `document`. The `signing_url` opens the template fill page. The signer fills in the template, the PDF is generated, and the signing page follows.

```json
{
  "reference_no": "AGR-2026-0107",
  "file_type": "TEMPLATES",
  "template_id": "83f1ecc84935",
  "signer_name": "Abhishek",
  "return_url": "https://partner.example.com/signing/callback"
}
```

Templates are created in **Draft Writer** and assigned to clients by the BSA team.
{% endtab %}
{% endtabs %}

## Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://app.shadowcipher.in/api/oauth/initiateTxn \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_no": "INV-2026-0042",
    "document": "'"$(base64 < invoice.pdf | tr -d '\n')"'",
    "signer_name": "Abhishek",
    "return_url": "https://partner.example.com/signing/callback",
    "page": "last",
    "position": "bottom-right"
  }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import { readFile } from "node:fs/promises";

const pdf = await readFile("invoice.pdf");
const res = await fetch("https://app.shadowcipher.in/api/oauth/initiateTxn", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reference_no: "INV-2026-0042",
    document: pdf.toString("base64"),
    signer_name: "Abhishek",
    return_url: "https://partner.example.com/signing/callback",
    page: "last",
    position: "bottom-right",
  }),
});
const { txn_no, signing_url } = await res.json();
// Redirect the signer's browser to signing_url
```

{% endtab %}
{% endtabs %}

## Responses

{% tabs %}
{% tab title="201 Created" %}

```json
{
  "txn_no": "3f2c1a9e8b7d4c6a9e1f0b2d3c4a5e6f",
  "reference_no": "INV-2026-0042",
  "status": 2,
  "message": "Initiated",
  "signing_url": "https://app.shadowcipher.in/secure/preview?txnref=q2v9Lx0bW3c...",
  "expires_at": "2026-10-20T12:20:00Z"
}
```

| Field          | Type      | Description                                                                                                |
| -------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
| `txn_no`       | string    | Transaction number. Keep it to fetch the document later.                                                   |
| `reference_no` | string    | Your reference, echoed back.                                                                               |
| `status`       | integer   | `2` (pending).                                                                                             |
| `message`      | string    | `Initiated`                                                                                                |
| `signing_url`  | string    | Send the signer's browser here. The `txnref` parameter is AES-256-GCM encrypted and checked on every open. |
| `expires_at`   | date-time | The link, and any signing session opened from it, stops working at this time (20 minutes after issue).     |
| {% endtab %}   |           |                                                                                                            |

{% tab title="400" %}
Invalid request body. `field` names the field that failed.

```json
{
  "error": "invalid_request",
  "error_description": "document must be a base64-encoded PDF",
  "field": "document"
}
```

Also returned for an unknown or inactive `template_id`.
{% endtab %}

{% tab title="401" %}
Missing, invalid or expired access token.

```json
{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has expired"
}
```

{% endtab %}

{% tab title="403" %}
The token lacks the `txn:initiate` scope, the client is inactive, or a signature type or template isn't assigned to your client.

```json
{
  "error": "forbidden",
  "error_description": "signature_type [6] is not enabled for this client",
  "field": "signature_type"
}
```

{% endtab %}

{% tab title="413" %}
The document is larger than 10 MB.

```json
{
  "error": "payload_too_large",
  "error_description": "..."
}
```

{% endtab %}

{% tab title="429" %}
Rate limit exceeded. See [Rate limits](https://docs.shadowcipher.in/reference/rate-limits.md).
{% endtab %}
{% endtabs %}

## After signing

When the signer finishes or cancels, they are redirected to your `return_url`:

```
https://partner.example.com/signing/callback?txn_no=3f2c...&reference_no=INV-2026-0042&status=...
```

Then call [Fetch a document](https://docs.shadowcipher.in/endpoints/fetch-document.md) to get the signed PDF. See [Signing flow and statuses](https://docs.shadowcipher.in/reference/signing-flow.md) for what each status means.

{% hint style="info" %}
Don't rely only on the redirect. Confirm the result by calling `fetchDoc` and checking that `status` is `SIGNED`.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.shadowcipher.in/endpoints/initiate-transaction.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
