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.
This retrieves the current balance on a gift/prepaid card.
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.
The Card Balance Enquiry Response.
The ID of the transaction.
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.
The time at which the transaction was created.
The ID of a customer
Optional. The invoice number to track this payment.
A reference specified by the merchant to identify the transaction
The name of the processor used for this transaction
Reference identifying the transaction, as provided by the processor.
Stores all details specific for the processor of the transaction.
The outcome of the payment request.
Message provided by the 3rd party service as additional information, when the transaction does not succeed.
A reason code assigned by the acquiring platform; '0000' in case of success
Acquirer reference number. Generated by the Acquirer at the time of clearing for card transactions.
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.
5B1D4CA 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>.
Determines the point of sale of a customer. Possible values: pos, moto, mail_order, telephone_order, ecommerce and cont_auth
System Trace Audit Number.
Bad Request
Unauthorised
Forbidden
Not Found
Internal Server Error
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-01-01"
},
"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-01-01T00:00:00.000Z",
"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-01-01",
"token_scope": "123e4567-e89b-12d3-a456-426614174000",
"token_status": "DELETED",
"created_at": "2026-01-01",
"updated_at": "2026-01-01",
"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-01-01",
"issuer_receipt_text": "text"
}
}Load Card (Add Funds)
Adds funds to an existing card. Use this for load, reload, top-up, and deposit operations.
Load a card with given value. This is to be used for load, reload, top-up, deposit operations.
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.
Response for gift card transactions
The ID of the transaction.
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:
The time at which the transaction was created.
The ID of a customer.
Optional. The invoice number to track this payment.
A reference specified by the merchant to identify the transaction.
The name of the processor used for this transaction
Reference identifying the transaction, as provided by the processor.
Reference identifying the transaction, as provided by the processor.
The outcome of the payment request.
Message provided by the 3rd party service as additional information, when the transaction does not succeed.
Acquirer reference number. Generated by the Acquirer at the time of clearing for card transactions.
-
When the payment is authorized successfully, this field holds the authorization code for the payment.
-
When the payment is not authorized, this field is not returned.
5B1D4CA 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>.
A reason code assigned by the acquiring platform; '0000' in case of success
Determines the point of sale of a customer. Possible values: pos, moto, mail_order, telephone_order, ecommerce and cont_auth
System Trace Audit Number.
A code defined by the merchant that affects the calculation of the total amount.
Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field.
0Bad Request
Unauthorised
Forbidden
Not Found
Internal Server Error
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-01-01"
},
"public_key_alias": "text"
}{
"id": "text",
"balance_amount": 1,
"created_at": "2026-01-01T00:00:00.000Z",
"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-01-01",
"token_scope": "123e4567-e89b-12d3-a456-426614174000",
"token_status": "DELETED",
"created_at": "2026-01-01",
"updated_at": "2026-01-01",
"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-01-01",
"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.
Activating the card allows the cardholder to access the funds stored on the card.
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.
Response for gift card transactions
The ID of the transaction.
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:
The time at which the transaction was created.
The ID of a customer.
Optional. The invoice number to track this payment.
A reference specified by the merchant to identify the transaction.
The name of the processor used for this transaction
Reference identifying the transaction, as provided by the processor.
Reference identifying the transaction, as provided by the processor.
The outcome of the payment request.
Message provided by the 3rd party service as additional information, when the transaction does not succeed.
Acquirer reference number. Generated by the Acquirer at the time of clearing for card transactions.
-
When the payment is authorized successfully, this field holds the authorization code for the payment.
-
When the payment is not authorized, this field is not returned.
5B1D4CA 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>.
A reason code assigned by the acquiring platform; '0000' in case of success
Determines the point of sale of a customer. Possible values: pos, moto, mail_order, telephone_order, ecommerce and cont_auth
System Trace Audit Number.
A code defined by the merchant that affects the calculation of the total amount.
Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field.
0Bad Request
Unauthorised
Forbidden
Not Found
Internal Server Error
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-01-01"
},
"public_key_alias": "text"
}{
"id": "text",
"balance_amount": 1,
"created_at": "2026-01-01T00:00:00.000Z",
"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-01-01",
"token_scope": "123e4567-e89b-12d3-a456-426614174000",
"token_status": "DELETED",
"created_at": "2026-01-01",
"updated_at": "2026-01-01",
"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-01-01",
"issuer_receipt_text": "text"
}
}Key Response Fields
Was this helpful?