Skip to main content
POST
/
payments
/
refund
/
{id}
Refund a payment
curl --request POST \
  --url https://sandbox-api.paynext.com/payments/refund/{id} \
  --header 'Authorization: Bearer <token>'
{
  "amount": 15000,
  "amount_usd": 15000,
  "avs_check": {
    "result": {
      "postal_code": "pass",
      "street_address": "pass"
    }
  },
  "created_at": "2025-05-25T14:30:00Z",
  "currency_code": "AED",
  "customer": {
    "address": {
      "city": "San Francisco",
      "country": "AD",
      "line1": "123 Market Street",
      "line2": "Suite 400",
      "postal_code": "94105",
      "state": "CA"
    },
    "created_at": "2025-05-28T14:00:00Z",
    "email": "alice.johnson@example.com",
    "external_id": "ext_001",
    "full_name": "Alice Johnson",
    "id": "cus_b8d0fe7e-3a7f-4b5f-a68b-d31358b49c3f",
    "metadata": {
      "key": "value"
    },
    "phone": "+1-555-123-4567",
    "updated_at": "2025-05-28T14:05:00Z"
  },
  "cvc_check": {
    "result": {
      "cvc": "pass"
    }
  },
  "id": "pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789",
  "metadata": {
    "key": "value"
  },
  "payment_details": {
    "arn": "123453",
    "auth_code": "334385",
    "network_payment_id": "119676610486528",
    "processor_transaction_id": "pi_3RgN6TJVVBuowJOx0B4fpGWi"
  },
  "payment_method": {
    "details": {
      "bin": "411111",
      "bin_data": {
        "brand": "visa",
        "country": "AD",
        "currency_code": "<string>",
        "description": "Chase Sapphire Preferred",
        "funding": "debit",
        "issuer": "Chase Bank",
        "type": "consumer"
      },
      "exp_month": 12,
      "exp_year": 2028,
      "is_network_tokenized": true,
      "last4": "1111",
      "number": "4111111111111111"
    },
    "type": "CARD",
    "billing_address": {
      "city": "San Francisco",
      "country": "AD",
      "line1": "123 Market Street",
      "line2": "Suite 400",
      "postal_code": "94105",
      "state": "CA"
    }
  },
  "payment_status": "PENDING",
  "payment_token_type": "CARD_PAN",
  "payment_type": "MIT",
  "processor": {
    "description": "Stripe US",
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "processor_merchant_id": "12345678",
    "type": "STRIPE"
  },
  "refund": {
    "amount": 123,
    "amount_usd": 123,
    "created_at": "<string>",
    "processor_transaction_id": "<string>",
    "status": "PENDING",
    "updated_at": "<string>"
  },
  "refunded_amount": 0,
  "statement_descriptor": "MY COMPANY",
  "status_reason": {
    "status": "declined",
    "status_reason": {
      "advice_code": "do_not_try_again",
      "decline_code": "insufficient_funds",
      "message": "<string>"
    }
  },
  "subscription": {
    "created_at": "2025-05-26T10:00:00Z",
    "current_period_end": "<string>",
    "current_period_start": "<string>",
    "id": "sub_123e4567-e89b-12d3-a456-426614174000",
    "metadata": {
      "key": "value"
    },
    "next_billing_date": "2025-06-26T12:00:00Z",
    "past_due": {
      "attempt_count": 2,
      "max_attempts_count": 7
    },
    "plan": {
      "id": "price_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "interval": "days",
      "interval_count": 1,
      "name": "Pro Plan",
      "price": {
        "amount": 1999,
        "currency": "AED"
      },
      "tax": {
        "collect_tax": "<unknown>"
      },
      "trial_interval": "days",
      "trial_interval_count": 14,
      "trial_price": {
        "amount": 1999,
        "currency": "AED"
      },
      "type": "recurring"
    },
    "status": "trial",
    "updated_at": "2025-05-27T10:00:00Z"
  },
  "tax": {
    "amount_subtotal": 123,
    "amount_subtotal_usd": 123,
    "amount_tax": 123,
    "amount_tax_usd": 123,
    "behavior": "<unknown>",
    "calculation_id": "<string>",
    "error": {
      "code": "<unknown>",
      "message": "<string>"
    },
    "provider": {
      "id": "<string>",
      "type": "NUMERAL"
    },
    "status": "<unknown>",
    "transaction_id": "<string>"
  },
  "three_d_secure": {
    "authentication_flow": "<string>",
    "electronic_commerce_indicator": {
      "liability_shift": true,
      "result": "<string>",
      "value": "<string>"
    },
    "status": "action-required",
    "status_reason": "<string>",
    "transaction_id": "<string>",
    "version": "<string>"
  },
  "updated_at": "2025-05-26T10:15:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.paynext.com/llms.txt

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

Authorizations

​
Authorization
string
header
required

Authentication header of the form api key, where api key is your organization api key.

Headers

​
X-API-Version
enum<string>

Specifies the version of the API to use

Available options:
1.0.0

Path Parameters

​
id
string
required

The ID of the payment to refund

Response

OK

​
amount
integer

Payment amount in the specified currency (e.g., cents)

Example:

15000

​
amount_usd
integer

Payment amount converted to USD (e.g., cents)

Example:

15000

​
avs_check
object

Avs check

​
created_at
string

The date and time at which the payment was created in UTC format.

Example:

"2025-05-25T14:30:00Z"

​
currency_code
enum<string>

The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars.

Available options:
AED,
AFN,
ALL,
AMD,
AOA,
ARS,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
BGN,
BHD,
BIF,
BMD,
BND,
BOB,
BRL,
BSD,
BTN,
BWP,
BYN,
BZD,
CAD,
CDF,
CHF,
CLP,
CNY,
COP,
CRC,
CUC,
CUP,
CVE,
CZK,
DJF,
DKK,
DOP,
DZD,
EGP,
ERN,
ETB,
EUR,
FJD,
FKP,
GBP,
GEL,
GHS,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HTG,
HUF,
IDR,
ILS,
IMP,
INR,
IQD,
IRR,
ISK,
JEP,
JMD,
JOD,
JPY,
KES,
KGS,
KHR,
KMF,
KPW,
KRW,
KWD,
KYD,
KZT,
LAK,
LBP,
LKR,
LRD,
LSL,
LYD,
MAD,
MDL,
MGA,
MKD,
MMK,
MNT,
MOP,
MRU,
MUR,
MVR,
MWK,
MXN,
MYR,
MZN,
NAD,
NGN,
NIO,
NOK,
NPR,
NZD,
OMR,
PAB,
PEN,
PGK,
PHP,
PKR,
PLN,
PYG,
QAR,
RON,
RSD,
RUB,
RWF,
SAR,
SBD,
SCR,
SDG,
SEK,
SGD,
SHP,
SLE,
SOS,
SRD,
SSP,
STD,
STN,
SVC,
SYP,
SZL,
THB,
TJS,
TMT,
TND,
TOP,
TRY,
TTD,
TWD,
TZS,
BOV,
COU,
CHE,
CHW,
MXV,
UGX,
VES,
VND,
VUV,
XAF,
XCD,
XCG,
XOF,
XPF,
YER,
USD
​
customer
object
​
cvc_check
object

CVC check

​
id
string

Unique identifier of the payment.

Example:

"pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789"

​
metadata
object

Custom metadata associated with the payment A dictionary of key-value pairs.

Example:
{ "key": "value" }
​
payment_details
object

Transaction details related to payment

​
payment_method
Card API Schema · object
​
payment_status
enum<string>

Current status of the payment

Available options:
PENDING,
FAILED,
AUTHORIZED,
SETTLING,
SETTLED,
DECLINED,
BLOCKED,
CANCELLED
​
payment_token_type
enum<string>

Type of card token used, if applicable

Available options:
CARD_PAN,
NETWORK_TOKEN,
PROCESSOR_TOKEN
​
payment_type
enum<string>

Indicates whether the transaction was merchant-initiated (MIT) or customer-initiated (CIT).

Available options:
MIT,
CIT
​
processor
object
​
refund
object

Information about refund

​
refunded_amount
integer

Amount refunded from the original payment

Example:

0

​
statement_descriptor
string

Statement descriptor shown on the customer's bank statement

Example:

"MY COMPANY"

​
status_reason
object

Reason of payment status

​
subscription
object
​
tax
object

Tax info (provider, calculation/transaction ids, amounts, status)

​
three_d_secure
object

Information about 3DS

​
updated_at
string

The date and time of the last payment update in UTC format.

Example:

"2025-05-26T10:15:00Z"