# Installment Transaction Service Installment Transaction Service ## Version: 1 ### Servers | URL | Description | | --- | ----------- | | https://cert.api.visa.com | Sandbox server | --- ## Installment Transaction Service API - Deprecated Financial Institution (FI) requests Visa Installments Service (VIS) for the list of confirmed or cancelled installment transactions for a given time-period, so they can process installment conversion together with the clearing file received from payment network. Financial Institution performs cancel and refund accordingly. ### [POST] /installments/planAcceptances/cancel **Cancel plan acceptances** Plan Cancellation API #### Parameters | Name | Located in | Description | Required | Schema | Style | Explode | | ---- | ---------- | ----------- | -------- | ------ | ----- | ------- | | X-SERVICE-CONTEXT | header | X-SERVICE-CONTEXT | Yes | string | simple | No | #### Request Body Plan acceptance cancellation information | Required | Schema | | -------- | ------ | | Yes | **application/json**: { **"consumerInfo"**: { **"hashedURN"**: string, **"encEmailAddress"**: string, **"encMobileNumber"**: string, **"encAccountNumber"**: string }, **"refundAmount"**: { **"amount"**: string, **"currencyCode"**: string }, **"transactionID"**: string, **"refundTransactionID"**: string, **"vInstallmentPlanAcceptanceID"**: string, **"vinstallmentPlanAcceptanceID"**: string }
| #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | | 201 | Created | **application/json**: { **"201"**: object, **"UpdatePlanAcceptanceResponse"**: { **"transactionId"**: string, **"cancellationStatus"**: string, **"cancellationDateTime"**: string, **"vinstallmentPlanAcceptanceId"**: string } }
| | 401 | Unauthorized | | | 403 | Forbidden | | | 404 | Not Found | | ### [POST] /installments/candidates/batch **Check Consumer Eligibility Batch** #### Parameters | Name | Located in | Description | Required | Schema | Style | Explode | | ---- | ---------- | ----------- | -------- | ------ | ----- | ------- | | X-SERVICE-CONTEXT | header | X-SERVICE-CONTEXT | Yes | string | simple | No | #### Request Body list of mobile phone numbers | Required | Schema | | -------- | ------ | | Yes | **application/json**: { **"consumerInfo"**: [ { **"hashedURN"**: string, **"encEmailAddress"**: string, **"encMobileNumber"**: string, **"encAccountNumber"**: string } ] }
| #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | | 201 | Created | **application/json**: { **"201"**: object, **"ConsumerEligibilityBatchResponse"**: { **"failureCount"**: integer, **"successCount"**: integer, **"batchExpirationDate"**: string, **"vEligibilityBatchID"**: string } }
| | 401 | Unauthorized | | | 403 | Forbidden | | | 404 | Not Found | | ### [POST] /installments/plans/{planID}/planAcceptances **Confirm plan acceptance** Plan Selection API #### Parameters | Name | Located in | Description | Required | Schema | Style | Explode | | ---- | ---------- | ----------- | -------- | ------ | ----- | ------- | | planID | path | A PlanID of an available plan | Yes | string | simple | No | | X-SERVICE-CONTEXT | header | X-SERVICE-CONTEXT | Yes | string | simple | No | #### Request Body Plan acceptance confirmation information | Required | Schema | | -------- | ------ | | Yes | **application/json**: { **"consumerInfo"**: { **"hashedURN"**: string, **"encEmailAddress"**: string, **"encMobileNumber"**: string, **"encAccountNumber"**: string }, **"vTransactionID"**: string, **"transactionAmount"**: { **"amount"**: string, **"currencyCode"**: string }, **"transactionDateTime"**: string, **"externalTransactionID"**: string, **"transactionDescriptor"**: string, **"vInstallmentPlanTermsAndConditionsVersion"**: { **"url"**: string, **"versionNumber"**: string } }
| #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | | 201 | Created | **application/json**: { **"201"**: object, **"ConfirmPlanAcceptanceResponse"**: { **"vTransactionID"**: string, **"vInstallmentPlanID"**: string, **"planAcceptanceStatus"**: string, **"vInstallmentPlanAcceptanceID"**: string } }
| | 401 | Unauthorized | | | 403 | Forbidden | | | 404 | Not Found | | ### [GET] /installments/candidates/batch/{vCandidatesBatchID} **Check Consumer Eligibility Batch Results by Batch ID** #### Parameters | Name | Located in | Description | Required | Schema | Style | Explode | | ---- | ---------- | ----------- | -------- | ------ | ----- | ------- | | vCandidatesBatchID | path | Batch id of the request job to getPlan the eligibility check results for the batch job submitted earlier | Yes | string | simple | No | | X-SERVICE-CONTEXT | header | X-SERVICE-CONTEXT | Yes | string | simple | No | | page | query | Results page you want to retrieve (0..N) | No | integer | form | Yes | | size | query | Number of records per page | No | integer | form | Yes | #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | | 200 | ok | **application/json**: { **"ConsumerEligibilityBatchDetailResponse"**: { **"batchData"**: { **"last"**: boolean, **"size"**: integer, **"sort"**: { **"empty"**: boolean, **"sorted"**: boolean, **"unsorted"**: boolean }, **"empty"**: boolean, **"first"**: boolean, **"number"**: integer, **"content"**: [ { **"errors"**: [ { **"error"**: string } ], **"consumerInfo"**: { **"hashedURN"**: string, **"encEmailAddress"**: string, **"encMobileNumber"**: string, **"encAccountNumber"**: string }, **"issuerBrandName"**: string, **"eligibilityStatus"**: boolean } ], **"pageable"**: { **"sort"**: { **"empty"**: boolean, **"sorted"**: boolean, **"unsorted"**: boolean }, **"paged"**: boolean, **"offset"**: long, **"unpaged"**: boolean, **"pageSize"**: integer, **"pageNumber"**: integer }, **"totalPages"**: integer, **"totalElements"**: long, **"numberOfElements"**: integer }, **"batchError"**: string, **"batchStatus"**: string,
**Available values:** "SUBMITTED", "COMPLETED", "FAILED", **"batchExpirationDate"**: string, **"veligibilityBatchID"**: string } }
| | 401 | Unauthorized | | | 403 | Forbidden | | | 404 | Not Found | | ### [POST] /installments/eligiblePlans **Fetch plan options** Eligibility Check API - Fetch Installment Plan Options #### Parameters | Name | Located in | Description | Required | Schema | Style | Explode | | ---- | ---------- | ----------- | -------- | ------ | ----- | ------- | | X-SERVICE-CONTEXT | header | X-SERVICE-CONTEXT | Yes | string | simple | No | #### Request Body Consumer Information | Required | Schema | | -------- | ------ | | Yes | **application/json**: { **"txnAmount"**: { **"amount"**: string, **"currencyCode"**: string }, **"consumerInfo"**: { **"hashedURN"**: string, **"encEmailAddress"**: string, **"encMobileNumber"**: string, **"encAccountNumber"**: string } }
| #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | | 201 | Created | **application/json**: { **"201"**: object, **"InstallmentOffersResponse"**: { **"fees"**: [ { **"rate"**: number, **"type"**: string,
**Available values:** "CONSUMER", "ISSUER_TO_ACQUIRER", "ACQUIRER_TO_ISSUER", **"amount"**: number } ], **"name"**: string, **"type"**: string, **"partnerID"**: string, **"promotionID"**: string, **"promotionCode"**: string, **"totalPlanCost"**: { **"amount"**: string, **"currencyCode"**: string }, **"txnAmountRanges"**: [ { **"maximumTxnAmount"**: string, **"minimumTxnAmount"**: string } ], **"installmentAmount"**: { **"amount"**: string, **"currencyCode"**: string }, **"termsAndConditions"**: [ { **"status"**: string, **"tncUrl"**: string, **"version"**: string, **"createdOn"**: string } ], **"vInstallmentPlanID"**: string, **"effectiveDateRanges"**: [ { **"endDate"**: string, **"startDate"**: string } ], **"totalFixedFeeAmount"**: { **"amount"**: string, **"currencyCode"**: string }, **"installmentFrequency"**: string, **"numberOfInstallments"**: integer, **"lastInstallmentAmount"**: { **"amount"**: string, **"currencyCode"**: string }, **"totalVariableFeeAmount"**: { **"amount"**: string, **"currencyCode"**: string } } }
| | 401 | Unauthorized | | | 403 | Forbidden | | | 404 | Not Found | | ### [POST] /installments/candidates **Check Consumer Eligibility for Installment Plans** Eligibility Check API - Initiate Check Consumer Eligibility #### Parameters | Name | Located in | Description | Required | Schema | Style | Explode | | ---- | ---------- | ----------- | -------- | ------ | ----- | ------- | | X-SERVICE-CONTEXT | header | X-SERVICE-CONTEXT | Yes | string | simple | No | #### Request Body list of mobile phone numbers | Required | Schema | | -------- | ------ | | Yes | **application/json**: { **"consumerInfo"**: [ { **"hashedURN"**: string, **"encEmailAddress"**: string, **"encMobileNumber"**: string, **"encAccountNumber"**: string } ] }
| #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | | 201 | Created | **application/json**: { **"201"**: object, **"ConsumerEligibilityResponse"**: { **"consumerInfo"**: { **"hashedURN"**: string, **"encEmailAddress"**: string, **"encMobileNumber"**: string, **"encAccountNumber"**: string }, **"issuerBrandName"**: string } }
| | 401 | Unauthorized | | | 403 | Forbidden | | | 404 | Not Found | | --- ## Installment Transaction Service API V2 APIs used by Sellers (Merchants/Acquirers/Gateways/Other Merchant Enablers) or issuers (in case of post-purchase model) to enable Visa Installment Solutions for both e-commerce and In-Store based on installment plans defined by issuers. ### [POST] /installments/v2/planAcceptances **Plan Selection API** This API enables the Merchant participant to confirm an Installment plan selection when the cardholder selects a plan among the eligible plan options and accepts terms and conditions for that plan. This API can also be used in post-purchase scenarios. The Merchant participant must get cardholders’ consent on the terms and conditions for the selected Installment plan before invoking this API.

Plan Selection can be made by providing either the orderInfo or transactionInfo. The orderInfo is recommended to be used only when transactionInfo details are not available and orderInfo.orderAmount is used to restrict the maximum transaction amount that can be applied on the created Plan Acceptance.

