Request PIN Control Access Token

curl --request POST \
  --globoff \
  --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 and is single-use: it is consumed by the first successful operation, so a reused or expired token is rejected. The token only authorises the scope it was created with; using it for another operation returns 400.

For the mobile webview flow, the device sends another API request — a POST to the pinUrl with an application/json request body containing the token id in a field named pinControlId.

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 pinControlId field (the token id).

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

For the SET_PIN and CHANGE_PIN scopes, the cardholder submits the PIN with the button inside the iframe. If you prefer to drive the submission from your own page instead, send a second window.postMessage() call with the operation field set to set-pin-set and no other fields; the iframe then submits the PIN currently entered in it.

POST

cards

{id}

pinControl

Request PIN Control Access Token

curl --request POST \
  --globoff \
  --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"

Introduction

Cards API

Cardholders API

PIN API

Wallet API

Transaction Lifecycle

Spend Controls API

Exchange Rates API

Fee Configuration

Request PIN Control Access Token

Authorizations

Headers

Path Parameters

Body

Response