# Visa Direct
Search API Reference
- [Getting Started](https://developer.visa.com/capabilities/visa_direct/docs)
- [How to Use Visa Direct](https://developer.visa.com/capabilities/visa_direct/docs-how-to)
- [How to Use Visa Alias Directory Service](https://developer.visa.com/capabilities/alias-directory-service/docs-getting-started)
- [Authentication and Encryption](https://developer.visa.com/capabilities/visa_direct/docs-authentication)
- [Error Codes](https://developer.visa.com/capabilities/visa_direct/docs-error-codes)
- [Request & Response Codes](https://developer.visa.com/request_response_codes)
## 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: application/json application/json application/xml
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
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". |
| cardAcceptor
required | object |
| | |
| --- | --- |
| address
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. |
| paymentFacilitator | object |
| | |
| --- | --- |
| additionalAcceptor | object |
| | |
| --- | --- |
| foreignRetailerIndicator | string \[ 1 .. 3 \] characters
Identifies a foreign retailer under a marketplace and/or payment facilitator.
May also Identify a foreign Conversion Affiliate under a Ramp
This tag must contain either:
A – Conversion Affiliate is located in the same country as Ramp provider
B – Conversion Affiliate is located in a different country as Ramp provider
Enum:"A""B" | | | |
| localTransactionDateTime
required | string
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 |
| 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. |
| 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. |
| argentinaNationalServiceData | object
Settlement Service Data object for Argentina required if transaction indicates Argentina national settlement. |
| | |
| --- | --- |
| reimbursementFee
required | number
This field contains the Argentina member supplied reimbursement fee. |
| reimbursementFeeTax | number
**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. |
| 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. |
| feeProgramIndicator | string 4 characters
Fee program indicator |
| merchantCategoryCode | 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 |
| merchantPseudoAbaNumber | string 9 characters
Merchant pseudo ABA number |
| 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". |
| merchantVerificationValue | object
Merchant verification value |
| messageReasonCode | 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'. |
| mexicoNationalServiceData | object
Settlement Service Data object for Mexico required if transaction indicates Mexico national settlement. |
| | |
| --- | --- |
| reimbursementFee
required | number
This field contains the Client-Calculated Interchange Reimbursement Fee in the same currency as the transaction. It must not contain zeros. |
| reimbursementFeeTax
required | number
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. | |
| nationalReimbursementFee | number \[ 0 .. 999999999.999 \]
National reimbursement fee |
| networkId | number
Network identifier |
| optionalResponseParameters | string \[ 0 .. 400 \] characters
Optional response parameters |
| originalDataElements | object
Original data elements |
| pointOfServiceCapability | object
Point of service capability data |
| pointOfServiceData | 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 | |
| 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". |
| recipientName | string \[ 1 .. 30 \] characters
Recipient name |
| rewardProgramIdentificationCode | string 6 characters
Used to identify the reward program. |
| schemeIdentifier | string 2 characters
Scheme identifier |
| 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". |
| senderPaymentCredentialReference | object
Object to carry a payment instrument that is an alternative to PAN or network token e.g. PCI Token Reference ID
**Conditional**
Only one of 'senderPrimaryAccountNumber' and 'senderPaymentCredentialReference' is provided in a request |
| | |
| --- | --- |
| type
required | string
Enum:"PCI_TOKEN_REFID""PAYMENT_CREDENTIAL_ID" |
| value
required | string \[ 1 .. 75 \] characters
The value of the payment instrument. For 'PCI_TOKEN_REFID', length is 1-75 and must accompany with 'merchantId'. For 'PAYMENT_CREDENTIAL_ID' length is 1-36 characters. |
| merchantId | string \[ 1 .. 50 \] characters
**Conditional**
Unique Merchant Identification assigned by Token Service Provider. | |
| senderPostalCode | string \[ 0 .. 16 \] characters
Sender postal code |
| senderPrimaryAccountNumber | 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. |
| 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. |
| serviceProcessingType | 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
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. |
| tokenData | object
Token data for payment |
| transactionCurrencyCode | string 3 characters
**Conditional**
Use a 3-character alpha or numeric currency code for currency of the original transaction.
Refer to [ISO Codes](https://developer.visa.com/request_response_codes#iso_country_and_currency_codes) |
| transactionLinkIdentifier | string \[ 1 .. 36 \] characters
Transaction Link Identifier returned from other networks like MasterCard and Pulse |
| transactionTypeCode | 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.) |
| visaMerchantIdentifier | string
Visa Merchant Identifier assigned by Visa. |
Responses
200
Adjustment Funds Transfer Response
##### Response Schema: application/json application/json application/xml
| | |
| --- | --- |
| actionCode
required | string 2 characters
The results of the transaction request
Refer to [actionCode](https://developer.visa.com/request_response_codes#action_code) |
| dateAndTimeTransmission
required | string
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](https://developer.visa.com/request_response_codes#action_code)
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". |
| serviceProcessingType | object
This field will contain values that identifies the type of service assigned for the transaction. |
| | |
| --- | --- |
| requestType | string <= 2 characters
Reserved for future use. | |
| settlementFlags | 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._