Download Visa Direct API Reference

Adjustment API

The AdjustReverseFundsTransactions resource credits (pushes back) funds to the sender's Visa account by initiating a financial message called an Account Funding Transaction Reversal (AFTR) without the 24 hours limitation in the AFTR.


Create Adjustment Reverse Funds Transaction
v1 - Latest

Create Adjustment Funds Transaction

Request
Request Body schema:

Request body for creating adjustment of funds transfer

acquirerCountryCode
required
number

Use a three digit numeric country code for the country of the BIN under which your Visa Direct program is registered.

acquiringBin
required
number

The Bank Identification Number (BIN) under which your Visa Direct is registered. This must match the information provided during enrollment.

amount
required
number <double>

The amount of the transaction, inclusive of all fees assessed for the transaction, including currency conversion fees.
Minimum Value: 0
Maximum value: 999999999.999
Allowed fractional digits: 3
Note: If a currency has three decimal places, the last digit of this field must be zero.
If a currency has 0 minor unit, this field must carry no fractional points.
If a currency has 2 minor units, the field must carry maximum two fractional points.

businessApplicationId
required
string 2 characters

Identifies the Visa Direct use case required for processing. This must match the value provided in the request of PullFundsTransactions.
For Argentina domestic purchase transactions the value should be "PS".

required
object
required
object
country
required
string [ 1 .. 3 ] characters

Should match the country information submitted in the original PullFundsTransactions

county
string <= 3 characters

Should match the county information submitted in the original PullFundsTransactions

state
string <= 2 characters

Should match the state information submitted in the original PullFundsTransactions

zipCode
string [ 5 .. 9 ] characters

Should match the zip code information submitted in the original PullFundsTransactions

idCode
required
string [ 1 .. 15 ] characters

A unique identifier for the card acceptor (Visa Direct merchant).

name
required
string [ 1 .. 25 ] characters

card acceptor name as it is sent in the original PullFundsTransactions.

terminalId
required
string [ 1 .. 8 ] characters

The identifier for the terminal at a card acceptor location. If sending transactions from a card not present environment, use the same value for all transactions.

localTransactionDateTime
required
string <date-time>

This field contains the local date and time when the Adjustment transaction is submitted.
Format: YYYY-MM-DDThh:mm:ss
Example: 2020-05-21T13:30:00

merchantCategoryCode
required
number

Contains a code describing the merchant's type of business product or service, also known as the merchant category code (MCC). These codes are based on the Merchant Classification Code Guideline available from the Bank Card Division of the ABA. Clients should send the same merchantCategoryCode that was submitted in the PullFundsTransactions

messageReasonCode
required
number

Message Reason Code: 2140 for AFT and 2150 for OCT. To identify advice type for issuers.
Message Reason Code: 5120 for OCT Debit Adjustments to reverse Sales Tax Rebates (Value-added tax) along with businessApplicationId field set to the value 'FD'.

required
object
panEntryMode
required
number

A 2-digit code that identifies the method used to enter the cardholder account number and card expiration date. This code specifies whether the entire magnetic stripe is included in an authorization or financial request. Note: Single digit value should pass directly without adding a 0 in front. Otherwise please use string data type.

posConditionCode
required
number

Contains a code identifying transaction conditions at the point-of-sale or point of service. For adjustment transaction, this field should set to 00 or 0.

specialConditionIndicatorMerchant
string 1 characters

1 - Purchase of Central Bank Digital Currency (CBDC) or Tokenized Deposits
2 - Purchase of Stablecoin (fiat-backed)
3 - Purchase of Blockchain Native Token/Coin
4 - Purchase of Non-Fungible Token (NFT)
7 - Purchase of Cryptocurrency

retrievalReferenceNumber
required
number

This field contains a number that is used with other data elements as a key to identify and track all messages related to a given cardholder transaction; that is, to a given transaction set. Recommended format: ydddhhnnnnnn. The first four digits must be a valid yddd date in the Julian date format, where the first digit = 0-9 (last digit of current year) and the next three digits = 001-366 (number of the day in the year), hh can be the two digit hour in a 24 hour clock (00-23) during which the transaction is performed, nnnnnn can be the systemsTraceAuditNumber or any 6 digit number. A unique value should be used for each API invocation. Note: This value for the purpose of credit adjustment must be different from the original request.

senderCurrencyCode
required
string 3 characters

Use a 3-character alpha or numeric currency code for currency of the sender. This code identifies the currency of the transaction amount sent in the amount field.
This field will be deprecated. Please use the replacement field transactionCurrencyCode instead.

senderPrimaryAccountNumber
required
string [ 13 .. 19 ] characters

