Issue a Card
POST/openapi/v2/cards/issueCard| Item | Value |
|---|---|
| HTTP method | POST |
| Request path | /openapi/v2/cards/issueCard |
| Request type | application/json |
Request parameters:
| Field | Type | Required | Description |
|---|---|---|---|
requestNo | string | Yes | Caller-provided business idempotency key, 1 to 64 visible ASCII characters; spaces are not allowed. |
email | string | Yes | User email address. |
memberId | string | No | Deprecated compatibility field; when provided, it is cross-checked against the email. |
cardTypeId | string | Yes | Card type ID, up to 64 characters. |
embossedName | string | No | Name embossed on the card; required status and length are determined by card product configuration. |
cardSuffix | string | No | Optional requested card suffix; support depends on the card product. |
mobile | string | No | Registered mobile number; format requirements are determined by card product configuration. |
deviceFingerprintId | string | Conditional | Device 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. |
deviceIpAddress | string | Conditional | Actual public device IP, up to 64 characters. For the Mastercard Global USD card, provide deviceCountryCode together with this field. |
deviceCountryCode | string | Conditional | Two-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 product | Device information requirements |
|---|---|
| Mastercard Hong Kong USD card | Optional. |
| Mastercard Global USD card | Provide 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
{
"requestNo": "ISSUE_20261010_001",
"email": "user@example.com",
"cardTypeId": "VIRTUAL_USD",
"deviceFingerprintId": "DEVICE_FINGERPRINT_001"
}Public IP and Country/Region Code
{
"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
| Field | Type | Description |
|---|---|---|
cardOrderNo | string | Platform card issuance order number. |
requestNo | string | Caller-provided business idempotency key. |
email | string | User email address. |
memberId | string | Platform member ID. |
cardTypeId | string | Card type ID. |
currency | string | Card product currency, usually a three-letter ISO 4217 code; determined by product configuration. |
type | string | Card type; currently known values are PHYSICAL, VIRTUAL. Product configuration may introduce additional values. |
feeAmount | string | Card issuance fee amount, as a string without scientific notation. |
feeAssetCode | string | Card issuance fee asset. |
accepted | boolean | Whether the request has been accepted. |
status | string | Platform card issuance status: PROCESSING, SUCCESS, FAILED. |
failCode | string | Failure code. |
failMessage | string | Failure message. |
last4 | string | Last four digits of the card number. |
expiryMonth | string | Expiry month. |
expiryYear | string | Expiry year. |
createTime | string | Order creation time. |
completedTime | string | Time when the order reached its terminal state. |
