Stored Value Cards

Stored value card operations cover the management of gift cards and prepaid cards — checking their balance, loading funds, and activating new cards.

Balance Enquiry

Retrieves the current balance on a gift or prepaid card. Accepts either an encrypted card or a reuse token.

Query the balance on a card

post

https://emea.gsc.verifone.cloud/oidchttps://us.gsc.verifone.cloud/oidchttps://nz.gsc.verifone.cloud/oidchttps://cst.test-gsc.vfims.com/oidchttps://uscst-gb.gsc.vficloud.net/oidc

/api/v2/transactions/balance

This retrieves the current balance on a gift/prepaid card.

Authorizations

BasicAuth

AuthorizationstringRequired

Header parameters

x-vfi-api-idempotencykeystringOptional

Example: 63bbc548-d2de-4546-b106-880a5018461c

A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.

Body

application/json

or

Responses

201

The Card Balance Enquiry Response.

application/json

400

Bad Request

application/json

401

Unauthorised

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post

/api/v2/transactions/balance

HTTPcURLJavaScriptPython

POST /oidc/api/v2/transactions/balance HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 718

{
  "payment_provider_contract": "30b8bec8-5042-4e67-939c-5453fbe41711",
  "customer": "0a57b387-2ba7-4f65-be2f-e176bb49d2ce",
  "dynamic_descriptor": "text",
  "invoice_number": "text",
  "merchant_reference": "7a1db7a8-6f24-4bc5-a51b-cef33fc05140",
  "shopper_interaction": "ECOMMERCE",
  "currency_code": "AED",
  "card_brand": "text",
  "encrypted_card": "U3dhZ2dlciByb2Nrcw==",
  "public_key_alias": "text",
  "token_preference": {
    "token_scope": "0e48425a-f1bc-431a-b7d8-f866de8ba276",
    "reuse_token_type": "INTERNAL",
    "token_type": "REUSE",
    "token_expiry_date": "2026-06-15"
  },
  "pay_with_points": {
    "enabled": false,
    "points_type": "AMEX",
    "points_transaction_reference": "text",
    "points_transaction_reference_type": "text",
    "points_to_redeem": "text",
    "total_basket_amount": 1
  }
}

{
  "id": "text",
  "balance_amount": 1,
  "balance_points": [
    {
      "points_type": "AMEX",
      "balance_points": "text",
      "identifier": "text",
      "points_transaction_reference": "text",
      "points_transaction_reference_type": "text",
      "points_conversion_rate": 1,
      "min_reward_amount": 1,
      "max_reward_amount": 1
    }
  ],
  "created_at": "2026-06-15T12:01:51.579Z",
  "customer": "text",
  "invoice_number": "text",
  "merchant_reference": "text",
  "processor": "text",
  "processor_reference": "text",
  "processor_details": {},
  "status": "INITIATED",
  "status_reason": "text",
  "reason_code": "text",
  "arn": "text",
  "authorization_code": "5B1D4C",
  "rrn": "text",
  "shopper_interaction": "ecommerce",
  "stan": 1,
  "token_details": {
    "reuse_token": "text",
    "reuse_token_type": "CHASE",
    "analytics_token": "text",
    "token_expiry_date": "2026-06-15",
    "token_scope": "123e4567-e89b-12d3-a456-426614174000",
    "token_status": "DELETED",
    "created_at": "2026-06-15",
    "updated_at": "2026-06-15",
    "variant": "NEW_WORLD",
    "type": "CREDIT",
    "issuer_name": "HSBC",
    "issuer_country": "ZZZ",
    "brand": "VISA",
    "expiry_year": 2021,
    "expiry_month": 12,
    "card_holder_name": "MR J HOLDER",
    "last_four": "3127",
    "bin": "492912",
    "currency_code": "AED"
  },
  "card_details": {
    "masked_card_number": "520000****1096",
    "expiry_year": 2024,
    "expiry_month": 12
  },
  "additional_data": {
    "acquirer_response_code": "0000",
    "acquirer_response_message": "text",
    "acquirer_authorizing_network_id": "text",
    "acquirer_authorizing_network_id_descriptor": "text",
    "settlement_date": "2026-06-15",
    "issuer_receipt_text": "text"
  }
}

