curl --request POST \
  --url https://api.sandbox.primer.io/payments/{id}/refund \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-VERSION: <x-api-version>' \
  --data '{}'

{
  "id": "kHdEw9EG",
  "date": "2021-02-21T15:36:16.367687",
  "dateUpdated": "2021-02-21T15:36:17.133701",
  "status": "SETTLED",
  "orderId": "order-abc",
  "customerId": "customer-123",
  "currencyCode": "EUR",
  "amount": 42,
  "cardTokenType": "CARD_PAN",
  "paymentMethod": {
    "paymentType": "SUBSCRIPTION",
    "paymentMethodToken": "heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4",
    "isVaulted": true,
    "authorizationType": "FINAL",
    "descriptor": "Purchase: Socks",
    "analyticsId": "VtkMDAxZW5isH0HsbbNxZ3lo",
    "paymentMethodType": "PAYMENT_CARD",
    "paymentMethodData": {
      "first6Digits": "411111",
      "last4Digits": "1111",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "cardholderName": "John Biggins",
      "network": "Visa",
      "isNetworkTokenized": false,
      "binData": {
        "network": "VISA",
        "regionalRestriction": "UNKNOWN",
        "accountNumberType": "UNKNOWN",
        "accountFundingType": "UNKNOWN",
        "prepaidReloadableIndicator": "NOT_APPLICABLE",
        "productUsageType": "UNKNOWN",
        "productCode": "VISA",
        "productName": "VISA"
      }
    }
  },
  "processor": {
    "name": "STRIPE",
    "processorMerchantId": "acct_stripe_1234",
    "amountCaptured": 42,
    "amountRefunded": 42
  },
  "transactions": [
    {
      "type": "SALE",
      "processorStatus": "SETTLED",
      "processorName": "STRIPE",
      "processorMerchantId": "acct_stripe_1234",
      "processorTransactionId": "54c4eb5b3ef8a",
      "cardTokenType": "CARD_PAN"
    },
    {
      "type": "REFUND",
      "processorStatus": "SETTLED",
      "processorName": "STRIPE",
      "processorMerchantId": "acct_stripe_1234",
      "processorTransactionId": "54c4eb5b3ef8a"
    }
  ],
  "customer": {
    "email": "customer123@gmail.com"
  },
  "metadata": {
    "productId": 123,
    "merchantId": "a13bsd62s"
  },
  "riskData": {
    "fraudChecks": {
      "source": "FRAUD_PROVIDER",
      "preAuthorizationResult": "THREE_DS",
      "postAuthorizationResult": "ACCEPT"
    },
    "cvvCheck": {
      "source": "PROCESSOR",
      "result": "MATCHED"
    },
    "avsCheck": {
      "source": "PROCESSOR",
      "result": {
        "streetAddress": "NOT_MATCHED",
        "postalCode": "NOT_VERIFIED"
      }
    }
  }
}

Refund a payment

Issue a full or partial refund for a previously settled payment. By default, the full amount will be refunded unless a specific amount is provided for a partial refund.

If the payment was partially captured multiple times, you can specify which capture to refund by using the transaction event ID. Refer to the transactions.events array in the payment object to find available transaction event IDs (when the appropriate expand parameter is passed).

When specifying a transaction event ID, the refund amount should not exceed the amount captured in that event. If no refund amount is provided, it defaults to the amount captured in that specific event.

POST

payments

{id}

refund

curl --request POST \
  --url https://api.sandbox.primer.io/payments/{id}/refund \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-VERSION: <x-api-version>' \
  --data '{}'

{
  "id": "kHdEw9EG",
  "date": "2021-02-21T15:36:16.367687",
  "dateUpdated": "2021-02-21T15:36:17.133701",
  "status": "SETTLED",
  "orderId": "order-abc",
  "customerId": "customer-123",
  "currencyCode": "EUR",
  "amount": 42,
  "cardTokenType": "CARD_PAN",
  "paymentMethod": {
    "paymentType": "SUBSCRIPTION",
    "paymentMethodToken": "heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4",
    "isVaulted": true,
    "authorizationType": "FINAL",
    "descriptor": "Purchase: Socks",
    "analyticsId": "VtkMDAxZW5isH0HsbbNxZ3lo",
    "paymentMethodType": "PAYMENT_CARD",
    "paymentMethodData": {
      "first6Digits": "411111",
      "last4Digits": "1111",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "cardholderName": "John Biggins",
      "network": "Visa",
      "isNetworkTokenized": false,
      "binData": {
        "network": "VISA",
        "regionalRestriction": "UNKNOWN",
        "accountNumberType": "UNKNOWN",
        "accountFundingType": "UNKNOWN",
        "prepaidReloadableIndicator": "NOT_APPLICABLE",
        "productUsageType": "UNKNOWN",
        "productCode": "VISA",
        "productName": "VISA"
      }
    }
  },
  "processor": {
    "name": "STRIPE",
    "processorMerchantId": "acct_stripe_1234",
    "amountCaptured": 42,
    "amountRefunded": 42
  },
  "transactions": [
    {
      "type": "SALE",
      "processorStatus": "SETTLED",
      "processorName": "STRIPE",
      "processorMerchantId": "acct_stripe_1234",
      "processorTransactionId": "54c4eb5b3ef8a",
      "cardTokenType": "CARD_PAN"
    },
    {
      "type": "REFUND",
      "processorStatus": "SETTLED",
      "processorName": "STRIPE",
      "processorMerchantId": "acct_stripe_1234",
      "processorTransactionId": "54c4eb5b3ef8a"
    }
  ],
  "customer": {
    "email": "customer123@gmail.com"
  },
  "metadata": {
    "productId": 123,
    "merchantId": "a13bsd62s"
  },
  "riskData": {
    "fraudChecks": {
      "source": "FRAUD_PROVIDER",
      "preAuthorizationResult": "THREE_DS",
      "postAuthorizationResult": "ACCEPT"
    },
    "cvvCheck": {
      "source": "PROCESSOR",
      "result": "MATCHED"
    },
    "avsCheck": {
      "source": "PROCESSOR",
      "result": {
        "streetAddress": "NOT_MATCHED",
        "postalCode": "NOT_VERIFIED"
      }
    }
  }
}

