Artha API
    • Introduction
    • Authentication
    • KYC/KYB Requirements
    • API Setup Guide
    • Card API Integration Flow
    • Customers
      • Create Customer
        POST
      • List Customers
        GET
      • Get Customer
        GET
      • Update Customer
        PATCH
    • Cards
      • Submit KYC/KYB Applicant
        POST
      • Get Applicant KYC Status
        GET
      • Issue Card
        POST
      • Cards List
        GET
      • Get Card
        GET
      • Get Sensitive Card Details
        GET
    • Card Operations
      • Activate Card
        POST
      • Freeze Card
        POST
      • Unfreeze Card
        POST
      • Cancel Card
        POST
      • Replace Card
        POST
      • Set / Reset Card PIN
        POST
      • Get Card Limits
        GET
      • Update Card Limits
        POST
    • Funding
      • Top Up Card
        POST
      • Get Top-Up Status
        GET
      • Get Card Balance
        GET
      • List Top-Up History
        GET
    • Transactions
      • List All Transactions
      • List Card Transactions
      • List Customer Transactions
      • Get Transaction
    • Products
      • List Products
      • Get Product
    • Utilities
      • Upload Documents
    • Webhook's
      • Webhooks

    Card API Integration Flow

    This guide walks through the complete steps required to onboard a customer, verify their identity, issue a card, and fund it via top-up. Each phase must be completed in order — steps are dependent on each other.

    Overview#

    card_api_integration_flow_v3.svg

    Phase 1 — Create Customer#

    Method: POST
    Endpoint: /api/v1/customers
    Create a customer record with basic personal details. No identity verification is performed at this stage.
    Response: Returns a customerId that is required for all subsequent API calls.
    ⚠️ Store the customerId returned in the response. It is the primary identifier used across KYC submission, card issuance, and top-up APIs.

    Phase 2 — Submit KYC / KYB#

    Method: POST
    Endpoint: /api/v1/customers/{customerId}/products/{productId}/applicant
    Submit identity verification details for the customer against a specific card product. Use the customerId from Phase 1 and the productId for the product the customer is applying for.
    Path parameters:
    ParameterDescription
    customerIdReturned from Phase 1
    productIdThe card product being applied for
    ⚠️ KYC/KYB must be submitted separately for each productId. If a customer applies for multiple card products, repeat this step with the same customerId and a different productId.

    Phase 3 — Poll KYC Status#

    Method: GET
    Endpoint: /api/v1/customers/{customerId}/products/{productId}/applicantstatus
    After submitting KYC/KYB, poll this endpoint to retrieve the current verification status.
    Path parameters:
    ParameterDescription
    customerIdSame as Phase 2
    productIdSame as Phase 2
    Status values and actions:
    StatusAction
    approvedProceed to Phase 4 — Issue Card
    underreviewWait and retry. Recommended interval: 30–60 seconds with exponential backoff
    rejectedCorrect the submitted data and resubmit via the Phase 2 endpoint
    💡 Set a maximum polling timeout (e.g. 24 hours) and surface an appropriate error to your end user if exceeded.

    Phase 4 — Issue Card#

    Method: POST
    Endpoint: /api/v1/cards
    Once KYC status is approved, submit a card issuance request.
    Response: Returns a cardId used for card status tracking.
    ⚠️ Do not proceed to this step unless the KYC status is approved.

    Phase 5 — Poll Card Status#

    Method: GET
    Endpoint: /api/v1/card/{cardId}
    Poll this endpoint after submitting the card issuance request. Check the state property in the response.
    Path parameters:
    ParameterDescription
    cardIdReturned from Phase 4
    state values and actions:
    stateAction
    activeProceed to Phase 6 — Top Up
    pendingWait and retry
    failedReview the error, contact support, or retry issuance
    ⚠️ Do not proceed to top-up until state is active.

    Phase 6 — Top Up Card#

    Method: POST
    Endpoint: /api/v1/cards/{cardId}/topup
    Fund the card by initiating a top-up from your merchant portal balance.
    Path parameters:
    ParameterDescription
    cardIdThe active card from Phase 5
    Response: Returns a transactionId which is used as the topupId for status tracking. The top-up is in pending status immediately on creation.

    Phase 7 — Poll Top-Up Status#

    Method: GET
    Endpoint: /api/v1/topupstatus/{topupId}
    Poll this endpoint using the transactionId returned from Phase 6.
    Path parameters:
    ParameterDescription
    topupIdThe transactionId returned from Phase 6
    Status values and actions:
    StatusAction
    approvedBalance is added to the card. Card is ready for transactions.
    rejectedThe top-up amount is automatically credited back to your merchant portal balance.
    pendingWait and retry

    Endpoint Summary#

    PhaseMethodEndpointKey Output
    1 — Create customerPOST/api/v1/customerscustomerId
    2 — Submit KYC/KYBPOST/api/v1/customers/{customerId}/products/{productId}/applicantSubmission acknowledged
    3 — Poll KYC statusGET/api/v1/customers/{customerId}/products/{productId}/applicantstatusapproved / rejected / under_review
    4 — Issue cardPOST/api/v1/cardscardId
    5 — Poll card statusGET/api/v1/card/{cardId}state: active / failed / under_review
    6 — Top up cardPOST/api/v1/cards/{cardId}/topuptransactionId (= topupId), status: pending
    7 — Poll top-up statusGET/api/v1/topupstatus/{topupId}approved / rejected / pending

    Frequently Asked Questions#

    Q: Can I submit KYC without specifying a product?
    No. The productId is a required path parameter. KYC/KYB requirements are product-specific.
    Q: Can the same customer apply for multiple card products?
    Yes. Repeat Phases 2–5 using the same customerId with a different productId for each product.
    Q: What does transactionId map to in the top-up status API?
    The transactionId returned by the top-up endpoint (POST /api/v1/cards/{cardId}/topup) is used as the topupId in the status endpoint (GET /api/v1/topupstatus/{topupId}).
    Q: What happens when a top-up is rejected?
    The full top-up amount is automatically refunded to your merchant portal balance. No manual action is required.
    Q: Can I use the card before adding a top-up?
    No. The card must have state: active AND a successful top-up before it can be used for transactions.
    Modified at 2026-03-31 13:18:33
    Previous
    API Setup Guide
    Next
    Create Customer
    Built with