Virtual and physical cards

Issue a card with POST /cards/users/{userId}/issue. The cardType field determines virtual or physical delivery. End users can hold multiple virtual and/or physical cards. Your business account is limited to 50 non-canceled cards in total, and 50 card creations every 90 days.

Virtual card

Virtual cards do not use courier shipping. They do require a residential physicalAddress:

Send physicalAddress on the issue request, or
Ensure the user already has a stored physicalAddress (from POST /users, PATCH /users/{userId}, or a prior physical issue)

If neither is present, the API returns 400.

Issue virtual card (address on request)

{
  "cardType": "virtual",
  "displayName": "Jane Doe Card",
  "physicalAddress": {
    "line1": "12 Main Road",
    "line2": "Suite 4",
    "city": "Johannesburg",
    "region": "Gauteng",
    "postalCode": "2000",
    "countryCode": "ZA"
  }
}

Issue virtual card (user already has stored physicalAddress)

{
  "cardType": "virtual",
  "displayName": "Jane Doe Card"
}

When you send physicalAddress on issue, it is upserted on the user and synced to the issuer. It is not sent as Rain card shipping. Virtual and physical cards are issued as active. No separate activate step is required. For dual card branding, see Business account.

physicalAddress fields

Field	Required	Meaning
`line1`	Yes	Street address line 1
`line2`	No	Apartment, suite, or unit
`city`	Yes	City
`region`	No	State, province, or region
`postalCode`	Yes	Postal code
`countryCode`	Yes	Two-letter ISO country code, for example `ZA`
`country`	No	Country display name

Physical card

Requires a shippingAddress object on the issue request (courier delivery + recipient phone). Issuing a physical card also upserts users.physicalAddress from the shipping fields (phone is dropped). Call GET /cards/fees first to read the once-off physical card fee (physicalCardFee in USDC cents). If it is greater than zero, send acceptCharge: true when issuing — otherwise the API returns a 400 with the charge amount. You also need enough treasury USDC to cover the fee.

GET /cards/fees

curl -s "https://b2b-api.easyonramp.com/api/v1/cards/fees" \
  -H "Authorization: Bearer YOUR_JWT"

Card fees response

{
  "physicalCardFee": 1000,
  "currency": "USDC"
}

physicalCardFee is in USDC cents (1000 = 10.00 USDC). When it is 0, acceptCharge is not required.

Issue physical card

{
  "cardType": "physical",
  "displayName": "Jane Doe Physical Card",
  "acceptCharge": true,
  "bulkShippingGroupId": "507f1f77bcf86cd799439022",
  "shippingAddress": {
    "line1": "12 Main Road",
    "line2": "Suite 4",
    "city": "Johannesburg",
    "region": "Gauteng",
    "postalCode": "2000",
    "countryCode": "ZA",
    "phoneNumber": "+27821234567"
  }
}

To group cards into one bulk shipment, send the address id as bulkShippingGroupId from Bulk shipping addresses (for example GET /cards/bulk-shipping-addresses/default). The issue call does not apply a default for you. Omit the field to ship that card individually.

shippingAddress fields

Field	Required	Meaning
`line1`	Yes	Delivery address line 1
`line2`	No	Delivery address line 2, apartment, suite, or unit
`city`	Yes	Delivery city
`region`	Yes	Delivery state, province, or region
`postalCode`	Yes	Delivery postal code
`countryCode`	Yes	Two-letter ISO country code, for example `ZA`
`phoneNumber`	Yes	Courier contact phone number for the recipient

Physical cards are issued as active. Set the PIN with Managing a card’s PIN after issuance. To permanently end a card, use DELETE /cards/{cardId}. See Lifecycle controls. For a compromised virtual card, see Replace a card.

Get started

Core concepts

Common workflows

How to manage users

How to fund your business wallet

How to use cards

How to use reports

Integration services

Virtual card

physicalAddress fields

Physical card

shippingAddress fields

​Virtual card

​physicalAddress fields

​Physical card

​shippingAddress fields

​Related

Virtual card

physicalAddress fields

Physical card

shippingAddress fields

Related