#### Parameters | Name | Located in | Description | Required | Schema | Explode | | ---- | ---------- | ----------- | -------- | ------ | ------- | | ex-correlation-id | header | Unique ID for every API request - an optional header. Generated by the API client. Used for end-to-end tracing/debugging. | No | string | No | | v-c-idempotency-key | header | Unique ID for every API request - an optional header. Generated by the API client. Used for idempotency. | No | string (uuid) | No | #### Request Body | Required | Schema | | -------- | ------ | | Yes | **application/json**: { **"encAccountNumber"**: byte, **"tokenAccountNumber"**: string, **"vProvisionedTokenID"**: string, **"paymentAccountReference"**: string } & { **"tokenReferenceID"**: string }
| #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | | 201 | Plan Acceptance was successfully created
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
**v-c-idempotency-key**: Unique ID for the API response. v-c-idempotency-key is echoed back. Used for idempotency.
| **application/json**: { **"vPlanID"**: string (uuid), **"vPlanIDRef"**: string, **"createdDateTime"**: dateTime, **"transactionInfo"**: { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } & { **"installmentTransactions"**: [ { **"status"**: string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } ] }, **"vPlanAcceptanceID"**: string (uuid), **"paymentAccountReference"**: string }
| | 400 | The 400 (Bad Request) HTTP Status code indicates that the server cannot or will not process the request due to an apparent client error. This can happen if you are trying to + Invoke an API request with missing or invalid parameters. + PlanAcceptances for Debit must include only orderInfo and must not include transactionInfo.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } }
| | 401 | API authorized error caused due to any of the following reasons: + x-pay-token is not present, blank, or not in a valid format. + Timestamp field not in valid UTC timestamp format. + Version field is invalid. + Token's timestamp is more than 8 minutes off from the current time. + Token hash mismatch. + APIKey not present in request. + APIKey is not active. + APIKey not valid. + APIKey not active. + Request has more than one authentication token, which is not supported
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 403 | The 403 (Forbidden) HTTP Status code indicates that the access failed due to insufficient permissions or the operation is not allowed. This can happen if you are trying to + Invoke an API request for a resource that is not part of your project. + Perform an operation that is not permitted in the given context Check for the following: + You are using a project and the credential for the project that includes the API being accessed. + You created a project and received sandbox credentials for the API’s being called. + You added the API being called to the project (if not already present) with the credentials that are being used. + The Consumer Information provided in the request is not eligible for the Installment plan.The value of errorResponse.reason is consumerInfoNotEligible + The Partner details given in the request is not authorized for on behalf of calls. The value of errorResponse.reason is forbiddenClientIDAccess + The Merchant is not allowed to perform Installment Plan Acceptance. The value of errorResponse.reason is planAcceptanceDisabled + The Merchant profile is not enabled for Debit Transactions.The value of errorResponse.reason is forbiddenException + Cross Border Transaction are not allowed on Debit PANs.The value of errorResponse.reason is forbiddenException + Post Purchase Transaction are not allowed on Debit PANs.The value of errorResponse.reason is forbiddenException + Plan Acceptances are not allowed on expired cards.The value of errorResponse.reason is consumerInfoNotEligible
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 404 | The referenced Installment Plan was not found, deleted, or expired. The value of errorResponse.reason is planNotFound
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 406 | Not Acceptable - Indicates that the "Accept:" header field is present in a request and none of the available representations for the response have a media type that is listed as acceptable. This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 410 | Gone - Indicates that the resource at this end point is no longer available. This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 429 | The Visa Developer Center project has clocked too many requests in a given amount of time. Please contact Visa Support Representative if you want to increase the time limits.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 500 | Internal Server Error. Please contact Visa Support Representative with a complete error message, full http request and response details.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 503 | The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server. There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request. The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received. Retry-After = HTTP-date \|\| delay-seconds examples: + Retry-After: Thu, 31 Dec 2020 23:59:59 GMT + Retry-After: 120 Please contact Visa Support Representative if the issue persists.
**Headers:**
**Retry-After**: Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed. The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received. Retry-After = HTTP-date || delay-seconds examples: + Retry-After: Thu, 31 Dec 2020 23:59:59 GMT + Retry-After: 120
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| #### Callback: planAcceptanceStatusChange ##### [POST] `{postbackNotificationUrl}` **Installment PlanAcceptance Status Change Notifications** These are API calls initiated by the Visa backend, made to the Visa Partner’s backend servers. The postbackNotificationUrl is configured by the Visa partners during onboarding. + This callback is available only for those clients that own the BIN for the PAN involved – Lenders/Processors/BIN users/BIN owners. + Invoked when one or more plan acceptances status change events are available for this lender. + These callbacks are sent only if the issuer has opted-in (as in the onboarding profile). + There will be 2 retries with random times from 1-30 minutes, if there are any 5XX or 404 errors returned from the client/partner. Note: This callback is invoked only when a status change occurs at the plan acceptance level. For example, if a transaction is added to the plan acceptance and the transaction is not confirmed, since there is no change to the overall status of the plan acceptance, there will be no PlanAcceptanceStatusChangeCallback invoked. However, InstallmentTransactionStatusChangeCallback will be invoked for that action. If there are many installment transactions associated with a plan acceptance, and if all of them are confirmed, then a plan acceptance confirmation callback is invoked. #### Parameters | Name | Located in | Description | Required | Schema | Explode | | ---- | ---------- | ----------- | -------- | ------ | ------- | | x-message-tracking-id | header | Tracking ID for callback and notification sent by Visa | Yes | string | No | | postbackNotificationUrl | path | | Yes | string | No | | apiKey | query | | Yes | string | Yes | | x-pay-token | header | See [XPayToken definition in Security Schemes](#/components/securitySchemes/x-pay-token) for details | Yes | string | No | #### Request Body | Required | Schema | | -------- | ------ | | No | **application/json**: { **"status"**: string,
**Available values:** "CREATED", "CANCELLED", "UPDATED", "CONFIRMED", **"cardType"**: string,
**Available values:** "CREDIT", "DEBIT", "PREPAID",
**Default:** CREDIT, **"cardBrand"**: string,
**Available values:** "VISA", "NON_VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "JCB", "UNIONPAY", "DINERSCLUB",
**Default:** VISA, **"orderInfo"**: { **"currency"**: string, **"orderAmount"**: long }, **"crossBorder"**: boolean, **"installmentPlan"**: { **"name"**: string, **"type"**: string,
**Available values:** "MARKET", "BI_LATERAL", "ISSUER_DEFAULT", "ISSUER_PROMOTION", "ISSUER_HYBRID", **"vPlanID"**: string (uuid), **"fundedBy"**: [ string,
**Available values:** "CONSUMER", "MERCHANT" ], **"vPlanIDRef"**: string, **"islamicPlan"**: boolean, **"promotionInfo"**: { **"promotionID"**: string, **"promotionCode"**: string }, **"termsAndConditions"**: [ { **"url"**: string, **"text"**: string, **"version"**: integer, **"languageCode"**: string } ], **"installmentFrequency"**: string,
**Available values:** "WEEKLY", "BIWEEKLY", "MONTHLY", "BIMONTHLY", **"numberOfInstallments"**: number (integer) } & { **"costInfo"**: { **"feeInfo"**: [ { **"type"**: string,
**Available values:** "ACQUIRER_TO_ISSUER", "ACQUIRER_TO_VISA", "ISSUER_TO_ACQUIRER", "ISSUER_TO_VISA", "ISSUER_TO_VISA_SCHEDULING_FEES", **"flatFee"**: long, **"ratePercentage"**: integer } ], **"currency"**: string, **"totalFees"**: long, **"totalPlanCost"**: long, **"lastInstallment"**: { **"amount"**: long, **"totalAmount"**: long, **"installmentFee"**: long }, **"firstInstallment"**: { **"upfrontFee"**: long, **"totalAmountExcludingUpfrontFee"**: long } & { **"amount"**: long, **"totalAmount"**: long, **"installmentFee"**: long }, **"totalUpfrontFees"**: long, **"totalRecurringFees"**: long, **"annualPercentageRate"**: integer } }, **"messageMetadata"**: { **"type"**: string,
**Available values:** "BATCH_COMPLETED", "ELIGIBILITY", "PLANACCEPTANCE_STATUS_UPDATE", "INSTALLMENT_TRANSACTION_STATUS_UPDATE", "BILATERAL_PLAN_PARTNER_STATUS_UPDATE", **"vMessageID"**: string (uuid), **"createdDateTime"**: string (date-time-nooffset) }, **"encAccountNumber"**: byte, **"externalClientID"**: string, **"statusTransitions"**: { **"createdDateTime"**: string (date-time-ms-nooffset), **"updatedDateTime"**: string (date-time-ms-nooffset), **"confirmedDateTime"**: string (date-time-ms-nooffset), **"cancellationDateTime"**: string (date-time-ms-nooffset) }, **"vPlanAcceptanceID"**: string (uuid), **"encSecondaryAccountNumber"**: byte, **"originalEncSecondaryAccountNumber"**: byte }
| #### Responses | Code | Description | | ---- | ----------- | | 401 | API authorized error caused due to any of the following reasons: + x-pay-token is not present or blank or not in valid format. + Timestamp field not in valid UTC timestamp format. + APIKey not present in request. + APIKey is not active. + APIKey not valid. + APIKey not active. | | 403 | Forbidden | | 500 | Internal server error | | 503 | Service unavailable | | 2XX | Callback successfully processed and no retries will be performed | ##### Security | Security Schema | Scopes | | --------------- | ------ | | apiKey | | x-pay-token | | #### Callback: installmentTransactionStatusChange ##### [POST] `{postbackNotificationUrl}` **Installment Transaction Status Change Notifications** These are API calls initiated by the Visa backend, made to the Visa Partner’s backend servers. The postbackNotificationUrl is configured by the Visa partners during onboarding. The + This callback is available only for those clients that own the BIN for the PAN involved – Lenders/Processors/BIN users/BIN owners. + Invoked when InstallmentTransaction status is updated. Installment Transaction corresponds to a clearing and a installment payment schedule. + These callbacks are sent only if the issuer has opted-in (as in the onboarding profile). + There will be 2 retries with random times from 1-30 minutes, if there are any 5XX or 404 errors returned from the client/partner. #### Parameters | Name | Located in | Description | Required | Schema | Explode | | ---- | ---------- | ----------- | -------- | ------ | ------- | | x-message-tracking-id | header | Tracking ID for callback and notification sent by Visa | Yes | string | No | | postbackNotificationUrl | path | | Yes | string | No | | apiKey | query | | Yes | string | Yes | | x-pay-token | header | See [XPayToken definition in Security Schemes](#/components/securitySchemes/x-pay-token) for details | Yes | string | No | #### Request Body | Required | Schema | | -------- | ------ | | No | **application/json**: { **"vPlanID"**: string (uuid), **"authCode"**: string, **"cardType"**: string,
**Available values:** "CREDIT", "DEBIT", "PREPAID",
**Default:** CREDIT, **"currency"**: string, **"cardBrand"**: string,
**Available values:** "VISA", "NON_VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "JCB", "UNIONPAY", "DINERSCLUB",
**Default:** VISA, **"vPlanIDRef"**: string, **"crossBorder"**: boolean, **"promotionInfo"**: { **"promotionID"**: string, **"promotionCode"**: string }, **"sourceCurrency"**: string, **"vTransactionID"**: string, **"messageMetadata"**: { **"type"**: string,
**Available values:** "BATCH_COMPLETED", "ELIGIBILITY", "PLANACCEPTANCE_STATUS_UPDATE", "INSTALLMENT_TRANSACTION_STATUS_UPDATE", "BILATERAL_PLAN_PARTNER_STATUS_UPDATE", **"vMessageID"**: string (uuid), **"createdDateTime"**: string (date-time-nooffset) }, **"encAccountNumber"**: byte, **"externalClientID"**: string, **"transactionAmount"**: long, **"vPlanAcceptanceID"**: string (uuid), **"installmentTransaction"**: { **"status"**: string,
**Available values:** "PENDING_CONFIRMATION", "CONFIRMED", "PENDING_CANCELLATION", "CANCELLED", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } & { **"refundAmount"**: long, **"sourceCurrency"**: string, **"lastRefundDateTime"**: dateTime, **"refundAmountInSourceCurrency"**: long, **"clearingAmountInSourceCurrency"**: long }, **"transactionRefundAmount"**: long, **"encSecondaryAccountNumber"**: byte, **"originalEncSecondaryAccountNumber"**: byte, **"transactionAmountInSourceCurrency"**: long, **"transactionRefundAmountInSourceCurrency"**: long }
| #### Responses | Code | Description | | ---- | ----------- | | 401 | API authorized error caused due to any of the following reasons: + x-pay-token is not present or blank or not in valid format. + Timestamp field not in valid UTC timestamp format. + APIKey not present in request. + APIKey is not active. + APIKey not valid. + APIKey not active. | | 403 | Forbidden | | 500 | Internal server error | | 503 | Service unavailable | | 2XX | Callback successfully processed and no retries will be performed | ##### Security | Security Schema | Scopes | | --------------- | ------ | | apiKey | | x-pay-token | | ### [POST] /installments/v2/planAcceptances/transactions/search **Retrieve Plan Acceptance Transactions - Search** This API retrieves the list of Installment Transactions associated with a PlanAcceptance for a given set of criteria. A PlanAcceptance can be associated with one or more ISO transactions or a part of an ISO transaction (one clearing/settlement record among the many clearing/settlement records in a ISO transaction) The results are sorted by plan acceptance createdDateTime in reverse chronological order. #### Parameters | Name | Located in | Description | Required | Schema | Explode | | ---- | ---------- | ----------- | -------- | ------ | ------- | | ex-correlation-id | header | Unique ID for every API request - an optional header. Generated by the API client. Used for end-to-end tracing/debugging. | No | string | No | | size | query | | No | integer,
**Default:** 100 | Yes | | page | query | | No | integer | Yes | #### Request Body | Required | Schema | | -------- | ------ | | Yes | **application/json**: { **"encAccountNumber"**: byte, **"tokenAccountNumber"**: string, **"vProvisionedTokenID"**: string, **"paymentAccountReference"**: string } & { **"tokenReferenceID"**: string } & { **"category"**: string, **"merchantReferenceID"**: string, **"partnerMerchantReferenceID"**: string } & { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"minTransactionAmount"**: long, **"externalTransactionRef"**: string }
| #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | | 200 | PlanAcceptance Transactions Results Page
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"last"**: boolean, **"empty"**: boolean, **"first"**: boolean, **"number"**: integer, **"totalCount"**: integer, **"totalPages"**: integer, **"resultsCount"**: integer } & { **"content"**: [ { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dormant"**: string,
**Available values:** "true", "false",
**Default:** false, **"cardBrand"**: string,
**Available values:** "VISA", "NON_VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "JCB", "UNIONPAY", "DINERSCLUB",
**Default:** VISA, **"vPlanIDRef"**: string, **"crossBorder"**: boolean, **"transactionAmount"**: long, **"vPlanAcceptanceID"**: string (uuid), **"installmentTransactions"**: [ { **"status"**: string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } & { **"refundAmount"**: long, **"lastRefundDateTime"**: dateTime } ], **"transactionRefundAmount"**: long } ] }
| | 400 | The errorResponse.details part of the error response can provide a list of fields that failed data validation constraints and errorResponse.reason values for this error include:

invalidRequestThe API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.

invalidRequestThe API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.

invalidRequestThe API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.

invalidRequestThe API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.

invalidRequestThe API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.

invalidRequestThe API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.

