[Documentation Mistake] Surcharge | Pull Funds Request

[Ajwah]

Below is the surcharge field as documented here:

https://developer.visa.com/capabilities/visa_direct/reference?next=visa_direct__funds_transfer__v1__...

surcharge

Optional

Decimal | Length: totalDigits12, fractionDigits 3 (minimum value is 0)

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.

It states that it can have 3 fraction digits, but in actual fact the sandbox api only allows 2 fraction digits.

an otherwise valid request, when it has the field like this: "surcharge": "3.451"

returns an error response:

{
"errorMessage": "API Validation Error: 3001. Mandatory field 'Surcharge' is missing or has invalid content."
}

Either I am misunderstanding something, so kindly clarify accordingly.

Either there is a mistake with the VISA Direct documentation, kindly update.

Either there is a mistake with the VISA Sandbox, kindly fix.

[API_Products]

Hi,

Thanks for posting your question to the community forum. You are right - it is 2 fraction digits.

The maximum value for surcharge and the foreignExchangeFeeTransaction depend on the amount of the transaction, so the values that are allowed are variable.

For example:

(1) For "amount": "10000.00",  "foreignExchangeFeeTransaction": "11.99", the maximum surcharge value that it allows is   "surcharge": "9988.99",

(2) For an  "amount": "10000.00",  "foreignExchangeFeeTransaction": "10.99", the maximum surcharge value that it allows is   "surcharge": "9987.99",

The relationship among the amount and fees is not documented in VDP, so you may not know of this relationship unless you are familiar with these types of transactions.

For the amount, foreignExchangeFeeTransaction and surcharge, the maximum error states the following, however, this is only true of the amount if only 2 fraction digits are provided:

{"errorMessage": "Message has failed validation: surcharge: cvc-maxInclusive-valid: Value 'xxxxxxxxxxxx' is not facet-valid with respect to maxInclusive

'999999999.999' for type 'AmountValueSignedV2V2'."}

Hope that helps!

Thank you,

Diana

[Ajwah]

Hi Diana,

Thanks for the feedback.

I am aware of the relationship between the attributes amount, surcharge and foreignExchangeFeeTransaction.

It is stated in the documentation for amount:

The amount of the transaction, inclusive of all fees you assess for the transaction, including currency conversion fees. If the originator is populating the surcharge or foreignExchangeFeeTransaction field, they must be included in the amount field.

Regardless as to all of that, the issue I reported still stands, namely that the Sandbox API currently does not support 3 fraction digits. It only supports 2 fraction digits. 

Next, after further research into the matter, I came to understand that for Visa to be accepting a static amount of fraction digits would be deceiving, as that should be currency dependent. Currencies define their own minor digits. For example, the smallest currency denomination for USD is cents, 100 cents make up 1 dollar, so USD as a currency can have at most 2 minor digits.

Other currencies, such as Iranian Rial, IRR do not have any minor digits, so to send an amount of 1.5 in such cases would be nonsensical.

http://www.unicode.org/cldr/charts/dev/supplemental/detailed_territory_currency_information.html#IRR

As such, I believe that the documentation needs to be updated on part of the attributes: amount, surcharge and foreignExchangeFeeTransaction that the amount of fractional digits depend on the currency. Also, since it pertains to currencies, the correct terminology should be 'minor digits' as opposed to 'fractional digits'.