Refund a POS sale

• Sandbox: PUT https://sandbox.payme.io/api/sales/{sale_guid}
• Production: PUT https://live.payme.io/api/sales/{sale_guid}

Credentials

• Request body field seller_payme_id (required): The seller's MPL. The sale must belong to this seller.
• Request body field payme_client_key (optional): Partners only: your partner key. You can send it in the PayMe-Partner-Key header instead.

Overview

Refunds a sale paid on a POS device. PayMe sends the refund to the device in payment.pos_id and returns the result in the same response.

Example: PUT https://sandbox.payme.io/api/sales/SALE1700-000000AA-EXAMPLE1-SALE0001.

• Send payment.action refund. Without it, this endpoint pays the sale instead of refunding it (see POS module overview).
• Leave out payment.amount to refund everything that can still be refunded, or send a smaller amount for a partial refund.
• payment.verify_only true runs the checks and returns without refunding.
• refunded_from_creditcard is true when the seller's balance didn't cover the refund and PayMe charged the seller's card on file for the difference.

Authentication

Send seller_payme_id (the seller's MPL) in the JSON body. The sale must belong to this seller. Partners also send payme_client_key, in the body or the PayMe-Partner-Key header.

Errors

Parameters

Request body

Content type: application/json

Request example

{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "payment": {
    "method": "pos",
    "action": "refund",
    "pos_id": "001"
  },
  "language": "en"
}

Code samples

curl

curl -X PUT 'https://sandbox.payme.io/api/sales/<sale_guid>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "payment": {
    "method": "pos",
    "action": "refund",
    "pos_id": "001"
  },
  "language": "en"
}'

Node.js

const response = await fetch("https://sandbox.payme.io/api/sales/<sale_guid>", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "payment": {
      "method": "pos",
      "action": "refund",
      "pos_id": "001"
    },
    "language": "en"
  }),
});

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

Python

import requests

response = requests.put(
    "https://sandbox.payme.io/api/sales/<sale_guid>",
    json={
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "payment": {
            "method": "pos",
            "action": "refund",
            "pos_id": "001",
        },
        "language": "en",
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "payment": {
    "method": "pos",
    "action": "refund",
    "pos_id": "001"
  },
  "language": "en"
}
BODY;

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

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

echo $response;

Responses

200 — The refund was processed. (success)

{
  "status_code": 0,
  "payme_status": "success",
  "payme_sale_id": "SALE1700-000000AA-EXAMPLE1-SALE0001",
  "payme_sale_code": 12346578,
  "payme_sale_status": "refunded",
  "sale_status": "refunded",
  "currency": "ILS",
  "price": 10000,
  "transaction_id": "order-1001",
  "sale_refund_buffer": 0,
  "payme_transaction_id": "TRAN1700-000000AA-EXAMPLE1-TRAN0002",
  "payme_transaction_total": 10000,
  "payme_transaction_card_brand": "Mastercard",
  "payme_transaction_auth_number": "0123456",
  "payme_signature": "db1c276**********c5b39",
  "refunded_from_creditcard": false,
  "sale_invoice_number": null,
  "sale_invoice_url": null
}

400 — The device or the POS service can't take the refund. See the error table. (error)

{
  "status_code": 1,
  "status_error_details": "Desired device is inactive",
  "status_additional_info": null,
  "status_error_code": 26018,
  "session": "FhT3aXe7"
}

500 — The request was refused or the refund was declined. See the error table. (error)

{
  "status_code": 1,
  "status_error_details": "Sale was not found",
  "status_additional_info": "SALE1700-000000AA-EXAMPLE1-SALE0001",
  "status_error_code": 350,
  "session": "FhT3aXe7"
}