**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 401 | API authorized error caused due to any of the following reasons: + x-pay-token is not present, blank, or not in a valid format. + Timestamp field not in valid UTC timestamp format. + Version field is invalid. + Token's timestamp is more than 8 minutes off from the current time. + Token hash mismatch. + APIKey not present in request. + APIKey is not active. + APIKey not valid. + APIKey not active. + Request has more than one authentication token, which is not supported
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 403 | The 403 (Forbidden) HTTP Status code indicates that the access failed due to insufficient permissions or the operation is not allowed. This can happen if you are trying to + Invoke an API request for a resource that is not part of your project. + Perform an operation that is not permitted in the given context Check for the following: + You are using a project and the credential for the project that includes the API being accessed. + You created a project and received sandbox credentials for the API’s being called. + You added the API being called to the project (if not already present) with the credentials that are being used.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 406 | Not Acceptable - Indicates that the "Accept:" header field is present in a request and none of the available representations for the response have a media type that is listed as acceptable. This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 410 | Gone - Indicates that the resource at this end point is no longer available. This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 413 | Payload Too Large
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 429 | The Visa Developer Center project has clocked too many requests in a given amount of time. Please contact Visa Support Representative if you want to increase the time limits.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 500 | Internal Server Error. Please contact Visa Support Representative with a complete error message, full http request and response details.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 503 | The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server. There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request. The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received. Retry-After = HTTP-date \|\| delay-seconds examples: + Retry-After: Thu, 31 Dec 2020 23:59:59 GMT + Retry-After: 120 Please contact Visa Support Representative if the issue persists.
**Headers:**
**Retry-After**: Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed. The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received. Retry-After = HTTP-date || delay-seconds examples: + Retry-After: Thu, 31 Dec 2020 23:59:59 GMT + Retry-After: 120
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| #### Callback: batchCompleted ##### [POST] `{postbackNotificationUrl}` **Postback Notifications** These are API calls initiated by the Visa backend to the Visa Partner’s backend servers. + The postbackNotificationUrl is configured by the Visa partners during onboarding. + Invoked whenever the enrollments batch request results are ready for Visa partner to pull the results from Visa using another API call. + There will be 2 retries with random times from 1-30 minutes if there are any 5XX or 404 errors returned from the client/partner. #### Parameters | Name | Located in | Description | Required | Schema | Explode | | ---- | ---------- | ----------- | -------- | ------ | ------- | | x-message-tracking-id | header | Tracking ID for callback and notification sent by Visa | Yes | string | No | | postbackNotificationUrl | path | | Yes | string | No | | apiKey | query | | Yes | string | Yes | | x-pay-token | header | See [XPayToken definition in Security Schemes](#/components/securitySchemes/x-pay-token) for details | Yes | string | No | #### Request Body | Required | Schema | | -------- | ------ | | No | **application/json**: { **"vBatchID"**: string (uuid), **"batchType"**: string,
**Available values:** "CARDHOLDER_ENROLLMENT", "CARDHOLDER_ENROLLMENT_UPDATE", "CARDHOLDER_ENROLLMENT_DELETE", "PLAN_ACCEPTANCE_IRREGULAR_PAYMENTS", "CANDIDATES", **"batchStatus"**: string,
**Available values:** "SUBMITTED", "COMPLETED", **"messageMetadata"**: { **"type"**: string,
**Available values:** "BATCH_COMPLETED", "ELIGIBILITY", "PLANACCEPTANCE_STATUS_UPDATE", "INSTALLMENT_TRANSACTION_STATUS_UPDATE", "BILATERAL_PLAN_PARTNER_STATUS_UPDATE", **"vMessageID"**: string (uuid), **"createdDateTime"**: string (date-time-nooffset) }, **"batchExecutionDateTime"**: dateTime, **"batchExpirationDateTime"**: dateTime }
| #### Responses | Code | Description | | ---- | ----------- | | 401 | Authorized error due to any of the following reasons: + x-pay-token is not present, is blank, or is not in a valid format. + Timestamp field not in UTC timestamp format. + apiKey not present in request. + apiKey is not active. + apiKey not valid. + apiKey not active. | | 403 | Forbidden | | 500 | Internal Server Error | | 503 | Service Unavailable | | 2XX | Callback successfully processed; no retries will be performed. | ##### Security | Security Schema | Scopes | | --------------- | ------ | | apiKey | | x-pay-token | | ### [POST] /installments/v2/planAcceptances/{vPlanAcceptanceID}/transactions **Transaction Association API** This API is invoked after a plan acceptance is created. + In case of Post Purchase scenario,this API is used to associate a new clearing with a plan acceptance. + In case of During Purchase scenario,this API is used to associate a new Transaction after authorization with a plan acceptance. The sum of all associated transactions cannot exceed the order amount including buffer. It is important that the transaction amount (passed-in) needs to match the amount on the transaction corresponding to the transactionID passed-in. + In case of ReAuthorized transaction,this API is used to swap existing transaction with the new Transaction #### Parameters | Name | Located in | Description | Required | Schema | Explode | | ---- | ---------- | ----------- | -------- | ------ | ------- | | vPlanAcceptanceID | path | | Yes | string (uuid) | No | | ex-correlation-id | header | Unique ID for every API request - an optional header. Generated by the API client. Used for end-to-end tracing/debugging. | No | string | No | | v-c-idempotency-key | header | Unique ID for every API request - an optional header. Generated by the API client. Used for idempotency. | No | string (uuid) | No | #### Request Body | Required | Schema | | -------- | ------ | | Yes | **application/json**: { **"transactionInfo"**: { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } & { **"installmentTransactions"**: [ { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } ] }, **"dormantTransactionInfo"**: { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } }
| #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | | 200 | Plan Acceptance was successfully associated with the given transaction
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
**v-c-idempotency-key**: Unique ID for the API response. v-c-idempotency-key is echoed back. Used for idempotency.
| **application/json**: { **"vPlanID"**: string (uuid), **"transactionInfo"**: { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } & { **"installmentTransactions"**: [ { **"status"**: string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } ] }, **"vPlanAcceptanceID"**: string (uuid), **"dormantTransactionInfo"**: { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long }, **"paymentAccountReference"**: string }
| | 400 | The 400 (Bad Request) HTTP Status code indicates that the server cannot or will not process the request due to an apparent client error. This can happen if you are trying to + Invoke an API request with missing or invalid parameters. + Multi Auth is not allowed for Debit based Plan Acceptance. + Transaction Association for Debit Transactions must not include dormantTransactionInfo. + For Debit Transactions, the Transaction Amount must match the order amount of the Plan Acceptance. + For Debit Transactions, the Transaction Currency must match the order currency of the Plan Acceptance.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } }
| | 401 | API authorized error caused due to any of the following reasons: + x-pay-token is not present, blank, or not in a valid format. + Timestamp field not in valid UTC timestamp format. + Version field is invalid. + Token's timestamp is more than 8 minutes off from the current time. + Token hash mismatch. + APIKey not present in request. + APIKey is not active. + APIKey not valid. + APIKey not active. + Request has more than one authentication token, which is not supported
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 403 | The 403 (Forbidden) HTTP Status code indicates that the access failed due to insufficient permissions or the operation is not allowed. This can happen if you are trying to + Invoke an API request for a resource that is not part of your project. + Perform an operation that is not permitted in the given context Check for the following: + You are using a project and the credential for the project that includes the API being accessed. + You created a project and received sandbox credentials for the API’s being called. + You added the API being called to the project (if not already present) with the credentials that are being used. + The Transaction Amount specified in the request exceeds the Order Amount.The value of errorResponse.reason is orderAmountExceeded + The Plan Acceptance status is in a state that cannot accept new transactions. The value of errorResponse.reason is invalidPlanAcceptanceState + The Merchant profile is not enabled for Debit Transactions. The value of errorResponse.reason is forbidden + Cross Border Transaction are not allowed on Debit PANs.The value of errorResponse.reason is forbidden + Post Purchase Transaction are not allowed on Debit PANs.The value of errorResponse.reason is forbidden
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 404 | Installment Plan Acceptance not found
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 406 | Not Acceptable - Indicates that the "Accept:" header field is present in a request and none of the available representations for the response have a media type that is listed as acceptable. This can happen when the requested API version is not available or unsupported; for example, when the version requested in the Accept: header is newer than the currently live/supported version.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 410 | Gone - Indicates that the resource at this end point is no longer available. This is usually returned for old API versions that are not available anymore - EOL (End-of-Life). The content-type header in the response indicates the latest supported API version.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 429 | The Visa Developer Center project has clocked too many requests in a given amount of time. Please contact Visa Support Representative if you want to increase the time limits.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 500 | Internal Server Error. Please contact Visa Support Representative with a complete error message, full http request and response details.
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| | 503 | The Visa system is currently unable to handle the request due to a temporary overloading or maintenance of the server. There may be a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request. The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received. Retry-After = HTTP-date \|\| delay-seconds examples: + Retry-After: Thu, 31 Dec 2020 23:59:59 GMT + Retry-After: 120 Please contact Visa Support Representative if the issue persists.
**Headers:**
**Retry-After**: Header field to suggest an appropriate amount of time for the client to wait before retrying the request, typically after a 503 error or after a batch request when the batch job is not completed. The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received. Retry-After = HTTP-date || delay-seconds examples: + Retry-After: Thu, 31 Dec 2020 23:59:59 GMT + Retry-After: 120
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
| **application/json**: { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } } & { **"errorResponse"**: { **"reason"**: string, **"status"**: integer } }
| #### Callback: planAcceptanceStatusChange ##### [POST] `{postbackNotificationUrl}` **Installment PlanAcceptance Status Change Notifications** These are API calls initiated by the Visa backend, made to the Visa Partner’s backend servers. The postbackNotificationUrl is configured by the Visa partners during onboarding. + This callback is available only for those clients that own the BIN for the PAN involved – Lenders/Processors/BIN users/BIN owners. + Invoked when one or more plan acceptances status change events are available for this lender. + These callbacks are sent only if the issuer has opted-in (as in the onboarding profile). + There will be 2 retries with random times from 1-30 minutes, if there are any 5XX or 404 errors returned from the client/partner. Note: This callback is invoked only when a status change occurs at the plan acceptance level. For example, if a transaction is added to the plan acceptance and the transaction is not confirmed, since there is no change to the overall status of the plan acceptance, there will be no PlanAcceptanceStatusChangeCallback invoked. However, InstallmentTransactionStatusChangeCallback will be invoked for that action. If there are many installment transactions associated with a plan acceptance, and if all of them are confirmed, then a plan acceptance confirmation callback is invoked. #### Parameters | Name | Located in | Description | Required | Schema | Explode | | ---- | ---------- | ----------- | -------- | ------ | ------- | | x-message-tracking-id | header | Tracking ID for callback and notification sent by Visa | Yes | string | No | | postbackNotificationUrl | path | | Yes | string | No | | apiKey | query | | Yes | string | Yes | | x-pay-token | header | See [XPayToken definition in Security Schemes](#/components/securitySchemes/x-pay-token) for details | Yes | string | No | #### Request Body | Required | Schema | | -------- | ------ | | No | **application/json**: { **"status"**: string,
**Available values:** "CREATED", "CANCELLED", "UPDATED", "CONFIRMED", **"cardType"**: string,
**Available values:** "CREDIT", "DEBIT", "PREPAID",
**Default:** CREDIT, **"cardBrand"**: string,
**Available values:** "VISA", "NON_VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "JCB", "UNIONPAY", "DINERSCLUB",
**Default:** VISA, **"orderInfo"**: { **"currency"**: string, **"orderAmount"**: long }, **"crossBorder"**: boolean, **"installmentPlan"**: { **"name"**: string, **"type"**: string,
**Available values:** "MARKET", "BI_LATERAL", "ISSUER_DEFAULT", "ISSUER_PROMOTION", "ISSUER_HYBRID", **"vPlanID"**: string (uuid), **"fundedBy"**: [ string,
**Available values:** "CONSUMER", "MERCHANT" ], **"vPlanIDRef"**: string, **"islamicPlan"**: boolean, **"promotionInfo"**: { **"promotionID"**: string, **"promotionCode"**: string }, **"termsAndConditions"**: [ { **"url"**: string, **"text"**: string, **"version"**: integer, **"languageCode"**: string } ], **"installmentFrequency"**: string,
**Available values:** "WEEKLY", "BIWEEKLY", "MONTHLY", "BIMONTHLY", **"numberOfInstallments"**: number (integer) } & { **"costInfo"**: { **"feeInfo"**: [ { **"type"**: string,
**Available values:** "ACQUIRER_TO_ISSUER", "ACQUIRER_TO_VISA", "ISSUER_TO_ACQUIRER", "ISSUER_TO_VISA", "ISSUER_TO_VISA_SCHEDULING_FEES", **"flatFee"**: long, **"ratePercentage"**: integer } ], **"currency"**: string, **"totalFees"**: long, **"totalPlanCost"**: long, **"lastInstallment"**: { **"amount"**: long, **"totalAmount"**: long, **"installmentFee"**: long }, **"firstInstallment"**: { **"upfrontFee"**: long, **"totalAmountExcludingUpfrontFee"**: long } & { **"amount"**: long, **"totalAmount"**: long, **"installmentFee"**: long }, **"totalUpfrontFees"**: long, **"totalRecurringFees"**: long, **"annualPercentageRate"**: integer } }, **"messageMetadata"**: { **"type"**: string,
**Available values:** "BATCH_COMPLETED", "ELIGIBILITY", "PLANACCEPTANCE_STATUS_UPDATE", "INSTALLMENT_TRANSACTION_STATUS_UPDATE", "BILATERAL_PLAN_PARTNER_STATUS_UPDATE", **"vMessageID"**: string (uuid), **"createdDateTime"**: string (date-time-nooffset) }, **"encAccountNumber"**: byte, **"externalClientID"**: string, **"statusTransitions"**: { **"createdDateTime"**: string (date-time-ms-nooffset), **"updatedDateTime"**: string (date-time-ms-nooffset), **"confirmedDateTime"**: string (date-time-ms-nooffset), **"cancellationDateTime"**: string (date-time-ms-nooffset) }, **"vPlanAcceptanceID"**: string (uuid), **"encSecondaryAccountNumber"**: byte, **"originalEncSecondaryAccountNumber"**: byte }
| #### Responses | Code | Description | | ---- | ----------- | | 401 | API authorized error caused due to any of the following reasons: + x-pay-token is not present or blank or not in valid format. + Timestamp field not in valid UTC timestamp format. + APIKey not present in request. + APIKey is not active. + APIKey not valid. + APIKey not active. | | 403 | Forbidden | | 500 | Internal server error | | 503 | Service unavailable | | 2XX | Callback successfully processed and no retries will be performed | ##### Security | Security Schema | Scopes | | --------------- | ------ | | apiKey | | x-pay-token | | #### Callback: installmentTransactionStatusChange ##### [POST] `{postbackNotificationUrl}` **Installment Transaction Status Change Notifications** These are API calls initiated by the Visa backend, made to the Visa Partner’s backend servers. The postbackNotificationUrl is configured by the Visa partners during onboarding. The + This callback is available only for those clients that own the BIN for the PAN involved – Lenders/Processors/BIN users/BIN owners. + Invoked when InstallmentTransaction status is updated. Installment Transaction corresponds to a clearing and a installment payment schedule. + These callbacks are sent only if the issuer has opted-in (as in the onboarding profile). + There will be 2 retries with random times from 1-30 minutes, if there are any 5XX or 404 errors returned from the client/partner. #### Parameters | Name | Located in | Description | Required | Schema | Explode | | ---- | ---------- | ----------- | -------- | ------ | ------- | | x-message-tracking-id | header | Tracking ID for callback and notification sent by Visa | Yes | string | No | | postbackNotificationUrl | path | | Yes | string | No | | apiKey | query | | Yes | string | Yes | | x-pay-token | header | See [XPayToken definition in Security Schemes](#/components/securitySchemes/x-pay-token) for details | Yes | string | No | #### Request Body | Required | Schema | | -------- | ------ | | No | **application/json**: { **"vPlanID"**: string (uuid), **"authCode"**: string, **"cardType"**: string,
**Available values:** "CREDIT", "DEBIT", "PREPAID",
**Default:** CREDIT, **"currency"**: string, **"cardBrand"**: string,
**Available values:** "VISA", "NON_VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "JCB", "UNIONPAY", "DINERSCLUB",
**Default:** VISA, **"vPlanIDRef"**: string, **"crossBorder"**: boolean, **"promotionInfo"**: { **"promotionID"**: string, **"promotionCode"**: string }, **"sourceCurrency"**: string, **"vTransactionID"**: string, **"messageMetadata"**: { **"type"**: string,
**Available values:** "BATCH_COMPLETED", "ELIGIBILITY", "PLANACCEPTANCE_STATUS_UPDATE", "INSTALLMENT_TRANSACTION_STATUS_UPDATE", "BILATERAL_PLAN_PARTNER_STATUS_UPDATE", **"vMessageID"**: string (uuid), **"createdDateTime"**: string (date-time-nooffset) }, **"encAccountNumber"**: byte, **"externalClientID"**: string, **"transactionAmount"**: long, **"vPlanAcceptanceID"**: string (uuid), **"installmentTransaction"**: { **"status"**: string,
**Available values:** "PENDING_CONFIRMATION", "CONFIRMED", "PENDING_CANCELLATION", "CANCELLED", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } & { **"refundAmount"**: long, **"sourceCurrency"**: string, **"lastRefundDateTime"**: dateTime, **"refundAmountInSourceCurrency"**: long, **"clearingAmountInSourceCurrency"**: long }, **"transactionRefundAmount"**: long, **"encSecondaryAccountNumber"**: byte, **"originalEncSecondaryAccountNumber"**: byte, **"transactionAmountInSourceCurrency"**: long, **"transactionRefundAmountInSourceCurrency"**: long }
| #### Responses | Code | Description | | ---- | ----------- | | 401 | API authorized error caused due to any of the following reasons: + x-pay-token is not present or blank or not in valid format. + Timestamp field not in valid UTC timestamp format. + APIKey not present in request. + APIKey is not active. + APIKey not valid. + APIKey not active. | | 403 | Forbidden | | 500 | Internal server error | | 503 | Service unavailable | | 2XX | Callback successfully processed and no retries will be performed | ##### Security | Security Schema | Scopes | | --------------- | ------ | | apiKey | | x-pay-token | | ### [POST] /installments/v2/planAcceptances/cancel **Plan Cancellation API** Merchant Participants can request the cancellation of the Installment Plan for refunds processed on the original purchase Installment Transaction by calling the Plan Cancellation API. This updates the status of the Installment Plan Selection. Failure to call this API on refunds will result in continued Installment Payments for the cardholder. If this API is invoked by any client other than the client that created the PlanAcceptance, then a 403 error is returned. Details on merchantInfo is captured as part of this API and used for authorization when invoked on behalf by the partner. This is a complex operation that involves updates to payments schedule and several updates to ledger activity. The parameters, including PII data, cannot be passed in the URI. Hence, it is a POST operation. Based on the request parameters the cancellation behaviour is as follows 1. Complete Plan Acceptance cancellation (all associated ISO Auth Transactions and Clearing) - if only vPlanAcceptanceID and encAccountNumber are provided.
Note: For PlanAcceptances created using v1 only this option is applicable. 2. Complete ISO Auth Transaction Cancellation (all associated clearing) - if only transactionInfo is provided and does not contain details on transactionRefundAmount or splitTransactionRefunds. 3. Cancellation based on refund amount at ISO Auth Transaction level - if transactionInfo is provided and contains transactionRefundAmount details. The associated clearing will be fully or partially cancelled based on transactionRefundAmount. 4. Cancellation based on refund amount at clearing level - if transactionInfo is provided and contains splitTransactionRefunds details.The clearing specified in splitTransactionRefunds will be partially or fully cancelled based on refundAmount. If the request contains both the vPlanAcceptanceID and splitTransactionRefunds then precedence is given to cancellation on clearing level based on splitTransactionRefunds. If the request contains both the transactionRefundAmount and splitTransactionRefunds then the total of refund amounts given in splitTransactionRefunds list must be equal to the transactionRefundAmount. #### Parameters | Name | Located in | Description | Required | Schema | Explode | | ---- | ---------- | ----------- | -------- | ------ | ------- | | ex-correlation-id | header | Unique ID for every API request - an optional header. Generated by the API client. Used for end-to-end tracing/debugging. | No | string | No | | v-c-idempotency-key | header | Unique ID for every API request - an optional header. Generated by the API client. Used for idempotency. | No | string (uuid) | No | #### Request Body | Required | Schema | | -------- | ------ | | Yes | **application/json**: { **"encAccountNumber"**: byte, **"tokenAccountNumber"**: string, **"vProvisionedTokenID"**: string, **"paymentAccountReference"**: string } & { **"tokenReferenceID"**: string }
| #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | | 200 | Successful Plan Acceptance Cancellation Response
**Headers:**
**ex-correlation-id**: Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging.
**v-c-idempotency-key**: Unique ID for the API response. v-c-idempotency-key is echoed back. Used for idempotency.
| **application/json**: { **"vPlanID"**: string (uuid), **"vPlanIDRef"**: string, **"transactions"**: [ { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } & { **"installmentTransactions"**: [ { **"status"**: string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } & { **"refundAmount"**: long, **"lastRefundDateTime"**: dateTime } ], **"transactionRefundAmount"**: long } ],
**Default:** , **"transactionInfo"**: { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } & { **"installmentTransactions"**: [ { **"status"**: string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } & { **"refundAmount"**: long, **"lastRefundDateTime"**: dateTime } ], **"transactionRefundAmount"**: long }, **"cancelledDateTime"**: dateTime, **"vPlanAcceptanceID"**: string (uuid), **"paymentAccountReference"**: string }
| | 400 | The errorResponse.details part of the error response can provide a list of fields that failed data validation constraints and errorResponse.reason values for this error include:

invalidRequestThe API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.

invalidRequestThe API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.

invalidRequestThe API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.

