Core Business Flows | EasyCards Developers

VCC · CARD ISSUANCE

From product selection to card creation

Read product requirements, prepare the customer, submit the card application, and confirm the current result through Webhooks and query endpoints.

ISSUANCE FLOW

sequenceDiagram
    autonumber
    participant M as Merchant system
    participant E as EasyCards API

    Note over M,E: Phase 1: Read the card-issuance requirements
        M->>E: List products and issuance requirements · GET /payment/vcc/products
        E->>M: [Synchronous response] product_code, card_mode, fees, limits, required_customer_fields
        opt The product requires file fields
            M->>E: Upload a customer file and obtain its identifier · POST /payment/vcc/files
            E->>M: [Synchronous response] file_id
        end

    Note over M,E: Phase 2: Create the customer and submit the application
        M->>E: Create the cardholder record · POST /payment/vcc/customers
        E->>M: [Synchronous response] customer_id, customer_status
        M->>E: Submit a card application · POST /payment/vcc/card-applications
        E->>M: [Synchronous acceptance] application_id, application_status

    Note over M,E: Phase 3: Receive status changes and query the current result
        opt application_status = PENDING
            E-->>M: [Asynchronous notification] vcc.application.updated · status or next_action changed
        end
        M->>E: Query the current application result · GET /payment/vcc/card-applications/{application_id}
        E->>M: [Synchronous response] application_status, with card_id on success
        opt application_status = SUCCESS
            M->>E: Query card state and basic details · GET /payment/vcc/cards/{card_id}
            E->>M: [Synchronous response] card_status and basic card details
        end

Synchronous acceptanceThe application request returns application_id and application_status in the current HTTP response.

Asynchronous changevcc.application.updated reports subsequent application-state changes.

Active queryRead the current resource state from the application and card detail endpoints.

VCC · CARD OPERATIONS

Balances, sensitive data, top-ups, withdrawals, and card state

Separates synchronous queries and acceptance responses from asynchronous top-up, shared-card withdrawal, and card-state notifications.

CARD OPERATIONS

sequenceDiagram
    participant M as Merchant system
    participant E as EasyCards API

    opt Read card funds
        M->>E: Query one card's current balance · GET /payment/vcc/cards/{card_id}/balance
        E->>M: [Synchronous response] balance, available, frozen
    end
    opt Retrieve sensitive card data
        M->>E: Retrieve RSA-encrypted card data · POST /payment/vcc/cards/sensitive
        E->>M: [Synchronous response] encrypt_data
    end
    opt Top up a card or increase a shared-card limit
        M->>E: Submit the amount through the unified top-up endpoint · POST /payment/vcc/cards/{card_id}/topups
        E->>M: [Synchronous acceptance] topup_id, topup_status
        E-->>M: [Asynchronous notification] vcc.topup.updated · top-up status changed
        M->>E: Query the current top-up result · GET /payment/vcc/topups/{topup_id}
        E->>M: [Synchronous response] topup_status, amount, and fee
    end
    opt Withdraw unused shared-card limit
        M->>E: Submit a shared-card withdrawal · POST /payment/vcc/cards/{card_id}/withdrawals
        E->>M: [Synchronous acceptance] withdrawal_id, withdrawal_status
        E-->>M: [Asynchronous notification] vcc.withdrawal.updated · withdrawal status changed
    end
    opt Freeze or unfreeze a card
        M->>E: Submit a card-state change · POST .../freeze or POST .../unfreeze
        E->>M: [Synchronous acceptance] resource_status
        E-->>M: [Asynchronous notification] vcc.card.updated · terminal result
        M->>E: Query the card's current state · GET /payment/vcc/cards/{card_id}
        E->>M: [Synchronous response] card_status
    end

Synchronous queriesBalances and encrypted sensitive data return within the current HTTP request.

Asynchronous notificationsLater top-up, shared-card withdrawal, freeze, and unfreeze state changes arrive through the corresponding Webhook.

State confirmationAfter a Webhook, use the corresponding query endpoint to read the current resource state; shared-card withdrawals can be confirmed through the withdrawal detail endpoint.

VCC Business Sequence Diagrams