Get Payout Metadata API is an optional API that enables clients to automate manual processes related to route requirements. The API will return all the required, conditional, and recommended fields to send a payment.
This API is currently available for Visa Direct for Account.
Implementing the Get Payout Metadata API enables clients to automate updates to their customer-facing user interface which may:
The Get Payout Metadata API communicates using files written in JSON format. This requires the client to have the ability to open and read JSON files to extract the critical information such as rules, conditions and schemas. Clients store the data required to send a payment to a specific country in a local repository, which powers the client-facing user interface.
Key tasks when using the API:
The API specification is Open API 3.0, with the Get Payout Metadata API response formatted in JSON using conditions driven by rules. The API retrieves the fields required to send a transaction. Conditions are driven by factors such as the type of sender/recipient, type of account number, or BAI. An example of this is a condition for the customer type. This could be an individual or a company. Once an option is selected, certain conditions are triggered for what naming options are available. For individual senders, first name, last name and name are the naming options. For company, the name field is the only naming option.
1. The info section returns the version information.
Start a Project
API Overview
API Reference
"info": {
"title": "getMetadata Response Australia",
"version": "1.0.0",
"versionDate": "2024-05-13",
"description": "This is the response schema for the getMetadata API for Australia"
2. The transactionReferences section returns client-driven or Visa-driven fields that are not required in the User Interface but are required to be submitted in the sendPayout API request.
"transactionReferences": [
{
"path": "$.transactionDetail",
"name": "clientReferenceId",
"$ref": "#/schemas/ClientReferenceId",
"presence": "required"
},
{
"path": "$.transactionDetail",
"name": "initiatingPartyId",
"$ref": "#/schemas/InitiatingPartyId",
"presence": "required"
}
],
3. The routeDefiningFields section returns the Get Payout Metadata API query parameters, all of which are key route defining data on the Send Payout API request.
"routeDefiningFields": [
4. The clientDrivenConditionalFields are fields or field-sets that are required to be provided by the client in specific use-cases. These are not API fields. For example, the sendPayout and validatePayout APIs do not have a field that specifies if a payment is related to a pension payment. This must be provided by the client. If the payment is for a pension payment, the Purpose of Payment field is required. Refer to the example below:
"clientDrivenConditionalFields": [
{
"name": "purposeOfPayment",
"path": "$.transactionDetail",
"$ref": "#/countrySpecificSchemas/PurposeOfPayment",
"presence": "conditional",
"condition": "isPensionPayment"
}
]
5. The conditionDefiningFields section returns the key fields in the Send Payout request that influence the presence/absence of another field or set of fields. These fields are the "facts" used in the conditions[] section of the Metadata response.
"conditionDefiningFields": [
{
"$ref": "#/schemas/SenderType",
"name": "type",
"path": "$.senderDetail",
"presence": "required"
}
6. The conditions section returns an array of conditions that applies on a route. These conditions are based on one or more of the conditionDefiningFields.
"conditions": [
{
"id": "accountNumberTypeIsDEFAULT",
"all": [
{
"fact": "$.recipientDetail.bank.accountNumberType",
"operator": "equal",
"value": "DEFAULT"
}
]
The conditions section is written in a rule engine format. If the “conditions”: in an “all”:[], “any”:[], and “not”:{} section is true, the conditionId will trigger the associated outcomes in the rules{} section. The field in the "fact" parameter is a Send Payout API field.
{
"id": "senderIsIndividual",
"all": [
{
"fact": "$.senderDetail.type",
"operator": "equal",
"value": "I"
}
]
},
{
"id": "senderIsCompany",
"all": [
{
"fact": "$.senderDetail.type",
"operator": "equal",
"value": "C"
}
]
}
7. The rules return the outcomes when a set of conditions are turned on. A rule/outcome contains a list of additional fields that need to be included in the Payout API request.
"rules": {
"condition": "supportedUseCases",
"items": [
{
"name": "transactionDetailGlobal",
"path": "$.transactionDetail",
"fields": [
{
"name": "senderSourceOfFunds",
"condition": "BAIIsFDAAPP",
"presence": "required",
"$ref": "#/schemas/SourceOfFunds"
},
{
"name": "transactionAmount",
"presence": "required",
"$ref": "#/schemas/Amount"
},
{
"name": "settlementCurrencyCode",
"condition": "transactionCurrencyIsRecipientBankCurrency",
"presence": "required",
"$ref": "#/countrySpecificSchemas/AlphaCurrencyCode"
}
]
}
8. The schemas section has all JSON schema compliant definitions for the globally applicable fields referenced in the transactionReferences, routeDefiningFields, conditionDefiningFields and rules sections.
"schemas":
{
9. The countrySpecifcSchemas section contains all JSON schema compliant definitions for the fields that have more restrictive (route specific) datatype, length or format.
"countrySpecificSchemas":
{
1. Combination of Path+ “.”+Name corresponds to the full path in the Send Payout API. Presence indicates whether the field is Required, Optional or Recommended.
"rules": {
"condition": "supportedUseCases",
"items": [
{
"name": "transactionDetailGlobal",
"path": "$.transactionDetail",
"fields": [
{
"name": "senderSourceOfFunds",
"condition": "BAIIsFDAAPP",
"presence": "required",
"$ref": "#/schemas/SourceOfFunds"
}
2. Description can optionally serve as Help Text or Tooltips in the UI, guiding customers on the information required.
"schemas":
{
"AlphaCountryCode": {
"type": "string",
"description": "3-character ISO-3166 (Alpha-3) country code.",
"pattern": "^[A-Z]{3}$"
},
"AddressLine1": {
"type": "string",
"description": "This field contains entity's 1st line of address.",
"minLength": 1,
"maxLength": 50
}
Anything which is contained with schemas{} and countrySpecificSchema{} is an existing JSON Schema construct and supported by JSON Schema libraries.
3. While the “name” parameter in the field[], oneOfFields[] or anyOfFields[] sections normally point to simple elements/fields, in specific cases, they point to objects (additionalData) or arrays (identificationList and structuredRemittance).
"fields": [
{
"name": "statementNarrative",
"path": "$.transactionDetail",
"$ref": "#/countrySpecificSchemas/StatementNarrative",
"presence": "recommended"
}
]
"fields": [
{
"name": "additionalData[0]",
"path": "$.recipientDetail",
"$ref": "#/countrySpecificSchemas/AdditionalDataEntry1",
"presence": "recommended"
}
]
"fields": [
{
"name": "structuredRemittance",
"path": "$.transactionDetail",
"$ref": "#/schemas/StructuredRemittance",
"presence": "recommended"
}
]
Clients should note the following before implementing the Get Payout Metadata API:
The Visa Direct for Account Endpoint guide should be read in conjunction when using the Get Payout Metadata API. The guide is updated monthly, potentially including updates which will affect the version of the client’s local repository. The guide has detailed information on the following items which are not returned in the API response: