Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nuvion.co/llms.txt

Use this file to discover all available pages before exploring further.

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

StatusDescription
successfulA successful refund
pendingA pending refund
failedA 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
}
​
id
string
Refund record identifier
​
reference
string
Client-provided unique refund reference. Length between 1 and 100 characters.
​
payment_intent_action_id
string
Identifier of the original payment action
​
amount
number
Refund amount
​
currency
string
ISO 4217 three-letter currency code of the original payment
​
refund_reason
string
Reason provided for issuing the refund. Maximum length of 100 characters.
​
status
string
Current refund processing status (pending|successful|failed)
​
status_reason
string
Explanation for the current status
​
account_id
string
Account associated with the refund
​
entity_id
string
Owning entity identifier
​
created
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_id": "pay_1234567890",
    "reference": "refund_001",
    "reason": "Customer requested a refund",
    "amount": 5000
  }'

​
Request Fields

​
payment_id
string
Identifier of the payment to be refunded
​
reference
string
Client-provided unique reference for the refund request. Length between 1 and 100 characters.
​
reason
string
Optional reason for requesting the refund. Maximum length of 100 characters.
​
amount
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
  }
}

​
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

​
status
string
Filter payment refunds by status (pending|successful|failed)
​
reference
string
Filter payment refunds by client-provided reference identifier
​
currency
string
Filter payment refunds by ISO currency code (e.g. USD)
​
date_from
string
Start date for filtering refunds (ISO 8601 format or Unix timestamp in milliseconds)
​
date_to
string
End date for filtering refunds (ISO 8601 format or Unix timestamp in milliseconds)
​
prev_cursor
string
Cursor for fetching the previous page of results
​
next_cursor
string
Cursor for fetching the next page of results
​
limit
number
Number of records to return per page (default: 20, max: 100)
​
account_id
string
ULID of the account to filter payment refunds
​
entity_id
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": {}
    }
  }
}

​
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

​
id
string
ULID of the payment refund to retrieve
​
entity_id
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
    }   
}