#### BaseConsumerInformation Schema Defines the cardholder/consumer that is initiating the creation of the plan acceptance or is selecting one of the eligible plans from the Seller. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | encAccountNumber | byte | JWE - This is a URL-safe base64-encoded string that represents the encrypted payload for AccountNumber. The format is the JSON Web Encryption using asymmetric/symmetric key material made available at time of onboarding. It is a standard JWT with a single custom AccountNumber claim, “accountNumber” that contains the card number/PAN. Visa uses JSON Web Encryption (JWE) to encrypt sensitive information in APIs. For more info, see "Encryption (JWE) Details". | No | | tokenAccountNumber | string | EMVCo Token account number provisioned by Visa
*Example:* `"4024007133554278"` | No | | vProvisionedTokenID | string | This is the token information corresponding to the PAN tokenized by the TokenRequester. The token requester is usually the seller.
*Example:* `"ac9e1cf6693c32cb7921112b7eb07d01"` | No | | paymentAccountReference | string | A Payment Account Reference (PAR) is a unique reference value associated with a specific card holder PAN. It identifies the card account, not just a card. PAR is a non-payment identifier that can be associated to PANs and tokens, as defined by EMVCo. PAR allows all participants in the payments chain to have a single, non-sensitive value assigned to a consumer. This value can be used in place of sensitive card holder identification fields, and transmitted across the payments ecosystem to facilitate card holder identification. PAR has a well-defined format (as per the Jan 2016 EMVCo documentation): - Fixed length of 29 characters - All Uppercase, Roman, & Alphanumeric values - 4-character BIN Controller ID assigned by EMVCo followed by a 25-character value
*Example:* `"V0010013820238835225373131610"` | No | #### PlanForSeller Schema Installment plan that has been matched against the eligibility criteria setup by the plan's issuer. The input for the matching criteria is provided by the Seller to Visa either during or after the purchase. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | PlanForSeller | { **"name"**: string, **"type"**: string,
**Available values:** "MARKET", "BI_LATERAL", "ISSUER_DEFAULT", "ISSUER_PROMOTION", "ISSUER_HYBRID", **"vPlanID"**: string (uuid), **"fundedBy"**: [ string,
**Available values:** "CONSUMER", "MERCHANT" ], **"vPlanIDRef"**: string, **"islamicPlan"**: boolean, **"promotionInfo"**: { **"promotionID"**: string, **"promotionCode"**: string }, **"termsAndConditions"**: [ { **"url"**: string, **"text"**: string, **"version"**: integer, **"languageCode"**: string } ], **"installmentFrequency"**: string,
**Available values:** "WEEKLY", "BIWEEKLY", "MONTHLY", "BIMONTHLY", **"numberOfInstallments"**: number (integer) } & { **"costInfo"**: { **"feeInfo"**: [ { **"type"**: string,
**Available values:** "CONSUMER", "CONSUMER_UPFRONT", "MERCHANT_FUNDING", "MERCHANT_SERVICE", **"flatFee"**: long, **"ratePercentage"**: integer, **"monthlyRatePercentage"**: integer } ], **"currency"**: string, **"totalFees"**: long, **"totalPlanCost"**: long, **"lastInstallment"**: { **"amount"**: long, **"totalAmount"**: long, **"installmentFee"**: long }, **"firstInstallment"**: { **"upfrontFee"**: long, **"totalAmountExcludingUpfrontFee"**: long } & { **"amount"**: long, **"totalAmount"**: long, **"installmentFee"**: long }, **"totalUpfrontFees"**: long, **"totalRecurringFees"**: long, **"annualPercentageRate"**: integer } } | Installment plan that has been matched against the eligibility criteria setup by the plan's issuer. The input for the matching criteria is provided by the Seller to Visa either during or after the purchase. | | #### CardNetworkBrand Schema The card network brand. When no value is set (or the field is not returned), it should be treated as VISA. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | CardNetworkBrand | string,
**Available values:** "VISA", "NON_VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "JCB", "UNIONPAY", "DINERSCLUB",
**Default:** VISA | The card network brand. When no value is set (or the field is not returned), it should be treated as VISA. | | #### BaseTransactionInformation Schema This structure represents the fields required for identifying a Visa transaction. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | authCode | string | ISO transaction auth code (alphanumeric)
*Example:* `"05754C"` | No | | currency | string | Conditional Mandatory Field : Always required when transactionAmount is specified. Currency of transactionAmount and transactionRefundAmount. Currency code in [ISO 4217 format](https://www.iban.com/currency-codes). | No | | vTransactionID | string | ISO Visa Authorization Transaction ID. + A unique value that Visa assigns to each transaction and returns to the acquirer in the authorization response. + Visa uses this value to maintain an audit trail throughout the life cycle of the transaction and all related transactions, such as reversals, adjustments, confirmations, and chargebacks. + In case of Post Purchase scenario, if Visa Transaction ID differs between authorization and clearing, this value should refer to clearing Visa Transaction ID.
Note:
In transactions using Mastercard credentials, where a single transaction ID is not available, Participants should use the Mastercard Tran ID field. Tran ID is made up of Financial Network Code + Banknet Reference Number + MMDD(TransactionDate), concatenated with no spaces.
*Example:* `"460162701383910"` | No | | externalTransactionRef | string | This is used by external clients as an opaque identifier and is sometimes used to correlate multiple transaction.
*Example:* `"17013357808877803992"` | No | #### EncryptedSecondaryAccountNumber Schema JWE - This is a URL-safe base64-encoded string that represents the encrypted payload for AccountNumber. The format is the JSON Web Encryption using asymmetric/symmetric key material made available at time of onboarding. It is a standard JWT with a single custom AccountNumber claim, “accountNumber” that contains the card number/PAN. Visa uses JSON Web Encryption (JWE) to encrypt sensitive information in APIs. For more info, see "Encryption (JWE) Details". | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | EncryptedSecondaryAccountNumber | byte | JWE - This is a URL-safe base64-encoded string that represents the encrypted payload for AccountNumber. The format is the JSON Web Encryption using asymmetric/symmetric key material made available at time of onboarding. It is a standard JWT with a single custom AccountNumber claim, “accountNumber” that contains the card number/PAN. Visa uses JSON Web Encryption (JWE) to encrypt sensitive information in APIs. For more info, see "Encryption (JWE) Details". | | #### y_JWK Schema EC y Coordinate in *base64Url* encoded value. Applicable only for EC key type. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | y_JWK | byte | EC y Coordinate in *base64Url* encoded value. Applicable only for EC key type. | | #### MerchantState Schema State where the merchant is located | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | MerchantState | string | State where the merchant is located | | #### BasicNonVisaTransactionData Schema This is a subset of common elements across ISO 8583 Authorization & Clearing Transaction Message fields for *non-Visa* cards as needed by installments application. This structure is used in callback/webhook responses as it does not contain the account number info. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | type | string,
**Available values:** "AUTH", "AUTH_REVERSAL", "CS_SALES_DRAFT", "CS_CREDIT_VOUCHER", "CS_CASH_DISBURSEMENT", "CS_SALES_DRAFT_REVERSAL", "CS_CREDIT_VOUCHER_REVERAL", "CS_CASH_DISBURSEMENT_REVERSAL" | ISO Transaction or Settlement message type + AUTH - ISO 0100/0110 - Authorization request/response data for purchase, cash, balance inquiry, return of goods + AUTH_REVERSAL - ISO 400/410 - ISO Reversal of an Authorization Request. Reversals are not the same as a merchandise return, but instead are used to reverse approved authorizations or financial transactions which are not completed due to unintended transactions. For example, when a merchant put the wrong dollar amount in an auth, the reversal ‘undoes’ it so that another auth message can be sent with the correct amount. + CS_SALES_DRAFT - TC 05 – Original purchase or representment; or dispute response financial + CS_CREDIT_VOUCHER - TC 06 – Original credit voucher or representment or dispute response financial; or original credit or representment + CS_CASH_DISBURSEMENT - TC 07 – Original cash disbursement/withdrawal or representment or dispute response financial + CS_SALES_DRAFT_REVERSAL - TC 25 – Reversal of an original purchase or representment or dispute response financial transaction + CS_CREDIT_VOUCHER_REVERAL - TC 26 – Reversal of an original credit voucher or representment or dispute response financial transaction; or original credit or representment transaction. + CS_CASH_DISBURSEMENT_REVERSAL - TC 27 – Reversal of an original cash disbursement/withdrawal transaction
*Enum:* `"AUTH"`, `"AUTH_REVERSAL"`, `"CS_SALES_DRAFT"`, `"CS_CREDIT_VOUCHER"`, `"CS_CASH_DISBURSEMENT"`, `"CS_SALES_DRAFT_REVERSAL"`, `"CS_CREDIT_VOUCHER_REVERAL"`, `"CS_CASH_DISBURSEMENT_REVERSAL"` | No | | authCode | string | ISO transaction Auth Code (alphanumeric). This Field 38 in ISO 8583 contains the response identification assigned by the authorizing institution.
*Example:* `"05754C"` | No | | category | string | The Merchant Category Code (MCC) is a four-digit number assigned to describe a merchant’s primary business based on annual sales volume measured in local currency. In addition, some MCCs identify a specific merchant or type of transaction. Visa and its members use MCC data for a range of purposes, including activity tracking, reporting, and risk management. Acquirers (and their agents) are required to assign the correct MCC to each of their merchants. Visa retains the right to require corrections to MCC assignments and use. The MCCs and descriptions have been derived from Standard Industrial Classification (SIC) Codes and the International Organization for Standardization (ISO) Codes. Please note that Visa MCCs and SIC codes do not always correspond. In many cases, Visa has consolidated several SIC codes into one MCC to manage the number of MCCs. In other cases, such as for T&E and direct marketing merchants, Visa established MCCs that do not have corresponding SIC codes. See [Visa Merchant Data Standards Manual](https://usa.visa.com/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf) for more info. For information related to MCC codes, please navigate to [this link](https://www.visa.com/supplierlocator-app/app/#/home/supplier-locator) about Supplier Locator.
*Example:* `"3001"` | No | | cardBrand | string,
**Available values:** "VISA", "NON_VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "JCB", "UNIONPAY", "DINERSCLUB",
**Default:** VISA | The card network brand. When no value is set (or the field is not returned), it should be treated as VISA.
*Enum:* `"VISA"`, `"NON_VISA"`, `"MASTERCARD"`, `"AMERICAN_EXPRESS"`, `"DISCOVER"`, `"JCB"`, `"UNIONPAY"`, `"DINERSCLUB"` | No | | merchantCity | string | Name of the merchant's city
*Example:* `"Foster City"` | No | | merchantName | string | Name of the merchant used for reporting purposes
*Example:* `"XYZ123"` | No | | merchantState | string | State where the merchant is located | No | | vPlanAcceptanceID | string (uuid) | Visa-generated identifier for a plan acceptance
*Example:* `"31e9f2b5-d90d-089e-67a5-1f533b02d301"` | No | | merchantPostalCode | string | Postal/Zip code of the merchant
*Example:* `"123456"` | No | | merchantCountryCode | string | ISO Country code where the merchant is located in ISO 3166-2 (alpha) format
*Example:* `"CA"` | No | | paymentAccountReference | string | A Payment Account Reference (PAR) is a unique reference value associated with a specific card holder PAN. It identifies the card account, not just a card. PAR is a non-payment identifier that can be associated to PANs and tokens, as defined by EMVCo. PAR allows all participants in the payments chain to have a single, non-sensitive value assigned to a consumer. This value can be used in place of sensitive card holder identification fields, and transmitted across the payments ecosystem to facilitate card holder identification. PAR has a well-defined format (as per the Jan 2016 EMVCo documentation): - Fixed length of 29 characters - All Uppercase, Roman, & Alphanumeric values - 4-character BIN Controller ID assigned by EMVCo followed by a 25-character value
*Example:* `"V0010013820238835225373131610"` | No | | originatorTransactionReference | string | Reference number allocated by the card acceptor to enable lookup of transaction for various use cases like disputes. This can be the acquirer reference number for the transaction in case of CS data. | No | #### InstallmentTransactionStatus Schema Status of the ISO Transaction's Clearing associated with a plan acceptance. + "CONFIRMED" - Clearing received and InstallmentTransaction is confirmed. + "CANCELLED" - Cancel request received and cancelled. + "PENDING_CONFIRMATION" - Authorization received and waiting for clearing match in Visa Installments. + "PENDING_CANCELLATION" - Cancel request received and waiting for original clearing. + "PARTIALLY_REFUNDED" - Cancel request received and transaction amount partially refunded. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | InstallmentTransactionStatus | string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED" | Status of the ISO Transaction's Clearing associated with a plan acceptance. + "CONFIRMED" - Clearing received and InstallmentTransaction is confirmed. + "CANCELLED" - Cancel request received and cancelled. + "PENDING_CONFIRMATION" - Authorization received and waiting for clearing match in Visa Installments. + "PENDING_CANCELLATION" - Cancel request received and waiting for original clearing. + "PARTIALLY_REFUNDED" - Cancel request received and transaction amount partially refunded. | | **Example**

CONFIRMED

#### AccountRangeEnrollmentIdentifier Schema Visa-generated identifier for a Account Range Enrollment | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | AccountRangeEnrollmentIdentifier | string (uuid) | Visa-generated identifier for a Account Range Enrollment | | **Example**

cd15d26e-5a4e-4eb5-9c35-9cfb4cbca7ee

#### EnrollmentStatus Schema Defined the enrollment status for each enrollment record. "NOT_ENROLLED" means the card holder is currently not enrolled or enrollment will end within 24 hours of enrollmentEndDate. "ERROR" means the card holder was not enrolled due to an error. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | EnrollmentStatus | string,
**Available values:** "ENROLLED", "NOT_ENROLLED", "ERROR" | Defined the enrollment status for each enrollment record. "NOT_ENROLLED" means the card holder is currently not enrolled or enrollment will end within 24 hours of enrollmentEndDate. "ERROR" means the card holder was not enrolled due to an error. | | **Example**

ENROLLED

#### TransactionRefundAmount Schema The amount used for partial or full cancellation of clearings associated with Visa ISO transaction. The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html)). If the currency is USD, “214010” is used for representing the amount, "$2,140.10". Note that there are no fractional minor units represented. They're rounded to the nearest whole number of minor units. When used in the HTTP request body for Visa Installment APIs + This field will be used to specify the refund amount to be split across the associated clearing within a transaction. + If this field is not provided then all clearing associated with the transaction will be fully cancelled based on the Transaction Amount. When returned in the HTTP response body or callback notifications, + This field is populated if provided by the merchant/seller in the request and represents the refund amount that was split across the associated clearing within a transaction. When requested in API request from Merchant (During Purchase scenario): + In multi-currency scenario, this field should be populated in source currency. When returned in API response or callback notification (During Purchase scenario): + When returned to Merchant in multi-currency scenario, this field will be populated in source currency. + When returned to Issuer in multi-currency scenario, this field will be populated in Issuer's currency. When requested in API request from Issuer (Post Purchase scenario): + In multi-currency scenario, this field should be populated in Issuer's currency. When returned in API response or callback notification to Issuer (Post Purchase scenario): + In multi-currency scenario, this field will be populated in Issuer's currency. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TransactionRefundAmount | long | The amount used for partial or full cancellation of clearings associated with Visa ISO transaction. The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html)). If the currency is USD, “214010” is used for representing the amount, "$2,140.10". Note that there are no fractional minor units represented. They're rounded to the nearest whole number of minor units. When used in the HTTP request body for Visa Installment APIs + This field will be used to specify the refund amount to be split across the associated clearing within a transaction. + If this field is not provided then all clearing associated with the transaction will be fully cancelled based on the Transaction Amount. When returned in the HTTP response body or callback notifications, + This field is populated if provided by the merchant/seller in the request and represents the refund amount that was split across the associated clearing within a transaction. When requested in API request from Merchant (During Purchase scenario): + In multi-currency scenario, this field should be populated in source currency. When returned in API response or callback notification (During Purchase scenario): + When returned to Merchant in multi-currency scenario, this field will be populated in source currency. + When returned to Issuer in multi-currency scenario, this field will be populated in Issuer's currency. When requested in API request from Issuer (Post Purchase scenario): + In multi-currency scenario, this field should be populated in Issuer's currency. When returned in API response or callback notification to Issuer (Post Purchase scenario): + In multi-currency scenario, this field will be populated in Issuer's currency. | | #### TransactionSequenceTotal Schema Total number of clearings for the corresponding Authorization. This is present only when there are multiple clearings per auth. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TransactionSequenceTotal | integer | Total number of clearings for the corresponding Authorization. This is present only when there are multiple clearings per auth. | | **Example**

#### Currency Schema Currency code in [ISO 4217 format](https://www.iban.com/currency-codes) | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | Currency | string | Currency code in [ISO 4217 format](https://www.iban.com/currency-codes) | | **Example**

USD

#### InstallmentTransactionForResponse Schema Associated transaction for a given plan acceptance. A plan acceptance can be created with a single ISO transaction or many ISO transactions, or a part of an ISO transaction (one clearing out of many, for example). Represents the schedule of payments corresponding to a plan acceptance. Clearing data will be always included when available.
NOTES: + When returned in the HTTP response body or callback notifications, all of the fields below are required (i.e., al fields are populated when used in response body). + When used in the HTTP request body of an API request to Visa Installments, the required fields must be provided. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | InstallmentTransactionForResponse | { **"status"**: string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } | Associated transaction for a given plan acceptance. A plan acceptance can be created with a single ISO transaction or many ISO transactions, or a part of an ISO transaction (one clearing out of many, for example). Represents the schedule of payments corresponding to a plan acceptance. Clearing data will be always included when available.
NOTES: + When returned in the HTTP response body or callback notifications, all of the fields below are required (i.e., al fields are populated when used in response body). + When used in the HTTP request body of an API request to Visa Installments, the required fields must be provided. | | #### BasePage Schema | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | last | boolean | | No | | empty | boolean | | No | | first | boolean | | No | | number | integer | | No | | totalCount | integer | | No | | totalPages | integer | | No | | resultsCount | integer | | No | #### InstallmentCostDetails Schema Cost details (fee and principal) for each Installment. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | amount | long | The principal amount for this Installment period. The currency is specified in the parent object that includes this structure. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units.
*Example:* `50000` | Yes | | totalAmount | long | The total amount payable for this Installment period, inclusive of principal amount, consumer fee and any upfront fee. The currency is specified in the parent object that includes this structure. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units.
*Example:* `55000` | Yes | | installmentFee | long | The consumer fee for this Installment period. This fee corresponds to the fee type CONSUMER. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units.
*Example:* `5000` | Yes | #### LastInstallment Schema Cost details (fee and principal) for the last Installment. Note that the last Installment includes the balance of the rounding amounts when amount is split across various Installment periods. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | LastInstallment | { **"amount"**: long, **"totalAmount"**: long, **"installmentFee"**: long } | Cost details (fee and principal) for the last Installment. Note that the last Installment includes the balance of the rounding amounts when amount is split across various Installment periods. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units. | | #### PlanAcceptanceStatusTransitions Schema The timestamps at which the Plan Acceptance status was updated. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | createdDateTime | string (date-time-ms-nooffset) | When the plan acceptance was created/initiated from the Seller.
*Example:* `"2021-01-17T16:15:21.298"` | Yes | | updatedDateTime | string (date-time-ms-nooffset) | When the plan acceptance was updated (associated with another ISO transaction). This field is present only if an additional ISO transaction was associated with this plan acceptance after creation.
*Example:* `"2021-01-17T16:15:21.298"` | No | | confirmedDateTime | string (date-time-ms-nooffset) | When the plan acceptance was confirmed after the Visa ISO transaction clearing. This field is present only if the plan acceptance is confirmed.
*Example:* `"2021-01-17T16:15:21.298"` | No | | cancellationDateTime | string (date-time-ms-nooffset) | When the plan acceptance was canceled before it was closed. This field is present only if the plan acceptance was canceled at some point.
*Example:* `"2021-01-17T16:15:21.298"` | No | #### AccountRangeMax Schema Maximum acceptable value in the defined Account Range Enrollment | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | AccountRangeMax | string | Maximum acceptable value in the defined Account Range Enrollment | | **Example**

5236910248839999

#### CandidatesBatchPageContentArrayItem Schema Each of the submitted ConsumerInfo object is echoed back in the response along with the following: + Eligibility Status + Error Response (if any encountered during matching process, eligibility status should be 'ERROR') | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | CandidatesBatchPageContentArrayItem | { **"errorResponse"**: { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string }, **"encAccountNumber"**: byte, **"eligibilityStatus"**: string,
**Available values:** "MATCHED", "NOT_MATCHED", "ERROR",
**Default:** MATCHED, **"tokenAccountNumber"**: string, **"vProvisionedTokenID"**: string } | Each of the submitted ConsumerInfo object is echoed back in the response along with the following: + Eligibility Status + Error Response (if any encountered during matching process, eligibility status should be 'ERROR') | | #### PromotionInformation Schema This is the promotion information shared between the Issuer and Seller. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | promotionID | string | An opaque string (as an external identifier) provided by the issuer to Visa that identifies a program or promotion that is setup outside of Visa Installment Services. + Up to 8 alphanumeric characters + This identifier is used during plan search or eligibility checks.
*Example:* `"MBANK12"` | No | | promotionCode | string | An opaque string (as an external identifier to this plan) provided by the issuer to Visa that identifies this Installment plan. + Up to 2 alphanumeric characters + It is typically shared to the Seller by the Financial Institution/Issuer so that it can be passed-in during eligibility checks or plan acceptance.
*Example:* `"A2"` | No | #### PlanEndDate Schema Effective End date of the Plan.Plan end date as set by the Issuer.This can be null if there is no end date. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | PlanEndDate | date | Effective End date of the Plan.Plan end date as set by the Issuer.This can be null if there is no end date. | | #### ProductType Schema Product Type of the PAN. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | ProductType | string,
**Available values:** "CREDIT", "DEBIT" | Product Type of the PAN. | | **Example**

DEBIT

#### AccountRange Schema Defines the set of cards corresponding to the enrollment profile. These account ranges are checked for ownership by the API caller; if not authorized, an HTTP 403 error is returned. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | max | string | The maximum of the account range to be included for PANs. All “wild card” digits in the account number should be filled with 0s.
*Example:* `"412667478532410943000"` | Yes | | min | string | The minimum of the account range to be included for PANs. All “wild card” digits in the account number should be filled with 0s.
*Example:* `"412667478532410942000"` | Yes | #### PlanFlatFee Schema Flat fee applied on the first Installment payment in Issuer currency. The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example). + The currency field decides the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html). If the currency is USD, “1034” is used for representing the amount "$10.34". + Note that there are no fractional minor units represented. They're rounded to the whole minor units. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | PlanFlatFee | long | Flat fee applied on the first Installment payment in Issuer currency. The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example). + The currency field decides the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html). If the currency is USD, “1034” is used for representing the amount "$10.34". + Note that there are no fractional minor units represented. They're rounded to the whole minor units. | | **Example**

#### InstallmentMode Schema Specifies the mode of installment.
Note: This is an optional field, however it must be provided when Acquirer makes the call on behalf of the Merchant(OnUs Transactions) and in such cases it must be set to DURING_PURCHASE. - "DURING_PURCHASE" - Indicates the installment is initiated during the purchase. - "POST_PURCHASE" - Indicates the installment is initiated after the purchase. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | InstallmentMode | string,
**Available values:** "DURING_PURCHASE", "POST_PURCHASE" | Specifies the mode of installment.
Note: This is an optional field, however it must be provided when Acquirer makes the call on behalf of the Merchant(OnUs Transactions) and in such cases it must be set to DURING_PURCHASE. - "DURING_PURCHASE" - Indicates the installment is initiated during the purchase. - "POST_PURCHASE" - Indicates the installment is initiated after the purchase. | | **Example**

DURING_PURCHASE

#### AccountRangeMin Schema Minimum acceptable value in the defined Account Range Enrollment | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | AccountRangeMin | string | Minimum acceptable value in the defined Account Range Enrollment | | **Example**

5236910248830000

#### BaseOnboardingInformation-1 Schema Details required to Onboard a client associated with a Partner | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | city | string | Name of the merchant's city
*Example:* `"Foster City"` | No | | phone | string | Client's primary phone number. Client's primary phone number and the format is based on the countryCode field

countryCode	MinLength	MaxLength	Format
AU (Australia) CA (Canada) US (United States of America)	10	16	Allowed characters are digits, a hyphen, an open parenthesis, a close parenthesis, a dot, a plus sign, or whitespace.Example:+(001)-97444108
MY (Malaysia) MX (Mexico) NZ (New Zealand)	3	15	Only digits are allowed.Example:0097444100888
Other Countries	1	16	Only digits are allowed.Example:0097444100888

| No | | address1 | string | First line of the client's primary address. This value can be Alphabetic, numeric, or the following characters: spaces, ' (single quote), # (pound-sign or hash), , (comma), _ (underscore), : (colon), / (forward slash), and - (hyphen)
*Example:* `"1 Main Street"` | Yes | | address2 | string | Second line of the client's primary address. It can be empty. This value can be Alphabetic, numeric, or the following characters: spaces, ' (single quote), # (pound-sign or hash), , (comma), _ (underscore), : (colon), / (forward slash), and - (hyphen)
*Example:* `"2nd Block"` | No | | postalCode | string | Postal/Zip code of the merchant
*Example:* `"123456"` | No | | countryCode | string | ISO Country code where the merchant is located in ISO 3166-2 (alpha) format
*Example:* `"CA"` | Yes | | cardAcceptorId | string | Unique identifier that identifies the card acceptor operating the POS terminal. This field must contain an acquirer-assigned alphanumeric code that identifies the Card Acceptor(store/merchant transaction point).
*Example:* `"234568785"` | No | | primaryLegalName | string | Legal name of client. This value must contain only English alphabets,numbers and space.
*Example:* `"ABZ Inc"` | Yes | | primaryTradeName | string | Trade name of client, such as a doing business-as (DBA) name. If not specified, the legal name (companyPrimaryLegalName) is used by default. This value must contain only English alphabets,numbers and space.
*Example:* `"ABZ Traders"` | No | | primaryWebsiteURL | string | URL of Clients's website.
*Example:* `"http://www.example.com"` | Yes | | stateProvinceCode | string | State or province code associated with the physical address in the specified country. This value can be alphabetic, numeric, or the following characters: spaces, '(single quote), ,(comma), and -(hyphen). Recommended to use the country subdivision codes defined in ISO-3166-2. (Note: must use ISO-3166-2 subdivision codes for AU, CA, and US). Additional validations based on countryCode:

countryCode	Description
AU (Australia), CA (Canada), US (United States of America)	Must be a subdivision code (up to three characters) defined in ISO-3166-2. e.g. NSW (AU), QC (CA), DE (US)

*Example:* `"QC"` | No | | primaryContactEmail | string | Email address of Client's primary contact, which is also the user name for Visa portal access.
*Example:* `"test@xyz.com"` | No | | primaryContactLastName | string | Surname of Client's primary contact person. Alphabetic or the following characters: spaces, ' (single quote), ` (back tick), ~ (tilde), " (double quote), . (period), and - (hyphen)
*Example:* `"Smith"` | No | | primaryContactFirstName | string | First name of Client's primary contact person. Alphabetic or the following characters: spaces, ' (single quote), ` (back tick), ~ (tilde), " (double quote), . (period), and - (hyphen)
*Example:* `"John"` | No | | partnerMerchantReferenceID | string | Usually, this reference ID is assigned by the Partner but in cases where not provided when onboarding the Merchant, this value will be generated by Visa and provided to the Partner. It is used by Visa for enforcing authorization (so that one Merchant's plan acceptance is not accessed/modified by an unauthorized merchant/partner), risk assessment and for instrumentation. It is also used to serve bilateral plan agreements between a Seller and Issuer. In the future, it can be used to specify merchant-specific filters for installment plans. - When provided in cancellation or search, this ID is used to match the plan acceptance and enforce authorization. - When provided in plan selection (plan acceptance creation) API, it is used to later for authorization checks on cancel or search plan acceptances. - When provided in plan match API, it is used for filter bilateral plans & instrumentation/reporting purposes.
*Example:* `"98243463"` | No | #### BatchStatus Schema Status of the submitted batch job. The results are available when the job is COMPLETED. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | BatchStatus | string,
**Available values:** "SUBMITTED", "COMPLETED" | Status of the submitted batch job. The results are available when the job is COMPLETED. | | **Example**

COMPLETED

#### AccountRangeEnrollment Schema Details of Account Range Enrollment in Installment | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | accountRangeMax | string | Maximum acceptable value in the defined Account Range Enrollment
*Example:* `"5236910248839999"` | Yes | | accountRangeMin | string | Minimum acceptable value in the defined Account Range Enrollment
*Example:* `"5236910248830000"` | Yes | | vEnrollmentProfileID | string (uuid) | Visa-generated Enrollment Profile Identifier
*Example:* `"278a6873-9dc2-b466-284c-1d10ee797301"` | Yes | | vAccountRangeEnrollmentID | string (uuid) | Visa-generated identifier for a Account Range Enrollment
*Example:* `"cd15d26e-5a4e-4eb5-9c35-9cfb4cbca7ee"` | Yes | #### TransactionInfoWithRefundInstallmentTransaction Schema Transaction information that includes the associated transaction along multiple clearing info and refund details. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TransactionInfoWithRefundInstallmentTransaction | { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } & { **"installmentTransactions"**: [ { **"status"**: string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } & { **"refundAmount"**: long, **"lastRefundDateTime"**: dateTime } ], **"transactionRefundAmount"**: long } | Transaction information that includes the associated transaction along multiple clearing info and refund details. | | #### EffectiveEnrollmentUpdateDate Schema Effective date for the enrollment profile Id update to be effective. *This must be later than (midnight() UTC + 24 hours), otherwise a 400 error will be returned* *Required* and used only when vEnrollmentProfileID is updated for an already enrolled cardholder. Otherwise, this value is ignored. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | EffectiveEnrollmentUpdateDate | date | Effective date for the enrollment profile Id update to be effective. *This must be later than (midnight() UTC + 24 hours), otherwise a 400 error will be returned* *Required* and used only when vEnrollmentProfileID is updated for an already enrolled cardholder. Otherwise, this value is ignored. | | #### NonVisaClearingSettlementData Schema This is a subset of Clearing / Settlement Transaction Message fields for *non-Visa* cards as needed by installments application. This structure is used in callback/webhook responses as it does not contain the account number info. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | NonVisaClearingSettlementData | { **"type"**: string,
**Available values:** "AUTH", "AUTH_REVERSAL", "CS_SALES_DRAFT", "CS_CREDIT_VOUCHER", "CS_CASH_DISBURSEMENT", "CS_SALES_DRAFT_REVERSAL", "CS_CREDIT_VOUCHER_REVERAL", "CS_CASH_DISBURSEMENT_REVERSAL", **"authCode"**: string, **"category"**: string, **"cardBrand"**: string,
**Available values:** "VISA", "NON_VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "JCB", "UNIONPAY", "DINERSCLUB",
**Default:** VISA, **"merchantCity"**: string, **"merchantName"**: string, **"merchantState"**: string, **"vPlanAcceptanceID"**: string (uuid), **"merchantPostalCode"**: string, **"merchantCountryCode"**: string, **"paymentAccountReference"**: string, **"originatorTransactionReference"**: string } & { **"sequenceTotal"**: integer, **"sequenceNumber"**: integer, **"settlementAmount"**: long, **"settlementCurrency"**: string, **"settlementDateTime"**: dateTime, **"settlementBillingAmount"**: long, **"settlementBillingCurrency"**: string } | This is a subset of Clearing / Settlement Transaction Message fields for *non-Visa* cards as needed by installments application. This structure is used in callback/webhook responses as it does not contain the account number info. | | #### StandardError Schema API errors are reported using a Standard Error Response structure. All errors are categorized into Standard errors and Business errors. Standard errors can be returned by any API and should be handled in a common way. Business errors are returned only by some APIs and are documented for each API. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | errorResponse | { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } | Standard error response body provided when there is an error. | No | #### DeviceSoftwareID Schema The unique name or id assigned to the software on the device | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | DeviceSoftwareID | string | The unique name or id assigned to the software on the device | | **Example**

SA2.0

#### ExternalKeyReference Schema + Meaningful only to the caller of this API + Used, optionally, to cross-reference with the keys between the request and response. Use numbers like '1', '2', etc. + If not present, the response will include the keys in the same order as the request | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | ExternalKeyReference | string | + Meaningful only to the caller of this API + Used, optionally, to cross-reference with the keys between the request and response. Use numbers like '1', '2', etc. + If not present, the response will include the keys in the same order as the request | | **Example**

#### EligibleTransaction Schema Invoked whenever there are transactions eligible for Installment plans of cardholders already registered through a POST_PURCHASE Installment mode. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | cardBrand | string,
**Available values:** "VISA", "NON_VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "JCB", "UNIONPAY", "DINERSCLUB",
**Default:** VISA | The card network brand. When no value is set (or the field is not returned), it should be treated as VISA.
*Enum:* `"VISA"`, `"NON_VISA"`, `"MASTERCARD"`, `"AMERICAN_EXPRESS"`, `"DISCOVER"`, `"JCB"`, `"UNIONPAY"`, `"DINERSCLUB"` | No | | matchedPlans | [ string (uuid) ] | List of eligible and active Installment Plans | Yes | | transactionInfo | { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } | | Yes | | encAccountNumber | byte | JWE - This is a URL-safe base64-encoded string that represents the encrypted payload for AccountNumber. The format is the JSON Web Encryption using asymmetric/symmetric key material made available at time of onboarding. It is a standard JWT with a single custom AccountNumber claim, “accountNumber” that contains the card number/PAN. Visa uses JSON Web Encryption (JWE) to encrypt sensitive information in APIs. For more info, see "Encryption (JWE) Details". | Yes | | eligibilityDateTime | dateTime | Time when this eligibility was determined by Visa Installments
*Example:* `"2021-01-17T16:15:21Z"` | Yes | | eligibilityExpiryDateTime | dateTime | Time when this eligibility expires
*Example:* `"2021-01-17T16:15:21Z"` | Yes | #### TokenReferenceIdentifier Schema Token Reference value for corresponding to the PAN tokenized by the TokenRequester. The token requester is usually the seller. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TokenReferenceIdentifier | string | Token Reference value for corresponding to the PAN tokenized by the TokenRequester. The token requester is usually the seller. | | **Example**

rf692we31cf6693c32cb7921112b7eb07d01

#### KeyFunction Schema The purpose of this key, which is generated by the device. + Typically, device keys are used for AUTHENTICITY; that is, the Payment Terminal/device Public Key is associated to Payment Terminal/device Authentication + Typically, Visa keys are used for AUTHENTICITY and KEY_AGREEMENT + AUTHENTICITY for the Visa Public Key associated to Authenticated Message in Visa responses occurring during Payment Terminal/Device Authentication + KEY_AGREEMENT for the Visa Static Public Key associated to Key Agreement occurring during Payment Terminal/Device Authentication | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | KeyFunction | string,
**Available values:** "AUTHENTICITY", "KEY_AGREEMENT",
**Default:** KEY_AGREEMENT | The purpose of this key, which is generated by the device. + Typically, device keys are used for AUTHENTICITY; that is, the Payment Terminal/device Public Key is associated to Payment Terminal/device Authentication + Typically, Visa keys are used for AUTHENTICITY and KEY_AGREEMENT + AUTHENTICITY for the Visa Public Key associated to Authenticated Message in Visa responses occurring during Payment Terminal/Device Authentication + KEY_AGREEMENT for the Visa Static Public Key associated to Key Agreement occurring during Payment Terminal/Device Authentication | | **Example**

AUTHENTICITY

#### PlanFeesForBilateral Schema Fee rate table used to calculate the fees. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | type | string,
**Available values:** "ACQUIRER_TO_ISSUER", "CONSUMER", "CONSUMER_UPFRONT", "ISSUER_TO_ACQUIRER", "APR" | Fee types applicable for Bilateral.
*Enum:* `"ACQUIRER_TO_ISSUER"`, `"CONSUMER"`, `"CONSUMER_UPFRONT"`, `"ISSUER_TO_ACQUIRER"`, `"APR"`
*Example:* `"ACQUIRER_TO_ISSUER"` | No | | amount | long | Flat Fee for the Plan The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example). + The currency field decides the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html). If the currency is USD, “1034” is used for representing the amount "$10.34". + Note that there are no fractional minor units represented. They're rounded to the whole minor units.
*Example:* `500` | No | | ratePercentage | integer | Interest fee rate in percentage applied on Installment payment. + Percentage rate and is a non-negative value. + The percentage value is represented with two implicit decimals. (max 10000) Example: 250 specifies 2.5% + For calculations, the actual percentage value should be interpreted as follows: actualPercentageValue = ratePercentage / 100.00
*Example:* `320` | No | #### InstallmentTransactionStatusForNotification Schema Status of an ISO Transaction's Clearing associated with a plan acceptance. + "PENDING_CONFIRMATION" - Authorization received and waiting for clearing match in Visa Installments. For Non-Visa based transactions, this should be used as a trigger to send the Auth/Clearing Feed to Visa Installments. + "CONFIRMED" - Clearing received and InstallmentTransaction is confirmed. + "PENDING_CANCELLATION" - Cancel request received and waiting for original clearing. + "CANCELLED" - Cancel request received and cancelled. + "PARTIALLY_REFUNDED" - Cancel request received and transaction amount partially refunded. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | InstallmentTransactionStatusForNotification | string,
**Available values:** "PENDING_CONFIRMATION", "CONFIRMED", "PENDING_CANCELLATION", "CANCELLED", "PARTIALLY_REFUNDED" | Status of an ISO Transaction's Clearing associated with a plan acceptance. + "PENDING_CONFIRMATION" - Authorization received and waiting for clearing match in Visa Installments. For Non-Visa based transactions, this should be used as a trigger to send the Auth/Clearing Feed to Visa Installments. + "CONFIRMED" - Clearing received and InstallmentTransaction is confirmed. + "PENDING_CANCELLATION" - Cancel request received and waiting for original clearing. + "CANCELLED" - Cancel request received and cancelled. + "PARTIALLY_REFUNDED" - Cancel request received and transaction amount partially refunded. | | **Example**

