Visa Direct API Reference
Visa Direct
Search API Reference
- Getting Started
- How to Use Visa Direct
- How to Use Visa Alias Directory Service
- Authentication and Encryption
- Error Codes
- 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 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 |
| 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 |
| 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 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.