Payment Refunds

A payment refund returns funds to a customer for a charge collected via a Payment Intent. Create a refund by referencing the original intent action; Nuvion processes it asynchronously.

The Refund object

string

Unique refund identifier.

string

Client-provided unique refund reference. 1–100 characters.

string

The ID of the Intent Action being refunded.

number

Refund amount in the smallest currency unit. 100 = $1.00 USD.

string

ISO 4217 currency code of the original payment.

string

Reason provided for issuing the refund, submitted as reason in the request. Maximum 100 characters.

string

Refund status. One of pending, successful, or failed.

string

Explanation for the current status. Present when status is failed.

string

The ID of the account the refund is debited from.

string

The ID of the entity that owns the account.

number

Unix timestamp in milliseconds when the refund was created.

Example refund object

{
  "status": "success",
  "message": "Payment refund retrieved successfully",
  "data": {
    "id": "01HXYZ5903ABCDEFGHJKMNPQRS",
    "reference": "refund_order_1044",
    "payment_intent_action_id": "01HXYZ5510ABCDEFGHJKMNPQRS",
    "amount": 1000,
    "currency": "USD",
    "refund_reason": "Refund requested after dispute",
    "status": "failed",
    "status_reason": "The requested refund amount exceeds the amount collected for this payment.",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "created": 1787952200000
  }
}

Refund statuses

Status	Description
`pending`	Refund created, being processed
`successful`	Funds returned to the customer
`failed`	Refund could not be completed. Check `status_reason`

Subscribe to payment_refund.completed and payment_refund.failed to track a refund in real time. See Event types for the full payload schema.

Create a payment refund

POST /refunds Refunds all or part of a charge collected via a card or Apple Pay Intent Action.

Request parameters

string

required

The ID of the Intent Action to refund. Returned by Confirm a payment intent.

string

required

Client-provided unique reference for the refund request. 1–100 characters.

number

required

Amount to refund, in the smallest currency unit. 100 = $1.00 USD. Must be greater than zero, and cannot exceed the amount still available to refund on the original payment.

string

Reason for requesting the refund. Returned as refund_reason in the response. Maximum 100 characters.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl -X POST https://api.nuvion.dev/refunds \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_action_id": "01HXYZ5504ABCDEFGHJKMNPQRS",
    "reference": "refund_order_1042",
    "reason": "Customer requested a refund",
    "amount": 100
  }'

Response

Returns the created refund with status: "pending".

{
  "status": "success",
  "message": "Payment refund created successfully",
  "data": {
    "id": "01HXYZ5901ABCDEFGHJKMNPQRS",
    "reference": "refund_order_1042",
    "payment_intent_action_id": "01HXYZ5504ABCDEFGHJKMNPQRS",
    "amount": 100,
    "currency": "USD",
    "refund_reason": "Customer requested a refund",
    "status": "pending",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "created": 1787952000000
  }
}

Errors

Code	Description
`400`	`payment_intent_action_id`, `reference`, or `amount` is missing or invalid. `amount` must be greater than zero.

Retrieve a payment refund

GET /refunds/{id} Returns a single payment refund.

string

required

Payment refund ID.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl https://api.nuvion.dev/refunds/01HXYZ5901ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

{
  "status": "success",
  "message": "Payment refund retrieved successfully",
  "data": {
    "id": "01HXYZ5901ABCDEFGHJKMNPQRS",
    "reference": "refund_order_1042",
    "payment_intent_action_id": "01HXYZ5504ABCDEFGHJKMNPQRS",
    "amount": 100,
    "currency": "USD",
    "refund_reason": "Customer requested a refund",
    "status": "successful",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "created": 1787952000000
  }
}

Errors

Code	Description
`404`	No payment refund found for the given `id`.

List payment refunds

GET /refunds Returns a paginated list of payment refunds.

string

Filter by status.

string

Filter by client-provided reference.

string

Filter by currency.

string

Filter by creation date start. ISO 8601 or Unix timestamp in milliseconds.

string

Filter by creation date end. ISO 8601 or Unix timestamp in milliseconds.

string

Filter by account.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

integer

Number of records to return. Between 1 and 100. Defaults to 20.

string

Cursor for the next page.

string

Cursor for the previous page.

Request

curl "https://api.nuvion.dev/refunds?limit=3" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

Like List payment intents, this endpoint returns the page under data.items, not data.data.

{
  "status": "success",
  "message": "Payment refunds retrieved successfully",
  "data": {
    "items": [
      {
        "id": "01HXYZ5901ABCDEFGHJKMNPQRS",
        "reference": "refund_order_1042",
        "payment_intent_action_id": "01HXYZ5504ABCDEFGHJKMNPQRS",
        "amount": 100,
        "currency": "USD",
        "refund_reason": "Customer requested a refund",
        "status": "successful",
        "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
        "created": 1787952000000
      },
      {
        "id": "01HXYZ5902ABCDEFGHJKMNPQRS",
        "reference": "refund_order_1043",
        "payment_intent_action_id": "01HXYZ5508ABCDEFGHJKMNPQRS",
        "amount": 500,
        "currency": "USD",
        "refund_reason": "Customer requested a partial refund",
        "status": "successful",
        "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
        "created": 1787952100000
      },
      {
        "id": "01HXYZ5903ABCDEFGHJKMNPQRS",
        "reference": "refund_order_1044",
        "payment_intent_action_id": "01HXYZ5510ABCDEFGHJKMNPQRS",
        "amount": 1000,
        "currency": "USD",
        "refund_reason": "Refund requested after dispute",
        "status": "failed",
        "status_reason": "The requested refund amount exceeds the amount collected for this payment.",
        "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
        "created": 1787952200000
      }
    ],
    "meta": {
      "pagination": {
        "order": "desc",
        "has_next": true,
        "limit": 3,
        "has_previous": false,
        "next_cursor": "01HXYZ5903ABCDEFGHJKMNPQRS",
        "previous_cursor": null
      },
      "filters_applied": {
        "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
        "sort": {
          "field": "_id",
          "order": "desc"
        }
      }
    }
  }
}

​The Refund object

​Refund statuses

​Create a payment refund

​Request parameters

​Request

​Response

​Errors

​Retrieve a payment refund

​Request

​Response

​Errors

​List payment refunds

​Request

​Response

The Refund object

Refund statuses

Create a payment refund

Request parameters

Request

Response

Errors

Retrieve a payment refund

Request

Response

Errors

List payment refunds

Request

Response