PENDING_CONFIRMATION

#### TransactionSequenceNumber Schema Transaction sequence number of this transaction when there are multiple clearings per Authorization. They are assumed to be in increments of 1 with no gaps. This is present only when there are multiple clearings per auth. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TransactionSequenceNumber | integer | Transaction sequence number of this transaction when there are multiple clearings per Authorization. They are assumed to be in increments of 1 with no gaps. This is present only when there are multiple clearings per auth. | | **Example**

#### TotalPlanCost Schema Grand total of the entire plan cost including the principal amounts and total fees charged to the consumer, across all Installment periods. The amount is represented in minor units. It is a numerical value in [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency (Cents for USD, for example). If the currency is USD, “61299” is used for representing the amount "$612.99". Note that there are no fractional minor units represented, they're rounded to the whole minor units.
For Canada, total plan cost calculation includes small buffer value to ensure Merchant displays the highest possible value for the transaction at the time of checkout (Issuers are not expected to use the value). | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TotalPlanCost | long | Grand total of the entire plan cost including the principal amounts and total fees charged to the consumer, across all Installment periods. The amount is represented in minor units. It is a numerical value in [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency (Cents for USD, for example). If the currency is USD, “61299” is used for representing the amount "$612.99". Note that there are no fractional minor units represented, they're rounded to the whole minor units.
For Canada, total plan cost calculation includes small buffer value to ensure Merchant displays the highest possible value for the transaction at the time of checkout (Issuers are not expected to use the value). | | **Example**

#### PlanAcceptanceStatus Schema Specifies the status of the plan acceptance. + CREATED: The intial state, until all of the installment transactions are confirmed or cancelled or until transaction is associated to this plan acceptance. + CANCELLED: Plan acceptance is transitioned to this state when all of the installment transactions are cancelled + CONFIRMED: Plan acceptance is transitioned to this state when all of the installment transactions are confirmed + UPDATED: Plan acceptance is transitioned to this state from CREATED state when a transaction is associated to this plan acceptance | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | PlanAcceptanceStatus | string,
**Available values:** "CREATED", "CANCELLED", "UPDATED", "CONFIRMED" | Specifies the status of the plan acceptance. + CREATED: The intial state, until all of the installment transactions are confirmed or cancelled or until transaction is associated to this plan acceptance. + CANCELLED: Plan acceptance is transitioned to this state when all of the installment transactions are cancelled + CONFIRMED: Plan acceptance is transitioned to this state when all of the installment transactions are confirmed + UPDATED: Plan acceptance is transitioned to this state from CREATED state when a transaction is associated to this plan acceptance | | **Example**

CREATED

#### MessageMetadata Schema Generic metadata that is always present for every postback message sent from Visa to the partners. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | type | string,
**Available values:** "BATCH_COMPLETED", "ELIGIBILITY", "PLANACCEPTANCE_STATUS_UPDATE", "INSTALLMENT_TRANSACTION_STATUS_UPDATE", "BILATERAL_PLAN_PARTNER_STATUS_UPDATE" | Type of the notification message. Here are the valid values: + BATCH_COMPLETED - For callback when a batch job is completed and results are available. + ELIGIBILITY - For callback when there are eligible transactions for post-purchase use cases. + PLANACCEPTANCE_STATUS_UPDATE - For callback when PlanAcceptance status is updated and the status updates are subscribed during onboarding. + INSTALLMENT_TRANSACTION_STATUS_UPDATE - For callback when Installment Transaction status is updated and the status updates are subscribed during onboarding. + BILATERAL_PLAN_PARTNER_STATUS_UPDATE - For callback when Bilateral Plan status is updated and the status updates are subscribed during onboarding.
*Enum:* `"BATCH_COMPLETED"`, `"ELIGIBILITY"`, `"PLANACCEPTANCE_STATUS_UPDATE"`, `"INSTALLMENT_TRANSACTION_STATUS_UPDATE"`, `"BILATERAL_PLAN_PARTNER_STATUS_UPDATE"`
*Example:* `"BATCH_COMPLETED"` | Yes | | vMessageID | string (uuid) | Unique message identifier for all postback messages produced by Visa.
*Example:* `"173e4567-e89b-12d3-a456-426614174000"` | Yes | | createdDateTime | string (date-time-nooffset) | Timestamp of the creation of this message
*Example:* `"2021-01-17T16:15:21"` | Yes | #### Crv_JWK Schema Applicable only for EC key type. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | Crv_JWK | string,
**Available values:** "P-256",
**Default:** P-256 | Applicable only for EC key type. | | **Example**

P-256

#### FeesAndCostForSeller Schema A list of applicable seller costs/fees for the Installment plan. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | feeInfo | [ { **"type"**: string,
**Available values:** "CONSUMER", "CONSUMER_UPFRONT", "MERCHANT_FUNDING", "MERCHANT_SERVICE", **"flatFee"**: long, **"ratePercentage"**: integer, **"monthlyRatePercentage"**: integer } ] | Fee rate table used to calculate the Seller fees. + The feeInfo will contain an array of fee type(s) with the associated ratePercentage or flatFee. + One or many of the fee types - CONSUMER, CONSUMER_UPFRONT, MERCHANT_FUNDING and MERCHANT_SERVICE might be present based on the plan type and plan setup. + MERCHANT_FUNDING and MERCHANT_SERVICE appear only when the API request is initiated by Acquirers. | Yes | | currency | string | Currency used for all of the above amounts. Currency code in [ISO 4217 format](https://www.iban.com/currency-codes) | Yes | | totalFees | long | Total fees charged to the consumer, calculated as totalUpfrontFees + totalRecurringFees. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units.
*Example:* `50000` | Yes | | totalPlanCost | long | Grand total of the entire plan cost including the principal amounts and total fees charged to the consumer, across all Installment periods. The amount is represented in minor units. It is a numerical value in [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency (Cents for USD, for example). If the currency is USD, “61299” is used for representing the amount "$612.99". Note that there are no fractional minor units represented, they're rounded to the whole minor units.
For Canada, total plan cost calculation includes small buffer value to ensure Merchant displays the highest possible value for the transaction at the time of checkout (Issuers are not expected to use the value).
*Example:* `612990` | Yes | | lastInstallment | { **"amount"**: long, **"totalAmount"**: long, **"installmentFee"**: long } | Cost details (fee and principal) for the last Installment. Note that the last Installment includes the balance of the rounding amounts when amount is split across various Installment periods. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units. | Yes | | firstInstallment | { **"upfrontFee"**: long, **"totalAmountExcludingUpfrontFee"**: long } & { **"amount"**: long, **"totalAmount"**: long, **"installmentFee"**: long } | Cost details (fee and principal) for the first Installment. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units. | Yes | | totalUpfrontFees | long | Total upfront fees charged to the consumer for this Installment plan. This fee corresponds to the fee type CONSUMER_UPFRONT. This is the amount charged upfront along with the first Installment principal only. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units.
*Example:* `10000` | Yes | | totalRecurringFees | long | Total recurring fees charged to the consumer for this Installment plan. This fee corresponds to the fee type CONSUMER. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units.
*Example:* `2000` | Yes | | annualPercentageRate | integer | Annual Percentage Rate (APR) as configured by the Issuer during plan creation. This is not used for calculations, but used only for display purposes. + Interest fee rate in percentage applied on Installment payment. + Percentage rate and is a non-negative value. + The percentage value is represented with two implicit decimals. (max 10000) Example: 320 specifies 3.2% + For your calculations, the actual percentage value should be interpreted as follows: actualPercentageValue = ratePercentage / 100.00
*Example:* `320` | No | #### ExternalClientIdentifier Schema Partner relationship ID. Relationship name identifier of the partner on whose behalf the API is called. This identifier is set up during client-partner relationship onboarding in Visa Developer Center.
This value must only be provided when the API caller is invoking this API on behalf of some other partner. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | ExternalClientIdentifier | string | Partner relationship ID. Relationship name identifier of the partner on whose behalf the API is called. This identifier is set up during client-partner relationship onboarding in Visa Developer Center.
This value must only be provided when the API caller is invoking this API on behalf of some other partner. | | **Example**

31e9f2b5-d90d-089e-67a5-1f533b02d301

#### MerchantName Schema Name of the merchant used for reporting purposes | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | MerchantName | string | Name of the merchant used for reporting purposes | | **Example**

XYZ123

#### PlanIdentifier Schema Visa-generated identifier for an Installment plan | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | PlanIdentifier | string (uuid) | Visa-generated identifier for an Installment plan | | **Example**

9d16a09e-3812-4ce3-a258-9981cc13a1f3

#### BatchExecutionDateTime Schema This is the execution date of the batch data. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | BatchExecutionDateTime | dateTime | This is the execution date of the batch data. | | **Example**

2021-01-17T16:15:21Z

#### EncryptedAccountNumbers Schema A URL-safe base64-encoded JWE string representing a set of eligible cardholders (set of PANs) for batch enrollment. JWE - This is an URL-safe base64 encoded string that represents the encrypted payload for a JSON array of accountNumbers. The number of items in the JSON array must be between 1 to 2000. The format is the JSON Web Encryption using asymmetric/symmetric key material made available at time of onboarding. It is a standard JWT with a single custom claim, "accountNumbers" that is a JSON array of '#/components/schemas/AccountNumber' Visa uses JSON Web Encryption (JWE) to encrypt sensitive information in APIs. For more info, see "Encryption (JWE) Details." | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | EncryptedAccountNumbers | byte | A URL-safe base64-encoded JWE string representing a set of eligible cardholders (set of PANs) for batch enrollment. JWE - This is an URL-safe base64 encoded string that represents the encrypted payload for a JSON array of accountNumbers. The number of items in the JSON array must be between 1 to 2000. The format is the JSON Web Encryption using asymmetric/symmetric key material made available at time of onboarding. It is a standard JWT with a single custom claim, "accountNumbers" that is a JSON array of '#/components/schemas/AccountNumber' Visa uses JSON Web Encryption (JWE) to encrypt sensitive information in APIs. For more info, see "Encryption (JWE) Details." | | #### AnnualPercentageRate Schema Annual Percentage Rate (APR) as configured by the Issuer during plan creation. This is not used for calculations, but used only for display purposes. + Interest fee rate in percentage applied on Installment payment. + Percentage rate and is a non-negative value. + The percentage value is represented with two implicit decimals. (max 10000) Example: 320 specifies 3.2% + For your calculations, the actual percentage value should be interpreted as follows: actualPercentageValue = ratePercentage / 100.00 | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | AnnualPercentageRate | integer | Annual Percentage Rate (APR) as configured by the Issuer during plan creation. This is not used for calculations, but used only for display purposes. + Interest fee rate in percentage applied on Installment payment. + Percentage rate and is a non-negative value. + The percentage value is represented with two implicit decimals. (max 10000) Example: 320 specifies 3.2% + For your calculations, the actual percentage value should be interpreted as follows: actualPercentageValue = ratePercentage / 100.00 | | **Example**

#### OrderAmount Schema The amount corresponding to the order for a Plan Acceptance. This is the max amount (within a certain tolerance percentage) that is enforced for all transactions added to this plan acceptance. The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html)). If the currency is USD, “214010” is used for representing the amount, "$2,140.10". Note that there are no fractional minor units represented. They're rounded to the nearest whole number of minor units.

In case of Post Purchase scenario, this value need not be provided and will internally be set as the sum of clearing amounts (installmentTransactions.clearingAmount). | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | OrderAmount | long | The amount corresponding to the order for a Plan Acceptance. This is the max amount (within a certain tolerance percentage) that is enforced for all transactions added to this plan acceptance. The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html)). If the currency is USD, “214010” is used for representing the amount, "$2,140.10". Note that there are no fractional minor units represented. They're rounded to the nearest whole number of minor units.

