> ## Documentation Index
> Fetch the complete documentation index at: https://docs.accelebit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/payments — Look Up Payment by Reference

> Search for a payment using your merchant reference ID. Requires the merchantRef query parameter. Returns the same fields as the retrieve endpoint.

Use this endpoint to look up a payment using the merchant reference ID you assigned when creating it — for example, an order number. Unlike the [Retrieve a Payment](/api-reference/payments/retrieve) endpoint, which requires Accelebit's internal payment UUID, this endpoint lets you query by your own identifier. The `merchantRef` query parameter is required; omitting it returns a `400` error. Payments are scoped to your merchant account — you can only retrieve payments created with your API key.

<Warning>
  This endpoint requires the `merchantRef` query parameter. Requests without it will return a `400 INVALID_REQUEST` error.
</Warning>

## Query parameters

<ParamField query="merchantRef" type="string" required>
  Your merchant reference ID to search for. This is the value you passed as `merchantRef` when creating the payment.
</ParamField>

## Headers

<ParamField header="X-API-Key" type="string" required>
  Your secret API key. Starts with `smtgw_sk_`.
</ParamField>

## Response

This endpoint returns the matching payment with the same fields as [Retrieve a Payment](/api-reference/payments/retrieve).

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="id" type="string">
      UUID of the transaction.
    </ResponseField>

    <ResponseField name="merchantId" type="string">
      Your merchant account ID.
    </ResponseField>

    <ResponseField name="customerId" type="string">
      UUID of the Accelebit customer record associated with this payment.
    </ResponseField>

    <ResponseField name="providerId" type="string">
      The upstream provider that processed the payment. `null` if the payment has not yet been submitted to a provider.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current transaction status. One of: `created`, `captured`, `authorized`, `pending_3ds`, `pending_consent`, `failed`.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Payment amount as a decimal string. For example: `"55.00"`.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Three-letter ISO 4217 currency code.
    </ResponseField>

    <ResponseField name="paymentMethod" type="string">
      `"card"` or `"stored_card"`.
    </ResponseField>

    <ResponseField name="merchantRef" type="string">
      Your merchant reference, as provided when the payment was created.
    </ResponseField>

    <ResponseField name="errorCode" type="string">
      Error code if the payment failed. `null` on success.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Human-readable error message if the payment failed. `null` on success.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of when the payment was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp of the last status update.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.gateway.accelebit.com/v1/payments?merchantRef=order_98765" \
    -H "X-API-Key: smtgw_sk_test_your_secret_key"
  ```

  ```typescript Node.js theme={null}
  const response = await fetch(
    'https://api.gateway.accelebit.com/v1/payments?merchantRef=order_98765',
    {
      headers: {
        'X-API-Key': process.env.ACCELEBIT_SECRET_KEY!,
      },
    }
  );

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.gateway.accelebit.com/v1/payments',
      params={'merchantRef': 'order_98765'},
      headers={'X-API-Key': ACCELEBIT_SECRET_KEY},
  )

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "data": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "merchantId": "merchant_abc123",
      "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "providerId": "everest",
      "status": "captured",
      "amount": "55.00",
      "currency": "EUR",
      "paymentMethod": "card",
      "merchantRef": "order_98765",
      "errorCode": null,
      "errorMessage": null,
      "createdAt": "2026-04-09T12:01:00.000Z",
      "updatedAt": "2026-04-09T12:01:02.000Z"
    },
    "meta": {
      "timestamp": "2026-04-09T12:05:00.000Z"
    }
  }
  ```

  ```json 400 - Missing merchantRef theme={null}
  {
    "data": null,
    "error": {
      "status": 400,
      "name": "INVALID_REQUEST",
      "message": "Query parameter merchantRef is required"
    }
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "data": null,
    "error": {
      "status": 404,
      "name": "NOT_FOUND",
      "message": "Transaction order_98765 not found"
    }
  }
  ```
</ResponseExample>