Create a partner-level token

• Sandbox: POST https://sandbox.payme.io/api/sellers/{mpl}/tokens
• Production: POST https://live.payme.io/api/sellers/{mpl}/tokens

Credentials

• Request body field options.validate_token (optional): Check the card with the issuer before saving it. Default true.

Overview

For PayMe partners only. Saves a card as a token that belongs to your partner account, so you can charge it later for any of your sellers. A buyer saves a card while buying from one seller and can then pay another seller without typing it again. A seller-level token can't do that.

The MPL in the path (the seller_payme_id of one of your sellers) identifies your account; the call takes no other key. Treat the MPL as a secret: call this endpoint from your server only, never from a browser.

This endpoint takes raw card details, so call it only if you are PCI DSS certified. Without that certification, capture the same kind of token on a page PayMe hosts: send generate-sale with sale_type: "seller-token" and show the buyer its sale_url. PayMe sets the price of such a sale itself.

Using the token

The token is the uuid in the response. Send it as token on generate-sale, with the seller_payme_id of the seller you are charging for. It is not a buyer_key: sent as buyer_key, it fails with error 600. Against a seller of a different partner it fails with error 605.

The token is permanent: it doesn't expire in PayMe, and each charge with it runs at once, with no CVV and no 3D Secure. A charge can still fail if the card has expired or the issuer declines it.

The response isn't PayMe's usual envelope. A success has no status_code, so check for HTTP 201 and a uuid. A failure has the usual status_code: 1 and status_error_code; decide from those, not from the HTTP status.

A token is a bearer credential: store it encrypted, and never log it or send it to a browser. See Saved Cards for the rules.

This page covers credit-card, the method checked in the sandbox.

Parameters

Request body

Content type: application/json

Request example

{
  "payment": {
    "method": "credit-card",
    "card_number": "4557430402053431",
    "card_expiry": "1230",
    "card_cvv": "200"
  },
  "customer": {
    "name": "First Last",
    "email": "buyer@example.com",
    "phone": "+972501234567",
    "social_id": "008336174"
  }
}

Code samples

curl

curl -X POST 'https://sandbox.payme.io/api/sellers/<mpl>/tokens' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "payment": {
    "method": "credit-card",
    "card_number": "4557430402053431",
    "card_expiry": "1230",
    "card_cvv": "200"
  },
  "customer": {
    "name": "First Last",
    "email": "buyer@example.com",
    "phone": "+972501234567",
    "social_id": "008336174"
  }
}'

Node.js

const response = await fetch("https://sandbox.payme.io/api/sellers/<mpl>/tokens", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "payment": {
      "method": "credit-card",
      "card_number": "4557430402053431",
      "card_expiry": "1230",
      "card_cvv": "200"
    },
    "customer": {
      "name": "First Last",
      "email": "buyer@example.com",
      "phone": "+972501234567",
      "social_id": "008336174"
    }
  }),
});

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

Python

import requests

response = requests.post(
    "https://sandbox.payme.io/api/sellers/<mpl>/tokens",
    json={
        "payment": {
            "method": "credit-card",
            "card_number": "4557430402053431",
            "card_expiry": "1230",
            "card_cvv": "200",
        },
        "customer": {
            "name": "First Last",
            "email": "buyer@example.com",
            "phone": "+972501234567",
            "social_id": "008336174",
        },
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "payment": {
    "method": "credit-card",
    "card_number": "4557430402053431",
    "card_expiry": "1230",
    "card_cvv": "200"
  },
  "customer": {
    "name": "First Last",
    "email": "buyer@example.com",
    "phone": "+972501234567",
    "social_id": "008336174"
  }
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/sellers/<mpl>/tokens');
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

201 — The token was created (success)

{
  "uuid": "00000000-0000-0000-0000-000000000000",
  "customer": {
    "name": "First Last",
    "email": "buyer@example.com",
    "phone": "+972501234567",
    "social_id": "008336174"
  },
  "payment": {
    "display": "455743******3431",
    "expiry": "1230",
    "brand": "Visa"
  }
}

400 — The card was declined or failed validation. Read status_code and status_error_code. (error)

{
  "status_code": 1,
  "status_error_code": 20004,
  "status_error_details": "Refusal by credit company. Please try a different card",
  "status_additional_info": "400000******0002"
}

500 — A required field is missing or invalid (error)

{
  "status_code": 1,
  "status_error_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "payment.card_cvv"
}