In case of Post Purchase scenario, this value need not be provided and will internally be set as the sum of clearing amounts (installmentTransactions.clearingAmount). | | #### PlanFeeRatePercentage Schema Interest fee rate in percentage applied on Installment payment. + Percentage rate and is a non-negative value. + The percentage value is represented with two implicit decimals. (max 10000) Example: 250 specifies 2.5% + For calculations, the actual percentage value should be interpreted as follows: actualPercentageValue = ratePercentage / 100.00 | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | PlanFeeRatePercentage | integer | Interest fee rate in percentage applied on Installment payment. + Percentage rate and is a non-negative value. + The percentage value is represented with two implicit decimals. (max 10000) Example: 250 specifies 2.5% + For calculations, the actual percentage value should be interpreted as follows: actualPercentageValue = ratePercentage / 100.00 | | **Example**

#### PlanAcceptanceIdentifier Schema Visa-generated identifier for a plan acceptance | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | PlanAcceptanceIdentifier | string (uuid) | Visa-generated identifier for a plan acceptance | | **Example**

31e9f2b5-d90d-089e-67a5-1f533b02d301

#### TransactionInfoWithPartialRefund Schema Transaction information that includes the associated transaction and cancellation/refund details. When used in the response body, this field is provided when the refund/cancellation information is available. When used in the request body, this field is to be used for specifying a refund details(refund amount,reason,shipped status) to be used for refund . | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TransactionInfoWithPartialRefund | { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } & { **"splitTransactionRefunds"**: [ { **"status"**: string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED", **"refundAmount"**: long, **"refundReason"**: string, **"itemShippedStatus"**: string,
**Available values:** "SHIPPED", "NOT_SHIPPED",
**Default:** SHIPPED, **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } ], **"transactionRefundAmount"**: long } | Transaction information that includes the associated transaction and cancellation/refund details. When used in the response body, this field is provided when the refund/cancellation information is available. When used in the request body, this field is to be used for specifying a refund details(refund amount,reason,shipped status) to be used for refund . | | #### DeviceSoftwareVersion Schema Version associated with the client software (the software making oauth2 requests) + String that follows the versioning scheme, ".[.]" + Where the alphabet for major_version, minor_version, and patch_version is only digits. + The patch version is optional + Versions must me incremental sequences as comparisons might be done on them in order to apply distinct logic + For comparison purposes the following conversion is done + Remove the '.' separating the minor and patch versions, if any, from the string + Convert the string into a float number + The device clients are responsible for defining their own version numbers as long as they adhere to the scheme | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | DeviceSoftwareVersion | string | Version associated with the client software (the software making oauth2 requests) + String that follows the versioning scheme, ".[.]" + Where the alphabet for major_version, minor_version, and patch_version is only digits. + The patch version is optional + Versions must me incremental sequences as comparisons might be done on them in order to apply distinct logic + For comparison purposes the following conversion is done + Remove the '.' separating the minor and patch versions, if any, from the string + Convert the string into a float number + The device clients are responsible for defining their own version numbers as long as they adhere to the scheme | | **Example**