---

Load Card (Add Funds)

Adds funds to an existing card. Use this for load, reload, top-up, and deposit operations.

Add funds to a card

post

https://emea.gsc.verifone.cloud/oidchttps://us.gsc.verifone.cloud/oidchttps://nz.gsc.verifone.cloud/oidchttps://cst.test-gsc.vfims.com/oidchttps://uscst-gb.gsc.vficloud.net/oidc

/api/v2/transactions/stored-value-card/load

Load a card with given value. This is to be used for load, reload, top-up, deposit operations.

Authorizations

BearerAuthBasicAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

x-vfi-api-idempotencykeystringOptional

Example: 63bbc548-d2de-4546-b106-880a5018461c

A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.

Body

application/json

or

Responses

201

Response for gift card transactions

application/json

400

Bad Request

application/json

401

Unauthorised

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post

/api/v2/transactions/stored-value-card/load

HTTPcURLJavaScriptPython

POST /oidc/api/v2/transactions/stored-value-card/load HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 561

{
  "payment_provider_contract": "30b8bec8-5042-4e67-939c-5453fbe41711",
  "customer": "0a57b387-2ba7-4f65-be2f-e176bb49d2ce",
  "invoice_number": "text",
  "merchant_reference": "7a1db7a8-6f24-4bc5-a51b-cef33fc05140",
  "dynamic_descriptor": "text",
  "shopper_interaction": "ECOMMERCE",
  "currency_code": "AED",
  "card_brand": "text",
  "promo_code": "text",
  "amount": 0,
  "encrypted_card": "U3dhZ2dlciByb2Nrcw==",
  "token_preference": {
    "token_scope": "0e48425a-f1bc-431a-b7d8-f866de8ba276",
    "reuse_token_type": "INTERNAL",
    "token_type": "REUSE",
    "token_expiry_date": "2026-06-15"
  },
  "public_key_alias": "text"
}

{
  "id": "text",
  "balance_amount": 1,
  "created_at": "2026-06-15T12:01:51.579Z",
  "customer": "text",
  "invoice_number": "text",
  "merchant_reference": "text",
  "processor": "text",
  "processor_reference": "text",
  "processor_details": {},
  "status": "INITIATED",
  "status_reason": "text",
  "arn": "text",
  "authorization_code": "5B1D4C",
  "rrn": "text",
  "reason_code": "text",
  "shopper_interaction": "ecommerce",
  "stan": 1,
  "promo_code": "text",
  "token_details": {
    "reuse_token": "text",
    "reuse_token_type": "CHASE",
    "analytics_token": "text",
    "token_expiry_date": "2026-06-15",
    "token_scope": "123e4567-e89b-12d3-a456-426614174000",
    "token_status": "DELETED",
    "created_at": "2026-06-15",
    "updated_at": "2026-06-15",
    "variant": "NEW_WORLD",
    "type": "CREDIT",
    "issuer_name": "HSBC",
    "issuer_country": "ZZZ",
    "brand": "VISA",
    "expiry_year": 2021,
    "expiry_month": 12,
    "card_holder_name": "MR J HOLDER",
    "last_four": "3127",
    "bin": "492912",
    "currency_code": "AED"
  },
  "card_details": {
    "masked_card_number": "520000****1096",
    "expiry_year": 2024,
    "expiry_month": 12
  },
  "amount": 0,
  "additional_data": {
    "acquirer_response_code": "0000",
    "acquirer_response_message": "text",
    "acquirer_authorizing_network_id": "text",
    "acquirer_authorizing_network_id_descriptor": "text",
    "settlement_date": "2026-06-15",
    "issuer_receipt_text": "text"
  }
}

---

Activate Card

Activates a new gift card, enabling the cardholder to access the stored funds. Setting activate_now: false checks activation eligibility without changing the card status.

activate_now: false is only supported for SVS gift cards in the US region.

Activate a gift card

post

