# Get a document

Building with an AI agent? Start at https://docs.payme.io/agents.md

- Sandbox: `GET https://sandbox.payme.io/api/documents/{document_id}`
- Production: `GET https://live.payme.io/api/documents/{document_id}`

## Credentials

- Header `PayMe-Merchant-Key` (API key)
- Header `PayMe-Partner-Key` (optional): Partners only: your partner key. The seller must belong to you (error `20`).

> ⚠️ **This API is deprecated** and is no longer recommended for use. For questions, contact partners@payme.io. 

## Overview

Returns a document created with [Create a document](/payments/invoices/post-create-invoice). `document_id` is the `doc_id` that call returned. The seller's invoicing service must be active; otherwise every documents call returns error `703` (HTTP 403).

Documents are created asynchronously. While the document job is still running (its status is `waiting`, `active`, `delayed`, `paused` or `stuck`), this call returns error `1005` with HTTP 400 and the status in `status_additional_info`, for example `status:waiting`. Wait a few seconds and call it again.

If the job failed, the call returns error `1003`. If the invoicing service reports an unknown job status, the response is HTTP 200 with `status_code` `0` and no document fields: call again later.

Example: `GET https://sandbox.payme.io/api/documents/fa397fce-aee6-4c6d-ae9c-273ae1e3a317` with the header `PayMe-Merchant-Key: MPLDEMO-MPLDEMO-MPLDEMO-1234567`.

### Errors

| HTTP | Code | When |
|---|---|---|
| `400` | `1005` | The document is still being created. `status_additional_info` is its status, such as `status:waiting`.  |
| `500` | `1003` | The document failed to generate.  |
| `400` | `1` | A partner key was sent, but no seller. `status_additional_info` is `seller_payme_id`.  |
| `400` | `20` | The seller doesn't belong to this partner. `status_additional_info` is `Merchant-Seller inconsistency`.  |
| `403` | `703` | The invoicing service isn't active for this seller.  |
| `500` | `1` | No credential was sent at all. `status_additional_info` is `payme_client_key`.  |
| `500` | `251` | The seller key is unknown.  |
| `500` | `163` | The seller isn't active.  |
| `500` | `200` | The partner key is unknown.  |
| `500` | `201` | The partner isn't active.  |
| `500` | `1001` | The invoicing service returned an error. `status_additional_info` carries its code and details. |
| `503` | `1001` | The invoicing service didn't answer in time. |

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `document_id` | path | string | yes | The document's `doc_id`, returned by [Create a document](/payments/invoices/post-create-invoice). |
| `PayMe-Merchant-Key` | header | string | yes | The seller's MPL. On a GET request this header is the only way to name the seller. |
| `PayMe-Partner-Key` | header | string | no | Partners only: your partner key. The seller must belong to you (error `20`). |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/documents/<document_id>' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  -H 'PayMe-Partner-Key: <PayMe-Partner-Key>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/documents/<document_id>", {
  method: "GET",
  headers: {
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    "PayMe-Partner-Key": "<PayMe-Partner-Key>",
  },
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/documents/<document_id>",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
        "PayMe-Partner-Key": "<PayMe-Partner-Key>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/documents/<document_id>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
        'PayMe-Partner-Key: <PayMe-Partner-Key>',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

## Responses

