OAuth 2.0 API Introduction

Introduction

Purpose

This specification defines the authentication and authorization protocol used between the Requestor and the Issuer for real-time transaction authorization.

The protocol is based on OAuth 2.0 using the Client Credentials Grant with private_key_jwt client authentication. Authorization requests and responses are protected end-to-end using JSON Web Encryption (JWE).

This specification defines the protocol contract only. Implementation details (frameworks, code, deployment) are outside the scope of this document.

Throughout this document the keywords MUST, SHOULD and MAY are to be interpreted as described in RFC 2119. All concrete values — domains, identifiers, keys, card numbers, amounts and timestamps — are illustrative examples only and do not constitute agreed values or a contract.

Terminology

Term	Description
Issuer	OAuth Authorization Server and Resource Server; authorization decision authority
Requestor	OAuth Client invoking the Authorization API
Access Token	JWT (JWS, ES256) issued by the Issuer
Client Assertion	JWT used to authenticate the Requestor (private_key_jwt)
JWK / JWKS	JSON Web Key / JSON Web Key Set
JWS	JSON Web Signature
JWE	JSON Web Encryption

Supported Standards

Standard	Description
RFC 6749	OAuth 2.0 Authorization Framework
RFC 7515	JSON Web Signature (JWS)
RFC 7516	JSON Web Encryption (JWE)
RFC 7517	JSON Web Key (JWK)
RFC 7518	JSON Web Algorithms (JWA)
RFC 7519	JSON Web Token (JWT)
RFC 7523	JWT Profile for OAuth 2.0 Client Authentication

Protocol Flow

Requestor
   | 1. Request access token (client_credentials + private_key_jwt)
   v
Issuer Token Endpoint
   | 2. JWT access token (ES256)
   v
Requestor
   | 3. POST Authorization API
   |     Authorization: Bearer <token>
   |     Body: JWE (encrypted with Issuer RSA public key)
   v
Issuer
   |     - Validate access token
   |     - Decrypt request
   |     - Process authorization decision
   |     - Encrypt response (with Requestor RSA public key)
   v
Requestor (decrypts JWE response)

Endpoints

Token Endpoint

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

Purpose: issue an OAuth 2.0 access token. The Requestor authenticates with private_key_jwt (no client_secret).

Request parameters:

Parameter	Required	Value / Notes
client_id	Yes	oob-client
grant_type	Yes	client_credentials
scope	Yes	START_OOB/ CHECK_OOB
client_assertion_type	Yes	urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion	Yes	Signed ES256 JWT (see §6)

Example (illustrative):

client_id=oob-client
grant_type=client_credentials
scope=START_OOB+CHECK_OOB
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<signed_jwt>

JWKS Endpoint

GET /.well-known/jwks.json

Purpose: expose the Issuer public keys. The endpoint MUST publish:

1. EC signing public key — used by the Requestor to verify the access token.
2. RSA encryption public key — used by the Requestor to encrypt the authorization request.

Each published JWK MUST carry a kid matching the kid used in the corresponding JWS/JWE header.

Client Authentication (private_key_jwt)

The Requestor MUST authenticate using OAuth 2.0 private_key_jwt (RFC 7523). The client_assertion is a JWT signed with the Requestor's EC private key (ES256).

JWT Header

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "requestor-key-01"
}

Required Claims

Claim	Required	Constraint
iss	Yes	MUST equal client_id
sub	Yes	MUST equal client_id
aud	Yes	MUST equal the token endpoint URL
exp	Yes	Short-lived; SHOULD be ≤ 5 minutes after iat
iat	Yes	Issued-at time
jti	Yes	Unique; MUST NOT be reused (replay protection)

The Issuer MUST reject an assertion failing signature verification, any claim constraint, or a clock skew greater than ±5 minutes.

Access Token

The Issuer MUST issue a JWT access token signed with its EC private key (ES256). Header carries alg=ES256 and the Issuer signing kid.

Required Claims

Claim	Description
iss	Issuer identifier
sub	Client identifier
aud	Authorization API audience
scope	Authorized scope (ACS)
iat	Issued-at time
exp	Expiration time

Token response example (illustrative):

{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "ACS"
}

Key Distribution

Both parties exchange only public keys; private keys MUST NEVER be exposed.

Key	Owner	Used by	Purpose	Distribution
EC public	Issuer	Requestor	Verify access token	Issuer JWKS
RSA public	Issuer	Requestor	Encrypt request	Issuer JWKS
EC public	Requestor	Issuer	Verify client_assertion	Registration / Requestor JWKS
RSA public	Requestor	Issuer	Encrypt response	Registration / Requestor JWKS

OAuth Error Responses

Token Endpoint

Per RFC 6749 §5.2, all token-endpoint errors return HTTP 400 except invalid_client, which returns HTTP 401.

HTTP	Error	Meaning
400	invalid_request	Malformed or missing parameters
400	invalid_grant	Invalid / expired client_assertion
400	invalid_scope	Requested scope not allowed
401	invalid_client	Client authentication failed

Example (illustrative):

{
  "error": "invalid_client"
}

Security Requirements

Transport

1. HTTPS is mandatory; TLS 1.2 or later MUST be supported.

Replay Protection

The Issuer MUST validate:

1. jti uniqueness (reject duplicates).

Access Token Validation

Before processing a request, the Issuer MUST validate the access token: JWT signature, issuer, audience, expiration and scope.

Key Management