https://emea.gsc.verifone.cloud/oidchttps://us.gsc.verifone.cloud/oidchttps://nz.gsc.verifone.cloud/oidchttps://cst.test-gsc.vfims.com/oidchttps://uscst-gb.gsc.vficloud.net/oidc

/api/v2/transactions/stored-value-card/activate

Activating the card allows the cardholder to access the funds stored on the card.

Authorizations

BearerAuthBasicAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

x-vfi-api-idempotencykeystringOptional

Example: 63bbc548-d2de-4546-b106-880a5018461c

A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.

Body

application/json

or

Responses

201

Response for gift card transactions

application/json

400

Bad Request

application/json

401

Unauthorised

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post

/api/v2/transactions/stored-value-card/activate

HTTPcURLJavaScriptPython

POST /oidc/api/v2/transactions/stored-value-card/activate HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 581

{
  "payment_provider_contract": "30b8bec8-5042-4e67-939c-5453fbe41711",
  "customer": "0a57b387-2ba7-4f65-be2f-e176bb49d2ce",
  "invoice_number": "text",
  "merchant_reference": "7a1db7a8-6f24-4bc5-a51b-cef33fc05140",
  "dynamic_descriptor": "text",
  "shopper_interaction": "ECOMMERCE",
  "currency_code": "AED",
  "card_brand": "text",
  "promo_code": "text",
  "amount": 0,
  "activate_now": true,
  "encrypted_card": "U3dhZ2dlciByb2Nrcw==",
  "token_preference": {
    "token_scope": "0e48425a-f1bc-431a-b7d8-f866de8ba276",
    "reuse_token_type": "INTERNAL",
    "token_type": "REUSE",
    "token_expiry_date": "2026-06-15"
  },
  "public_key_alias": "text"
}

{
  "id": "text",
  "balance_amount": 1,
  "created_at": "2026-06-15T12:01:51.579Z",
  "customer": "text",
  "invoice_number": "text",
  "merchant_reference": "text",
  "processor": "text",
  "processor_reference": "text",
  "processor_details": {},
  "status": "INITIATED",
  "status_reason": "text",
  "arn": "text",
  "authorization_code": "5B1D4C",
  "rrn": "text",
  "reason_code": "text",
  "shopper_interaction": "ecommerce",
  "stan": 1,
  "promo_code": "text",
  "token_details": {
    "reuse_token": "text",
    "reuse_token_type": "CHASE",
    "analytics_token": "text",
    "token_expiry_date": "2026-06-15",
    "token_scope": "123e4567-e89b-12d3-a456-426614174000",
    "token_status": "DELETED",
    "created_at": "2026-06-15",
    "updated_at": "2026-06-15",
    "variant": "NEW_WORLD",
    "type": "CREDIT",
    "issuer_name": "HSBC",
    "issuer_country": "ZZZ",
    "brand": "VISA",
    "expiry_year": 2021,
    "expiry_month": 12,
    "card_holder_name": "MR J HOLDER",
    "last_four": "3127",
    "bin": "492912",
    "currency_code": "AED"
  },
  "card_details": {
    "masked_card_number": "520000****1096",
    "expiry_year": 2024,
    "expiry_month": 12
  },
  "amount": 0,
  "additional_data": {
    "acquirer_response_code": "0000",
    "acquirer_response_message": "text",
    "acquirer_authorizing_network_id": "text",
    "acquirer_authorizing_network_id_descriptor": "text",
    "settlement_date": "2026-06-15",
    "issuer_receipt_text": "text"
  }
}

---

Key Response Fields

StoredValueCardResponse / BalanceEnquiryResponse
  ├── id                ← transaction ID
  ├── status            ← AUTHORIZED, DECLINED, etc.
  ├── balance_amount    ← remaining balance (no decimal, e.g. $1.50 = 150)
  ├── authorization_code
  ├── rrn
  └── token_details     ← populated if token_preference was sent

balance_amount follows ISO 4217 decimal conventions (e.g. USD uses 2 decimal places, so 150 = $1.50). Iceland Krona (ISK) uses 2 decimal places with fixed minor units of 00.