Void an authorization

• Sandbox: POST https://sandbox.payme.io/api/refund-sale
• Production: POST https://live.payme.io/api/refund-sale

Credentials

• Request body field payme_client_key (optional): Partners: your partner key. You can send it in the PayMe-Partner-Key header instead. A seller leaves it out.
• Request body field seller_payme_id (optional): The seller's MPL. Required unless you send seller_id with payme_client_key. You can send it in the PayMe-Merchant-Key header instead.

Overview

Releases the hold of an authorized sale, in full or in part. It is the same call as refund-sale: PayMe voids instead of refunding because the sale is authorized.

Credentials

The same as refund-sale: send seller_payme_id, or seller_id with your partner key (payme_client_key). A partner key on its own fails with error 1.

Rules

• The sale's status must be authorized, or partial-void to release more of the hold. Otherwise the call returns error 305.
• Leave out sale_refund_amount to release the whole hold; the sale becomes voided.
• Send an amount to release part of the hold; the sale becomes partial-void and can no longer be captured. To charge less than you authorized, capture with a lower sale_price instead. After a partial void, sale_refund_buffer shows the hold that remains.
• An authorization that multi-capture has already captured from can't be voided (HTTP 400, error 369).
• PayMe never voids an authorization on its own. If you don't void it, the card issuer releases the hold on its own schedule.

PayMe sends the same refund callback as for a refund. See Callbacks.

Parameters

This endpoint takes no path, query or header parameters.

Request body

Content type: application/json

Request example

{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
  "language": "en"
}

Code samples

curl

curl -X POST 'https://sandbox.payme.io/api/refund-sale' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
  "language": "en"
}'

Node.js

const response = await fetch("https://sandbox.payme.io/api/refund-sale", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
    "language": "en"
  }),
});

console.log(await response.text());

Python

import requests

response = requests.post(
    "https://sandbox.payme.io/api/refund-sale",
    json={
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
        "language": "en",
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
  "language": "en"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/refund-sale');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Responses

200 — The hold was released, in full or in part. (success)

{
  "status_code": 0,
  "status_error_code": 0,
  "payme_status": "success",
  "refunded_from_creditcard": false,
  "sale_invoice_number": null,
  "sale_invoice_url": null,
  "sale_refund_buffer": 0,
  "sale_status": "voided",
  "payme_transaction_total": 10000,
  "payme_transaction_total_aft_deduction": 10000,
  "payme_transaction_id": "TRANDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
  "payme_transaction_card_brand": "Mastercard",
  "payme_transaction_auth_number": "72****4",
  "payme_transaction_voucher": "24****9",
  "payme_signature": "b71e**************ca5a",
  "payme_transaction_acquirer": null,
  "payme_transaction_arn": null,
  "session": "Ab12Cd34"
}

400 — Error 1: no seller named (a partner key on its own). Error 352: sale_refund_amount isn't a positive number. Error 369: multi-capture has already captured part of this authorization. (error)

{
  "status_code": 1,
  "status_error_details": "Authorization cannot be voided",
  "status_additional_info": "",
  "status_error_code": 369,
  "session": "Ab12Cd34"
}

403 — Error 303: the sale belongs to another partner or another seller. (error)

{
  "status_code": 1,
  "status_error_details": "Could not access sale",
  "status_additional_info": "",
  "status_error_code": 303,
  "session": "Ab12Cd34"
}

500 — Request errors. 305: the sale isn't authorized or partial-void. 357: this sale type can't be voided. 519: the amount is above the sale price. 352: a partial amount outside the account's limits. 363: already fully voided. 520: more than the hold that remains. 251: unknown seller. 350: no sale has this ID. (error)

{
  "status_code": 1,
  "status_error_details": "Cannot perform action due to an incorrect status",
  "status_additional_info": "completed",
  "status_error_code": 305,
  "session": "Ab12Cd34"
}