Test data

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.

These values require a sandbox portal configured for the simulated payment scenarios. Request an API key and a suitable portalId through Sandbox access. Use the sandbox at https://apistagepc.grogov.us. Do not use these fixtures for live payments or send real card details to the sandbox.

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

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

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.

cURL

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:

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

Worked scenarios

Run complete cURL examples for payments, refunds, and error responses.

Get started

Core concepts

Hosted checkout

Testing

Common request data

Test card numbers

Card payment example

Test card tokens

Request and retry scenarios

Refund and void scenarios

Other errors

Worked scenarios

​Common request data

​Test card numbers

​Card payment example

​Test card tokens

​Request and retry scenarios

​Refund and void scenarios

​Other errors

Worked scenarios

Common request data

Test card numbers

Card payment example

Test card tokens

Request and retry scenarios

Refund and void scenarios

Other errors