curl --request POST \
--url https://api.sandbox.primer.io/payments/{id}/cancel \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"reason": "Customer cancelled order #1234."
}
'import requests
url = "https://api.sandbox.primer.io/payments/{id}/cancel"
payload = { "reason": "Customer cancelled order #1234." }
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: 'Customer cancelled order #1234.'})
};
fetch('https://api.sandbox.primer.io/payments/{id}/cancel', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.primer.io/payments/{id}/cancel",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reason' => 'Customer cancelled order #1234.'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.primer.io/payments/{id}/cancel"
payload := strings.NewReader("{\n \"reason\": \"Customer cancelled order #1234.\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.primer.io/payments/{id}/cancel")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"reason\": \"Customer cancelled order #1234.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.primer.io/payments/{id}/cancel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reason\": \"Customer cancelled order #1234.\"\n}"
response = http.request(request)
puts response.read_body{
"id": "kHdEw9EG",
"date": "2021-02-21T15:36:16.367687",
"dateUpdated": "2021-02-21T15:36:17.133701",
"status": "CANCELLED",
"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",
"firstDigits": "41111111",
"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": 0,
"amountRefunded": 0
},
"transactions": [
{
"type": "SALE",
"processorStatus": "CANCELLED",
"processorName": "STRIPE",
"processorMerchantId": "acct_stripe_1234",
"processorTransactionId": "54c4eb5b3ef8a",
"cardTokenType": "CARD_PAN",
"reason": "Customer cancelled order #1234."
}
],
"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"
}
}
}
}Cancel a payment
Provided the payment has not reached SETTLED status, Primer will
send a “void” request to the payment processor, thereby cancelling the payment
and releasing the hold on customer funds. Upon success, the payment will transition
to CANCELLED. The payload is optional.
Failed request limit: Primer limits how many failed requests a single
payment can have. Failed capture, cancel, refund and adjust-authorization
requests all count towards the same limit, which is currently 100 per payment.
Once a payment reaches the limit, any further capture, cancel, refund or
adjust-authorization request for that payment is rejected with a 409 and the
error ID PaymentRequestLimitExceeded. The rejected request is not sent to the
processor. Do not retry after this error: retrieve the payment to see why its
previous requests failed, and contact Primer support if you need the payment
unblocked.
curl --request POST \
--url https://api.sandbox.primer.io/payments/{id}/cancel \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"reason": "Customer cancelled order #1234."
}
'import requests
url = "https://api.sandbox.primer.io/payments/{id}/cancel"
payload = { "reason": "Customer cancelled order #1234." }
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: 'Customer cancelled order #1234.'})
};
fetch('https://api.sandbox.primer.io/payments/{id}/cancel', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.primer.io/payments/{id}/cancel",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reason' => 'Customer cancelled order #1234.'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.primer.io/payments/{id}/cancel"
payload := strings.NewReader("{\n \"reason\": \"Customer cancelled order #1234.\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.primer.io/payments/{id}/cancel")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"reason\": \"Customer cancelled order #1234.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.primer.io/payments/{id}/cancel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reason\": \"Customer cancelled order #1234.\"\n}"
response = http.request(request)
puts response.read_body{
"id": "kHdEw9EG",
"date": "2021-02-21T15:36:16.367687",
"dateUpdated": "2021-02-21T15:36:17.133701",
"status": "CANCELLED",
"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",
"firstDigits": "41111111",
"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": 0,
"amountRefunded": 0
},
"transactions": [
{
"type": "SALE",
"processorStatus": "CANCELLED",
"processorName": "STRIPE",
"processorMerchantId": "acct_stripe_1234",
"processorTransactionId": "54c4eb5b3ef8a",
"cardTokenType": "CARD_PAN",
"reason": "Customer cancelled order #1234."
}
],
"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"
}
}
}
}Headers
Path Parameters
Body
Response
Successful Response
See the payment status table for more information.
PENDING, FAILED, AUTHORIZED, SETTLING, PARTIALLY_SETTLED, SETTLED, DECLINED, CANCELLED The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars.
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, 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, SLE, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XCG, XOF, XPF, YER, ZAR, ZMW, ZWG, ZWL