Skip to main content
POST
/
payments
/
{id}
/
cancel
Cancel a payment
curl --request POST \
  --url https://api.sandbox.primer.io/payments/{id}/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-VERSION: <x-api-version>' \
  --data '
{
  "reason": "Customer cancelled order #1234."
}
'
{
  "id": "<string>",
  "date": "2023-11-07T05:31:56Z",
  "dateUpdated": "2023-11-07T05:31:56Z",
  "status": "PENDING",
  "cardTokenType": "CARD_PAN",
  "orderId": "<string>",
  "currencyCode": "AED",
  "amount": 1,
  "order": {
    "lineItems": [
      {
        "amount": 1,
        "itemId": "<string>",
        "name": "<string>",
        "description": "<string>",
        "quantity": 1,
        "discountAmount": 1,
        "taxAmount": 1,
        "taxCode": "<string>",
        "productType": "PHYSICAL",
        "productData": {
          "sku": "<string>",
          "brand": "<string>",
          "color": "<string>",
          "globalTradeItemNumber": "<string>",
          "manufacturerPartNumber": "<string>",
          "weight": 1,
          "weightUnit": "<string>",
          "pageUrl": "<string>"
        }
      }
    ],
    "countryCode": "AW",
    "retailerCountryCode": "AW",
    "fees": [
      {
        "amount": 1,
        "type": "<string>",
        "description": "<string>"
      }
    ],
    "shipping": {
      "amount": 1,
      "methodId": "<string>",
      "methodName": "<string>",
      "methodDescription": "<string>"
    }
  },
  "customerId": "<string>",
  "customer": {
    "emailAddress": "jsmith@example.com",
    "mobileNumber": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "billingAddress": {
      "firstName": "<string>",
      "lastName": "<string>",
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "countryCode": "AW",
      "postalCode": "<string>"
    },
    "shippingAddress": {
      "firstName": "<string>",
      "lastName": "<string>",
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "countryCode": "AW",
      "postalCode": "<string>"
    },
    "taxId": "<string>",
    "nationalDocumentId": "<string>"
  },
  "metadata": {},
  "paymentMethod": {
    "descriptor": "<string>",
    "paymentType": "FIRST_PAYMENT",
    "paymentMethodToken": "<string>",
    "isVaulted": false,
    "analyticsId": "<string>",
    "paymentMethodType": "PAYMENT_CARD",
    "paymentMethodData": {
      "last4Digits": "<string>",
      "expirationMonth": "<string>",
      "expirationYear": "<string>",
      "first6Digits": "<string>",
      "cardholderName": "<string>",
      "network": "<string>",
      "isNetworkTokenized": false,
      "binData": {
        "network": "AMEX",
        "regionalRestriction": "DOMESTIC_USE_ONLY",
        "accountNumberType": "PRIMARY_ACCOUNT_NUMBER",
        "accountFundingType": "CREDIT",
        "prepaidReloadableIndicator": "RELOADABLE",
        "productUsageType": "CONSUMER",
        "productCode": "<string>",
        "productName": "<string>",
        "issuerCountryCode": "AW",
        "issuerName": "<string>",
        "issuerCurrencyCode": "AED"
      }
    },
    "threeDSecureAuthentication": {
      "response_code": "NOT_PERFORMED"
    },
    "authorizationType": "ESTIMATED"
  },
  "processor": {
    "name": "<string>",
    "processorMerchantId": "<string>",
    "amountCaptured": 1,
    "amountRefunded": 1
  },
  "requiredAction": {
    "name": "3DS_AUTHENTICATION",
    "description": "<string>",
    "clientToken": "<string>"
  },
  "statusReason": {
    "type": "APPLICATION_ERROR",
    "declineType": "SOFT_DECLINE",
    "code": "ERROR",
    "message": "<string>",
    "paymentMethodResultCode": "<string>",
    "paymentMethodResultMessage": "<string>",
    "paymentMethodAdviceCode": "<string>",
    "paymentMethodAdviceMessage": "<string>",
    "advisedAction": "RETRY_LATER"
  },
  "transactions": [
    {
      "date": "<string>",
      "amount": 1,
      "currencyCode": "AED",
      "processorMerchantId": "<string>",
      "orderId": "<string>",
      "transactionType": "SALE",
      "processorTransactionId": "<string>",
      "processorName": "<string>",
      "processorStatus": "PENDING",
      "processorStatusReason": {
        "type": "APPLICATION_ERROR",
        "declineType": "SOFT_DECLINE",
        "code": "ERROR",
        "message": "<string>",
        "paymentMethodResultCode": "<string>",
        "paymentMethodResultMessage": "<string>",
        "paymentMethodAdviceCode": "<string>",
        "paymentMethodAdviceMessage": "<string>",
        "advisedAction": "RETRY_LATER"
      },
      "cardTokenType": "CARD_PAN",
      "reason": "Item returned.",
      "events": [
        {
          "id": "46d25279-9d36-4237-8f45-2dc4e4e262d6",
          "date": "2025-01-22T13:39:18.992928",
          "type": "CAPTURE_SUCCEEDED",
          "processorEventId": "30B258847H402782C",
          "amount": 1234,
          "final": false
        }
      ]
    }
  ],
  "riskData": {
    "fraudChecks": {
      "source": "FRAUD_PROVIDER",
      "preAuthorizationResult": "THREE_DS",
      "preAuthorizationRecommendation": "TRANSACTION_RISK_ANALYSIS",
      "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

​
id
string
required

ID of payment to cancel.

Body

application/json
​
reason
string

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

​
expand
enum<string>[] | null

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

Available options:
transactions.events

Response

Successful Response

​
id
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.

Available options:
CARD_PAN,
NETWORK_TOKEN,
PROCESSOR_TOKEN
Example:

"CARD_PAN"

​
orderId
string

Your reference for the payment.

Maximum string 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<int64>

The amount you charged the customer, in minor units.

Required range: x >= 0
​
order
Order Details · object

More information associated with the order.

​
customerId
string

The unique identifier for your customer.

Maximum string length: 256
​
customer
Customer Details · object

More information associated with the customer.

​
metadata
Payment Metadata · object

Additional data to be used throughout the payment lifecycle.

​
paymentMethod
Payment Method Options · object

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

​
processor
Processor Information · object

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

​
requiredAction
Required action · 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
Status Reason · object

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

​
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.

​
riskData
Risk Data · object

Risk data associated with this payment.