Payment Refund

This endpoint allows you to create a refund for a payment. You can specify the amount to be refunded, the reason for the refund, payment_id and unique reference.

Refund Statuses

Status	Description
`successful`	A successful refund
`pending`	A pending refund
`failed`	A failed refund

Refund Response Object

{
    "id": "refund_1234567890",
    "reference": "refund_001",
    "payment_intent_action_id": "pay_1234567890",
    "amount": 5000,
    "currency": "USD",
    "refund_reason": "Customer requested a refund",
    "status": "pending",
    "status_reason": null,
    "account_id": "acc_1234567890",
    "entity_id": "ent_1234567890",
    "created": 1700000000000
}

string

Refund record identifier

string

Client-provided unique refund reference. Length between 1 and 100 characters.

string

Identifier of the original payment action

number

Refund amount

string

ISO 4217 three-letter currency code of the original payment

string

Reason provided for issuing the refund. Maximum length of 100 characters.

string

Current refund processing status (pending|successful|failed)

string

Explanation for the current status

string

Account associated with the refund

string

Owning entity identifier

number

The Unix timestamp in milliseconds indicating the creation time

Create a Payment Refund

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

Request Fields

string

Identifier of the payment intent action to be refunded

string

Client-provided unique reference for the refund request. Length between 1 and 100 characters.

string

Optional reason for requesting the refund. Maximum length of 100 characters.

number

Amount to refund; must be greater than zero

Response

{
  "status": "success",
  "message": "Refund created successfully",
  "data": {
    "id": "refund_1234567890",
    "reference": "refund_001",
    "payment_intent_action_id": "pay_1234567890",
    "amount": 5000,
    "currency": "USD",
    "refund_reason": "Customer requested a refund",
    "status": "pending",
    "status_reason": null,
    "account_id": "acc_1234567890",
    "entity_id": "ent_1234567890",
    "created": 1700000000000
  }
}

{
  "status": "error",
  "message": "Invalid refund request",
  "details": {
    "payment_intent_action_id": "Payment intent action ID is required",
    "amount": "Amount must be greater than zero"
  }
}

Retrieve Payment Refunds

Returns paginated list of payment refunds with optional filtering by status, reference, currency, date range, account_id and entity_id.

curl -X GET https://api.nuvion.dev/refunds \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -d status=pending \
  -d limit=20 \
  -d reference=refund_001 \
  -d currency=USD \
  -d date_from=2024-01-01T00:00:00Z \
  -d date_to=2024-12-31T23:59:59Z \
  -d prev_cursor=abc123 \
  -d next_cursor=def456 \
  -d account_id=acc_1234567890 \
  -d entity_id=ent_1234567890

Query Parameters

string

Filter payment refunds by status (pending|successful|failed)

string

Filter payment refunds by client-provided reference identifier

string

Filter payment refunds by ISO currency code (e.g. USD)

string

Start date for filtering refunds (ISO 8601 format or Unix timestamp in milliseconds)

string

End date for filtering refunds (ISO 8601 format or Unix timestamp in milliseconds)

string

Cursor for fetching the previous page of results

string

Cursor for fetching the next page of results

number

Number of records to return per page (default: 20, max: 100)

string

ULID of the account to filter payment refunds

string

ULID of the entity to filter payment refunds

Response

{
  "status": "success",
  "message": "Refunds retrieved successfully",
  "data": {
    "items": [
      {
        "id": "refund_1234567890",
        "reference": "refund_001",
        "payment_intent_action_id": "pay_1234567890",
        "amount": 5000,
        "currency": "USD",
        "refund_reason": "Customer requested a refund",
        "status": "pending",
        "status_reason": null,
        "account_id": "acc_1234567890",
        "entity_id": "ent_1234567890",
        "created": 1700000000000
      }
    ],
    "meta": {
      "pagination": {
        "order": "desc",
        "has_next": false,
        "limit": 20,
        "has_previous": false,
        "next_cursor": null,
        "previous_cursor": null
      },
      "filters_applied": {}
    }
  }
}

{
  "status": "error",
  "message": "Failed to retrieve refunds",
  "details": {
    "status": "Invalid status filter value",
    "date_from": "Invalid date format for date_from"
  }
}

Retrieve a Payment Refund by ID

Returns details of a specific payment refund identified by its ULID.

curl -X GET https://api.nuvion.dev/refunds/refund_1234567890 \
  -H "Authorization: Bearer $NUVION_API_KEY" \

Request Parameters

string

ULID of the payment refund to retrieve

string

ULID of the entity the payment refund belongs to (optional, used for additional access control)

Response

{
    "status": "success",
    "message": "Refund retrieved successfully",
    "data": {
        "id": "refund_1234567890",
        "reference": "refund_001",
        "payment_intent_action_id": "pay_1234567890",
        "amount": 5000,
        "currency": "USD",
        "refund_reason": "Customer requested a refund",
        "status": "pending",
        "status_reason": null,
        "account_id": "acc_1234567890",
        "entity_id": "ent_1234567890",
        "created": 1700000000000
    }   
}

{
    "status": "error",
    "message": "Failed to retrieve refund",
    "details": {
        "id": "Refund not found with the provided ID",
        "entity_id": "Entity ID does not match the refund's entity"
    }
}

Payment Refund Webhook Events

Payment refund events are sent to your registered webhook endpoint when a refund is completed, or fails. You can listen for the following events:

Event	Types
`payment_refund.completed`	A refund request completes successfully
`payment_refund.failed`	A refund request fails

Payment Refund Event Payloads

{
  "event": "payment_refund.completed",
  "data": {
    "id": "01KV814KD8CXG2ANFVX9XSPXXX",
    "reference": "refund_003",
    "payment_intent_action_id": "01KV80YE1HCD5DXP15XBHBAXXX",
    "amount": 5000,
    "currency": "USD",
    "refund_reason": "Customer requested",
    "status": "successful",
    "account_id": "01K8TN588BZKJHZ3VHR2BF3XXX",
    "entity_id": "01K8QZHTWHNGS2Y21HXB36VXXX",
    "created": 1781607321000
  }
}

{
  "event": "payment_refund.failed",
  "data": {
    "id": "01KV814KD8CXG2ANFVX9XSPXXX",
    "reference": "refund_003",
    "payment_intent_action_id": "01KV80YE1HCD5DXP15XBHBAXXX",
    "amount": 5000,
    "currency": "USD",
    "refund_reason": "Customer requested",
    "status": "failed",
    "status_reason": "Insufficient funds in the account",
    "account_id": "01K8TN588BZKJHZ3VHR2BF3XXX",
    "entity_id": "01K8QZHTWHNGS2Y21HXB36VXXX",
    "created": 1781607321000
  }
}

​Refund Statuses

​Refund Response Object

​Create a Payment Refund

​Request Fields

​Response

​Retrieve Payment Refunds

​Query Parameters

​Response

​Retrieve a Payment Refund by ID

​Request Parameters

​Response

​Payment Refund Webhook Events

​Payment Refund Event Payloads

Refund Statuses

Refund Response Object

Create a Payment Refund

Request Fields

Response

Retrieve Payment Refunds

Query Parameters

Response

Retrieve a Payment Refund by ID

Request Parameters

Response

Payment Refund Webhook Events

Payment Refund Event Payloads