Refunds

Refund requests identify a payment by its id. A payment’s line items describe what was paid for (each with its share of the service fee); they are not refunded individually.

Line-item refunds are not supported. Pass the payment’s id in the {id} path parameter; a line-item id returns 404 PAYMENT_NOT_FOUND.

Full and partial refunds

The principal is the payment amount excluding the service fee.

Request body	What is refunded
`{}` (no `amountCents`)	All of the remaining principal
`{ "amountCents": 2500 }`	2500 cents of principal
`{ "feeType": "include_fee" }` (no `amountCents`)	All remaining principal and the service fee

The service fee is refunded only on a full refund with feeType: "include_fee". Partial refunds return principal only.
If you refunded the principal without the fee, send another refund with feeType: "include_fee" and no amountCents to refund the fee.
Asking for more principal than remains returns 422 INVALID_STATE; message gives the remaining amount in cents.
reason is optional (up to 1000 characters).

`reversalType`

The response’s reversalType identifies whether the payment was voided or refunded:

"void" means the payment had not settled and was voided.
"refund" means the payment had settled and was refunded.

The API selects the operation based on settlement status.

Amounts after a refund

On the payment (GET /payments/{id}):

refundedAmountCents is the total refunded so far, including principal and service fee.
remainingRefundableAmountCents is the amount still refundable, including principal and service fee.
status is partially_refunded until the principal and service fee have both been fully refunded. It then becomes refunded.

Example: full refund including the fee

curl -X POST https://apistagepc.grogov.us/api/partner/v1/payments/a1b2c3d4-e5f6-7890-abcd-ef1234567890/refund \
  -H "Authorization: ApiKey pc_<your-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "feeType": "include_fee", "reason": "Case dismissed" }'

const res = await fetch(
  "https://apistagepc.grogov.us/api/partner/v1/payments/a1b2c3d4-e5f6-7890-abcd-ef1234567890/refund",
  {
    method: "POST",
    headers: {
      Authorization: "ApiKey pc_<your-key>",
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({ feeType: "include_fee", reason: "Case dismissed" }),
  }
);
const data = await res.json();

Response:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "target": "group",
    "reversalType": "refund",
    "amountCents": 10300,
    "currency": "USD",
    "reason": "Case dismissed",
    "status": "succeeded",
    "remainingRefundableAmountCents": 0,
    "gateway": { "transactionId": "4938271649" },
    "createdAt": "2024-03-01T12:00:00.000Z"
  }
}

target is always "group", indicating that the refund applies to the payment. Individual line items cannot be refunded separately. amountCents is the amount returned by this refund. In this example, it includes 10000 cents of principal and a 300-cent service fee.

Example: partial refund

cURL

curl -X POST https://apistagepc.grogov.us/api/partner/v1/payments/a1b2c3d4-e5f6-7890-abcd-ef1234567890/refund \
  -H "Authorization: ApiKey pc_<your-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amountCents": 2500, "reason": "Partial fine waiver" }'

When the fee refund fails

If the principal refund succeeds but the separate service-fee refund fails, you get 502 PARTIAL_REFUND_PENDING with details.remainingRefundableAmountCents. Retry the same refund to finish it. See Errors.

Line items

Each line item in the payment response carries its amountCents, its pro-rated share of the service fee (serviceFeeCents), and your referenceId, description and metadata. Use them for reconciliation and display.

Idempotency

Refunds support the Idempotency-Key header, so retries are safe. See Idempotency.

Get started

Core concepts

Hosted checkout

Testing

Full and partial refunds

`reversalType`

Amounts after a refund

Example: full refund including the fee

Example: partial refund

When the fee refund fails

Line items

Idempotency

​Full and partial refunds

​reversalType

​Amounts after a refund

​Example: full refund including the fee

​Example: partial refund

​When the fee refund fails

​Line items

​Idempotency

Full and partial refunds

`reversalType`

Amounts after a refund

Example: full refund including the fee

Example: partial refund

When the fee refund fails

Line items

Idempotency