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

# Worked scenarios

> Self-contained cURL scenarios for the common payment flows and error cases.

<Note>
  These scenarios run against the sandbox (`https://apistagepc.grogov.us`). Replace `pc_<your-sandbox-key>` and `<your-portal-id>` with your sandbox credentials. The card numbers are test fixtures listed in [Test data](/guides/test-data). Your portal must support these simulated scenarios. See [Sandbox access](/guides/sandbox-keys-and-portals).
</Note>

Each snippet authenticates with `Authorization: ApiKey pc_…`. You do not need to obtain an access token. Replace `$(uuidgen)` with any unique string if your shell does not have `uuidgen`. For independent tests, use a fresh payment-level `referenceId` as described in [Test data](/guides/test-data#common-request-data) to avoid restrictions caused by earlier attempts.

## 1. Successful sale

Create a payment with the Visa test card and the sandbox `portalId` provided by GroGov. Returns `status: "succeeded"` immediately.

```bash cURL theme={null}
curl -s -X POST https://apistagepc.grogov.us/api/partner/v1/payments \
  -H "Authorization: ApiKey pc_<your-sandbox-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "portalId": "<your-portal-id>",
    "amountCents": 5000,
    "currency": "USD",
    "paymentMethod": {
      "type": "card",
      "cardNumber": "4111111111111111",
      "expirationDate": "12/30",
      "cvv": "123"
    },
    "payer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com"
    },
    "lineItems": [
      {
        "amountCents": 5000,
        "referenceId": "CASE-2024-001",
        "description": "Court filing fee"
      }
    ]
  }'
```

## 2. Refund

Refund the payment from scenario 1 in full, including the service fee. Replace `$PAYMENT_ID` with its `id`. Returns `reversalType` (`"void"` while the batch is open, `"refund"` after it settles) and `remainingRefundableAmountCents: 0`.

```bash cURL theme={null}
curl -s -X POST https://apistagepc.grogov.us/api/partner/v1/payments/$PAYMENT_ID/refund \
  -H "Authorization: ApiKey pc_<your-sandbox-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "feeType": "include_fee", "reason": "Case dismissed" }'
```

Authorize-then-capture is not supported: `capture: "auth"` returns `501 CAPTURE_NOT_SUPPORTED`.

## 3. Declined charge

Use the general-decline test card `4111511111111112`. The request returns `402` with code `PAYMENT_DECLINED`. When the attempt was recorded, `details.id` holds the failed payment's ID; `GET /payments/{id}` returns it with status `failed`.

```bash cURL theme={null}
curl -s -X POST https://apistagepc.grogov.us/api/partner/v1/payments \
  -H "Authorization: ApiKey pc_<your-sandbox-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "portalId": "<your-portal-id>",
    "amountCents": 5000,
    "currency": "USD",
    "paymentMethod": {
      "type": "card",
      "cardNumber": "4111511111111112",
      "expirationDate": "12/30",
      "cvv": "123"
    },
    "payer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com"
    },
    "lineItems": [
      {
        "amountCents": 5000,
        "referenceId": "CASE-2024-001",
        "description": "Court filing fee"
      }
    ]
  }'
```

## 4. Unknown charge outcome

Use the test card `4200400000000077` to simulate an unreadable payment gateway response. The request returns `504` with code `PAYMENT_TIMEOUT`. When you receive this error the outcome is unknown. List recent payments (`GET /api/partner/v1/payments` with `portalId` and a `from`/`to` window) to check before retrying. See [Errors](/guides/errors) for retry guidance.

```bash cURL theme={null}
curl -s -X POST https://apistagepc.grogov.us/api/partner/v1/payments \
  -H "Authorization: ApiKey pc_<your-sandbox-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "portalId": "<your-portal-id>",
    "amountCents": 5000,
    "currency": "USD",
    "paymentMethod": {
      "type": "card",
      "cardNumber": "4200400000000077",
      "expirationDate": "12/30",
      "cvv": "123"
    },
    "payer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com"
    },
    "lineItems": [
      {
        "amountCents": 5000,
        "referenceId": "CASE-2024-001",
        "description": "Court filing fee"
      }
    ]
  }'
```

## 5. Portal without gateway

Charging a portal with no payment gateway configured returns `503` with code `GATEWAY_NOT_CONFIGURED`. Contact GroGov support to request a sandbox portal configured for this scenario.

```bash cURL theme={null}
curl -s -X POST https://apistagepc.grogov.us/api/partner/v1/payments \
  -H "Authorization: ApiKey pc_<your-sandbox-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "portalId": "<portal-without-gateway>",
    "amountCents": 5000,
    "currency": "USD",
    "paymentMethod": {
      "type": "card",
      "cardNumber": "4111111111111111",
      "expirationDate": "12/30",
      "cvv": "123"
    },
    "payer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com"
    },
    "lineItems": [
      {
        "amountCents": 5000,
        "referenceId": "CASE-2024-001",
        "description": "Court filing fee"
      }
    ]
  }'
```

## 6. Unauthorized portal

Use a `portalId` your API account cannot access. This example uses a placeholder UUID and returns `403` with code `PORTAL_ACCESS_DENIED`; unknown portals return the same code, so the response does not reveal whether a portal exists.

```bash cURL theme={null}
curl -s -X POST https://apistagepc.grogov.us/api/partner/v1/payments \
  -H "Authorization: ApiKey pc_<your-sandbox-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "portalId": "00000000-0000-4000-a000-000000000000",
    "amountCents": 5000,
    "currency": "USD",
    "paymentMethod": {
      "type": "card",
      "cardNumber": "4111111111111111",
      "expirationDate": "12/30",
      "cvv": "123"
    },
    "payer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com"
    },
    "lineItems": [
      {
        "amountCents": 5000,
        "referenceId": "CASE-2024-001",
        "description": "Court filing fee"
      }
    ]
  }'
```

## 7. Idempotent replay

Send the same request body and `Idempotency-Key` twice using your sandbox `portalId`. The second response is identical to the first and carries the `Idempotent-Replayed: true` response header. Replace `my-idempotency-key-001` with any fixed string; the key must be the same in both calls.

```bash cURL theme={null}
# First call. Process the payment.
curl -s -X POST https://apistagepc.grogov.us/api/partner/v1/payments \
  -H "Authorization: ApiKey pc_<your-sandbox-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-idempotency-key-001" \
  -d '{
    "portalId": "<your-portal-id>",
    "amountCents": 5000,
    "currency": "USD",
    "paymentMethod": {
      "type": "card",
      "cardNumber": "4111111111111111",
      "expirationDate": "12/30",
      "cvv": "123"
    },
    "payer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com"
    },
    "lineItems": [
      {
        "amountCents": 5000,
        "referenceId": "CASE-2024-001",
        "description": "Court filing fee"
      }
    ]
  }'

# Second call. Reuse the key and body to receive the original response with Idempotent-Replayed: true.
curl -si -X POST https://apistagepc.grogov.us/api/partner/v1/payments \
  -H "Authorization: ApiKey pc_<your-sandbox-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-idempotency-key-001" \
  -d '{
    "portalId": "<your-portal-id>",
    "amountCents": 5000,
    "currency": "USD",
    "paymentMethod": {
      "type": "card",
      "cardNumber": "4111111111111111",
      "expirationDate": "12/30",
      "cvv": "123"
    },
    "payer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com"
    },
    "lineItems": [
      {
        "amountCents": 5000,
        "referenceId": "CASE-2024-001",
        "description": "Court filing fee"
      }
    ]
  }'
```

## 8. Partial refund

Refund part of a payment's principal by its `id` (line items cannot be refunded individually). Replace `$PAYMENT_ID` with the payment's `id`. The service fee is not refunded on a partial refund.

```bash cURL theme={null}
curl -s -X POST https://apistagepc.grogov.us/api/partner/v1/payments/$PAYMENT_ID/refund \
  -H "Authorization: ApiKey pc_<your-sandbox-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amountCents": 2500
  }'
```

<Card title="API Reference" icon="code">
  Switch to the **API Reference** tab above to browse every endpoint, inspect request and response schemas, and try requests directly in the interactive playground.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.