> ## 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.

# Quickstart

> Create your first sandbox payment.

<Warning>
  **Breaking change:** `transactionId` on payment, refund and void responses and on webhook `data` is now `id`. `gateway.transactionId` still holds the payment processor's transaction ID.
</Warning>

<Steps>
  <Step title="Get your credentials">
    Email `support@grogov.us` to start a partner agreement and request API access. GroGov creates your API account and provides an API key, prefixed with `pc_`, and one or more `portalId` values.

    A **portal** is an agency's payment configuration in GroGov. It determines the payment gateway and service fee configuration used for a payment. GroGov provides the `portalId` values your API account can access.

    Ask for sandbox credentials at the same time. See [Sandbox access](/guides/sandbox-keys-and-portals). The examples below use `pc_<your-sandbox-key>` and `<your-portal-id>` as placeholders for them.
  </Step>

  <Step title="Exchange your key for an access token (optional)">
    Send your API key in the `Authorization` header to get an access token, a JWT valid for one hour (`expiresIn: 3600`).

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://apistagepc.grogov.us/api/partner/v1/auth/token \
        -H "Authorization: ApiKey pc_<your-sandbox-key>"
      ```

      ```ts Node.js theme={null}
      const res = await fetch(
        "https://apistagepc.grogov.us/api/partner/v1/auth/token",
        {
          method: "POST",
          headers: { Authorization: "ApiKey pc_<your-sandbox-key>" },
        },
      );
      const { data } = await res.json();
      const jwt = data.accessToken; // valid one hour
      ```
    </CodeGroup>

    Response:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "accessToken": "<jwt>",
        "tokenType": "Bearer",
        "expiresIn": 3600,
        "issuedAt": "2026-06-29T12:00:00.000Z"
      }
    }
    ```

    You can also skip this step and send `Authorization: ApiKey pc_…` on every call. See [Authentication](/guides/authentication) for credential lifetime and renewal.
  </Step>

  <Step title="Create a payment">
    Create a test payment using the `portalId` provided with your sandbox credentials. Payments charge the card immediately. The `amountCents` must equal the sum of the line-item amounts (here 7500 + 2500 = 10000 cents = \$100.00). Generate an `Idempotency-Key` for each new charge and reuse it when retrying that charge.

    The card here is `4111111111111111`, the standard Visa test number; your sandbox credentials come with test cards for other outcomes. For supported payment methods, see [Test data](/guides/test-data).

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

      ```ts Node.js theme={null}
      const res = await fetch(
        "https://apistagepc.grogov.us/api/partner/v1/payments",
        {
          method: "POST",
          headers: {
            Authorization: `Bearer ${jwt}`,
            "Content-Type": "application/json",
            "Idempotency-Key": crypto.randomUUID(),
          },
          body: JSON.stringify({
            portalId: "<your-portal-id>",
            amountCents: 10000, // $100.00
            currency: "USD",
            referenceId: "CASE-2024-001",
            paymentMethod: { type: "card", cardNumber: "4111111111111111", expirationDate: "12/30", cvv: "123" },
            payer: { firstName: "Jane", lastName: "Doe", email: "jane.doe@example.com" },
            lineItems: [
              { amountCents: 7500, referenceId: "CITATION-001", description: "Court filing fee" },
              { amountCents: 2500, referenceId: "CITATION-002", description: "Processing fee" },
            ],
          }),
        },
      );
      const { data } = await res.json();
      const paymentId = data.id;
      ```
    </CodeGroup>

    A successful payment returns `status: "succeeded"`. Key fields in the response:

    | Field | Description |
    | - | - |
    | `data.status` | `"succeeded"` indicates that the card was charged |
    | `data.id` | Payment ID. Save it to retrieve, refund, or void the payment |
    | `data.serviceFeeCents` | Fee added on top of `amountCents` (cents) |
    | `data.totalChargedCents` | `amountCents + serviceFeeCents` actually charged to the card (cents) |
    | `data.confirmationNumber` | Human-readable confirmation number for the payer |

    See the API Reference for the full response schema.
  </Step>

  <Step title="Retrieve the payment">
    Retrieve the payment by its `id`.

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://apistagepc.grogov.us/api/partner/v1/payments/$PAYMENT_ID \
        -H "Authorization: Bearer $JWT"
      ```

      ```ts Node.js theme={null}
      const res = await fetch(
        `https://apistagepc.grogov.us/api/partner/v1/payments/${paymentId}`,
        { headers: { Authorization: `Bearer ${jwt}` } },
      );
      const { data } = await res.json();
      ```
    </CodeGroup>
  </Step>
</Steps>

<Card title="Next steps" icon="arrow-right">
  * Review statuses, voids, and refunds in [Payment lifecycle](/guides/payment-lifecycle).
  * Follow the retry rules in [Idempotency](/guides/idempotency).
  * Handle failures using the [error reference](/guides/errors).
</Card>


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