Start 3D Secure authentication

• Sandbox: POST https://sandbox.payme.io/api/sales/{payme_sale_id}/3ds
• Production: POST https://live.payme.io/api/sales/{payme_sale_id}/3ds

Credentials

• Header PayMe-Public-Key (API key)

Overview

Starts 3D Secure 2 authentication for a card on an existing sale, without charging it. Use it when another gateway processes the payment and you need the 3DS values (eci, cavv, xid) from PayMe's MPI. The whole flow: Standalone 3D Secure: process flow.

Call it from the buyer's browser with the seller's public key in the PayMe-Public-Key header. The sale must belong to that seller. Send the browser data that PayMe's JS library collected (meta_data_jwt); see 3DS integration using JS API.

The response has one of two outcomes:

• status_code 0: frictionless approval. Pass hash_3dsecure to your server and resolve it with Resolve a 3D Secure hash.
• status_code 5: the issuer wants a challenge. Send the buyer to redirect_url (a GET request). After the challenge, the hash comes back to the page that opened it.

The seller must have the 3D Secure service active.

Errors

Parameters

Request body

Content type: application/json

Request example

{
  "payment": {
    "method": "credit-card",
    "card_number": "4111111111111111",
    "card_expiry": "1230"
  },
  "customer": {
    "name": "Israel Israeli",
    "email": "buyer@example.com",
    "phone": "0500000000"
  },
  "meta_data_jwt": "META_DATA_JWT_FROM_THE_LIBRARY"
}

Code samples

curl

curl -X POST 'https://sandbox.payme.io/api/sales/<payme_sale_id>/3ds' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Public-Key: <PayMe-Public-Key>' \
  --data-raw '{
  "payment": {
    "method": "credit-card",
    "card_number": "4111111111111111",
    "card_expiry": "1230"
  },
  "customer": {
    "name": "Israel Israeli",
    "email": "buyer@example.com",
    "phone": "0500000000"
  },
  "meta_data_jwt": "META_DATA_JWT_FROM_THE_LIBRARY"
}'

Node.js

const response = await fetch("https://sandbox.payme.io/api/sales/<payme_sale_id>/3ds", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Public-Key": "<PayMe-Public-Key>",
  },
  body: JSON.stringify({
    "payment": {
      "method": "credit-card",
      "card_number": "4111111111111111",
      "card_expiry": "1230"
    },
    "customer": {
      "name": "Israel Israeli",
      "email": "buyer@example.com",
      "phone": "0500000000"
    },
    "meta_data_jwt": "META_DATA_JWT_FROM_THE_LIBRARY"
  }),
});

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

Python

import requests

response = requests.post(
    "https://sandbox.payme.io/api/sales/<payme_sale_id>/3ds",
    headers={
        "PayMe-Public-Key": "<PayMe-Public-Key>",
    },
    json={
        "payment": {
            "method": "credit-card",
            "card_number": "4111111111111111",
            "card_expiry": "1230",
        },
        "customer": {
            "name": "Israel Israeli",
            "email": "buyer@example.com",
            "phone": "0500000000",
        },
        "meta_data_jwt": "META_DATA_JWT_FROM_THE_LIBRARY",
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "payment": {
    "method": "credit-card",
    "card_number": "4111111111111111",
    "card_expiry": "1230"
  },
  "customer": {
    "name": "Israel Israeli",
    "email": "buyer@example.com",
    "phone": "0500000000"
  },
  "meta_data_jwt": "META_DATA_JWT_FROM_THE_LIBRARY"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/sales/<payme_sale_id>/3ds');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'PayMe-Public-Key: <PayMe-Public-Key>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

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

echo $response;

Responses

200 — Frictionless approval (0) or a challenge (5). (success)

{
  "status_code": 5,
  "status_message": "Generating validation page, please wait",
  "redirect_url": "https://sandbox.payme.io/3ds/redirect/SALE1700-000000AA-EXAMPLE1-SALE0001?pa=REDACTED"
}

400 — Browser data is missing, the sale uses another payment method, or 3D Secure was blocked. Codes: 4, 670, 720. (error)

{
  "status_code": 1,
  "status_error_details": "Meta data details are missing",
  "status_additional_info": null,
  "status_error_code": 670,
  "session": "a1B2c3D4"
}

500 — 3D Secure isn't available, the sale wasn't found, or the card data is invalid. See the error table. (error)

{
  "status_code": 1,
  "status_error_details": "Invalid credit card expiry",
  "status_additional_info": "1221f",
  "status_error_code": 356,
  "session": "a1B2c3D4"
}