Create a Card

Issue a new virtual or physical card, optionally linked to a cardholder and a budget account, with transaction limits and authorization controls.
Request Parameters
requestIdstring
required
Idempotency key for this card-creation request. Assign a unique value per request to safely retry without issuing duplicate cards. Must be unique within your partnerId. Max 64 characters.
cardBrandstring
required
Card network brand.

Valid Values:

MASTERCARD — Mastercard network.
cardholderIdstring
Associated cardholder ID. Optional — a card can be created without a cardholder. Max 64 characters.
mediaTypestring
Card media type. Defaults to VIRTUAL.

Valid Values:

VIRTUAL — Virtual card.
budgetIdstring
Associated budget account ID. Can only be set at creation and cannot be changed later. Max 64 characters.
cardNickNamestring
Merchant-defined friendly name for the card. Max 120 characters.
notestring
Free-text note. Max 512 characters.
purposestring
Card purpose description. Max 64 characters.
emailstring
Email associated with the card, used for transaction and reconciliation notifications. Must be a valid email format. Max 256 characters.
mobilePhonestring
Mobile phone associated with the card, including the international dialing code. Max 32 characters.
billingAddressAddress
Billing address. See Data Types.
transactionLimitsarray of TransactionLimits
required
Transaction limit configuration, aggregated by currency. Maximum 5 entries. At creation, each limit only needs interval and rangeAmount.
Show child parametersShow child parameters
authorizationControlAuthorizationControl
Authorization control rules governing when and where the card can transact.
Show child parametersShow child parameters
metadataobject
Merchant-defined metadata. Up to 50 keys.
enableSyncActivationboolean
Whether to activate the card synchronously. Defaults to asynchronous issuance.
threeDsFrictionlessboolean
Whether to waive the 3DS challenge (true = transactions require no additional 3DS verification).
Response Parameters
resultResult
See Result.
idstring
Unique card identifier. Use this ID for subsequent query, sensitive-info, and update operations. Max 64 characters.
statusstring
Current card status.

Valid Values:

PENDING — Card application submitted, awaiting review or production.
ACTIVE — Card is activated and ready for transactions.
FAILED — Card creation failed.
cardholderIdstring
Associated cardholder ID. Max 64 characters.
mediaTypestring
Card media type.
createdAtdatetime
Creation timestamp. ISO 8601 extended format.
cardBrandstring
Card network brand.
budgetIdstring
Associated budget account ID. Max 64 characters.
cardNumberstring
Masked card number. Returned only when status is ACTIVE. Max 19 characters.
expiryDatestring
Card expiry date. Returned only when status is ACTIVE. Format MM/YY.
last4Digitsstring
Last 4 digits of the card number. Max 4 characters.
cardNickNamestring
Merchant-defined friendly name. Max 120 characters.
notestring
Free-text note. Max 512 characters.
purposestring
Card purpose description. Max 64 characters.
emailstring
Email associated with the card. Max 256 characters.
mobilePhonestring
Mobile phone associated with the card. Max 32 characters.
billingAddressAddress
Billing address. See Data Types.
transactionLimitsarray of TransactionLimits
Transaction limit configuration per request.
Show child parametersShow child parameters
authorizationControlAuthorizationControl
Authorization control rules (activation/expiry time, MCC allow/blocklists, allowed currencies, authorization count cap).
metadataobject
Merchant-defined metadata. Up to 50 keys; key up to 40 characters, value up to 500 characters.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccess.Card creation accepted.
PARAM_ILLEGALFIllegal parameters exist.Verify request fields against this reference, including `transactionLimits` and `authorizationControl`.
RISK_REJECTFRequest rejected due to risk concerns.Contact WorldFirst support to review the risk decision.
CARDHOLDER_NOT_EXISTFCardholder {cardholderId} not found.Verify the `cardholderId` is correct, or omit it to create a card without a cardholder.
USER_NOT_EXISTFThe user does not exist.Retry with correct user information.
USER_NO_PERMISSIONFUser does not have permission.Retry with a user that has card-issuing permission.
CONTRACT_CHECK_FAILFThe contract check has failed.Contact WorldFirst support to confirm the contract status, then retry.
REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.A prior request reused this `requestId` with different parameters. Keep all parameters identical, or use a new `requestId`.
UN_SUPPORT_BUSINESSFUnsupported business.The requested card configuration is not supported. Contact WorldFirst support.
AUTHORIZATION_NOT_EXISTFThe authorization does not exist.Verify the `account-id` / `access-token` authorization before retrying.
PROCESS_FAILFA general business failure occurred. Do not retry.Do not retry. Contact WorldFirst support.
Definition
POST /api/open/v1/issuing/cards/create
Request
{
"requestId": "req_card_create_001",
"cardBrand": "MASTERCARD",
"cardNickName": "Team Travel Card",
"note": "Marketing Q2 budget",
"mobilePhone": "+8613800138000",
"billingAddress": {
  "address1": "No.1 Test Street",
  "address2": "Suite 100",
  "city": "Shanghai",
  "state": "Shanghai",
  "region": "CN",
  "zipCode": "200000"
},
"transactionLimits": [
  {
    "currency": "USD",
    "limits": [
      {
        "interval": "PER_TRANSACTION",
        "rangeAmount": 1000
      },
      {
        "interval": "DAILY",
        "rangeAmount": 5000
      },
      {
        "interval": "MONTHLY",
        "rangeAmount": 50000
      },
      {
        "interval": "ALL_TIME",
        "rangeAmount": 200000
      }
    ]
  }
],
"authorizationControl": {
  "allowedAuthTimes": 100,
  "allowedCurrencies": [
    "USD",
    "EUR",
    "GBP"
  ],
  "cardActiveAt": "2026-06-19T00:00:00Z",
  "cardCancelAt": "2027-06-18T00:00:00Z"
},
"metadata": {
  "purpose": "vendor-payment",
  "department": "finance"
}
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"id": "CARD_20260618190272001208****",
"status": "PROCESSING",
"cardholderId": "CH_20260302290272001208****",
"mediaType": "VIRTUAL",
"createdAt": "2026-06-18T02:06:34Z",
"cardBrand": "MASTERCARD",
"cardNickName": "Team Travel Card",
"note": "Marketing Q2 budget",
"email": "123@gmail.com",
"mobilePhone": "+86*******0881",
"billingAddress": {
  "city": "Shanghai",
  "region": "CN",
  "zipCode": "200000"
},
"transactionLimits": [
  {
    "currency": "USD",
    "limits": [
      {
        "interval": "PER_TRANSACTION",
        "rangeAmount": 1000
      },
      {
        "interval": "DAILY",
        "rangeAmount": 5000
      },
      {
        "interval": "MONTHLY",
        "rangeAmount": 50000
      },
      {
        "interval": "ALL_TIME",
        "rangeAmount": 200000
      }
    ]
  }
],
"authorizationControl": {
  "allowedAuthTimes": 100,
  "allowedCurrencies": [
    "USD",
    "EUR",
    "GBP"
  ],
  "cardActiveAt": "2026-06-19T00:00:00Z",
  "cardCancelAt": "2027-06-18T00:00:00Z"
}
}