This field contains a number identifying the customer account which could be a PAN or a token.
This field will be deprecated. Please use the replacement field primaryAccountNumber instead.

systemsTraceAuditNumber
required
number

This field contains a number assigned by the merchant, service provider or acquirer that uniquely identifies a cardholder transaction and all message types (also known as system transactions) that comprise it per individual program rules. A unique value should be used for each API invocation. Note: This value for the purpose of credit adjustment must be different from the original request.

transactionIdentifier
required
number

Clients shall send the Visa transaction identifier returned in the response of PullFundsTransactions. Note: This value for the purpose of credit adjustment must be same as the original request.

transactionTypeCode
required
number

A 2-digit code identifying the transaction type. It must be 02 (Adjustment—Debit) or 22 (Adjustment—Credit).
Note: For JSON format request, 02 is not legal for integer data type, please use 2 instead or pass “02” as a string. (AFT Debit adjustment is not available.)

object

Settlement Service Data object for Argentina required if transaction indicates Argentina national settlement.

reimbursementFee
required
number <double>

This field contains the Argentina member supplied reimbursement fee.

reimbursementFeeTax
number <double>

Conditional.

This field contains the VAT calculated for the IRF applicable to the transaction.

cardExpiryDate
string


Recommended Format: YYYY-MM
The expiration date for the sender's Visa account number in primaryAccountNumber.

cardProductCode
string [ 1 .. 2 ] characters

Used to identify the specific card product for the issuer.

object

Settlement Service Data object for Colombia required if transaction indicates Colombia national settlement.

countryCodeNationalService
required
number

The acquirer’s country code. Must be 170 for Colombia.

nationalNetReimbursementFeeBaseAmount
required
number <double>

The client supplied interchange reimbursement amount expressed in the transaction currency. This must be less than the transaction amount.

addValueTaxAmount
number <double>

This is the national government tax for added value of good or service.

addValueTaxReturn
number <double>

