Cards

Ele issues payment cards to members of an organization. Each card belongs to one person, its cardholder, and has a monthly spending limit in US dollars.

Card numbers and security codes (CVV) cannot be read through the API.

What you can do

Give a member access to a card, with a monthly limit.
Issue the member’s virtual card.
Order a physical card, activate it and set its PIN.
Change a card’s limit.
Freeze and unfreeze a card.
Read a card’s state and spending.
Review and answer 3-D Secure checks.

The sequence

1. Give a member card access

An owner or admin creates a card entitlement for a member with createCardEntitlement. The user_id comes from listMembers:

curl -s "$ELE_API_BASE/api/v1/organizations/$ORGANIZATION_ID/card-entitlements" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"user_id\": \"$MEMBER_USER_ID\", \"monthly_limit\": 2000, \"allow_physical\": true}"

monthly_limit is a whole number of US dollars, from 1 to 100,000; see Money. allow_physical says whether the member may order a physical card.

In production, a person can have one card from each card provider in an organization, and one unused entitlement at a time.

listCardEntitlements lists the entitlements not yet used. Add holder=me to see only the signed-in person’s own.

2. Issue the card

The cardholder turns the entitlement into a card with createCard. Only the person the entitlement names can do this, signed in as themselves:

curl -s "$ELE_API_BASE/api/v1/cards" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"card_entitlement_id\": \"$ENTITLEMENT_ID\"}"

The cardholder must have passed their own identity check first; otherwise Ele answers 422 kyc_required. See Onboarding.

The new card is virtual. It works online and in phone wallets straight away.

3. Read the card

getCard returns one card; listCards returns the organization’s cards, or the signed-in person’s own with holder=me:

curl -s "$ELE_API_BASE/api/v1/cards/$CARD_ID" \
  -H "Authorization: Bearer $ELE_TOKEN"

The card shows last_four, status, frozen, the limit with spent_this_month, and the physical card’s physical.state.

available_actions lists what the signed-in person can do to this card now: order_physical, activate, set_pin, freeze or unfreeze. Show only those actions.

For a card whose card_provider is thredd, getCardDetails returns the masked number, expiry date and name on card. Other cards answer 422 provider_not_supported.

4. Change the limit

An owner or admin changes monthly_limit, or allow_physical, with updateCard. Send at least one of the two:

curl -s -X PATCH "$ELE_API_BASE/api/v1/cards/$CARD_ID" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"monthly_limit": 5000}'

5. Freeze and unfreeze

freezeCard blocks the card at once, for example when it is lost. It needs no step-up, so nothing slows down a person locking a card:

curl -s -X POST "$ELE_API_BASE/api/v1/cards/$CARD_ID/freeze" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY"

unfreezeCard lets it spend again. It needs step-up: the person confirms they are present. See Step-up and approvals:

curl -s -X POST "$ELE_API_BASE/api/v1/cards/$CARD_ID/unfreeze" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY"

Freezing a frozen card, or unfreezing one that is not frozen, answers 409 conflict. Read frozen first. Neither call cancels a card. The API cannot cancel a card; contact Ele support to do that.

6. Order a physical card

Only the cardholder orders their physical card, and only when the card’s available_actions includes order_physical. First list the products the card can be ordered as, with their prices, using listPhysicalCardOptions:

curl -s "$ELE_API_BASE/api/v1/cards/$CARD_ID/physical-order/options" \
  -H "Authorization: Bearer $ELE_TOKEN"

Then order with orderPhysicalCard, which needs step-up. offer_id picks an option; without it, Ele orders the first one. Without street_address, Ele ships to the cardholder’s home address on file:

curl -s "$ELE_API_BASE/api/v1/cards/$CARD_ID/physical-order" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"offer_id\": \"$OFFER_ID\"}"

The price is charged to the organization’s balance. If the balance is too small, Ele answers 422 insufficient_balance. If the delivery address cannot be used, Ele answers 422 delivery_violation, and details names the fields.

Follow delivery with getPhysicalOrder, which shows the order’s status and, once shipped, tracking_number and carrier.

Physical cards with card_provider thredd cannot be ordered through the API yet.

7. Activate the physical card and set its PIN

When the plastic arrives, the cardholder activates it with activateCard. Until then, it is declined at shops and cash machines; online and wallet payments keep working.

curl -s -X POST "$ELE_API_BASE/api/v1/cards/$CARD_ID/activate" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY"

Then they choose a PIN with setCardPin:

curl -s "$ELE_API_BASE/api/v1/cards/$CARD_ID/pin" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"pin\": \"$PIN\"}"

A PIN has 4 to 12 digits, and no digit may appear more than twice. Pass the PIN straight through: never store or log it. Both calls need step-up.

googleWalletProvision adds a thredd card to the cardholder’s Google Wallet. The identifiers it takes come from Google’s provisioning tools, in an Android app or on the web, and it needs step-up.

3-D Secure checks