Authorizations

X-API-KEY

string

header

required

Headers

X-Idempotency-Key

string

Optional key to make the request idempotent. Enables a safe retry of a request without risking the user being charged or refunded multiple times. The idempotency key must be generated by the client and needs to be unique for every new request.

X-API-VERSION

string

required

Specifies the version of the API to use. This must be set to 2.4.

Example:

"2.4"

Path Parameters

string

required

ID of payment to refund.

Body

application/json

amount

integer

The amount you would like to refund the customer, in minor units. e.g. for $7, use 700.

Defaults to remaining non-refunded amount.

Required range: x >= 0

orderId

string

Optionally you can pass a specific order ID for the refund.

By default this will be set to the original orderId given on payment creation.

reason

string

You can optionally specify a reason for the refund. This is for your own records.

transactionEventId

string<uuid>

Specific capture ID to target for the refund. Use this to specify which transaction event the refund should apply to.

Example:

"57a2027d-36a6-494f-ad07-a6e1d0c77772"

expand

enum<string>[] | null

A list of fields to expand, such as transactions.events.

Show child attributes

Response

Successful Response

string

The unique payment ID.

You can use this ID to retrieve the payment details, or perform downstream operations.

date

string<date-time>

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

dateUpdated

string<date-time>

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

status

enum<string>

See the payment status table for more information.

Available options:

PENDING,

FAILED,

AUTHORIZED,

SETTLING,

PARTIALLY_SETTLED,

SETTLED,

DECLINED,

CANCELLED

cardTokenType

enum<string>

The type of card token used for the payment.

Only applies for card payments.

An enumeration.

Available options:

CARD_PAN,

NETWORK_TOKEN,

PROCESSOR_TOKEN

Example:

"CARD_PAN"

orderId

string

Your reference for the payment.

Maximum length: 256

currencyCode

enum<string>

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

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BOV,

BRL,

BSD,

BTN,

BWP,

BYR,

BYN,

BZD,

CAD,

CDF,

CHE,

CHF,

CHW,

CLP,

CNY,

COP,

COU,

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,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

IRR,

ISK,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MKD,

MMK,

MNT,

MOP,

MRO,

MUR,

MVR,

MWK,

MXN,

MXV,

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,

SOS,

SRD,

SSP,

SVC,

SYP,

SZL,

THB,

TJS,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VND,

VUV,

WST,

XAF,

XAG,

XAU,

XBA,

XBB,

XBC,

XBD,

XCD,

XDR,

XFU,

XOF,

XPD,

XPF,

XPT,

XSU,

XTS,

XUA,

YER,

ZAR,

ZMW,

ZWL

amount

integer

The amount you charged the customer, in minor units.

Required range: x >= 0

order

object

More information associated with the order.

Show child attributes

customerId

string

The unique identifier for your customer.

Maximum length: 256

customer

object

More information associated with the customer.

Show child attributes

metadata

object

Additional data to be used throughout the payment lifecycle.

paymentMethod

object

The payment method options provided in the request, as well as the token used to process the payment.

Show child attributes

processor

object

More information associated with the payment processor, including the processor name.

Show child attributes

requiredAction

object

Required action to perform in order to resume the payment workflow. This can be requiring a 3DS check from the customer for instance.

Show child attributes

statusReason

object

Check this field for more information regarding the payment's status. This is especially useful when the status is DECLINED or FAILED.

Show child attributes

transactions

TransactionOverviewAPISchema · object[]

A list summarizing the transactions that occurred while processing the payment.

Note: a refund is a separate transaction and so will appear in this transactions list if a refund was performed.

Show child attributes

riskData

object

Risk data associated with this payment.

Show child attributes

Cancel a payment Resume a payment

API reference

Authorizations

Headers

Path Parameters

Body

Response