Skip to content

Issue a Card ​

POST /openapi/v2/cards/issueCard
ItemValue
HTTP methodPOST
Request path/openapi/v2/cards/issueCard
Request typeapplication/json

Request parameters:

FieldTypeRequiredDescription
requestNostringYesCaller-provided business idempotency key, 1 to 64 visible ASCII characters; spaces are not allowed.
emailstringYesUser email address.
memberIdstringNoDeprecated compatibility field; when provided, it is cross-checked against the email.
cardTypeIdstringYesCard type ID, up to 64 characters.
embossedNamestringNoName embossed on the card; required status and length are determined by card product configuration.
cardSuffixstringNoOptional requested card suffix; support depends on the card product.
mobilestringNoRegistered mobile number; format requirements are determined by card product configuration.
deviceFingerprintIdstringConditionalDevice fingerprint, up to 128 characters. The Mastercard Global USD card requires at least a fingerprint or a complete public IP and country/region code pair.
deviceIpAddressstringConditionalActual public device IP, up to 64 characters. For the Mastercard Global USD card, provide deviceCountryCode together with this field.
deviceCountryCodestringConditionalTwo-letter country/region code for the device IP location, such as HK, not the user's nationality. For the Mastercard Global USD card, provide deviceIpAddress together with this field.

Device Information Requirements ​

Requirements depend on the card product identified by cardTypeId:

Card productDevice information requirements
Mastercard Hong Kong USD cardOptional.
Mastercard Global USD cardProvide at least a nonblank deviceFingerprintId, or both a nonblank deviceIpAddress and a nonblank deviceCountryCode.

The Mastercard Global USD card accepts both forms of device information together. However, even when a fingerprint is provided, the public IP and country/region code must not be supplied individually. The caller must provide device information; the API does not automatically fill it from the request source.

Request Examples ​

The following examples show the two ways to provide device information for the Mastercard Global USD card.

Device Fingerprint ​

json
{
  "requestNo": "ISSUE_20261010_001",
  "email": "user@example.com",
  "cardTypeId": "VIRTUAL_USD",
  "deviceFingerprintId": "DEVICE_FINGERPRINT_001"
}

Public IP and Country/Region Code ​

json
{
  "requestNo": "ISSUE_20261010_002",
  "email": "user@example.com",
  "cardTypeId": "VIRTUAL_USD",
  "deviceIpAddress": "203.0.113.10",
  "deviceCountryCode": "HK"
}

cardTypeId and the device information are placeholders. Replace them with the actual card product ID and real device information; the example IP must not be used for actual card issuance. The country/region code must match the actual device IP location.

Response data ​

FieldTypeDescription
cardOrderNostringPlatform card issuance order number.
requestNostringCaller-provided business idempotency key.
emailstringUser email address.
memberIdstringPlatform member ID.
cardTypeIdstringCard type ID.
currencystringCard product currency, usually a three-letter ISO 4217 code; determined by product configuration.
typestringCard type; currently known values are PHYSICAL, VIRTUAL. Product configuration may introduce additional values.
feeAmountstringCard issuance fee amount, as a string without scientific notation.
feeAssetCodestringCard issuance fee asset.
acceptedbooleanWhether the request has been accepted.
statusstringPlatform card issuance status: PROCESSING, SUCCESS, FAILED.
failCodestringFailure code.
failMessagestringFailure message.
last4stringLast four digits of the card number.
expiryMonthstringExpiry month.
expiryYearstringExpiry year.
createTimestringOrder creation time.
completedTimestringTime when the order reached its terminal state.