Some online shops ask the cardholder to confirm a payment. For cardholders who receive these checks on WhatsApp, Ele sends a message with a link. The link carries a one-time token that authorizes two calls, with no bearer token:

reviewThreeDS returns the shop’s name, the amount, the currency and the card’s last four digits.
confirmThreeDS approves or declines the payment.

curl -s "$ELE_API_BASE/api/v1/three-ds/review" \
  -H 'Content-Type: application/json' \
  -d "{\"token\": \"$THREE_DS_TOKEN\"}"

curl -s "$ELE_API_BASE/api/v1/three-ds/confirm" \
  -H 'Content-Type: application/json' \
  -d "{\"token\": \"$THREE_DS_TOKEN\", \"approve\": true}"

The API does not list pending checks: the token reaches only the cardholder. The cardholder decides each one; never approve a check on their behalf. A check lasts 5 minutes and can be answered once. After that, both calls answer 404 not_found.

States

A card’s status:

`status`	Meaning	What you do
`active`	The card can be used, unless `frozen` is `true`.	Nothing.
`inactive`	The card provider reports it as not active. It cannot be used.	Contact Ele support if it does not change.
`expired`	Past its expiry date.	Nothing.
`revoked`	Cancelled for good. It offers no actions.	Nothing.

frozen is separate from status: a frozen card is still active.

The physical card’s physical.state:

`physical.state`	Meaning	What you do
`none`	No physical card was ordered.	Order one, if `available_actions` allows.
`awaiting_activation`	Ordered or on its way. Declined at shops and cash machines.	Activate it when it arrives.
`active`	Activated.	Set a PIN, if `available_actions` includes `set_pin`.

physical.replacement is true when the card was reissued. A replacement can have a new number; last_four always shows the current one.

Step-up and approvals

Call	Needs
`createCardEntitlement`, `createCard`, `updateCard`, `freezeCard`	Neither.
`unfreezeCard`, `orderPhysicalCard`, `activateCard`, `setCardPin`, `googleWalletProvision`	Step-up.
`reviewThreeDS`, `confirmThreeDS`	The cardholder’s token.

No card call creates an approval request.

Who can do what

Operation	Roles
`createCardEntitlement`	Owner, admin
`listCardEntitlements`	Owner, admin. Any member with `holder=me`.
`createCard`	The person the entitlement names.
`listCards`	Owner, admin. Any member with `holder=me`.
`getCard`, `getCardDetails`	The cardholder, or an owner or admin.
`updateCard`	Owner, admin
`freezeCard`, `unfreezeCard`	The cardholder, or an owner or admin.
`listPhysicalCardOptions`, `orderPhysicalCard`, `getPhysicalOrder`, `activateCard`, `setCardPin`, `googleWalletProvision`	The cardholder only.

What to poll

getCard to refresh limit.spent_this_month and available_actions.
getPhysicalOrder once a day while a physical card is on its way.
Card payments appear in listTransactions as card_transaction; see Staying in sync.

Common errors

Status	`type`	When	What to do
`403`	`step_up_required`	A call that needs step-up, with no step-up window open.	Complete step-up with the person, then call again.
`404`	`entitlement_not_found`	The entitlement is unknown.	List the entitlements again.
`404`	`not_found`	The card is unknown, the person may not see it, or a 3-D Secure token is used or expired.	Check the ID.
`409`	`conflict`	Freezing a frozen card, or unfreezing one that is not frozen.	Read `frozen`, then decide.
`422`	`user_not_in_organization`	The entitlement’s `user_id` is not an active member.	Choose a member from `listMembers`.
`422`	`entitlement_exists`	The member already has an unused entitlement.	Use it.
`422`	`card_limit_reached`	The member already has a card from this provider here.	Use the existing card.
`422`	`entitlement_already_accepted`	The entitlement was already turned into a card.	Read the card instead.
`422`	`kyc_required`	The cardholder has not passed their identity check.	Finish their identity check first.
`422`	`provider_disabled`	The chosen card provider is not available.	Leave `card_provider` unset.
`422`	`physical_not_allowed`	Ordering a physical card when `allow_physical` is `false`.	Have an owner or admin allow it.
`422`	`physical_already_ordered`	A physical card was already ordered.	Follow the existing order.
`422`	`insufficient_balance`	The balance does not cover the physical card’s price.	Add money, then order again.
`422`	`delivery_violation`	The delivery address cannot be used. `details` names the fields.	Fix the address.
`422`	`card_blocked`	Activating a blocked card.	Contact Ele support.
`422`	`invalid_pin_length`, `invalid_pin_format`, `invalid_pin_consecutive`, `invalid_pin_repeated`	The PIN breaks a rule above.	Ask the cardholder for another PIN.
`422`	`provider_not_supported`	`getCardDetails` for a card that is not `thredd`, or ordering a physical `thredd` card.	Do not offer it for that card.
`429`	`rate_limited`	Too many card or entitlement creations.	Wait, then retry.

For other types, see Errors.