Balance Inquiry

Request to retrieve the balance available to spend on a card. You can use this operation to request: The balance available on a gift card, or The balance available to spend by redeeming rewards earned using a card enrolled in a rewards program. For gift cards, only the balance available is returned. For credit or debit cards enrolled in the American Express Membership Rewards program, points available to redeem and the conversion rate used to determine the available balance are returned.

PUT https://api/rest/version/67 / merchant / {merchantId} / balanceInquiry

Authentication

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • Basic HTTP authentication as described at w3.org. Provide 'merchant.<your gateway merchant ID>' in the userid portion and your API password in the password portion.

Request

URL Parameters

{merchantId} Alphanumeric + additional characters REQUIRED

The unique identifier issued to you by your payment provider.


This identifier can be up to 12 characters in length.


Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40

Fields

correlationId String OPTIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
order.currency Upper case alphabetic text REQUIRED

The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.subMerchant OPTIONAL

Provide these parameters if you are a payment aggregator or facilitator and process payments on behalf of other merchants.

These merchants are referred to as your sub-merchants. The sub-merchant's details you provide may be displayed on the payer's cardholder statement. Note that your acquirer may require you to register with the card scheme(s) before allowing you to submit sub-merchant details with a transaction. This data must be on the initial transaction of an order, subsequent transactions with sub-merchant will be rejected.

order.subMerchant.address OPTIONAL

The sub-merchant's address.

order.subMerchant.address.city String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.company String OPTIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.country Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.subMerchant.address.postcodeZip Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
order.subMerchant.address.stateProvince String OPTIONAL

The state or province code of the address.

For an address in the United States provide the 2-letter ISO 3166-2 state code. For US military bases provide one of AE, AA, AP.

For an address in Canada provide the 2-letter ISO 3166-2 province code.

Data can consist of any characters

Min length: 1 Max length: 20
order.subMerchant.address.street String OPTIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.street2 String OPTIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.bankIndustryCode Digits OPTIONAL

Code used by acquirer to describe the business or industry the sub-merchant operates in.

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 4
order.subMerchant.disputeContactPhone Telephone Number OPTIONAL

Only provide this field if you have received a notification from the scheme that either you or the sub-merchant has a high number of disputes.

In this case, provide a phone number that payers can use to contact the sub-merchant in case of a dispute. Where applicable, the issuer may display this phone number on the cardholder statement. The phone number must be provided in ITU-T E123 format.

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
order.subMerchant.email Email OPTIONAL

The sub-merchant's email address.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

order.subMerchant.governmentCountryCode Upper case alphabetic text OPTIONAL

Only provide this field if the sub merchant is a government owned or controlled merchant.

A sub merchant is considered a government owned or controlled entity (government controlled merchant) if 50% or more of the sub merchant is owned by the government. Provide the ISO 3166 three-letter country code of the government country where this differs from the sub merchant's physical location country.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.subMerchant.identifier Alphanumeric + additional characters REQUIRED

Your identifier for the sub-merchant.

You can use this identifier in searches and reports in the gateway.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '.'

Min length: 1 Max length: 100
order.subMerchant.marketplaceId String OPTIONAL

If the sub merchant is a marketplace, provide the marketplace ID assigned to them by Visa.

A sub merchant is considered a marketplace if they operate a platform (online commerce website or mobile application) where retailers can sell goods and services.

Data can consist of any characters

Min length: 1 Max length: 11
order.subMerchant.phone String OPTIONAL

The sub-merchant's phone number

Data can consist of any characters

Min length: 1 Max length: 20
order.subMerchant.registeredName String OPTIONAL

The legal name of the sub-merchant.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.tradingName String REQUIRED

The trading name of the sub merchant, also known as doing business as (DBA), operating as or trading as.

For MasterCard transactions the name must not exceed 21 characters. For American Express transactions the name must not exceed 27 characters (or 36 characters including the aggregator name). The trading name may be displayed on the payer's cardholder statement. Therefore if you need to shorten it, use an abbreviation that will be meaningful to the payer when displayed on their statement.

Data can consist of any characters

Min length: 1 Max length: 100
responseControls OPTIONAL

Container for fields that control the response returned for the request.

responseControls.sensitiveData String OPTIONAL

Indicates how sensitive data is returned in the response.

Data can consist of any characters

Min length: 1 Max length: 50
session.id ASCII Text OPTIONAL

Identifier of the payment session containing values for any of the request fields to be used in this operation.

Values provided in the request will override values contained in the session.

Data consists of ASCII characters

