Worked scenarios

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. Your portal must support these simulated scenarios. See Sandbox access.

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

cURL

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.

cURL

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.

cURL

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 for retry guidance.

cURL

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.

cURL

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.

cURL

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.

cURL

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

cURL

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
  }'

API Reference

Switch to the API Reference tab above to browse every endpoint, inspect request and response schemas, and try requests directly in the interactive playground.

Get started

Core concepts

Hosted checkout

Testing

1. Successful sale

2. Refund

3. Declined charge

4. Unknown charge outcome

5. Portal without gateway

6. Unauthorized portal

7. Idempotent replay

8. Partial refund

API Reference

​1. Successful sale

​2. Refund

​3. Declined charge

​4. Unknown charge outcome

​5. Portal without gateway

​6. Unauthorized portal

​7. Idempotent replay

​8. Partial refund

API Reference

1. Successful sale

2. Refund

3. Declined charge

4. Unknown charge outcome

5. Portal without gateway

6. Unauthorized portal

7. Idempotent replay

8. Partial refund