Card Issuing

Issue multi-currency JCB cards at scale. Cards can be used for local transactions and international payments at ultra-low rates. The Issuing API lets you manage card statuses, set spending limits, activate physical cards, and track every transaction in real time via webhooks.

Card management

Everything about the card itself — types, data model, lifecycle statuses, spending controls, and operations you can perform on individual cards.

Workflow

1 Select the card typeDOCthat you want to integrate with and contact with our Wonder support@wonder.app.

2 Choose if you need virtual card or physical card or both.

3 To enable card spend, you need to add fundDOC .

4 (Optional)Set up spending limitDOC, if you dont set, then the card limit is 100,000,000,000.00HKD.

5 Simulate the card transaction via card simulator.

Card types

Cards are provisioned in bulk by the Wonder team — there is no API to create cards. Once delivered, you manage them through the cards API. Two card models are available depending on how funds are structured.

Card model

A card is identified by its UUID and card_reference_id. Sensitive data (full PAN) is encrypted and requires an ECDSA exchange keyDOC to get full card numberAPI.

Statuses

Card.status: The status for virtual card. Please be noted, if change the status field to Suspended, Locked or Terminated, the associated physical card status also will be changed accordingly.

Card.physical_status: The status for physical card, only when you create the virtual card, then can apply the physical card for that virtual card. Please be noted the physical_status change wont affect the associated virtual card status.

Card limits

Four independent limit rules control spending across different time windows(see edit card limitAPI). All four can be active simultaneously. To disable a rule, set its limit_amount to "0".

Card operations

Manage individual cards throughout their lifecycle.

Physical card activation

Virtual cards are active immediately after provisioning. Physical cards require a PIN to be set through a secure ECDSA key exchange session.

1 Generate keys using the ECDSA algorithm. 2 Call ECDSA key exchange session to exchange keys. 3 Calculate and obtain the secretkey using the returned key. 4 Encrypt the password with the secretkey and call Set card pin and activeAPI.

Supproting services

Cardholder identity, transaction verification, real-time notifications, and balance management — everything that sits around the card itself.

Consumer cardholders

Consumer cards require a cardholder for identity management. Each cardholder can hold exactly one card.

3D secure verification

3D Secure (3DS) adds a verification step during online card payments, shifting fraud liability to the issuer. Wonder sends the OTP to your server via webhookDOC — you choose how to deliver it to your cardholder(both business and consumer).

Add fund

You need to add fund to your account, then make transaction. The process for business card and consumer cand is differenct, please see below:

Business type wallet top up: To top up in Wonder dashboard, see How to Add Fund to your Global Account

Consumer type wallet top up: Consumer cards have independent balances that start at zero. Cardholders add funds by sending crypto (USDT on Solana or Ethereum) to a deposit address generated by the Wallet API. Wonder handles the conversion from crypto to the card's settlement currency automatically. Besides, you can use platform transfer APIAPI to move funds to another consumer card in real time, and can use get platform transfer API listAPI to track every request.

ECDSA exchange key sample

This example demonstrates the complete process for securely activating a physical card and setting its PIN using ECDSA key exchange and JWE encryption.

1. Dependencies and constants

import(
    "crypto/ecdsa"
    "crypto/elliptic"
    "crypto/rand"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "github.com/go-jose/go-jose/v3"
)

const(
    P256Curve = elliptic.P256() // NIST P-256 curve
    KeySize   = 32              // 256 bits for SHA-256 derived key
    ExchangeKeyAPI = "/svc/card_issuer/api/v1/pci_session"
    SetPinActiveAPI = "/api/v1/pci_pin_with_session"
)

2. Step 1: Generate ECDSA key pair and kid

func generateECDSAKeyPair() (*ecdsa.PrivateKey, string, string, string) {
    privateKey, _ := ecdsa.GenerateKey(P256Curve, rand.Reader)
    publicKey := privateKey.Public().(*ecdsa.PublicKey)

    pubKeyX := hex.EncodeToString(publicKey.X.Bytes())
    pubKeyY := hex.EncodeToString(publicKey.Y.Bytes())
    kid := generateUUID() // Generate unique key ID

    return privateKey, pubKeyX, pubKeyY, kid
}

3. Step 2: Call exchange key API

func exchangeKeys(pubKeyX, pubKeyY, kid string) (*jose.JSONWebKey, error) {
    requestPayload := map[string]string{
        "kty": "EC",
        "crv": "P-256",
        "kid": kid,
        "x":   pubKeyX,
        "y":   pubKeyY,
    }
    // Send POST request (pseudo-code)
    // responseBody := httpPost(ExchangeKeyAPI, requestPayload)
    // Parse response and return server's ephemeral public key
    return parseServerEphemPubKey(responseBody), nil
}

4. Step 3: Derive secretKey via ECDH and SHA-256

func deriveSecretKey(clientPriv *ecdsa.PrivateKey, serverEphemPubKey *jose.JSONWebKey, kid string) []byte {
    // Decode server's public key
    x, y := serverEphemPubKey.Key.(*ecdsa.PublicKey).X, serverEphemPubKey.Key.(*ecdsa.PublicKey).Y
    if !P256Curve.IsOnCurve(x, y) {
        panic("Server public key is not on P-256 curve") // Security check
    }

    // Compute ECDH shared secret
    sharedSecret, _ := clientPriv.ECDH(serverEphemPubKey.Key.(*ecdsa.PublicKey))

    // Build KDF combined data
    combinedData := append([]byte{}, kid.Bytes()...)
    combinedData = append(combinedData, sharedSecret...)

    // Apply SHA-256 hash and truncate
    derivedKey := sha256.Sum256(combinedData)
    return derivedKey[:KeySize]
}

5. Step 4: Encrypt PIN via JWE and call activation API

func encryptPINAndActivate(secretKey []byte, kid, pinCode string) error {
    pinData, _ := json.Marshal(map[string]string{"password": pinCode})

    // Configure JWE encrypter (using DIRECT mode)
    encrypter, _ := jose.NewEncrypter(jose.DIRECT, jose.Recipient{Algorithm: jose.DIRECT, Key: secretKey}, nil)

    // Encrypt and build JWE object
    jweObject, _ := encrypter.Encrypt(pinData)
    jweCompact, _ := jweObject.CompactSerialize()

    // Send POST request for activation (pseudo-code)
    // response := httpPost(SetPinActiveAPI, jweCompact)
    fmt.Printf("PIN encrypted successfully, JWE: %s\n", jweCompact)
    return nil
}

6. Main workflow integration

func main() {
    pinCode := "your_pin" // PIN to be set

    // Step 1: Generate key pair
    privateKey, pubKeyX, pubKeyY, kid := generateECDSAKeyPair()

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

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

    // Step 4: Encrypt PIN and activate
    err := encryptPINAndActivate(secretKey, kid, pinCode)
    if err != nil {
        fmt.Println("Activation failed:", err)
    } else {
        fmt.Println("Card activation workflow completed")
    }
}

Transaction webhook

Real-time transaction webhookDOC are sent to your configured webhook URL for every authorization, reversal, and settlement.

Balance

Query real-time balances for your corporate account or any cardholder account. Balances update immediately as funds move.

Related APIs

Get card transaction listAPI

The transactions that this card make.

Edit consumer cardholderAPI

Edit the information for this consumer cardholder by p_user_id, such as phone.

Get consumer cardholderAPI

Query the consumer cardholder information.