Min length: 31 Max length: 35
session.version ASCII Text OPTIONAL

Use this field to implement optimistic locking of the session content.

Do this if you make business decisions based on data from the session and wish to ensure that the same data is being used for the request operation.

To use optimistic locking, record session.version when you make your decisions, and then pass that value in session.version when you submit your request operation to the gateway.

If session.version provided by you does not match that stored against the session, the gateway will reject the operation with error.cause=INVALID_REQUEST.

See Making Business Decisions Based on Session Content.

Data consists of ASCII characters

Min length: 10 Max length: 10

Response

Fields

correlationId String CONDITIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
merchant Alphanumeric + additional characters ALWAYS PROVIDED

Your identifier issued to you by your provider.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
order.currency Upper case alphabetic text ALWAYS PROVIDED

The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.subMerchant CONDITIONAL

Provide these parameters if you are a payment aggregator or facilitator and process payments on behalf of other merchants.

These merchants are referred to as your sub-merchants. The sub-merchant's details you provide may be displayed on the payer's cardholder statement. Note that your acquirer may require you to register with the card scheme(s) before allowing you to submit sub-merchant details with a transaction. This data must be on the initial transaction of an order, subsequent transactions with sub-merchant will be rejected.

order.subMerchant.address CONDITIONAL

The sub-merchant's address.

order.subMerchant.address.city String CONDITIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.company String CONDITIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.country Upper case alphabetic text CONDITIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.subMerchant.address.postcodeZip Alphanumeric + additional characters CONDITIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
order.subMerchant.address.stateProvince String CONDITIONAL

The state or province code of the address.

For an address in the United States provide the 2-letter ISO 3166-2 state code. For US military bases provide one of AE, AA, AP.

For an address in Canada provide the 2-letter ISO 3166-2 province code.

Data can consist of any characters

Min length: 1 Max length: 20
order.subMerchant.address.street String CONDITIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.street2 String CONDITIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.bankIndustryCode Digits CONDITIONAL

Code used by acquirer to describe the business or industry the sub-merchant operates in.

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 4
order.subMerchant.disputeContactPhone Telephone Number CONDITIONAL

Only provide this field if you have received a notification from the scheme that either you or the sub-merchant has a high number of disputes.

In this case, provide a phone number that payers can use to contact the sub-merchant in case of a dispute. Where applicable, the issuer may display this phone number on the cardholder statement. The phone number must be provided in ITU-T E123 format.

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
order.subMerchant.email Email CONDITIONAL

The sub-merchant's email address.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

order.subMerchant.governmentCountryCode Upper case alphabetic text CONDITIONAL

Only provide this field if the sub merchant is a government owned or controlled merchant.

A sub merchant is considered a government owned or controlled entity (government controlled merchant) if 50% or more of the sub merchant is owned by the government. Provide the ISO 3166 three-letter country code of the government country where this differs from the sub merchant's physical location country.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.subMerchant.identifier Alphanumeric + additional characters ALWAYS PROVIDED

Your identifier for the sub-merchant.

You can use this identifier in searches and reports in the gateway.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '.'

Min length: 1 Max length: 100
order.subMerchant.marketplaceId String CONDITIONAL

If the sub merchant is a marketplace, provide the marketplace ID assigned to them by Visa.

A sub merchant is considered a marketplace if they operate a platform (online commerce website or mobile application) where retailers can sell goods and services.

Data can consist of any characters

Min length: 1 Max length: 11
order.subMerchant.phone String CONDITIONAL

The sub-merchant's phone number

Data can consist of any characters

Min length: 1 Max length: 20
order.subMerchant.registeredName String CONDITIONAL

The legal name of the sub-merchant.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.tradingName String ALWAYS PROVIDED

The trading name of the sub merchant, also known as doing business as (DBA), operating as or trading as.

For MasterCard transactions the name must not exceed 21 characters. For American Express transactions the name must not exceed 27 characters (or 36 characters including the aggregator name). The trading name may be displayed on the payer's cardholder statement. Therefore if you need to shorten it, use an abbreviation that will be meaningful to the payer when displayed on their statement.

Data can consist of any characters

Min length: 1 Max length: 100
response ALWAYS PROVIDED

Value as generated by the acquirer that summarizes the success or otherwise of the proposed operation.

response.acquirerCode ASCII Text CONDITIONAL

Value as generated by the acquirer that summarizes the success or otherwise of the proposed operation.

Data consists of ASCII characters