2.0.11

#### PaymentAccountReference Schema A Payment Account Reference (PAR) is a unique reference value associated with a specific card holder PAN. It identifies the card account, not just a card. PAR is a non-payment identifier that can be associated to PANs and tokens, as defined by EMVCo. PAR allows all participants in the payments chain to have a single, non-sensitive value assigned to a consumer. This value can be used in place of sensitive card holder identification fields, and transmitted across the payments ecosystem to facilitate card holder identification. PAR has a well-defined format (as per the Jan 2016 EMVCo documentation): - Fixed length of 29 characters - All Uppercase, Roman, & Alphanumeric values - 4-character BIN Controller ID assigned by EMVCo followed by a 25-character value | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | PaymentAccountReference | string | A Payment Account Reference (PAR) is a unique reference value associated with a specific card holder PAN. It identifies the card account, not just a card. PAR is a non-payment identifier that can be associated to PANs and tokens, as defined by EMVCo. PAR allows all participants in the payments chain to have a single, non-sensitive value assigned to a consumer. This value can be used in place of sensitive card holder identification fields, and transmitted across the payments ecosystem to facilitate card holder identification. PAR has a well-defined format (as per the Jan 2016 EMVCo documentation): - Fixed length of 29 characters - All Uppercase, Roman, & Alphanumeric values - 4-character BIN Controller ID assigned by EMVCo followed by a 25-character value | | **Example**

V0010013820238835225373131610

#### Amount Schema + All Amount fields use a representation in minor units only. For example, in Cents for USD currency + There are no fractional minor units; they are rounded to a whole number of minor units + The currency field contains the [number of minor units (per ISO 4217)](https://www.currency-iso.org/en/home/tables/table-a1.html). For example, “123112” in USD represents the amount, USD 1231.12. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | Amount | long | + All Amount fields use a representation in minor units only. For example, in Cents for USD currency + There are no fractional minor units; they are rounded to a whole number of minor units + The currency field contains the [number of minor units (per ISO 4217)](https://www.currency-iso.org/en/home/tables/table-a1.html). For example, “123112” in USD represents the amount, USD 1231.12. | | **Example**

#### RefundAmount Schema The amount used for partial or full cancellation of clearing. This field will be always populated when clearing is in PARTIALLY_REFUNDED or fully CANCELLED state. The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html)). If the currency is USD, “214010” is used for representing the amount, "$2,140.10". Note that there are no fractional minor units represented. They're rounded to the nearest whole number of minor units. When requested in API request from Merchant (During Purchase scenario): + In multi-currency scenario, this field should be populated in source currency. When returned in API response or callback notification (During Purchase scenario): + When returned to Merchant in multi-currency scenario, this field will be populated in source currency. + When returned to Issuer in multi-currency scenario, this field will be populated in Issuer's currency. When requested in API request from Issuer (Post Purchase scenario): + In multi-currency scenario, this field should be populated in Issuer's currency. When returned in API response or callback notification to Issuer (Post Purchase scenario): + In multi-currency scenario, this field will be populated in Issuer's currency. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | RefundAmount | long | The amount used for partial or full cancellation of clearing. This field will be always populated when clearing is in PARTIALLY_REFUNDED or fully CANCELLED state. The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html)). If the currency is USD, “214010” is used for representing the amount, "$2,140.10". Note that there are no fractional minor units represented. They're rounded to the nearest whole number of minor units. When requested in API request from Merchant (During Purchase scenario): + In multi-currency scenario, this field should be populated in source currency. When returned in API response or callback notification (During Purchase scenario): + When returned to Merchant in multi-currency scenario, this field will be populated in source currency. + When returned to Issuer in multi-currency scenario, this field will be populated in Issuer's currency. When requested in API request from Issuer (Post Purchase scenario): + In multi-currency scenario, this field should be populated in Issuer's currency. When returned in API response or callback notification to Issuer (Post Purchase scenario): + In multi-currency scenario, this field will be populated in Issuer's currency. | | #### TransactionRefundAmountInSourceCurrency Schema The amount (in source currency) used for partial or full cancellation of clearings associated with Visa ISO transaction. The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html)). If the currency is USD, “214010” is used for representing the amount, "$2,140.10". Note that there are no fractional minor units represented. They're rounded to the nearest whole number of minor units. When used in the HTTP request body for Visa Installment APIs + This field will be used to specify the refund amount to be split across the associated clearing within a transaction. + If this field is not provided then all clearing associated with the transaction will be fully cancelled based on the Transaction Amount. When returned in the HTTP response body or callback notifications, + This field is populated if provided by the merchant/seller in the request and represents the refund amount that was split across the associated clearing within a transaction. When returned in API response or callback notification to Issuer (During Purchase scenario): + In multi-currency scenario, this field will be populated in source currency. This field will not be returned to Issuer in Post Purchase scenario. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TransactionRefundAmountInSourceCurrency | long | The amount (in source currency) used for partial or full cancellation of clearings associated with Visa ISO transaction. The amount is represented in minor units. It is a numerical value in the minor units of the currency (Cents for USD, for example [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html)). If the currency is USD, “214010” is used for representing the amount, "$2,140.10". Note that there are no fractional minor units represented. They're rounded to the nearest whole number of minor units. When used in the HTTP request body for Visa Installment APIs + This field will be used to specify the refund amount to be split across the associated clearing within a transaction. + If this field is not provided then all clearing associated with the transaction will be fully cancelled based on the Transaction Amount. When returned in the HTTP response body or callback notifications, + This field is populated if provided by the merchant/seller in the request and represents the refund amount that was split across the associated clearing within a transaction. When returned in API response or callback notification to Issuer (During Purchase scenario): + In multi-currency scenario, this field will be populated in source currency. This field will not be returned to Issuer in Post Purchase scenario. | | #### BatchType Schema | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | BatchType | string,
**Available values:** "CARDHOLDER_ENROLLMENT", "CARDHOLDER_ENROLLMENT_UPDATE", "CARDHOLDER_ENROLLMENT_DELETE", "PLAN_ACCEPTANCE_IRREGULAR_PAYMENTS", "CANDIDATES" | | | **Example**

CANDIDATES

#### ErrorResponse Schema Standard error response body provided when there is an error. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | reason | string | API developers must use this field to drive their error handling logic
*Example:* `"invalidRequest"` | Yes | | status | integer | 3-digit HTTP Status Code
*Example:* `400` | No | | details | [ { **"reason"**: string, **"message"**: string, **"location"**: string } ] | Array of fields - Data validation errors should use this array to specify fields that failed validation using the location field | No | | message | string | Every error should have a human readable message describing the error. The message can very even for the same reason, thus providing additional details. API providers are free to change the message at any point of time. API clients should not use the message field to drive their business logic or to expose it directly to the consumers via UI or other means.
*Example:* `"Input parameters validation failed"` | No | #### BaseInstallmentTransaction Schema This structure represents the fields required for identifying a Clearing. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | clearingAmount | long | Clearing amount for the transaction. This field will always be populated by Visa Installments when clearing data is available. This field is also used to create Plan Acceptance for a clearing in Post Purchase scenario. When returned in API response or callback notification (During Purchase scenario): + When returned to Merchant in multi-currency scenario, this field will be populated in source currency. + When returned to Issuer in multi-currency scenario, this field will be populated in Issuer's currency. When requested in API request from Issuer (Post Purchase scenario): + This field must always be provided. + In multi-currency scenario, this field should be populated in Issuer's currency. When returned in API response or callback notification to Issuer (Post Purchase scenario): + In multi-currency scenario, this field will be populated in Issuer's currency. | No | | clearingDateTime | dateTime | Clearing date and time as set by the card network. This is the information in the clearing data sent to the issuers by the card network. This field will be always populated by Visa Installments when clearing data is available. + When returned in the HTTP response body or callback notifications,the time value will be defaulted to '00:00:00Z' when only clearing date is available from source system. + When used in the HTTP request body of an API request to Visa Installments, the value must conform to date-time format.
*Example:* `"2021-01-17T00:00:00Z"` | No | | settlementCurrency | string | Always required when clearingAmount is specified. Currency of clearingAmount and refundAmount. Currency code in [ISO 4217 format](https://www.iban.com/currency-codes). | No | | ~~clearingSequenceNumber~~ | string | This field is deprecated and only supported for clients currently using it. New clients must not use this field. Clearing sequence number, provided for multi-clearing scenarios - where a single transaction corresponds to multiple clearings. This field is used to identify the particular clearings associated with a plan acceptance when a partial transaction is used to associate with a plan acceptance. If this field is not provided, a sequence number is generated by Visa Installments. When used in the response for plan acceptances associated with a partial transactions, this field is populated. This field will be always populated by Visa Installments when clearing data is available. When used in the request body for Visa Installment APIs it is highly recommended for the Visa partners to pass this in, if available. Otherwise, it will be generated by Visa Installments.
*Example:* `"2"`
**Deprecated** | No | | acquirerReferenceNumber | string | Acquirer Reference Number (ARN) is a 23-digit identification number associated with every draft and voucher. It consists of a Format Code, BASE Identification Number (BIN), Capture Date, Film Locator, and Check Digit. The ARN must be unique for each clearing.
*Example:* `"15524351474316171567231"` | No | #### TransactionAmount Schema Conditional Mandatory Field :
The amount used in the Visa ISO transaction authorization and is represented as numerical value in the minor units of the currency (Cents for USD, for example [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html)). When requested in API request from Merchant (During Purchase scenario): + In multi-currency scenario, this field should be populated in source currency. When returned in API response or callback notification (During Purchase scenario): + When returned to Merchant in multi-currency scenario, this field will be populated in source currency. + When returned to Issuer in multi-currency scenario, this field will be populated in Issuer's currency. When requested in API request from Issuer (Post Purchase scenario): + This field need not be provided and will internally be set as the sum of clearing amounts (installmentTransactions.clearingAmount). When returned in API response or callback notification to Issuer (Post Purchase scenario): + In multi-currency scenario, this field will be populated in Issuer's currency. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TransactionAmount | long | Conditional Mandatory Field :
The amount used in the Visa ISO transaction authorization and is represented as numerical value in the minor units of the currency (Cents for USD, for example [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html)). When requested in API request from Merchant (During Purchase scenario): + In multi-currency scenario, this field should be populated in source currency. When returned in API response or callback notification (During Purchase scenario): + When returned to Merchant in multi-currency scenario, this field will be populated in source currency. + When returned to Issuer in multi-currency scenario, this field will be populated in Issuer's currency. When requested in API request from Issuer (Post Purchase scenario): + This field need not be provided and will internally be set as the sum of clearing amounts (installmentTransactions.clearingAmount). When returned in API response or callback notification to Issuer (Post Purchase scenario): + In multi-currency scenario, this field will be populated in Issuer's currency. | | #### BaseOnboardingInformation Schema Details required to Onboard a client associated with a Partner | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | city | string | Name of the merchant's city
*Example:* `"Foster City"` | No | | phone | string | Client's primary phone number. Client's primary phone number and the format is based on the countryCode field

countryCode	MinLength	MaxLength	Format
AU (Australia) CA (Canada) US (United States of America)	10	16	Allowed characters are digits, a hyphen, an open parenthesis, a close parenthesis, a dot, a plus sign, or whitespace.Example:+(001)-97444108
MY (Malaysia) MX (Mexico) NZ (New Zealand)	3	15	Only digits are allowed.Example:0097444100888
Other Countries	1	16	Only digits are allowed.Example:0097444100888

countryCode	Description
AU (Australia), CA (Canada), US (United States of America)	Must be a subdivision code (up to three characters) defined in ISO-3166-2. e.g. NSW (AU), QC (CA), DE (US)

*Example:* `"QC"` | No | | primaryContactEmail | string | Email address of Client's primary contact. This field is optional. Partners may choose not to provide the email address of their indirect merchants.
*Example:* `"test@xyz.com"` | No | | primaryContactLastName | string | Surname of Client's primary contact person. Alphabetic or the following characters: spaces, ' (single quote), ` (back tick), ~ (tilde), " (double quote), . (period), and - (hyphen)
*Example:* `"Smith"` | No | | onBehalfOfRelationships | [ { **"relationshipType"**: string,
**Available values:** "OBO_FUNDING_FEE_COLLECTOR", "OBO_SERVICE_FEE_COLLECTOR", **"partnerReferenceID"**: string, **"onBehalfOfReferenceID"**: string } ] | This field is used to specify third-party partners that perform operation on-behalf-of the client/merchant being onboarded. | No | | primaryContactFirstName | string | First name of Client's primary contact person. Alphabetic or the following characters: spaces, ' (single quote), ` (back tick), ~ (tilde), " (double quote), . (period), and - (hyphen)
*Example:* `"John"` | No | | partnerMerchantReferenceID | string | Usually, this reference ID is assigned by the Partner but in cases where not provided when onboarding the Merchant, this value will be generated by Visa and provided to the Partner. It is used by Visa for enforcing authorization (so that one Merchant's plan acceptance is not accessed/modified by an unauthorized merchant/partner), risk assessment and for instrumentation. It is also used to serve bilateral plan agreements between a Seller and Issuer. In the future, it can be used to specify merchant-specific filters for installment plans. - When provided in cancellation or search, this ID is used to match the plan acceptance and enforce authorization. - When provided in plan selection (plan acceptance creation) API, it is used to later for authorization checks on cancel or search plan acceptances. - When provided in plan match API, it is used for filter bilateral plans & instrumentation/reporting purposes.
*Example:* `"98243463"` | No | #### CardHolderSearchResultItem Schema | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | productType | string,
**Available values:** "CREDIT", "DEBIT" | Product Type of the PANs enrolled in this Batch.If the Product type is not provided in request the PANs enrolled will be considered as Credit by default. | No | | encAccountNumber | byte | JWE - This is a URL-safe base64-encoded string that represents the encrypted payload for AccountNumber. The format is the JSON Web Encryption using asymmetric/symmetric key material made available at time of onboarding. It is a standard JWT with a single custom AccountNumber claim, “accountNumber” that contains the card number/PAN. Visa uses JSON Web Encryption (JWE) to encrypt sensitive information in APIs. For more info, see "Encryption (JWE) Details". | Yes | | enrollmentStatus | string,
**Available values:** "ENROLLED", "NOT_ENROLLED", "ERROR" | Defined the enrollment status for each enrollment record. "NOT_ENROLLED" means the card holder is currently not enrolled or enrollment will end within 24 hours of enrollmentEndDate. "ERROR" means the card holder was not enrolled due to an error.
*Enum:* `"ENROLLED"`, `"NOT_ENROLLED"`, `"ERROR"`
*Example:* `"ENROLLED"` | No | | enrollmentEndDate | dateTime | Enrollment end date - Returned if provided during enrollment. | No | | enrollmentStartDate | dateTime | Enrollment date of the latest Enrollment Event | No | | enrollmentTimestamp | dateTime | Timestamp of cardholder enrollment.
*Example:* `"2021-01-17T16:15:21Z"` | Yes | | vEnrollmentProfileID | string (uuid) | Visa-generated Enrollment Profile Identifier
*Example:* `"278a6873-9dc2-b466-284c-1d10ee797301"` | Yes | | lastEnrollmentEndDate | dateTime | Enrollment end date of the latest UnEnrollment Event | No | | extendedEligibilityEndDate | dateTime | Extended Eligibility end date - Returned if provided during enrollment. | No | #### TransactionInfoWithBasicInstallmentTransactionDetails Schema Transaction information that includes the associated transaction and multiple clearing info. When used in the response body, this field is provided when the clearing information is available. When used in request body, this object will be used to specify the required transaction information used for plan acceptance creation. It is highly recommended for the Visa partners to populate all the available fields in the transaction information during plan acceptance creation. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TransactionInfoWithBasicInstallmentTransactionDetails | { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } & { **"installmentTransactions"**: [ { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } ] } | Transaction information that includes the associated transaction and multiple clearing info. When used in the response body, this field is provided when the clearing information is available. When used in request body, this object will be used to specify the required transaction information used for plan acceptance creation. It is highly recommended for the Visa partners to populate all the available fields in the transaction information during plan acceptance creation. | | #### TotalRecurringFees Schema Total recurring fees charged to the consumer for this Installment plan. This fee corresponds to the fee type CONSUMER. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TotalRecurringFees | long | Total recurring fees charged to the consumer for this Installment plan. This fee corresponds to the fee type CONSUMER. The amount is represented in minor units. It is a numerical value in the [minor units](https://www.currency-iso.org/en/home/tables/table-a1.html) of the currency, such as Cents for USD. If the currency is USD, “13400” is used for representing the amount, "$134.00". Note that there are no fractional minor units represented. They're rounded to the whole minor units. | | **Example**

#### DevicePreferredName Schema Preferred name of the Payment Terminal | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | DevicePreferredName | string | Preferred name of the Payment Terminal | | **Example**

BNPL TERMINAL

#### TransactionInfoWithRefundInstallmentTransactionForLender Schema Transaction information that includes the associated transaction along multiple clearing info and refund details. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | TransactionInfoWithRefundInstallmentTransactionForLender | { **"authCode"**: string, **"currency"**: string, **"vTransactionID"**: string, **"externalTransactionRef"**: string } & { **"dateTime"**: dateTime, **"transactionAmount"**: long } & { **"sourceCurrency"**: string, **"installmentTransactions"**: [ { **"status"**: string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } & { **"sourceCurrency"**: string, **"clearingAmountInSourceCurrency"**: long } & { **"refundAmount"**: long, **"lastRefundDateTime"**: dateTime, **"refundAmountInSourceCurrency"**: long } ], **"transactionRefundAmount"**: long, **"transactionAmountInSourceCurrency"**: long, **"transactionRefundAmountInSourceCurrency"**: long } | Transaction information that includes the associated transaction along multiple clearing info and refund details. | | #### BaseBilateralPlan Schema | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | fees | [ { **"type"**: string,
**Available values:** "ACQUIRER_TO_ISSUER", "CONSUMER", "CONSUMER_UPFRONT", "ISSUER_TO_ACQUIRER", "APR", **"amount"**: long, **"ratePercentage"**: integer } ] | Fees for Plan | No | | name | string | Name of the installment plan. This may not be unique.
*Example:* `"The Market Plan"` | Yes | | type | string,
**Available values:** "BI_LATERAL" | Type of the installment plan as configured in Visa Developer Center/Portal by the issuer. + BI_LATERAL

