Request PIN Control Access Token

curl --request POST \
  --url 'https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope": "VIEW_PIN",
  "sequenceNumber": 1
}
'

import requests

url = "https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl"

payload = {
    "scope": "VIEW_PIN",
    "sequenceNumber": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({scope: 'VIEW_PIN', sequenceNumber: 1})
};

fetch('https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'scope' => 'VIEW_PIN',
    'sequenceNumber' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl"

	payload := strings.NewReader("{\n  \"scope\": \"VIEW_PIN\",\n  \"sequenceNumber\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"scope\": \"VIEW_PIN\",\n  \"sequenceNumber\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"scope\": \"VIEW_PIN\",\n  \"sequenceNumber\": 1\n}"

response = http.request(request)
puts response.read_body

{
  "id": "20218aae-b15e-406c-9e9f-23735cd86a48",
  "pinUrl": "https://api.tenant.sandbox.mycore.enfuce.com/issuer-web/pin/view",
  "pinFrameUrl": "https://api.tenant.sandbox.mycore.enfuce.com/issuer-web/pin/view/frame"
}

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "JSON parse error: Unexpected character...",
  "instance": "/v1/cards",
  "id": "5cc541cb-f456-4331-b537-d2380fca0400",
  "timestamp": "2026-02-24T12:34:56Z"
}

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access Denied",
  "instance": "/v1/cards",
  "id": "5cc541cb-f456-4331-b537-d2380fca0403",
  "timestamp": "2026-02-24T12:34:56Z"
}

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Entity not found - Program with id: 2ec117b7-454e-4cc5-8b89-dea5485aab2b",
  "instance": "/v1/cards",
  "id": "5cc541cb-f456-4331-b537-d2380fca0404",
  "timestamp": "2026-02-24T12:34:56Z"
}

{
  "type": "about:blank",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Unexpected error occurred.",
  "instance": "/v1/cards",
  "id": "5cc541cb-f456-4331-b537-d2380fca0500",
  "timestamp": "2026-02-24T12:34:56Z"
}

Cards API

Request PIN Control Access Token

Send a request to this endpoint to generate a PIN control access token for a specific card version. The requested scope determines which PIN operation the token authorises: VIEW_PIN, SET_PIN or CHANGE_PIN. If no sequenceNumber is provided, the latest card version is used.

For the SET_PIN scope, sequenceNumber is ignored and the latest card version is always used, because a PIN can only be set on the latest card version.

For multi-application cards, the SET_PIN and CHANGE_PIN scopes can only be requested for the main card, not for its card applications; requesting either scope for a card application returns 400.

A successful response returns the token id, a pinUrl for the mobile device webview and a pinFrameUrl for the desktop browser iframe. Both URLs are specific to the requested scope. The token is valid for 30 seconds.

For the mobile webview flow, the device sends another API request — a POST to the pinUrl, including the token id in a parameter named controlId.

For the desktop browser flow, open an iframe to the pinFrameUrl. After the iframe has loaded, the browser makes a window.postMessage() call to the iframe. The message object contains an operation field (view-pin for the VIEW_PIN scope, set-pin for the SET_PIN and CHANGE_PIN scopes) and a controlId field (the token id).

Note that you must use set-pin as the operation for the CHANGE_PIN scope as well.

POST

cards

{id}

pinControl

Request PIN Control Access Token

curl --request POST \
  --url 'https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope": "VIEW_PIN",
  "sequenceNumber": 1
}
'

import requests

url = "https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl"

payload = {
    "scope": "VIEW_PIN",
    "sequenceNumber": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({scope: 'VIEW_PIN', sequenceNumber: 1})
};

fetch('https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'scope' => 'VIEW_PIN',
    'sequenceNumber' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl"

	payload := strings.NewReader("{\n  \"scope\": \"VIEW_PIN\",\n  \"sequenceNumber\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"scope\": \"VIEW_PIN\",\n  \"sequenceNumber\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer/v1/cards/{id}/pinControl")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"scope\": \"VIEW_PIN\",\n  \"sequenceNumber\": 1\n}"

response = http.request(request)
puts response.read_body

{
  "id": "20218aae-b15e-406c-9e9f-23735cd86a48",
  "pinUrl": "https://api.tenant.sandbox.mycore.enfuce.com/issuer-web/pin/view",
  "pinFrameUrl": "https://api.tenant.sandbox.mycore.enfuce.com/issuer-web/pin/view/frame"
}

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "JSON parse error: Unexpected character...",
  "instance": "/v1/cards",
  "id": "5cc541cb-f456-4331-b537-d2380fca0400",
  "timestamp": "2026-02-24T12:34:56Z"
}

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access Denied",
  "instance": "/v1/cards",
  "id": "5cc541cb-f456-4331-b537-d2380fca0403",
  "timestamp": "2026-02-24T12:34:56Z"
}

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Entity not found - Program with id: 2ec117b7-454e-4cc5-8b89-dea5485aab2b",
  "instance": "/v1/cards",
  "id": "5cc541cb-f456-4331-b537-d2380fca0404",
  "timestamp": "2026-02-24T12:34:56Z"
}

{
  "type": "about:blank",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Unexpected error occurred.",
  "instance": "/v1/cards",
  "id": "5cc541cb-f456-4331-b537-d2380fca0500",
  "timestamp": "2026-02-24T12:34:56Z"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-audit-user

string

Optional audit user header

Path Parameters

string<uuid>

required

Unique identifier of the card for which you want to access the PIN.

Body

application/json

scope

enum<string>

required

Describes the scope of the operation authorised by the user.

Available options:

VIEW_PIN,

SET_PIN,

CHANGE_PIN

Example:

"VIEW_PIN"

sequenceNumber

integer

The sequence number of the card version, this value is also known as PSN (pan sequence number)

Required range: x >= 1

Example:

1

Response

Successful creation of the PIN control access token

string<uuid>

required

The ID of this PIN Control access token.

Example:

"20218aae-b15e-406c-9e9f-23735cd86a48"

pinUrl

string

The URL that the cardholder's mobile device webview should browse to for accessing the PIN.

Example:

"https://api.tenant.sandbox.mycore.enfuce.com/issuer-web/pin/view"

pinFrameUrl

string

The URL of the iframe for desktop browser based flows for accessing PIN.

Example:

"https://api.tenant.sandbox.mycore.enfuce.com/issuer-web/pin/view/frame"

⌘I

Introduction

Cards API

Cardholders API

PIN API

Wallet API

Transaction Lifecycle

Spend Controls API

Exchange Rates API

Request PIN Control Access Token

Authorizations

Headers

Path Parameters

Body

Response