Card Transfer

Before You Start

Read the following guides before proceeding:

Guide	Why
Getting Started	Platform overview and setup
Api Basics	Required headers and request configuration
Authentication	How to obtain access tokens
Onboarding	User and wallet registration
KYC	KYC verification requirements
Recipients	Recipient management

Overview

Push to card transfers credit funds directly to an external payment card (Visa/Mastercard) using OCT (Original Credit Transaction) rails.

The transfer flow:

Estimate — Get transfer quote with exchange rates for available tokens
Execute — Complete the transfer using selected token

Capability Check

Push to card requires the CardTransfer capability to be active. Check capability status via the capabilities endpoint before initiating transfers.

Estimate Transfer

Get a transfer estimation with exchange rates for the requested tokens.

Endpoint

POST /api/v1/cards/transfer/estimate

Request

{
  "external_card_id": "c34908da-d980-4a9c-9b39-4dabd6f6144e",
  "currency": "EUR",
  "amount": 100.00,
  "tokens": [
    "0x0774164DC20524Bb239b39D1DC42573C3E4C6976",
    "0x5c55F314624718019A326F16a62A05D6C6d8C8A2"
  ]
}

Field	Type	Required	Description
`external_card_id`	string	Yes	Card token from tokenization step (`card.card_id`). Can be retrieved via `GET /api/v1/recipients`
`currency`	string	No	Target currency (default: EUR)
`amount`	float	Yes	Amount to credit to card
`tokens`	string[]	Yes	Token addresses to quote

Response

{
  "estimation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expires_at": 1704110400,
  "currency": "EUR",
  "amount": 100.00,
  "fee_amount": 0.50,
  "estimated_amounts": [
    {
      "amount": 109.41,
      "precise_amount": "109411230370000000000",
      "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976",
      "token_symbol": "WUSD",
      "rate": 0.914
    },
    {
      "amount": 100.50,
      "precise_amount": "100500000000000000000",
      "token_address": "0x5c55F314624718019A326F16a62A05D6C6d8C8A2",
      "token_symbol": "WEUR",
      "rate": 0.995
    }
  ]
}

Field	Type	Description
`estimation_id`	string (UUID)	Identifier for this estimation
`expires_at`	integer	Unix timestamp when estimation expires
`currency`	string	Target currency
`amount`	float	Amount to be credited to card
`fee_amount`	float	Transfer fee amount
`estimated_amounts`	array	Debit amount per token
`estimated_amounts[].amount`	float	Token amount (scaled to precision)
`estimated_amounts[].precise_amount`	string	Token amount in smallest unit
`estimated_amounts[].token_address`	string	Token contract address
`estimated_amounts[].token_symbol`	string	Token symbol
`estimated_amounts[].rate`	float	Exchange rate applied

Execute Transfer

Execute the transfer using a valid estimation. Select which token to debit from the estimated amounts.

Endpoint

POST /api/v1/cards/transfer

Request

{
  "estimation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
}

Field	Type	Required	Description
`estimation_id`	string (UUID)	Yes	Estimation identifier
`token_address`	string	Yes	Token to debit (must be in estimated_amounts)

Response

{
  "id": "d4e5f6a7-b8c9-0123-def4-567890123456"
}

Field	Type	Description
`id`	string (UUID)	Transaction identifier

Transaction Webhook

After the transfer is processed, an activity webhook is delivered.

Endpoint: POST {base_url}/v2/webhooks/activities

{
  "id": "d4e5f6a7-b8c9-0123-def4-567890123456",
  "user_address": "0x7e1Cc1685D68D486b22D3880030C24434E3b90a9",
  "type": "CardTransfer",
  "status": "Completed",
  "direction": "Outbound",
  "source": {
    "type": "Wallet",
    "wallet": {
      "address": "0xAAFF0821A09A1Aac28B72dD3Ff410A7ea5FEb874"
    }
  },
  "destination": {
    "type": "Cards",
    "card": {
      "id": "c34908da-d980-4a9c-9b39-4dabd6f6144e",
      "pan_last": "4242",
      "payment_system": "VISA"
    }
  },
  "source_amount": {
    "amount": 109.41,
    "token_symbol": "WUSD",
    "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
  },
  "destination_amount": {
    "amount": 100.00,
    "currency": "EUR"
  },
  "operations": [
    {
      "hash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
      "operation_amount": {
        "amount": -109.41,
        "token_symbol": "WUSD",
        "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
      },
      "rate": {
        "ticker": "EUR/WUSD",
        "rate": 0.914
      }
    }
  ],
  "created_at": "2024-01-01T13:00:00.000Z",
  "activity_steps": [
    {
      "type": "Initiated",
      "status": "Completed",
      "created_at": "2024-01-01T13:00:00.000Z",
      "completed_at": "2024-01-01T13:00:00.000Z"
    },
    {
      "type": "CryptoOut",
      "status": "Completed",
      "created_at": "2024-01-01T13:00:00.000Z",
      "completed_at": "2024-01-01T13:00:10.000Z"
    },
    {
      "type": "Review",
      "status": "Completed",
      "created_at": "2024-01-01T13:00:10.000Z",
      "completed_at": "2024-01-01T13:00:15.000Z"
    },
    {
      "type": "CardOut",
      "status": "Completed",
      "created_at": "2024-01-01T13:00:15.000Z",
      "completed_at": "2024-01-01T13:00:30.000Z"
    },
    {
      "type": "Completed",
      "status": "Completed",
      "created_at": "2024-01-01T13:00:30.000Z",
      "completed_at": "2024-01-01T13:00:30.000Z"
    }
  ]
}

Activity Steps

Step	Description
`Initiated`	Transfer request received
`CryptoOut`	Tokens debited from user's wallet
`Review`	Compliance review (automatic for most transfers)
`CardOut`	Funds sent to recipient's card
`Completed`	Transfer completed

Webhook Fields

Field	Type	Description
`type`	string	`CardTransfer`
`status`	enum	`Pending`, `Processing`, `Completed`, `Failed`
`direction`	string	Always `Outbound` for push to card
`source.wallet.address`	string	User's wallet address
`destination.card.id`	string	Card token (external_card_id)
`destination.card.pan_last`	string	Last 4 digits of card
`destination.card.payment_system`	string	`VISA` or `MASTERCARD`

Error Handling

Estimation Errors

Error Reason	Field	Description
`ErrorMissingField`	`external_card_id`	Card token is required
`ErrorInvalidField`	`amount`	Amount must be greater than zero
`ErrorMissingField`	`tokens`	At least one token address required
`ErrorNotSupported`		CardTransfer capability not active

Execution Errors

Error Reason	Field	Description
`ErrorInvalidField`	`estimation_id`	Must be a valid UUID
`ErrorInvalidField`	`token_address`	Must be a valid address
`ErrorNotFound`	`estimation_id`	Estimation not found or expired
`ErrorInsufficientFunds`		User lacks sufficient token balance
`ErrorNotSupported`		CardTransfer capability not active

Error Response Format

{
  "error_reason": "ErrorMissingField",
  "error_description": "external card id is required",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    {
      "key": "field",
      "details": "external_card_id"
    },
    {
      "key": "issue",
      "details": "missing"
    }
  ]
}

Capability

Push to card requires CardTransfer capability to be active. Check capabilities via GET /api/v2/user before initiating transfers.