---
title: "Create merchant report"
method: POST
path: "/merchant-reports"
tags: ["Merchant Reports"]
---

# Create merchant report

`POST /merchant-reports`

## Request

- Base URL: `https://api.natural.com`
- URL: `https://api.natural.com/merchant-reports`
- Auth: HTTP bearer

Report a merchant checkout you couldn't pay with a browser token. Natural uses the details to add support for the merchant or its processor.

## Headers

- `X-Instance-ID` string, nullable

## Request body

- object
  - `data` object, required
    - `attributes` object, required
      - `merchantUrl` string, uri, required: The checkout page you were on. Strip query strings that carry personal data or tokens.
      - `outcome` 'host_not_allowed' | 'proxy_error' | 'card_refused' | 'three_ds_required' | 'bot_wall' | 'other', required: What stopped the payment. host_not_allowed: the card request went to a host you couldn't put in allowedHosts. proxy_error: the proxy answered an error (put its code in proxyErrorCode). card_refused: the merchant or processor refused the card. three_ds_required: a 3DS challenge you couldn't complete. bot_wall: a CAPTCHA or bot check kept you from the card form. other: anything else; say what in notes.
      - `cardSessionId` string: The card session the attempt used, if any.
      - `proxyErrorCode` string: The proxy's error code when outcome is proxy_error (card_proxy_adyen_checkout_unknown, ...).
      - `checkout` object: Details of the checkout, for adding support later. Fill in what you saw; never card data.
        - `cardFieldOrigin` string: Where the card number field comes from: the merchant page itself, or the iframe origin (https://checkoutshopper-live.adyen.com, https://flex.cybersource.com, ...).
        - `processorSdkUrl` string: URL of the payment script the page loads (the processor's SDK or the merchant's own encryption bundle).
        - `processorSdkVersion` string: Its version, when the URL or script says.
        - `submitUrl` string: The request that carries the card or its token out of the browser (method and URL).
        - `submitContentType` string: Its Content-Type.
        - `cardFieldNames` string[]: Field names in that request that carry the card or its ciphertext (encryptedCardNumber, token, ...).
        - `errorText` string: The error the page or the proxy showed, verbatim.
      - `notes` string: What you tried and what happened, in your own words.
      - `customerPartyId` string: Customer party you were acting for (pty_*). Omit when acting as your own party.

## Response `201`

Successful Response

- object
  - `data` object, required
    - `reportId` string, required
    - `merchantHost` string, required
    - `outcome` 'host_not_allowed' | 'proxy_error' | 'card_refused' | 'three_ds_required' | 'bot_wall' | 'other', required: What stopped the payment. host_not_allowed: the card request went to a host you couldn't put in allowedHosts. proxy_error: the proxy answered an error (put its code in proxyErrorCode). card_refused: the merchant or processor refused the card. three_ds_required: a 3DS challenge you couldn't complete. bot_wall: a CAPTCHA or bot check kept you from the card form. other: anything else; say what in notes.
    - `createdAt` string, required

## Other responses

- `400`: Validation Error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409`: Conflict
- `422`: Validation Error. The response contains one error object for each invalid request value.
- `428`: Precondition Required
- `429`: Too Many Requests
- `500`: Internal Server Error
- `501`: Not Implemented
- `502`: Bad Gateway
- `503`: Service Unavailable

## Changes

- **2026-10-19** `5586b9ef00e1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/natural/apis/natural-api/changes/merchant-reports/post.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) - [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) - [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/59c1208fa5dc?raw)