This is base value of the IVA (Sales tax). Optional. This field indicates base value of the IVA ( Sales tax which is part of the benefit of the tax legislations for the 2% sale tax return to the cardholder.

costTransactionIndicator
string 1 characters

Contains one of the below valid values:
0 - Not a cost inquiry amount
1 - Cost inquiry transaction

emvTransactionIndicator
string 1 characters

Contains one of the below valid values:
0 - Does not apply to EMV
1 - EMV transaction
2 - Fallback transaction

nationalChargebackReason
number

Contains a domestic chargeback reason code.

nationalNetMiscAmount
number <double>

This is an amount field that contains an airport charge, cashback or a tip.

nationalNetMiscAmountType
string 1 characters

It identifies the type of the miscellaneous amount – i.e. whether it is one of:
A - Airport charge
C - Cashback
T - Tip

Must be one of the above valid values if nationalNetMiscAmount > 0.

Must be skipped if nationalNetMiscAmount = 0.

nationalReimbursementFee
number <double>

Numeric entry indicating a fee for a National Settlement transaction. It must be zeros unless the transaction is a National Settlement transaction for a country using this capability. Two decimal positions are implied.
Minimum Value: 0
Maximum value: 999999999.999
Allowed fractional digits: 3

taxAmountConsumption
number <double>

This is the national consumption tax amount.

cpsAuthorizationCharacteristicsIndicator
string 1 characters

Conditional
Request for CPS authorization. If present, a valid value is required. Spaces or special characters are not allowed. Possible values are : Y (Transaction requests participation).

Note:Supported only in US for CPS (Custom Payment Service). This field is required for the transaction to qualify for CPS qualified Interchange rates and to avoid Transaction Integrity Fee. Please reach out to your Visa representative for details.

customerReference
string

Conditional.

This field contains a value that identifies the customer.
This field needs to be populated for Argentina domestic (OCT Debit Adjustment ) transactions where businessApplicationId is "PS".

digitalWalletProviderId
string [ 1 .. 11 ] characters

Used to identify the digital wallet provider. V.I.P. does not edit the field; it also does not send it to the issuer processor nor does it return this field in the response.

dynamicCurrencyConversionIndicator
string 1 characters

Used to indicate if the merchant or the ATM acquirer has performed Dynamic Currency Conversion (DCC).

enablerVerificationValue
string 5 characters

Enabler Verification Value (EVV) is a Visa assigned value that is used to identify enablers that participate in certain programs. The EVV is unique to the enabler.

merchantReference
string <= 35 characters

Conditional.

This field contains the merchant account key value for Argentina domestic purchase (POS) transactions.
This field needs to be populated for Argentina domestic (AFT Credit Adjustment ) transactions where businessApplicationId is "PS".

object

Settlement Service Data object for Mexico required if transaction indicates Mexico national settlement.

reimbursementFee
required
number <double>

This field contains the Client-Calculated Interchange Reimbursement Fee in the same currency as the transaction. It must not contain zeros.

reimbursementFeeTax
required
number <double>

This field contains the VAT calculated for the IRF applicable to the transaction. It must not contain zeros.

accountType
string 2 characters

This field contains one of the following values:
CO - Commercial products
CR - Credit
DB - Debit
PL - Private label
PP - Prepaid

irfCategoryCode
string [ 1 .. 2 ] characters

This field optionally contains any value from 00 to 99.

irfType
string 1 characters

This field contains one of the following values:
0 - Unknown/default
1 - Fixed
2 - Ad valorem (%)
3 - Composite (fixed amount and ad valorem)

merchantFiscalId
string <= 13 characters

This field contains RFC for the merchant. This is an alphanumeric field. The RFC format can be AAAANNNNNNAAA, where A is alphanumeric value and N is a numeric value.

primaryAccountNumber
string [ 13 .. 19 ] characters

Conditional

This field contains a number identifying the customer account which could be a PAN or a token.

recipientIdentificationNumberBusiness
string

Conditional.

For Argentina domestic purchase transactions this field contains the merchant’s value-added tax (VAT) registration number or single business reference number (SBRN).
This field needs to be populated for Argentina domestic (AFT Credit Adjustment ) transactions where businessApplicationId is "PS".

rewardProgramIdentificationCode
string 6 characters

Used to identify the reward program.

senderCardExpiryDate
string


Recommended Format: YYYY-MM
The expiration date for the sender's Visa account number in senderPrimaryAccountNumber.
This field will be deprecated. Please use the replacement field cardExpiryDate instead.

senderIdentificationNumberIndividual
string

Conditional.

This field contains the identification number issued to the individual by the government or an authorized national entity. For Argentina domestic purchase transactions this field contains the customer’s VAT registration number for tax identification.
This field needs to be populated for Argentina domestic (OCT Debit Adjustment ) transactions where businessApplicationId is "PS".

senderReference
string <= 16 characters

If the transaction is a money transfer, pre-paid load, or credit card bill pay, and if the sender intends to fund the transaction with a non-financial instrument (for example, cash), a reference number unique to the sender is required.

If the transaction is a funds disbursement, the field is required.

This field is required if senderAccountNumber is not sent.

object

This field will contain values that identify the type of service the transaction should be processed.

requestType
string <= 2 characters

Reserved for future use.

settlementServiceIndicator
number

This flag enables the originator to request for a particular settlement service to be used for settling the transaction.

Valid values are:
0 - International Settlement
9 - VIP to decide
8 - National Settlement

Note: The default value is 9. This field is only relevant for specific countries where the acquirer has to select 8 in order to settle in the national net settlement service.

surcharge
string <double>

When present, this field contains the sender's surcharge as assessed by the originator. Values in this field must be in the same currency and format as defined in the amount field.

tokenAssuranceMethod
string 2 characters

This field contains different category value to determine the Risk Score associated with the token and transaction.

transactionCurrencyCode
string 3 characters

Conditional

Use a 3-character alpha or numeric currency code for currency of the transaction. This code identifies the currency of the transaction amount sent in the amount field.

transactionLinkIdentifier
string [ 1 .. 36 ] characters

Transaction Link Identifier returned from other networks like MasterCard and Pulse

visaMerchantIdentifier
string

Visa Merchant Identifier assigned by Visa.

Responses
200

Adjustment Funds Transfer Response

Response Schema:
actionCode
required
string 2 characters

The results of the transaction request

Refer to actionCode

dateAndTimeTransmission
required
string <date-time>

This field contains the year, month, day, and time the transaction was processed by Visa Direct. Example: 2020-05-21T08:03:00.000Z

transactionIdentifier
required
number

Visa transaction identifier .

additionalTokenRespInfo
string 1 characters

This field when present in the API response identifies if the transaction is eligible for token services. Valid token service values are: 1 (Token program).

This field will not be sent in the response if the transaction is ineligible for token services.

cpsAuthorizationCharacteristicsIndicator
string 1 characters

Conditional
Indicates whether AFT transaction has qualified for CPS. Possible values are : F (Meets CPS/Account Funding requirements) , N (Not Qualified), T (Not Qualified)

Note:Supported only in US for CPS (Custom Payment Service). Please reach out to your Visa representative for details.

customerReference
string

This field contains a value that identifies the customer.
This field will be populated in the response for Argentina domestic AFT Credit Adjustment, transactions when businessApplicationId is "PS".

enablerVerificationValue
string 5 characters

Enabler Verification Value (EVV) is a Visa assigned value that is used to identify enablers that participate in certain programs. The EVV is unique to the enabler.

masterCardMerchantPaymentGatewayId
string [ 1 .. 11 ] characters

This field contains merchant payment gateway ID assigned by Mastercard, provided by the acquirer when a registered merchant payment gateway service provider participates in the transaction. Value is right-justified and zero-filled.

merchantReference
string <= 35 characters

This field contains the merchant account key value for Argentina domestic purchase (POS) transactions.
This field will be populated in the response for Argentina domestic, OCT Debit Adjustment, transactions where businessApplicationId is "PS".

originalActionCode
string 2 characters

The action code of the original transaction request
Refer to actionCode
Note: This field is only present, when the request is identified as a duplicate.

recipientIdentificationNumberBusiness
string

For Argentina domestic purchase transactions this field contains the merchant’s value-added tax (VAT) registration number or single business reference number (SBRN).
This field will be populated in the response for Argentina domestic OCT Debit Adjustment, transactions where businessApplicationId is "PS".

senderIdentificationNumberIndividual
string

This field contains the identification number issued to the individual by the government or an authorized national entity. For Argentina domestic purchase transactions this field contains the customer’s VAT registration number for tax identification.
This field will be populated in the response for Argentina domestic AFT Credit Adjustment, transactions when businessApplicationId is "PS".

object

This field will contain values that identifies the type of service assigned for the transaction.

requestType
string <= 2 characters

Reserved for future use.

object
settlementResponsibilityFlag
required
string

Possible values are true or false

givPreviouslyUpdatedFlag
string

Possible values are true or false

givUpdatedFlag
string

Possible values are true or false

settlementServiceFlag
string <= 1 characters

Possible values are:
0 - International Settlement
9 - VIP to decide
8 - National Settlement

tokenAssuranceMethod
string 2 characters

This field contains different category value to determine the Risk Score associated with the token and transaction.

transactionLinkIdentifier
string [ 1 .. 36 ] characters

Transaction Link Identifier returned from other networks like MasterCard and Pulse

© Copyright Visa. All Rights Reserved.

NOTICE: The software and accompanying information and documentation (together, the “Software”) remain the property of and are proprietary to Visa and its suppliers and affiliates. The Software remains protected by intellectual property rights and may be covered by U.S. and foreign patents or patent applications. The Software is licensed and not sold.

By accessing the Software you are agreeing to Visa's terms of use (developer.visa.com/terms) and privacy policy (usa.visa.com/legal/global-privacy-notice.html). In addition, all permissible uses of the Software must be in support of Visa products, programs and services provided through the Visa Developer Program (VDP) platform only (developer.visa.com). THE SOFTWARE AND ANY ASSOCIATED INFORMATION OR DOCUMENTATION IS PROVIDED ON AN “AS IS,” “AS AVAILABLE,” “WITH ALL FAULTS” BASIS WITHOUT WARRANTY OR CONDITION OF ANY KIND. YOUR USE IS AT YOUR OWN RISK.

post/visadirect/v1/adjustment

Sandbox server

https://sandbox.api.visa.com/visadirect/v1/adjustment
Request samples
{
  • "rewardProgramIdentificationCode": "A34324",
  • "amount": 124.02,
  • "localTransactionDateTime": "2023-05-05T12:00:00",
  • "cpsAuthorizationCharacteristicsIndicator": "Y",
  • "pointOfServiceData": {
    },
  • "digitalWalletProviderId": "VCIND",
  • "colombiaNationalServiceData": {
    },
  • "cardAcceptor": {
    },
  • "transactionIdentifier": 100148555877923,
  • "acquirerCountryCode": 840,
  • "acquiringBin": 408999,
  • "senderCurrencyCode": "USD",
  • "retrievalReferenceNumber": 433122895499,
  • "transactionTypeCode": 22,
  • "messageReasonCode": 2150,
  • "systemsTraceAuditNumber": 895499,
  • "businessApplicationId": "AA",
  • "senderPrimaryAccountNumber": "4104920120500001",
  • "settlementServiceIndicator": 9,
  • "cardProductCode": "15",
  • "merchantCategoryCode": 6012,
  • "senderCardExpiryDate": "2021-10",
  • "dynamicCurrencyConversionIndicator": "Y"
}
Response samples
{
  • "senderIdentificationNumberIndividual": "string",
  • "settlementFlags": {
    },
  • "cpsAuthorizationCharacteristicsIndicator": "string",
  • "dateAndTimeTransmission": "string",
  • "customerReference": "string",
  • "originalActionCode": "string",
  • "transactionIdentifier": 0,
  • "actionCode": "string",
  • "serviceProcessingType": {
    },
  • "merchantReference": "string",
  • "recipientIdentificationNumberBusiness": "string"
}