1. Public keys distributed via the JWKS endpoint(s); private keys never exposed.
2. Private keys SHOULD be stored in an HSM/KMS and rotated periodically (e.g. every 90 days).
3. RSA keys MUST be ≥ 2048-bit.

Supported Algorithms

Usage	Algorithm
JWS signature (access token, client_assertion)	ES256
JWE key management	RSA-OAEP-256
JWE content encryption	A128GCM

Conformance

A conforming implementation MUST:

1. Support the OAuth 2.0 Client Credentials Grant.
2. Support private_key_jwt client authentication (ES256).
3. Issue and validate JWT access tokens (ES256).
4. Expose public keys via JWKS.
5. Support JWE Compact Serialization for requests and responses.
6. Encrypt requests to the Issuer RSA public key and responses to the Requestor RSA public key (RSA-OAEP-256 + A128GCM).
7. Enforce replay protection (jti).
8. Validate all mandatory security requirements in §12.

API List

No.	Module	API Name	API Description	Prepaid	Debit	Remark
1	Application	CardApplication	Support both Physical / virtual card application (delivery address is mandatory for Physical card)	M	M
2	Customer	CustomerCardInfoInquiry	Return the card information (including card status) with inquiry of the customer id	M	M
3		CustomerAccountInfoInquiry	Return the account information (including account status) with inquiry of the customer id	O	NA
4		CustomerInfoUpdate	For customer Information maintenance, including mobile number, email address, address (delivery address for physical card)…	O	O
5	Account	AccountLinkage	Associate a card with an account	O	O
6		AccountStatusUpdate	Change Account Status including block, close etc.	O	NA
7	Card	CardInfoInquiry	Return card information, card plastic status and status date, renew/reissuing information and other card-related information	O	O
8		CardActivation	Activate a card	O	O
9
10		CardReplacement	Support Card Replacement with Same Card number or Specific card number or Random card number; Also can be used to convert virtual card to physical card	O	O
11		CardCancellation	Card Cancellation with reason codes or memo	O	O
12		CardStatusUpdate	Change Card Status including lost, stolen, block etc.	C	C
13		CardLimitSetting	Set transaction limit + Domestic/Oversea & e-commerce/POS Transaction Indicator	O	O	Card level limit control
14		CardCVV2Inquiry	Retrieve Card number, expiry date, CVV2 by card token	O	NA	Only for virtual card
15		CardCVV2Verify	Verify CVV2 by card token	O	NA	Only for virtual card
16		GenerateDCVV	Generate a new CVV2	O	O
17		CardExpiryDateUpdate	Update Card Expiry Date		NA
18		CardSecureRegist	3D-Secure Service for cardholder. if registered, the cardholder will get OTP by mail /SMS when e-commerce transaction need authentication	O	O	If use Coshine’s ACS Services
19		BlacklistUpdate	Insert or delete blacklist or whitelist card	NA	NA	Old Version. Not used now.
20		PINReset	Reset Card PIN	O	M	If card support online PIN
21		PINChange	Change Card PIN	O	M
22		PINVerify	Verify Card PIN	O	O
23	Transaction	BalanceInquiry	Balance Inquiry	O	NA	Wallet / Banking system will provide their own API if account is controlled by their system
24		LoadFund	Load fund / Payment to card account	O	NA
25		Withdraw	Withdraw in ATM	C	NA	If prepaid card support ATM transaction
26		TransferFund	Transfer between two card	O	NA
27		Purchase	Purchase /Sale transaction	C	NA
28		Refund	Refund or Void transaction	C	NA
29		Reversal	Reversal for LoadFund , Withdraw, TransferFund and Purchase	M	NA
30		BlockFund	For Preauthorization or other purpose to block the amount	C	NA	If prepaid card support pre-auth / block fund
31		UnblockFund	Release/ Partial release preauthorization	C	NA
32		ServiceCharge	Service Fee charge	O	NA
33		Verification	Card/Account Verification	O	NA
34		DebitAdjustment	Debit Adjustment (Miscellaneous adjustment with memo)	O	NA
35		CreditAdjustment	Credit Adjustment (Miscellaneous adjustment with memo)	O	NA
36		TransactionHistory	Inquiry Transaction History by token number	M	NA
37		AuthorizationHistory	Inquiry Authorization History by token number	O	NA
38	Token	TokenInquiry	Inquiry token information by card number.
39		TokenRequest	After Generated UnionPay Virtual PAN based on issuer’s mobile APP Account, initialize Token for the Virtual PAN.
40		TokenStateUpdate	When the Cardholder or the mobile application suspends, resumes, or deletes the card, the mobile application shall send the Token State Update request to change the state of the Token.
41		TokenStateNotification	When the UMPS suspends, resumes, or deletes the card, the UMPS will send the Token State Notification request to notify the mobile application.
42		TokenMetadataUpdate	The Token metadata, e.g., Token expiry date, needs to be updated from the mobile application’s side if the PAN expiry date has already been renewed.
43		ReplenishTokenLUK	Mobile application will call SDK API “tokenValidForProcessing” to check if there are available LUKs in SDK before payment for a given Token identified by the Token ID
44	Authentication	SendOTP	Direct OTP authentication request to issuer
45		VerifyOTP	Request to verify the OTP provided
46		StartOOBAuthen	Direct OOB authentication request to issuer
47		OOBResultInquiry	Inquiry the result of OOB authentication
48	Parameter	DropDownListInquiry	Retrieve lookup table from our system, such as reason list for card replacement