openapi: 3.0.1
info:
title: Foreign Exchange Rates Account Management service API
description: The Account Management web services are used to manage payment controls for existing card accounts and to request virtual accounts while setting controls. The endpoints allow the user to retrieve the status of new account requests, view authorization rules, submit virtual card requisitions for an employee , and retrieve security code (CVV2) details of an existing account.
version: '1'
servers:
- url: https://sandbox.api.visa.com
description: Sandbox server
security: []
tags:
- name: Account Management service
description: The Account Management web services are used to manage payment controls for existing card accounts and to request virtual accounts while setting controls. The endpoints allow the user to retrieve the status of new account requests, view authorization rules, submit virtual card requisitions for an employee , and retrieve security code (CVV2) details of an existing account.
paths:
/vpa/v1/accountManagement/GetSecurityCode:
post:
tags:
- Account Management service
summary: Get Security Code
description: ''
operationId: Get Security Code
requestBody:
description: Get Security Code Request
content:
application/json:
schema:
required:
- accountNumber
- buyerId
- clientId
- expirationDate
- messageId
type: object
properties:
buyerId:
maxLength: 25
type: string
description: Buyer ID is the buyer identifier as defined in Visa Payables Automation(VPA) system. Value format is 0-9.
clientId:
maxLength: 25
type: string
description: Client ID field is a unique identification of the financial institution. This will be provided by Visa at the time of setup.
messageId:
maxLength: 36
type: string
description: Unique identifier for this request. Each request sent to VPA requires its own unique ID.
accountNumber:
maxLength: 19
type: string
description: The full 16 digit Visa account number.
expirationDate:
maxLength: 6
type: string
description: Expiration date of the account for which the CVV2 is requested. The format is MM/YYYY.
examples:
Default:
summary: Default
value:
clientId: B2BWS_1_1_9999
messageId: '2017-04-06T03:47:20.000Z'
buyerId: 9999
accountNumber: 4111111111111111
expirationDate: 10/2022
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
GetSecurityResponse:
required:
- messageID
- statusCode
- statusDesc
type: object
properties:
messageID:
maxLength: 36
type: string
description: Unique identifier which was sent in the request.
statusCode:
maxLength: 6
type: string
description: Status code of the response. It is alphanumeric. The values are specific to each method. Example- CS001, CS002, and so on. In case of error please refer to the <a href="https://developer.visa.com/pages/B2B-virtual-account-payment-method-error-codes#get_security_code">Error Codes</a> page for this api
statusDesc:
maxLength: 255
type: string
description: Status description of the response.
securityCode:
maxLength: 3
type: string
description: CVV2 number.
description: Success
'400':
description: Refer to the <a href="https://developer.visa.com/pages/B2B-virtual-account-payment-method-error-codes#get_security_code">Error Codes</a> page for the list of error codes for this API.
content:
application/json:
schema:
type: object
properties:
messageId:
maxLength: 36
type: string
description: Unique identifier which was sent in the request.
statusCode:
maxLength: 6
type: string
description: Status code of the response.
statusDesc:
maxLength: 255
type: string
description: Status description of the response.
x-codegen-request-body-name: getsecuritycode
x-operationVersions:
- label: v1
operationPointer: '#/paths/~1vpa~1v1~1accountManagement~1GetSecurityCode/post'
default: false
/vpa/v1/getRequisitionDetails:
post:
tags:
- Account Management service
summary: Get Requisition Details
description: Get Requisition Details request and response
operationId: Get Requisition Details
requestBody:
description: Get Requisition Details Request
content:
application/json:
schema:
required:
- accountNumber
- buyerId
- clientId
- messageId
type: object
properties:
buyerId:
maxLength: 15
type: string
description: Unique numeric identifier for the buyer that's defined by the Issuer.
clientId:
maxLength: 50
type: string
description: Unique identifier for the financial institution, provided by Visa during setup.
messageId:
maxLength: 36
type: string
description: Unique identifier for the API request, generated by the API consumer, for tracking and referencing purposes. Each request mandates a unique messageId.
accountNumber:
maxLength: 16
type: string
description: Account number for which requisition details are being requested.
required: true
responses:
'200':
description: In case of error please refer to the <a href="https://developer.visa.com/pages/B2B-virtual-account-payment-method-error-codes#request_virtual_account">Response Codes</a> page for this api
content:
application/json:
schema:
type: object
properties:
GetRequisitionDetailsResponse:
type: object
properties:
rules:
type: array
description: List of authorization rules set on the account.
items:
type: object
properties:
ruleCode:
maxLength: 8
type: string
description: Contains the authorization Rule Code. For the list of valid Visa Payment Controls (VPC) refer to the <VPC Rules and Overrides table>
overrides:
type: array
description: 'Complex element which contains one or more overrides for the authorization rules. This element contains: Sequence, Override Code, and Override Value. Override is nothing but a value which you want to change in the default rule.'
items:
type: object
properties:
sequence:
maxLength: 3
type: string
description: Contains the sequence number for the override. Each rule starts with 0 so if you have an SPV and BUS, then SPV will have sequence 0 and BUS will have a 0. If there are multiple fields/overrides within a rule, e.g. SPV. Each override - amount, currency code, range type, etc.- have the same sequence number. E.g. amount, currency code and range type will all have 0. If there is a rule that can have multiple amounts e.g. Exact match, then each VPAS rule overrides must have a unique sequence number so first VPAS has 0, then second has 1, third has 2.
overrideCode:
maxLength: 33
type: string
description: Contains the code for the override.
overrideValue:
maxLength: 25
type: string
description: Contains the value for the override.
buyerId:
maxLength: 15
type: string
description: Unique numeric identifier for the buyer that's defined by the Issuer.
endDate:
maxLength: 10
type: string
description: User specified account validity end date for the requisition
clientId:
maxLength: 50
type: string
description: Unique identifier for the financial institution, provided by Visa during setup.
timeZone:
maxLength: 12
type: string
description: User specified time zone for the requisition start and end dates.
messageId:
maxLength: 36
type: string
description: Unique identifier for the API request.
responses:
type: array
description: 'Complex element which contains a collection of responses returned in the response. This element contains: Response Code, Response Description'
items:
type: object
properties:
responseCode:
maxLength: 10
type: string
description: This element contains the response code sent by the VPA system. The list can be found in the Response Codes page for this api
responseDescription:
maxLength: 250
type: string
description: This element contains the response description.
startDate:
maxLength: 10
type: string
description: User specified account validity start date for the requisition
optionalInfo:
type: array
description: Complex element which allows the web service consumer to pass optional field name and value as name value pairs. A maximum of 50 optional field name and values will be returned.
items:
type: object
properties:
optionalFieldName:
maxLength: 50
type: string
description: Name of the Optional Field
optionalFieldValue:
maxLength: 100
type: string
description: Value of the Optional Field
accountNumber:
maxLength: 16
type: string
description: Account number for which requisition details were requested.
mcgRuleAction:
maxLength: 5
type: string
description: This field defines action on the MCG rules sent in the request. Default value returned is Block even if no value is sent in the request. MCG rules are not defined for the card that has only VPAS rule with value of one cent set.
expirationDate:
maxLength: 7
type: string
description: Contains the expiration date of the card account. Format- MM/YYYY.
description: Success
x-codegen-request-body-name: body
x-operationVersions:
- label: v1
operationPointer: '#/paths/~1vpa~1v1~1getRequisitionDetails/post'
default: false
x-hideTryIt: true
/vpa/v2/accountManagement/getPaymentControls:
post:
tags:
- Account Management service
summary: Get Payment Controls
description: This version is recommended for buyers subscribed to Visa payment Control(VPC) and supporting mcgRuleAction field.
operationId: Get Payment Controls
requestBody:
description: Get Payment Controls Request
content:
application/json:
schema:
required:
- accountNumber
- buyerId
- clientId
- messageId
type: object
properties:
buyerId:
maxLength: 15
type: string
description: Buyer ID numeric is the buyer identifier as defined in Visa Payables Automation system. This is often the ID defined at the processor for the corporate buyer. This will be provided by the issuer.
clientId:
maxLength: 50
type: string
description: ClientID uniquely identifies a financial institution. This will be provided by the Visa implementation team.
messageId:
maxLength: 36
type: string
description: Unique identifier for the API request.
accountNumber:
maxLength: 16
type: string
description: Account Number for which the auth rules are requested. You must send at least the last 4 digits, but can send up to the entire account number. The value sent should uniquely identify the account number. If the last 4 digits are not unique then it will fail
examples:
Default:
summary: Default
value:
clientID: B2BWS_84994_1940
messageId: '{{$timestamp}}'
buyerID: '84994'
accountNumber: '4715338901038473'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
GetPaymentControlsResponse:
type: object
properties:
rules:
type: array
description: List of authorization rules set on the account.
items:
type: object
properties:
ruleCode:
maxLength: 8
type: string
description: Contains the authorization Rule Code. For the list of valid Visa Payment Controls (VPC) refer to the <a href='/pages/B2B-virtual-account-payment-method-codes#rules_and_overrides_for_request_virtual_account_and_manage_payment_controls'>VPC Rules and Overrides table</a>. <br> For buyers using VANs please refer to the <a href='/pages/B2B-virtual-account-payment-method-codes#rules_and_overrides_for_request_virtual_account__for_tsys_vpp'>VPP Rules and Overrides table</a>. <br>.
overrides:
type: array
description: 'Complex element which contains one or more overrides for the authorization rules. This element contains: Sequence, Override Code, and Override Value. Override is nothing but a value which you want to change in the default rule.<br><br> For e.g. to set the threshold rule for the account you have requested,if you want to set the threshold as $1000 then you should pass the amount override as 1000 and the currency override as 840.'
items:
type: object
properties:
sequence:
maxLength: 3
type: string
description: Contains the sequence number for the override. Each rule starts with 0 so if you have an SPV and BUS, then SPV will have sequence 0 and BUS will have a 0. If there are multiple fields/overrides within a rule, e.g. SPV. Each override - amount, currency code, range type, etc.- have the same sequence number. E.g. amount, currency code and range type will all have 0. If there is a rule that can have multiple amounts e.g. Exact match, then each VPAS rule overrides must have a unique sequence number so first VPAS has 0, then second has 1, third has 2.
overrideCode:
maxLength: 33
type: string
description: Contains the code for the override. <br> Note, follow the rule specification (provided in the link in the Rule code field description) as not every ruleCode requires an overrideCode.
overrideValue:
maxLength: 25
type: string
description: Contains the value for the override. <br> Note, follow the rule specification (provided in the link in the Rule code field description) as not every ruleCode requires an overrideValue.
messageId:
maxLength: 36
type: string
description: Unique identifier which was sent in the request.
statusCode:
maxLength: 10
type: string
description: Status code of the response. It is alphanumeric. The values are specific to each method. The list of status codes can be found in the following link
statusDesc:
maxLength: 255
type: string
description: Status description of the response.
mcgRuleAction:
maxLength: 5
type: string
description: This field defines action on the MCG rules sent in the request. Default value returned is "Block" even if no value sent in request, MCG rules are not defined or card has VPAS(one cent rule) set. For VPP buyers this field won’t be returned.
description: Success
examples:
Default:
summary: Default
value:
statusDesc: Payment control details retrieved successfully.
messageId: '{{$timestamp}}'
rules:
- ruleCode: AIR
- ruleCode: AUTO
- ruleCode: REST
- ruleCode: SPV
overrides:
- sequence: '0'
overrideCode: spendLimitAmount
overrideValue: '1000.00'
- sequence: '0'
overrideCode: maxAuth
overrideValue: '10'
- sequence: '0'
overrideCode: recurringDay
overrideValue: '15'
- sequence: '0'
overrideCode: amountCurrencyCode
overrideValue: '840'
- sequence: '0'
overrideCode: rangeType
overrideValue: '1'
- sequence: '0'
overrideCode: consumedAmount
overrideValue: '263.39'
- sequence: '0'
overrideCode: consumedAuthCount
overrideValue: '1'
- sequence: '0'
overrideCode: balanceAuthAmount
overrideValue: '736.61'
- sequence: '0'
overrideCode: balanceAuthCount
overrideValue: '9'
statusCode: AMGP000
'400':
description: In case of error please refer to the <a href="https://developer.visa.com/pages/B2B-virtual-account-payment-method-error-codes#get_payment_controls">Error Codes</a> page for this api
content:
application/json:
schema:
type: object
properties:
errors:
type: array
description: array of errors
items:
type: object
properties:
code:
type: string
description: error code
statusDesc:
type: string
description: error description
messageId:
maxLength: 36
type: string
description: Unique identifier which was sent in the request.
statusCode:
maxLength: 6
type: string
description: Status code of the response.
statusDesc:
maxLength: 255
type: string
description: Status description of the response.
x-codegen-request-body-name: GetPaymentControls
x-operationVersions:
- label: v1
operationPointer: '#/paths/~1vpa~1v1~1accountManagement~1getPaymentControls/post'
default: false
- label: v2 - Latest
operationPointer: '#/paths/~1vpa~1v2~1accountManagement~1getPaymentControls/post'
default: false
x-hideTryIt: true
/vpa/v1/accountManagement/ManagePaymentControls:
post:
tags:
- Account Management service
summary: Manage Payment Controls
description: ''
operationId: Manage Payment Controls
requestBody:
content:
application/json:
schema:
required:
- accountNumber
- buyerId
- clientId
- messageId
type: object
properties:
source:
type: string
description: This element indicates whether the request was made for VPA related cards or for VVAM related cards. Valid codes are VPA, VVAM.<br> Note, if sending source as VPA you must also include a sample invoice.
buyerId:
maxLength: 25
type: string
description: Buyer ID is the buyer identifier as defined in Visa Payables Automation(VPA) system. Value format is 0-9.
eMailId:
maxLength: 128
type: string
description: Email address of the employee. Note- This email address is only required for VAM clients.
clientId:
maxLength: 50
type: string
description: Client ID field is a unique identification of the financial institution. This will be provided by Visa at the time of setup.
invoices:
type: array
description: This complex element contains the details of all invoices for which the exact match rule needs to be set.
items:
type: object
properties:
invoiceDate:
maxLength: 10
type: string
description: This contains the date of the invoice being paid. Format is YYYY-MM-DD.
invoiceAmount:
maxLength: 16
type: string
description: Invoice amount. maximum length is 16. Maximum number of decimals is two. Format is XXXXXXXXXX9999.99
invoiceNumber:
maxLength: 30
type: string
description: Invoice Number.
messageId:
maxLength: 36
type: string
description: Unique identifier for this request. Each request sent to VPA requires its own unique ID.
accountNumber:
maxLength: 16
type: string
description: Card account number for which the authorization controls are being managed.
companyAdminEMailId:
maxLength: 128
type: string
description: Contains the company admin email ID. Note- This email address is only required for VAM clients.
paymentControlDetails:
type: array
description: This complex element contains multiple authorization control(s) details.
items:
type: object
properties:
endDate:
maxLength: 10
type: string
description: Contains the last date when the card account and the authorization rules will be effective. All the authorization rules specified in the Requisition detail will be removed from the card the next day (after the end date). <br> Format is YYYY-MM-DD.
rulesSet:
type: array
description: This complex element contains the details of all invoices for which the exact match rule needs to be set.
items:
type: object
properties:
rules:
type: array
description: 'This complex element contains the details of all the authorization rules that needs to be added/update/deleted or refreshed. '
items:
type: object
properties:
ruleCode:
maxLength: 8
type: string
description: This contains the rule code. <br> For detailed information regarding the rule codes and overrides, see the <a href='/pages/B2B-virtual-account-payment-method-codes#rules_and_overrides_for_request_virtual_account_and_manage_payment_controls'>Rules and Overrides table</a>.
overrides:
type: array
description: This complex element contains the details of the overrides for an authorization rule.
items:
type: object
properties:
Sequence:
maxLength: 3
type: string
description: Contains the sequence number for the override. A few authorization rules have multiple overrides and the sequence number identifies each of them uniquely.
overrideCode:
maxLength: 50
type: string
description: Contains the override code. For a list of override codes, refer to the Rules and Overrides table.
overrideValue:
maxLength: 10
type: string
description: Contains the override value.
action:
maxLength: 1
type: string
description: Rule Action valid values are<br> ATo Add a Payment Controls<br> RTo Refresh all Payment Controls (replace existing rules with new rules) <br> XTo Remove All Payment Controls immediately
timeZone:
maxLength: 12
type: string
description: Contains the Time zone to use for the start and end dates. The UTC OFFSET needs to be sent. Like UTC-8 for PST, UTC-6 for CST, UTC+5:30 for IST.
startDate:
maxLength: 10
type: string
description: Contains the date when the card account and the authorization rules on the account will be made effective. Format is YYYY-MM-DD.
mcgRuleAction:
maxLength: 5
type: string
description: 'This field defines action on the MCG rules in the request. Allowed actions are "Allow"" and "Block". If no value provided will be considered as Block. This field is case insensitive. The value "Allow" with MCG rule code "AIR" allows authorization transaction for the card from Airline MCC''s. The value "Block" with MCG rule code "AIR" blocks authorization transaction for the card from Airline MCC''s. The value doesn''t apply to following MCG''s: MCCB,MCCX,CAID,CAIDB,NOTFUEL and ignored.'
examples:
Default:
summary: Default
value:
clientId: B2BWS_1_1_9999
invoices:
- invoiceNumber: INV0001
invoiceAmount: 500
invoiceDate: '2017-02-01'
eMailId: aaa@bbb.com
paymentControlDetails:
- rulesSet:
- action: A
rules:
- ruleCode: VPAS
overrides:
- sequence: 0
overrideCode: amount
overrideValue: 840
- sequence: 0
overrideCode: amount
overrideValue: 55
endDate: '2020-03-01'
timeZone: UTC-6
startDate: '2017-03-01'
messageId: '2017-04-06T03:47:20.000Z'
source: VVAM
buyerId: 9999
accountNumber: 4111111111111111
companyAdminEMailId: compAdmin@bbb.com
required: true
responses:
'200':
description: In case of error please refer to the <a href="https://developer.visa.com/pages/B2B-virtual-account-payment-method-error-codes#manage_payment_controls">Error Codes</a> page for this api
content:
application/json:
schema:
type: object
properties:
# --- truncated at 32 KB (121 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visa/refs/heads/main/openapi/visa-account-management-service-api-openapi.yml