Issuing Management API

danger

This part have released for public.

The Issuing management API is about how to create and manage your cards through OpenAPI.

Cards are divided into B2B cards and B2C cards, suitable for different business needs:

Cards API

The Cards API is a core interface for card management systems, which is used to manage card statuses and edit card limits, among other operations such as updating cardholder information.

info

The cards need to be purchased in one batch through the business team. After the purchase is completed, a document containing all card information will be delivered to you. Therefore, there is no need to create cards via the online API.

Lock Card: If you want to temporarily deactivate the card, then please change the card status to Locked via the card lock API, the Locked status of the card will not allow any transactions.
Unlock Card: If the temporary deactivation is expected to be terminated, then the card can be brought back into normal use via the Unlock Card API.
Termination Card: If it is decided that the card is no longer to be used, the card is terminated via the Card Termination API.

info

which is used to terminate the card. Unlike the Lock Card API, terminating a card is permanent and unrecoverable.

Card Limit

In addition to specifying the limit policy when creating the card, it can be modified through the Edit Card Limit Configure API. We support 4 different rules at the same time, if you want to disable a rule, set the amount to 0.

Transaction: Maximum limit per transaction.
Daily: Aggregate limit within a single natural day.
Monthly: Aggregate limit within a single natural month.
Lifetime: Aggregate limit within whole lifetime.

Physical card activation

When the bulk card purchase is completed, the virtual cards will be activated immediately and ready for direct use. However, physical cards require a PIN code setup to initiate the activation process.

Generate keys using the ECDSA algorithm
Send a POST request to the Exchange Key API to exchange keys
Calculate and obtain the secretKey using the returned key
Encrypt the password with the secretKey and send a POST request to the Set Pin And Card Active API

Get Full Card Number

The full card number is extremely sensitive information and also requires ECDSA encrypted transmission in requests.

ECDSA Sample Code - Golang

This process implements a secure workflow for physical card activation and PIN code setup, leveraging Elliptic Curve Cryptography (ECC) (ECDSA for key generation, ECDH for key exchange), SHA-256 for key derivation, and JWE (JSON Web Encryption) for PIN encryption. The core goal is to ensure the secure transmission of the PIN code during the card activation process by avoiding plaintext transmission and using ephemeral key exchange.

Generate ECDSA Key Pair: Generate an Elliptic Curve Digital Signature Algorithm (ECDSA) key pair using the NIST P-256 (secp256r1) curve, a widely adopted 256-bit elliptic curve standard for balancing security and performance. The key pair consists of a private key (a large random integer) and a public key (a point on the curve represented by X/Y coordinates). Additionally, generate a unique Key ID (Kid) to identify this key pair.
Exchange Keys via the Exchange Key API: Send a POST request to the /svc/card_issuer/api/v1/pci_session endpoint (Exchange Key API) with the ECDSA public key (X/Y coordinates in hex string format) and Kid. The server responds with its ephemeral public key (EphemPubKey) in JWK (JSON Web Key) format, which is also based on the P-256 curve.
Derive SecretKey via ECDH and SHA-256: ECDH Key Exchange: Use the client's ECDSA private key and the server's ephemeral public key to compute a shared secret via the Elliptic Curve Diffie-Hellman (ECDH) algorithm. Both parties (client and server) can independently compute the same shared secret without transmitting it directly.Key Derivation Function (KDF): Combine the shared secret with context data (e.g., Kid) and apply the SHA-256 hash function to derive a fixed-length (32-byte) symmetric key (secretKey). This step enhances key uniqueness and security by incorporating additional context.
Encrypt PIN with SecretKey and Call Set Pin And Card Active API: Encrypt the PIN code using the derived secretKey with the JWE (JSON Web Encryption) standard in DIRECT encryption mode (a lightweight symmetric encryption mode for short data). Send a POST request to the /api/v1/pci_pin_with_session endpoint with the JWE-encrypted data to complete PIN setup and physical card activation.

// Global constants and dependencies
CONST P256_CURVE = NIST P-256 (secp256r1)
CONST KEY_SIZE = 32  // 256 bits for SHA-256 derived key
CONST EXCHANGE_KEY_API = "/svc/card_issuer/api/v1/pci_session"
CONST SET_PIN_ACTIVE_API = "/api/v1/pci_pin_with_session"

// Step 1: Generate ECDSA key pair and Kid
FUNCTION generateECDSAKeyPair():
    // Generate ECDSA private key using cryptographically secure random number generator
    privateKey = ECDSA.GenerateKey(P256_CURVE, CryptRandom.Reader)
    // Extract public key (X/Y coordinates) from the private key
    publicKey = privateKey.PublicKey
    // Encode X/Y coordinates to hex strings for API transmission
    pubKeyX = Hex.Encode(publicKey.X.Bytes())
    pubKeyY = Hex.Encode(publicKey.Y.Bytes())
    // Generate unique Key ID (Kid) for the key pair
    kid = UUID.Generate()
    RETURN privateKey, pubKeyX, pubKeyY, kid

// Step 2: Call Exchange Key API to get server's ephemeral public key
FUNCTION exchangeKeys(pubKeyX, pubKeyY, kid):
    // Build request payload (JWK format for ECC key)
    requestPayload = {
        "kty": "EC",
        "crv": "P-256",
        "kid": kid,
        "x": pubKeyX,
        "y": pubKeyY
    }
    // Send POST request to Exchange Key API
    response = HTTP.Post(EXCHANGE_KEY_API, requestPayload)
    // Parse response to extract server's ephemeral public key (JWK)
    serverEphemPubKey = response.jwk
    RETURN serverEphemPubKey

// Step 3: Derive secretKey using ECDH and SHA-256 KDF
FUNCTION deriveSecretKey(clientPrivateKey, serverEphemPubKey, kid):
    // Decode server's X/Y hex strings to big integers
    sdkX = Hex.Decode(serverEphemPubKey.x)
    sdkY = Hex.Decode(serverEphemPubKey.y)
    x = BigInt.FromBytes(sdkX)
    y = BigInt.FromBytes(sdkY)

    // Validate if the server's public key is on the P-256 curve (security check)
    IF NOT P256_CURVE.IsOnCurve(x, y):
        THROW Error("Server public key is not on P-256 curve")

    // Construct server's ECDSA public key object
    serverPublicKey = ECDSA.PublicKey(Curve = P256_CURVE, X = x, Y = y)

    // Compute ECDH shared secret
    clientECDHKey = clientPrivateKey.ECDH()
    serverECDHKey = serverPublicKey.ECDH()
    sharedSecret = clientECDHKey.ECDH(serverECDHKey)

    // Build combined data for KDF: alg + apuData + apvData + kid + sharedSecret
    combinedData = Concat(EmptyBytes, EmptyBytes, kid.Bytes(), sharedSecret)

    // Apply SHA-256 hash and truncate to key size
    derivedKey = SHA256.Hash(combinedData)
    secretKey = derivedKey[:KEY_SIZE]

    RETURN secretKey

// Step 4: Encrypt PIN with secretKey via JWE and call activation API
FUNCTION encryptPINAndActivate(secretKey, kid, pinCode):
    // Build payload with PIN code
    pinData = {
        "password": pinCode
    }
    pinDataBytes = JSON.Marshal(pinData)

    // Build JWE protected headers (include Kid for key identification)
    jweHeaders = JWE.NewHeaders()
    jweHeaders.Set("kid", kid)

    // Encrypt PIN data using JWE DIRECT mode with secretKey
    jweBlock = JWE.Encrypt(
        plaintext = pinDataBytes,
        key = secretKey,
        algorithm = JWA.DIRECT,
        headers = jweHeaders
    )

    // Send POST request to Set Pin And Card Active API
    activationResponse = HTTP.Post(SET_PIN_ACTIVE_API, jweBlock)

    RETURN activationResponse

// Main workflow
FUNCTION main(pinCode):
    // Step 1: Generate ECDSA key pair
    privateKey, pubKeyX, pubKeyY, kid = generateECDSAKeyPair()

    // Step 2: Exchange keys with server
    serverEphemPubKey = exchangeKeys(pubKeyX, pubKeyY, kid)

    // Step 3: Derive secretKey
    secretKey = deriveSecretKey(privateKey, serverEphemPubKey, kid)

    // Step 4: Encrypt PIN and activate card
    activationResult = encryptPINAndActivate(secretKey, kid, pinCode)

    PRINT "Card activation result: ", activationResult

Field	Comment
p_business_id	your wonder side merchant id
card_reference_id	the card identifier
verification_id	the verification identifier
business_name	name of the p_business_id
card_num	desensitized card number information
transaction_currency	the transaction currency
transaction amount	the transaction amount
merchant_id	the transaction merchant id
merchant_city	the transaction merchant city
merchant_name	the transaction merchant name
otp_code	OTP code of the verification, 6 digits

Action	Description
Authorization	When new transaction authorized
Reversed	When transaction void from acquirer side
Settled	Settled an authorized transaction

Field	Comment
id	the transaction id
p_business_id	your wonder side merchant id
card	the wonder card id
type	transaction type
transaction_currency	the transaction currency
transaction amount	the transaction amount
local currency	billing currency
local amount	billing_amount
calculated_fee	total transaction fee of local_currency
billing_currency	equal to local_currency
billing_amount	total billing_amount, includes calculated_fee
merchant_id	the transaction merchant id
merchant_city	the transaction merchant city
merchant_name	the transaction merchant name

Issuing Management API

Cards API​

Card Limit​

Physical card activation​

Get Full Card Number​

ECDSA Sample Code - Golang​

Users API​

Wallet API​

Platform Transfer API​

Create platform transfer​

Balance API​

Process 3DS Verification​

Realtime Webhook​

Actions​

Request Body​

Cards API

Card Limit

Physical card activation

Get Full Card Number

ECDSA Sample Code - Golang

Users API

Wallet API

Platform Transfer API

Create platform transfer

Balance API

Process 3DS Verification

Realtime Webhook

Actions

Request Body