# List contract files

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

- Sandbox: `GET https://sandbox.payme.io/api/payment-contracts/{payment_contract_guid}/invoices`
- Production: `GET https://live.payme.io/api/payment-contracts/{payment_contract_guid}/invoices`

## Credentials

- Header `PayMe-Merchant-Key` (API key)

Lists the files (invoices, receipts and other documents) attached to a contract. Both sellers on the contract see every file, whoever uploaded it. Authenticate with your MPL in the `PayMe-Merchant-Key` header; only the two sellers on the contract can call it (error `385` otherwise).

To list one type of file, add `type`, e.g. `?type=Invoice%20Receipt`. To get one file, call `GET /payment-contracts/{payment_contract_guid}/invoices/{invoice_guid}`: it returns that file's `name`, `mime_type`, `type`, `url` and `id` at the top level (not in an array), or error `757` if the contract has no such file.

### Errors

HTTP status | Error code | Message | When
---|---|---|---
`400` | `251` | Seller was not found | The `PayMe-Merchant-Key` header is missing. `status_additional_info` is the header name. 
`400` | `385` | Action not allowed - please contact Customer Support | This seller is neither side of the contract. `status_additional_info` is the seller key. 
`400` | `757` | Invoice not found | You asked for one file and the contract has no file with that ID. 
`422` | `20` | (a validation message) | `type` is not a known file type. `status_additional_info` lists what failed. 
`500` | `251` | Seller was not found | The seller key is unknown. 
`500` | `163` | Account settings problem - please contact Customer Support | The seller is not active. 
`500` | `380` | Payment contract not found | No contract has this GUID. `status_additional_info` is the GUID.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | Your `seller_payme_id` (MPL). You must be one of the two sellers on the contract. |
| `payment_contract_guid` | path | string | yes | The contract's `guid`, as returned when the contract was created, e.g. `CONT1700-000000AA-EXAMPLE1-CONT0001`. It already starts with `CONT`; don't add another prefix. |
| `type` | query | string | no | Only files of this type: `Invoice`, `Invoice Receipt`, `Receipt`, `Invoice Refund`, `Receipt Donation`, `Order`, `Delivery`, `Return`, `Offer` or `PurchaseOrder`. URL-encode the space (`Invoice%20Receipt`). |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>'
```

### Node.js

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

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
)

print(response.text)
```

### PHP

```php
<?php

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

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

echo $response;
```

## Responses

### 200 — The contract's files. An empty array if none is attached. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `session` | string | PayMe session ID. Quote it when you contact PayMe support. |
| `invoices` | array | The files attached to the contract. |
| `invoices[].name` | string | File name, as uploaded. |
| `invoices[].mime_type` | string | The file's MIME type, e.g. `application/pdf`. |
| `invoices[].type` | string | The file type. |
| `invoices[].url` | string | Link to the file. |
| `invoices[].id` | string | The file ID (`INV…`). Use it as `invoice_guid` to replace or delete the file. |

```json
{
  "status_code": 0,
  "session": "FhT3aXe7",
  "invoices": [
    {
      "name": "invoice-1001.pdf",
      "mime_type": "application/pdf",
      "type": "Invoice Receipt",
      "url": "https://reparser2.paymeservice.com/external/files/3e8ce1bb-c6ff-4e05-94df-f24f30928180",
      "id": "INV17000-000000AA-EXAMPLE1-FILE0001"
    }
  ]
}
```

### 400 — Bad Request (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "PayMe-Merchant-Key",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```

### 422 — Unprocessable Entity (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "The selected type is invalid.",
  "status_additional_info": "The selected type is invalid.",
  "status_error_code": 20,
  "session": "FhT3aXe7"
}
```

### 500 — Internal Server Error (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```