Payments API

Refund a payment

POST
https://api.sandbox.primer.io/payments/:id/refund

By default, this request will refund the full amount.

Optionally, pass in a lesser amount for a partial refund.

Path parameters

id
string

ID of payment to refund.

Headers

X-Idempotency-Key
optional string

Optional key to make the request idempotent. Learn more in the Idempotency Key guide.

Request

This endpoint expects an object.
amount
optional 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.

orderId
optional 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
optional string

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

Response

This endpoint return an object.
id
optional string

The unique payment ID.

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

date
optional datetime

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

status
optional enum

See the payment status table for more information.

orderId
optional string

Your reference for the payment.

currencyCode
optional enum

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

amount
optional integer

The amount you charged the customer, in minor units.

order
optional object

More information associated with the order.

customerId
optional string

The unique identifier for your customer.

customer
optional object

More information associated with the customer.

metadata
optional map from strings to any

Additional data to be used throughout the payment lifecycle.

paymentMethod
optional object

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

processor
optional object

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

requiredAction
optional object

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

statusReason
optional object

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

transactions
optional list of objects

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.

riskData
optional object

Errors

POST
/payments/:id/refund
1
2
3
4
curl -X POST "https://api.sandbox.primer.io/payments/id/refund" \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{}'
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "status": "PENDING",
  "currencyCode": "AED",
  "order": {
    "countryCode": "AW",
    "retailerCountryCode": "AW"
  },
  "customer": {
    "billingAddress": {
      "countryCode": "AW"
    },
    "shippingAddress": {
      "countryCode": "AW"
    }
  },
  "paymentMethod": {
    "paymentType": "FIRST_PAYMENT",
    "paymentMethodType": "PAYMENT_CARD",
    "threeDSecureAuthentication": {
      "responseCode": "NOT_PERFORMED"
    },
    "authorizationType": "ESTIMATED"
  },
  "statusReason": {
    "type": "APPLICATION_ERROR",
    "declineType": "SOFT_DECLINE",
    "code": "ERROR"
  },
  "riskData": {
    "fraudCheck": {
      "source": "FRAUD_PROVIDER",
      "preAuthorizationResult": "ACCEPT",
      "postAuthorizationResult": "ACCEPT"
    }
  }
}