Min length: 1 Max length: 100
response.acquirerMessage ASCII Text CONDITIONAL

The response from the acquirer in the text form.

This field is used in addition to response.acquirerCode for some acquirers where additional information needs to be communicated. For example, contact details to allow the merchant to contact the issuer directly to seek authorisation for the transaction.

Data consists of ASCII characters

Min length: 1 Max length: 255
response.gatewayCode Enumeration ALWAYS PROVIDED

Summary of the success or otherwise of the operation.

Value must be a member of the following list. The values are case sensitive.

BALANCE_AVAILABLE

A balance amount is available for the card, and the payer can redeem points.

BALANCE_UNKNOWN

A balance amount might be available for the card. Points redemption should be offered to the payer.

NO_BALANCE

A balance amount is not available for the card. The payer cannot redeem points.

TIMED_OUT

The gateway has timed out the request to the acquirer because it did not receive a response. Points redemption should not be offered to the payer.

result Enumeration ALWAYS PROVIDED

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

FAILURE

The operation was declined or rejected by the gateway, acquirer or issuer

PENDING

The operation is currently in progress or pending processing

SUCCESS

The operation was successfully processed

UNKNOWN

The result of the operation is unknown

sourceOfFunds ALWAYS PROVIDED
sourceOfFunds.provided CONDITIONAL

Information about the source of funds when it is directly provided (as opposed to via a token or session).

For browser payments, the source of funds details are usually collected from the payer on the payment provider's website and provided to you when you retrieve the transaction details (for a successful transaction). However, for some payment types (such as giropay), you must collect the information from the payer and supply it here.

sourceOfFunds.provided.giftCard CONDITIONAL

Contains gift card details

sourceOfFunds.provided.giftCard.brand Enumeration ALWAYS PROVIDED

The brand name used to describe the card that is recognized and accepted globally.

For many major card types this will match the scheme name.

Value must be a member of the following list. The values are case sensitive.

LOCAL_BRAND_ONLY

The card does not have a global brand.

sourceOfFunds.provided.giftCard.localBrand String ALWAYS PROVIDED

The brand name used to describe a card as determined by the gateway, based on the BIN range of the card.

Data can consist of any characters

Min length: 1 Max length: 50
sourceOfFunds.provided.giftCard.number Masked digits ALWAYS PROVIDED

Card number as printed or embossed on the gift card.

Data is a string that consists of the characters 0-9, plus 'x' for masking

Min length: 9 Max length: 19
sourceOfFunds.provided.giftCard.pin Masked digits CONDITIONAL

PIN number for the gift card.

Data is a string that consists of the characters 0-9, plus 'x' for masking

Min length: 4 Max length: 8
sourceOfFunds.provided.giftCard.scheme Enumeration ALWAYS PROVIDED

The organization that owns a card brand and defines operating regulations for its use.

Value must be a member of the following list. The values are case sensitive.

OTHER

The scheme of the card used in the transaction could not be identified.

sourceOfFunds.type Enumeration CONDITIONAL

The payment method your payer has chosen for this payment.

Value must be a member of the following list. The values are case sensitive.

CARD

Use this value for payments that obtained the card details either directly from the card, or from a POS terminal, or from a wallet, or through a device payment method.

Errors

error

Information on possible error conditions that may occur while processing an operation using the API.

error.cause Enumeration

Broadly categorizes the cause of the error.

For example, errors may occur due to invalid requests or internal system failures.

Value must be a member of the following list. The values are case sensitive.

INVALID_REQUEST

The request was rejected because it did not conform to the API protocol.

REQUEST_REJECTED

The request was rejected due to security reasons such as firewall rules, expired certificate, etc.

SERVER_BUSY

The server did not have enough resources to process the request at the moment.

SERVER_FAILED

There was an internal system failure.

error.explanation String

Textual description of the error based on the cause.

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.

Data can consist of any characters

Min length: 1 Max length: 1000
error.field String

Indicates the name of the field that failed validation.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Data can consist of any characters

Min length: 1 Max length: 100
error.supportCode String

Indicates the code that helps the support team to quickly identify the exact cause of the error.

This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.

Data can consist of any characters

Min length: 1 Max length: 100
error.validationType Enumeration

Indicates the type of field validation error.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Value must be a member of the following list. The values are case sensitive.

INVALID

The request contained a field with a value that did not pass validation.

MISSING

The request was missing a mandatory field.

UNSUPPORTED

The request contained a field that is unsupported.

result Enumeration

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

ERROR

The operation resulted in an error and hence cannot be processed.