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

# Test data

> Sandbox card numbers, card tokens, and request inputs for payment scenarios.

Use these test fixtures to simulate successful payments, declines, and errors through the Partner Payments API. The tables list the input to send and the response to expect.

<Note>
  These values require a sandbox portal configured for the simulated payment scenarios. Request an API key and a suitable `portalId` through [Sandbox access](/guides/sandbox-keys-and-portals). Use the sandbox at `https://apistagepc.grogov.us`. Do not use these fixtures for live payments or send real card details to the sandbox.
</Note>

## Common request data

Start with these values for `POST /api/partner/v1/payments`. Change the input identified in a scenario table and keep the rest of the request valid.

| Field | Test value | Purpose |
| - | - | - |
| `portalId` | Your assigned sandbox portal ID | Selects the payment configuration your API account can access |
| `amountCents` | `5000` | Charges a principal of \$50.00 USD, plus the portal's service fee |
| `currency` | `"USD"` | The supported currency |
| `referenceId` | A unique value such as `"TEST-<unique-value>"` | Identifies this test payment and avoids reusing a case reference from an earlier test |
| `lineItems` | One item with `amountCents: 5000` and its own `referenceId` | Line-item amounts must add up to the payment amount |
| `paymentMethod.expirationDate` | `"12/30"`, or another future date in `MM/YY` format | Keeps the request valid so it reaches the selected card scenario |
| `paymentMethod.cvv` | `"123"` | A valid three-digit test security code |
| `payer` | `{ "firstName": "Jane", "lastName": "Doe", "email": "jane.doe@example.com" }` | Fictional payer information |
| `Idempotency-Key` header | A new UUID for each independent test | Prevents an earlier response from being replayed for a new scenario |