Installment Plan Type	Party Responsible for Installment Funding Fees	Description
`BI_LATERAL`	Dictated by the `fundedBy` value as the responsible party can be any of the following: Merchant Participant Seller Consumer Hybrid Arrangement where two parties are involved	Applies an Installment Funding Fee different from Market Rate Installment Funding Fee. This Installment Funding Fee is agreed to between an Issuer and a Merchant Participant pursuant to a written agreement between the Merchant Participant and the Issuer. These Installment Plans are available only to specific Merchant Participants which have a Bilateral Plan with the Issuer pursuant to an agreement with the Issuer.

*Enum:* `"BI_LATERAL"`
*Example:* `"BI_LATERAL"` | Yes | | vPlanID | string (uuid) | Visa-generated identifier for an Installment plan
*Example:* `"9d16a09e-3812-4ce3-a258-9981cc13a1f3"` | Yes | | currency | string | Plan Currency. Currency code in [ISO 4217 format](https://www.iban.com/currency-codes) | No | | fundedBy | [ string,
**Available values:** "CONSUMER", "MERCHANT" ] | Party responsible for Installment Funding Fees of this plan. | Yes | | issuerName | string | Name of the Issuer created this Plan
*Example:* `"Bank of VI"` | No | | vPlanIDRef | string | A Visa-generated, alphanumeric, unique, and short human-readable friendly name for Installment Plan.This identifier is called Plan Registration System Identifier in Auth and Clearing messages. Reference - Field 104 in Auth.Base II TCR D Position 43-52.SMS Raw Data Financial Transaction record 5 -V22226.
*Example:* `"A123459876"` | Yes | | promotionInfo | { **"promotionID"**: string, **"promotionCode"**: string } | This is the promotion information shared between the Issuer and Seller. | No | | termsAndConditions | [ { **"url"**: string, **"text"**: string, **"version"**: integer, **"longText"**: string, **"languageCode"**: string } ] | Plan terms and conditions as setup by Issuers in Plan configuration. There may be one terms and conditions per language. If there is only one setup, then there will be only one item in the array. | Yes | | effectiveDateRanges | [ { **"endDate"**: date, **"startDate"**: date } ] | Effective Date ranges of Bilateral Plan | Yes | | planBilateralStatus | string,
**Available values:** "ACTIVE", "INACTIVE", "PENDING" | Indicates if the Bilateral plan has been opted in by the Seller. This value must be always provided for Bilateral plans and is not applicable for other type of plans + "PENDING" - Bilateral Plan has not yet been opted in by Seller + "ACTIVE" - Bilateral Plan has been opted in by/for Seller + "INACTIVE" - Bilateral Plan has been opted out by/for Seller
*Enum:* `"ACTIVE"`, `"INACTIVE"`, `"PENDING"`
*Example:* `"ACTIVE"` | No | | installmentFrequency | string,
**Available values:** "WEEKLY", "BIWEEKLY", "MONTHLY", "BIMONTHLY" | Supported Tenure Types for a plan.
*Enum:* `"WEEKLY"`, `"BIWEEKLY"`, `"MONTHLY"`, `"BIMONTHLY"`
*Example:* `"WEEKLY"` | Yes | | numberOfInstallments | number (integer) | Maximum number of installments that can be in the Plan Acceptance created from this plan.
*Example:* `10` | Yes | | transactionAmountRanges | [ { **"maximumTransactionAmount"**: long, **"minimumTransactionAmount"**: long } ] | Transaction Amount Ranges | Yes | #### MerchantPostalCode Schema Postal/Zip code of the merchant | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | MerchantPostalCode | string | Postal/Zip code of the merchant | | **Example**

#### NonVisaTransactionPageContentArrayItem Schema Results of the Non-Visa transaction save action showing the errors, if any. + If there were any errors, then the errorResponse element must be present to describe the error. + If the transaction was successfully saved, then there will be no errorResponse element | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | type | string,
**Available values:** "AUTH", "AUTH_REVERSAL", "CS_SALES_DRAFT", "CS_CREDIT_VOUCHER", "CS_CASH_DISBURSEMENT", "CS_SALES_DRAFT_REVERSAL", "CS_CREDIT_VOUCHER_REVERAL", "CS_CASH_DISBURSEMENT_REVERSAL" | ISO Transaction or Settlement message type + AUTH - ISO 0100/0110 - Authorization request/response data for purchase, cash, balance inquiry, return of goods + AUTH_REVERSAL - ISO 400/410 - ISO Reversal of an Authorization Request. Reversals are not the same as a merchandise return, but instead are used to reverse approved authorizations or financial transactions which are not completed due to unintended transactions. For example, when a merchant put the wrong dollar amount in an auth, the reversal ‘undoes’ it so that another auth message can be sent with the correct amount. + CS_SALES_DRAFT - TC 05 – Original purchase or representment; or dispute response financial + CS_CREDIT_VOUCHER - TC 06 – Original credit voucher or representment or dispute response financial; or original credit or representment + CS_CASH_DISBURSEMENT - TC 07 – Original cash disbursement/withdrawal or representment or dispute response financial + CS_SALES_DRAFT_REVERSAL - TC 25 – Reversal of an original purchase or representment or dispute response financial transaction + CS_CREDIT_VOUCHER_REVERAL - TC 26 – Reversal of an original credit voucher or representment or dispute response financial transaction; or original credit or representment transaction. + CS_CASH_DISBURSEMENT_REVERSAL - TC 27 – Reversal of an original cash disbursement/withdrawal transaction
*Enum:* `"AUTH"`, `"AUTH_REVERSAL"`, `"CS_SALES_DRAFT"`, `"CS_CREDIT_VOUCHER"`, `"CS_CASH_DISBURSEMENT"`, `"CS_SALES_DRAFT_REVERSAL"`, `"CS_CREDIT_VOUCHER_REVERAL"`, `"CS_CASH_DISBURSEMENT_REVERSAL"` | Yes | | authCode | string | ISO transaction Auth Code (alphanumeric). This Field 38 in ISO 8583 contains the response identification assigned by the authorizing institution.
*Example:* `"05754C"` | Yes | | cardBrand | string,
**Available values:** "VISA", "NON_VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "JCB", "UNIONPAY", "DINERSCLUB",
**Default:** VISA | The card network brand. When no value is set (or the field is not returned), it should be treated as VISA.
*Enum:* `"VISA"`, `"NON_VISA"`, `"MASTERCARD"`, `"AMERICAN_EXPRESS"`, `"DISCOVER"`, `"JCB"`, `"UNIONPAY"`, `"DINERSCLUB"` | Yes | | errorResponse | { **"reason"**: string, **"status"**: integer, **"details"**: [ { **"reason"**: string, **"message"**: string, **"location"**: string } ], **"message"**: string } | Standard Error Response Body - Provided only when this transaction data has errors and was not successfully saved. | No | | vPlanAcceptanceID | string (uuid) | Visa-generated identifier for a plan acceptance
*Example:* `"31e9f2b5-d90d-089e-67a5-1f533b02d301"` | Yes | | paymentAccountReference | string | A Payment Account Reference (PAR) is a unique reference value associated with a specific card holder PAN. It identifies the card account, not just a card. PAR is a non-payment identifier that can be associated to PANs and tokens, as defined by EMVCo. PAR allows all participants in the payments chain to have a single, non-sensitive value assigned to a consumer. This value can be used in place of sensitive card holder identification fields, and transmitted across the payments ecosystem to facilitate card holder identification. PAR has a well-defined format (as per the Jan 2016 EMVCo documentation): - Fixed length of 29 characters - All Uppercase, Roman, & Alphanumeric values - 4-character BIN Controller ID assigned by EMVCo followed by a 25-character value
*Example:* `"V0010013820238835225373131610"` | Yes | #### PlanStartDate Schema Effective Start date of the Plan.Plan start date as set by the Issuer. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | PlanStartDate | date | Effective Start date of the Plan.Plan start date as set by the Issuer. | | #### InstallmentTransactionForResponseForLender Schema Associated transaction for a given plan acceptance. A plan acceptance can be created with a single ISO transaction or many ISO transactions, or a part of an ISO transaction (one clearing out of many, for example). Represents the schedule of payments corresponding to a plan acceptance. Clearing data will be always included when available.
NOTES: + When returned in the HTTP response body or callback notifications, all of the fields below are required (i.e., al fields are populated when used in response body). + When used in the HTTP request body of an API request to Visa Installments, the required fields must be provided. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | InstallmentTransactionForResponseForLender | { **"status"**: string,
**Available values:** "CONFIRMED", "CANCELLED", "PENDING_CONFIRMATION", "PENDING_CANCELLATION", "PARTIALLY_REFUNDED", **"vInstallmentTransactionID"**: string (uuid) } & { **"clearingAmount"**: long, **"clearingDateTime"**: dateTime, **"settlementCurrency"**: string, **"clearingSequenceNumber"**: string, **"acquirerReferenceNumber"**: string } & { **"sourceCurrency"**: string, **"clearingAmountInSourceCurrency"**: long } | Associated transaction for a given plan acceptance. A plan acceptance can be created with a single ISO transaction or many ISO transactions, or a part of an ISO transaction (one clearing out of many, for example). Represents the schedule of payments corresponding to a plan acceptance. Clearing data will be always included when available.
NOTES: + When returned in the HTTP response body or callback notifications, all of the fields below are required (i.e., al fields are populated when used in response body). + When used in the HTTP request body of an API request to Visa Installments, the required fields must be provided. | | #### PartnerMerchantReferenceID Schema Usually, this reference ID is assigned by the Partner but in cases where not provided when onboarding the Merchant, this value will be generated by Visa and provided to the Partner. It is used by Visa for enforcing authorization (so that one Merchant's plan acceptance is not accessed/modified by an unauthorized merchant/partner), risk assessment and for instrumentation. It is also used to serve bilateral plan agreements between a Seller and Issuer. In the future, it can be used to specify merchant-specific filters for installment plans. - When provided in cancellation or search, this ID is used to match the plan acceptance and enforce authorization. - When provided in plan selection (plan acceptance creation) API, it is used to later for authorization checks on cancel or search plan acceptances. - When provided in plan match API, it is used for filter bilateral plans & instrumentation/reporting purposes. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | PartnerMerchantReferenceID | string | Usually, this reference ID is assigned by the Partner but in cases where not provided when onboarding the Merchant, this value will be generated by Visa and provided to the Partner. It is used by Visa for enforcing authorization (so that one Merchant's plan acceptance is not accessed/modified by an unauthorized merchant/partner), risk assessment and for instrumentation. It is also used to serve bilateral plan agreements between a Seller and Issuer. In the future, it can be used to specify merchant-specific filters for installment plans. - When provided in cancellation or search, this ID is used to match the plan acceptance and enforce authorization. - When provided in plan selection (plan acceptance creation) API, it is used to later for authorization checks on cancel or search plan acceptances. - When provided in plan match API, it is used for filter bilateral plans & instrumentation/reporting purposes. | | **Example**

98243463

#### Locale Schema Locale in in [IETF BCP 47 format](https://tools.ietf.org/html/bcp47) The BCP 47 locale format is --