### 200 — The document is ready. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `doc_id` | string | The document's job ID. Use it with [Get a document](/payments/invoices/show-generated-document-by-id). |
| `doc_num` | string | The document number, once the invoicing service has assigned one. |
| `doc_status` | string | Status of the document job, when the invoicing service returns one. |
| `doc_url` | string | Link to the document. |
| `doc_type` | integer | Document type. See [Document types](/payments/codes-statuses/document-types). |
| `buyer_name` | string | Buyer name on the document. |
| `buyer_address` | string | Buyer address on the document, if sent. |
| `doc_date` | string | Document date. |
| `due_date` | string | Payment due date, if sent. |
| `pay_date` | string | Payment date, if sent. |
| `currency` | string | ISO 4217 currency code of the document. |
| `language` | string | Document language. |
| `doc_title` | string | Title printed at the top of the document. |
| `doc_comments` | string | Comments printed on the document. |
| `exchange_rate` | number | Exchange rate used on the document. |
| `vat_rate` | number | VAT rate applied to the document. |
| `discount` | number | Discount applied to the document. |
| `total_excluding_vat` | number | Total before VAT. |
| `total_sum_after_discount` | number | Total after the discount. |
| `total_sum_including_vat` | number | Total including VAT. |
| `total_vat` | number | Total VAT. |
| `total_paid` | number | Total paid on this document. |
| `total_paid_including_vat` | number | Total paid, including VAT. |
| `items` | array | Document lines. |
| `items[].description` | string | Line description. |
| `items[].quantity` | integer | Quantity. |
| `items[].unit_price` | number | Unit price before VAT. |
| `items[].unit_price_with_vat` | number | Unit price including VAT. |
| `items[].vat_exempt` | boolean | `true` if the line is exempt from VAT. |
| `items[].currency` | string | ISO 4217 currency code of the line. |
| `items[].exchange_rate` | number | Exchange rate of the line's currency. |
| `cash` | object | Cash payment recorded on the document. |
| `cash.sum` | number | Amount paid in cash. |
| `cheques` | array | Cheques recorded on the document. |
| `cheques[].sum` | number | Cheque amount. |
| `cheques[].date` | string | Cheque date. |
| `cheques[].bank` | number | Bank code. |
| `cheques[].branch` | number | Branch number. |
| `cheques[].account` | string | Account number. |
| `cheques[].number` | string | Cheque number. |
| `bank_transfer` | object | Bank transfer recorded on the document. |
| `bank_transfer.sum` | number | Amount transferred. |
| `bank_transfer.date` | string | Transfer date. |
| `bank_transfer.account` | string | Account number. |
| `paypal` | object | PayPal payment recorded on the document. |
| `paypal.sum` | number | Amount paid with PayPal. |
| `paypal.date` | string | Payment date. |
| `paypal.transaction_id` | string | PayPal transaction ID. |
| `paypal.buyer_name` | string | Payer name. |
| `credit_card` | object | Card payment recorded on the document. It holds no card number or CVV. |
| `credit_card.sum` | number | Amount paid by card. |
| `credit_card.installments` | integer | Number of installments. |
| `credit_card.first_payment` | number | Amount of the first installment. |
| `credit_card.type` | string | Card brand. |
| `credit_card.expiry` | string | Card expiry, `MMYY`. |
| `credit_card.buyer_name` | string | Card holder's name. |
| `credit_card.buyer_social_id` | string | Card holder's national ID. |
| `credit_card.auth_number` | string | Authorization number of the card payment. |

```json
{
  "status_code": 0,
  "doc_type": 400,
  "buyer_name": "Israel Israeli",
  "doc_date": "2026-11-09",
  "currency": "ILS",
  "language": "he",
  "doc_title": "Receipt for order 1001",
  "total_paid": 140,
  "items": [
    {
      "description": "Monthly plan",
      "quantity": 1,
      "unit_price": 140,
      "vat_exempt": false,
      "currency": "ILS"
    }
  ],
  "cash": {
    "sum": 40
  },
  "credit_card": {
    "sum": 100,
    "installments": 1,
    "type": "Visa",
    "expiry": "1230",
    "buyer_name": "Israel Israeli",
    "auth_number": "0123456"
  },
  "doc_id": "fa397fce-aee6-4c6d-ae9c-273ae1e3a317",
  "doc_num": "10023",
  "doc_status": "completed",
  "doc_url": "https://invoice-staging.paymeservice.com/documents/fa397fce-aee6-4c6d-ae9c-273ae1e3a317"
}
```

### 400 — Bad request. See the error table. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | What went wrong, in the language you asked for (Hebrew by default). |
| `status_additional_info` | string | The field or value concerned. Can be `null`. |
| `status_error_code` | integer | PayMe error code. See the error table above and [Errors](/payments/getting-started/errors). |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "Document you're requested not ready yet",
  "status_additional_info": "status:waiting",
  "status_error_code": 1005,
  "session": "FhT3aXe7"
}
```

### 403 — The invoicing service isn't active for this seller (`703`). (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | What went wrong, in the language you asked for (Hebrew by default). |
| `status_additional_info` | string | The field or value concerned. Can be `null`. |
| `status_error_code` | integer | PayMe error code. See the error table above and [Errors](/payments/getting-started/errors). |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "Action is not permitted",
  "status_additional_info": "Invoicing Service was not properly activated. Operation not permitted",
  "status_error_code": 703,
  "session": "FhT3aXe7"
}
```

### 500 — Credentials or the invoicing service failed. See the error table. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | What went wrong, in the language you asked for (Hebrew by default). |
| `status_additional_info` | string | The field or value concerned. Can be `null`. |
| `status_error_code` | integer | PayMe error code. See the error table above and [Errors](/payments/getting-started/errors). |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "Document not found",
  "status_additional_info": null,
  "status_error_code": 1003,
  "session": "FhT3aXe7"
}
```