For an idempotency test, reuse the key as directed in [Request and retry scenarios](#request-and-retry-scenarios). Changing only the card number while reusing a key returns `409 IDEMPOTENCY_MISMATCH` instead of the card's result.

Repeated declines can trigger `409 DECLINE_BLOCKED` or `429 VELOCITY_LIMIT` before the card scenario runs. Use a fresh payment-level `referenceId` for independent tests.

## Test card numbers

Set `paymentMethod.type` to `"card"` and use one of these values for `paymentMethod.cardNumber`. All numbers below are sandbox fixtures. Unless stated otherwise, use the common request data above.

| Card number | Simulated scenario | Expected API response |
| - | - | - |
| `4111111111111111` | Approved payment | `200`, `data.status: "succeeded"` |
| `4000000000000000006` | Approved payment with a 19-digit card number | `200`, `data.status: "succeeded"` |
| `4111511111111112` | General card decline | `402 PAYMENT_DECLINED` |
| `4000400000000202` | Insufficient funds | `402 PAYMENT_DECLINED` |
| `4005100000000203` | Card limit exceeded | `402 PAYMENT_DECLINED` |
| `4005400000000223` | Card issuer reports an expired card | `402 PAYMENT_DECLINED` |
| `4000500000000225` | Card security code mismatch | `402 PAYMENT_DECLINED` |
| `4000400000000301` | Billing postal code mismatch | `402 PAYMENT_DECLINED` |
| `4111011111111113` | Payment gateway server error | `502 PAYMENT_GATEWAY_ERROR` |
| `4111911111111114` | Delayed payment gateway failure | `502 PAYMENT_GATEWAY_ERROR` |
| `4200400000000077` | Unreadable payment gateway response; charge outcome unknown | `504 PAYMENT_TIMEOUT` |
| `4111111111111202` | Approved payment whose subsequent void is rejected | Creation returns `200`, `data.status: "succeeded"`. Voiding that payment returns `422 VOID_FAILED` with `details.suggestedAction: "refund"` |

The card number selects the simulated decline reason. Keep a future expiration date and `cvv: "123"`, including for the expired-card and security-code-mismatch scenarios. An expired date or malformed security code in the request causes `400 VALIDATION_ERROR` before the card scenario runs.

For errors, read the HTTP status and `details.code`. Several decline scenarios share `PAYMENT_DECLINED`; do not use the human-readable `message` as a stable identifier.

<Warning>
  `504 PAYMENT_TIMEOUT` means the charge outcome is unknown. Use `4200400000000077` to test this response. Check the payment before attempting another charge. If you sent an `Idempotency-Key`, retrying with that key returns `409 IDEMPOTENCY_RECONCILIATION_REQUIRED`. See [Errors](/guides/errors#504-payment_timeout) and [Idempotency](/guides/idempotency).
</Warning>

### Card payment example

Replace the credential and portal placeholders. Generate a new payment reference and idempotency key for each independent test. To test another outcome, change `cardNumber` using the table above.

```bash cURL theme={null}
TEST_REFERENCE="TEST-$(uuidgen)"
IDEMPOTENCY_KEY="$(uuidgen)"

curl -i -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: $IDEMPOTENCY_KEY" \
  -d "{
    \"portalId\": \"<your-portal-id>\",
    \"referenceId\": \"$TEST_REFERENCE\",
    \"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\": \"$TEST_REFERENCE-ITEM-1\", \"description\": \"Test payment\" }
    ]
  }"
```

## Test card tokens

Replace the entire `paymentMethod` object with `{ "type": "card_token", "token": "<test-card-token>" }`. Use one of the literal tokens below. You do not need to create these sandbox tokens or provide a card number, expiration date, or security code.

| `paymentMethod.token` | Simulated scenario | Expected API response |
| - | - | - |
| `pc_test_card_approved` | Approved payment | `200`, `data.status: "succeeded"` |
| `pc_test_card_error` | Payment gateway server error | `502 PAYMENT_GATEWAY_ERROR` |
| `pc_test_card_malformed` | Incomplete payment gateway response; charge outcome unknown | `504 PAYMENT_TIMEOUT` |

For example, use this object with the other fields from the card payment example:

```json theme={null}
{
  "type": "card_token",
  "token": "pc_test_card_approved"
}
```

These are reusable sandbox fixtures, not production payment credentials. A card token represents card details and is separate from the access token used to authenticate API requests. Send your API key or access token in the `Authorization` header as usual.

## Request and retry scenarios

Use the approved card and common request data unless a row specifies another input. Change one condition at a time.

| Scenario | Input or action | Expected API response |
| - | - | - |
| Missing authentication | Omit the `Authorization` header | `401 Unauthorized` |
| Amount mismatch | Send `amountCents: 5000` with one line item of `4000` cents | `400 VALIDATION_ERROR` |
| Invalid expiration date | Send `paymentMethod.expirationDate: "13/99"` | `400 VALIDATION_ERROR` |
| Invalid security code | Send `paymentMethod.cvv: "12a"` | `400 VALIDATION_ERROR` |
| Invalid payer email | Send `payer.email: "not-an-email"` | `400 VALIDATION_ERROR` |
| Unknown portal | Send `portalId: "00000000-0000-4000-a000-000000000000"`, the unknown-portal test placeholder | `403 PORTAL_ACCESS_DENIED` |
| Authorize without charging | Send `capture: "auth"` | `501 CAPTURE_NOT_SUPPORTED` |
| Idempotent replay | Create a successful payment, then repeat the same body with the same `Idempotency-Key` | Original response, with `Idempotent-Replayed: true`; no additional charge |
| Idempotency conflict | Create a successful payment, then reuse its key with a different `referenceId` | `409 IDEMPOTENCY_MISMATCH` |
| Unknown-outcome retry | Use `4200400000000077` with an idempotency key, then repeat the same request and key | First response: `504 PAYMENT_TIMEOUT`. Retry: `409 IDEMPOTENCY_RECONCILIATION_REQUIRED` |

## Refund and void scenarios

Create a separate successful payment for each scenario below. Use its returned `id` in the request path. Amounts below assume the original principal was `5000` cents.

| Scenario | Input or action | Expected API response |
| - | - | - |
| Full reversal, including service fee | Call `POST /payments/{id}/refund` with `{ "feeType": "include_fee" }` | `200`, `data.remainingRefundableAmountCents: 0`. `data.reversalType` identifies whether the operation used a void or refund |
| Partial refund | Call `POST /payments/{id}/refund` with `{ "amountCents": 2500 }` | `200`, `data.amountCents: 2500`. The service fee is not refunded |
| Refund exceeds remaining principal | Call `POST /payments/{id}/refund` with `{ "amountCents": 5001 }` before any refund | `422 INVALID_STATE` |
| Successful void | Call `POST /payments/{id}/void` with `{}` before settlement | `200`. Retrieving the payment returns `data.status: "voided"` |
| Void rejected | Create with `4111111111111202`, then call `POST /payments/{id}/void` with `{}` | `422 VOID_FAILED`, `details.suggestedAction: "refund"` |
| Void an already voided payment | Void a payment successfully, then send another void with a new idempotency key | `422 INVALID_STATE` |

The paths in this table use the `/api/partner/v1` prefix. Use a new idempotency key for each distinct operation. Reuse the key only when retrying that operation.

## Other errors

| API response | Root cause |
| - | - |
| `503 GATEWAY_NOT_CONFIGURED` | The selected portal has no payment gateway configured. |
| `403 PAYMENT_BLOCKED` | An active payment block prevents payment for the case identified by the payment-level `referenceId`. |
| `409 PAYMENT_HELD` | A temporary hold prevents payment for the case identified by the payment-level `referenceId`. |
| `429 VELOCITY_LIMIT` | Recent payment attempts for the case or card have reached the configured limit. |
| `502 PARTIAL_REFUND_PENDING` | The principal reversal succeeded, but the separate service fee reversal failed. |

See [Errors](/guides/errors) for guidance on handling these responses.

Storing cards and charging stored cards are not supported. `POST /vault` and `paymentMethod.type: "vault"` return `501 VAULT_NOT_SUPPORTED`.

<Card title="Worked scenarios" icon="list-checks" href="/guides/test-scenarios">
  Run complete cURL examples for payments, refunds, and error responses.
</Card>


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