Get the buyer key of a sale or subscription

• Sandbox: POST https://sandbox.payme.io/api/get-buyer-key
• Production: POST https://live.payme.io/api/get-buyer-key

Credentials

• Request body field seller_payme_id (optional): The seller's MPL, for a seller-level token (saved with buyer_is_private: true). Don't send it for an account-level token: that fails with error 603. Send this or payme_client_key.
• Request body field payme_client_key (optional): Partners: your partner key, in the JSON body. Reads both kinds of token when you send no seller_payme_id.

Overview

Returns the saved card (buyer_key) of a paid sale or of a subscription. Send payme_sale_id or sub_payme_id, not both.

Use sub_payme_id for a subscription whose card was entered on sub_url: subscription calls and callbacks never return the buyer_key.

For Israeli direct debit, approving a new authorization creates a buyer key behind the scenes; read it with this call.

Which credential to send

Send the credential in the JSON body; a PayMe-Partner-Key header alone isn't enough.

A direct seller has no partner key, so it must save the token with buyer_is_private: true to read it back.

Parameters

This endpoint takes no path, query or header parameters.

Request body

Content type: application/json

Request example

{
  "payme_client_key": "XXXXXXXX",
  "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
  "language": "en"
}

Code samples

curl

curl -X POST 'https://sandbox.payme.io/api/get-buyer-key' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "payme_client_key": "XXXXXXXX",
  "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
  "language": "en"
}'

Node.js

const response = await fetch("https://sandbox.payme.io/api/get-buyer-key", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "payme_client_key": "XXXXXXXX",
    "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/get-buyer-key",
    json={
        "payme_client_key": "XXXXXXXX",
        "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
        "language": "en",
    },
)

print(response.text)

PHP

<?php

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

$ch = curl_init('https://sandbox.payme.io/api/get-buyer-key');
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 saved card. (success)

{
  "status_code": 0,
  "payme_sale_id": "SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
  "buyer_key": "BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567",
  "buyer_card_mask": "532610******5846",
  "buyer_card_expiry": "1230",
  "buyer_card_brand": "MasterCard",
  "session": "Ab12Cd34"
}

400 — Error 1: neither payme_sale_id nor sub_payme_id sent. Error 20: both sent. Error 600: no saved card on this sale or subscription, or the sale isn't paid (status_additional_info then holds its status, initial or failed). (error)

{
  "status_code": 1,
  "status_error_details": "Buyer not found",
  "status_additional_info": "No Buyer for Sale",
  "status_error_code": 600,
  "session": "Ab12Cd34"
}

403 — Error 603: seller_payme_id sent for an account-level token. Error 303 (sale) or 370 (subscription): it belongs to another partner. (error)

{
  "status_code": 1,
  "status_error_details": "Merchant not allowed to use this buyer",
  "status_additional_info": "",
  "status_error_code": 603,
  "session": "Ab12Cd34"
}

500 — Request errors. 1: neither payme_client_key nor seller_payme_id in the body. 200: unknown partner key. 251: unknown seller. 350: no sale has this ID. 605: a seller-level token read with another seller's MPL. (error)

{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "payme_client_key / seller_payme_id",
  "status_error_code": 1,
  "session": "Ab12Cd34"
}