Balance Enquiry

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

idstring · uuid-flexibleOptional

The ID of the transaction.

balance_amountintegerOptional

Balance amount is the amount remaining on a card or account of cardholder without a decimal place e.g. $1.5 = 150.

The required number of decimal places for a currency code is according to ISO 4217. However the following table takes precedence over ISO 4217:

Code	Currency	Decimals	Fixed minor units
ISK	Iceland krona	2	00

For Account Verification transactions, provide 0 as value for this field.

created_atstring · date-timeOptional

The time at which the transaction was created.

customerstringOptional

The ID of a customer

invoice_numberstring · max: 127Optional

Optional. The invoice number to track this payment.

merchant_referencestring · max: 50Optional

A reference specified by the merchant to identify the transaction

processorstringOptional

The name of the processor used for this transaction

processor_referencestringOptional

Reference identifying the transaction, as provided by the processor.

processor_detailsobjectOptional

Stores all details specific for the processor of the transaction.

statusstring · enumOptional

The outcome of the payment request.

Possible values:

status_reasonstringOptional

Message provided by the 3rd party service as additional information, when the transaction does not succeed.

reason_codestring · max: 4Optional

A reason code assigned by the acquiring platform; '0000' in case of success

arnstringOptional

Acquirer reference number. Generated by the Acquirer at the time of clearing for card transactions.

authorization_codestring · max: 6Optional

Authorization code:

• When the payment is authorized successfully, this field holds the authorisationCode code for the payment.

• When the payment is not authorized, this field is not returned.

Example: 5B1D4C

rrnstring · max: 12Optional

A client (user friendly) identifier for the transaction generated at the outset of a business event. The format will be dependent on the calling system.

    A reference supplied by the system retaining the original source information and used to assist in locating that transaction or a copy of the transaction. This value is critical in matching values that are sent to other Payment processors or Acquirers. This value would correspond to the ISO8583 specification as RRN in attribute DE 37, which limits the value to being an alphanumeric value 12 characters.
    
    For the GSC client android application the format will correspond to YYMMdd<stan 6 digits>.

shopper_interactionstring · enumOptional

Determines the point of sale of a customer. Possible values: pos, moto, mail_order, telephone_order, ecommerce and cont_auth

Possible values:

stannumberOptional

System Trace Audit Number.

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-13"
  },
  "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-13T15:59:24.392Z",
  "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-13",
    "token_scope": "123e4567-e89b-12d3-a456-426614174000",
    "token_status": "DELETED",
    "created_at": "2026-06-13",
    "updated_at": "2026-06-13",
    "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-13",
    "issuer_receipt_text": "text"
  }
}