HIFI Docs

An External Card is a debit, prepaid or credit card belonging to a Counter Party, used as the destination for a push style card payout.

Two ways to add a card

Method	Who can use it	How it works
Card API	Clients certified PCI DSS Level 1	Your backend collects the card number/CVV and sends them directly to HIFI.
External Card Session	All other developers	The recipient enters their card details on a HIFI-hosted page - raw card data never touches your servers.

If you aren’t PCI DSS Level 1 certified, use an External Card Session instead of calling the Card API directly - contact HIFI if you’re unsure which applies to you.

Counterparty requirements

The counterparty must be ACTIVE, and have the following accepted fields set in addition to its own minimum, before you can add an external card for them:

Counterparty type	Additional required fields
Individual	`phoneNumber`, `email`, `address`
Business	`phoneNumber`, `email`, `address`

If a required field is missing, HIFI rejects the request with ACTION_NOT_ALLOWED (422) - update the counterparty with the missing field and retry.

The counterparty doesn’t need to be created upfront if the card is added through an External Card Session submission, since the session’s own schema already enforces these fields. Otherwise, you can also pass counterpartyId as an optional fields when creating the session.

Supported Card Network

Network	Type
Visa	OCT

Add an external card via API

Registers a card directly against an existing counterparty. Requires an Idempotency-Key header. cardNumber and cvv are used once to tokenize the card with HIFI’s card provider and are never returned in the response. Request

curl -X POST https://sandbox.hifi.com/v3/users/usr_x1y2z3/counter-parties/cpty_a1b2c3/external-cards \
  -H "Idempotency-Key: <unique-key>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "cardNumber": "4111111111111234",
    "expiryMonth": "09",
    "expiryYear": "28",
    "cvv": "123"
  }'

Response

{
    "id": "extcrd_QW1e2r3t4y",
    "userId": "usr_x1y2z3",
    "counterPartyId": "cpty_a1b2c3",
    "firstName": "Jane",
    "lastName": "Doe",
    "cardNumber": "************1234",
    "expiryMonth": "09",
    "expiryYear": "28",
    "status": "ACTIVE",
    "createdAt": "2026-07-24T22:10:00.000Z",
    "updatedAt": "2026-07-24T22:10:00.000Z"
}

Deactivate an external card

Revokes a previously-added card. A deactivated card can no longer be used as a payout destination, but its record and history are preserved. Request

curl -X DELETE https://sandbox.hifi.com/v3/users/usr_x1y2z3/counter-parties/cpty_a1b2c3/external-cards/extcrd_QW1e2r3t4y \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "id": "extcrd_QW1e2r3t4y",
    "userId": "usr_x1y2z3",
    "counterPartyId": "cpty_a1b2c3",
    "firstName": "Jane",
    "lastName": "Doe",
    "cardNumber": "************1234",
    "expiryMonth": "09",
    "expiryYear": "28",
    "status": "INACTIVE",
    "createdAt": "2026-07-24T22:10:00.000Z",
    "updatedAt": "2026-07-24T22:15:00.000Z"
}

Retrieve a counterparty’s external cards

List a counterparty’s registered cards Request

curl https://sandbox.hifi.com/v3/users/usr_x1y2z3/counter-parties/cpty_a1b2c3/external-cards \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "data": [
        {
            "id": "extcrd_QW1e2r3t4y",
            "userId": "usr_x1y2z3",
            "counterPartyId": "cpty_a1b2c3",
            "firstName": "Jane",
            "lastName": "Doe",
            "cardNumber": "************1234",
            "expiryMonth": "09",
            "expiryYear": "28",
            "status": "ACTIVE",
            "createdAt": "2026-07-24T22:10:00.000Z",
            "updatedAt": "2026-07-24T22:10:00.000Z"
        }
    ],
    "pagination": {
        "hasMore": false,
        "startCursor": "extcrd_QW1e2r3t4y",
        "endCursor": "extcrd_QW1e2r3t4y"
    }
}

External Card Sessions

An External Card Session is the hosted alternative to the Card API - the required path if you aren’t PCI DSS Level 1 certified. Instead of your backend collecting the card number, the recipient types their own card and identity details directly into a HIFI-hosted page, so raw card data never touches your servers. You generate a session and get back a hosted URL; HIFI’s hosted page collects the counterparty and card details from there and creates both once the recipient submits.

Generate a session

requestId is a client-supplied UUID that makes the call idempotent. If counterPartyId is omitted, the recipient enters their own counterparty details as part of the hosted flow; if provided, only card details are collected. Set recipientEmail to have HIFI email the hosted link directly to the recipient. Request

curl -X POST https://sandbox.hifi.com/v3/users/usr_x1y2z3/external-card-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "requestId": "5c1b1e0a-1234-4a5b-8c9d-0e1f2a3b4c5d",
    "recipientEmail": "jane@example.com",
    "redirectUrl": "https://yourapp.com/card-collection-complete",
    "expiresIn": 3600
  }'

Response

{
    "id": "ecs_QW1e2r3t4y",
    "userId": "usr_x1y2z3",
    "counterPartyId": null,
    "url": "https://dashboard.hifi.com/sandbox/external-card-sessions/ecs_QW1e2r3t4y#sessionToken=...",
    "recipientEmail": "jane@example.com",
    "redirectUrl": "https://yourapp.com/card-collection-complete",
    "status": "PENDING",
    "expiredAt": "2026-07-24T23:10:00.000Z",
    "createdAt": "2026-07-24T22:10:00.000Z",
    "updatedAt": "2026-07-24T22:10:00.000Z"
}

Retrieving or submitting a session directly from your own backend isn’t supported - that’s handled entirely by the hosted page. Subscribe to EXTERNAL_CARD and COUNTER_PARTY webhook events to know when the resulting resources are created.

Getting Help

📧 Email: support@hifi.com
💬 Slack: Message us in our shared Slack channel

Counterparty Overview - Counterparty resources
Counter Party - Create and manage recipients/payers
External Account - Bank accounts for a counterparty

Introduction

Core concepts

Features

Compliance

Payments

References

External Card

Two ways to add a card

Counterparty requirements

Supported Card Network

Add an external card via API

Deactivate an external card

Retrieve a counterparty’s external cards

External Card Sessions

Generate a session

Getting Help

​Two ways to add a card

​Counterparty requirements

​Supported Card Network

​Add an external card via API

​Deactivate an external card

​Retrieve a counterparty’s external cards

​External Card Sessions

​Generate a session

​Getting Help

​Related Resources

Two ways to add a card

Counterparty requirements

Supported Card Network

Add an external card via API

Deactivate an external card

Retrieve a counterparty’s external cards

External Card Sessions

Generate a session

Getting Help

Related Resources