swagger: '2.0' info: title: Mastercard Bill Payment Validator Account Opening Plans API description: This service is provided on behalf of the Mastercard Remote Payment and Presentment (RPPS) Bill Payment Processing Network, which supports consumer to business "push" bill payments (i.e. those which are not funded by debit/credit card transactions) in the U.S. version: '1.0' x-artifactId: billpay-api contact: name: Bill Pay Development Support email: Bill_Pay_Development_Support@mastercard.com host: sandbox.api.mastercard.com basePath: /billpayAPI/v1 schemes: - https consumes: - application/json produces: - application/json tags: - name: Plans paths: /plans: post: tags: - Plans description: 'When a cardholder chooses one of the installment offers previously shown through the Offer Presentment API, customers need to send the details of the selected offer, including the PAN, transaction information, merchant details, and offer specifics, without any changes. Mastercard then validates this data against the presented offer to ensure its integrity and provides a success or failure response If the API processing is successful, it returns an HTTP status code of 201, a status of CREATED, and a unique Plan Identifier. In this scenario, customers can inform the cardholder that the installment offer has been processed successfully. However, if the API processing fails for some reason, it returns a corresponding HTTP status code and the customer should inform the cardholder about the failure in paying with installments. - This endpoint requires partial request payload encryption to encrypt sensitive data, merchant name and consumers primary account number as part of sensitiveData field. Please refer to request specification for more details. The encryption needs to be performed using [JWE payload encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#jwe-encryption). Please refer to the [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) sections for implementation details.' summary: Notify Mastercard when a consumer chooses a previously presented offer, which is henceforth called as an Installment Plan. x-mastercard-api-encrypted: true operationId: savePlan parameters: - $ref: '#/components/parameters/CorrelationIdHeaderParameter' requestBody: $ref: '#/components/requestBodies/PlanPostRequestBody' responses: '201': $ref: '#/components/responses/PlanCreated' '400': $ref: '#/components/responses/PlanCreateInvalidInput' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' /plans/{plan_id}: get: tags: - Plans summary: Retrieves Buy Now, Pay Later installment plan. description: This operation returns a BNPL installment plan based on the selected plan ID provided in the request. The API response contains encrypted values of the consumer's email and phone, and the issuer needs to decrypt the response using the Mastercard client encryption key. operationId: getPlan parameters: - $ref: '#/components/parameters/plan_id' responses: '200': $ref: '#/components/responses/InstallmentPlan' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' components: responses: UnauthorizedError: content: application/json: example: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: unauthorized Description: Unauthorized to access the resource. Details: None Recoverable: false schema: $ref: '#/components/schemas/ErrorWrapper' description: 'Unauthorized: Authentication is required and has failed or has not been provided.' MethodNotAllowed: description: 'Method Not Allowed: Method used to request the resource is not allowed.' content: application/json: schema: $ref: '#/components/schemas/ErrorWrapper' examples: MethodNotAllowed: $ref: '#/components/examples/MethodNotAllowed' BadRequestError: description: This response code is returned when a request is invalid, or data in the request is not valid. content: application/json: schema: $ref: '#/components/schemas/ErrorWrapper' examples: InvalidCardProductError: $ref: '#/components/examples/InvalidCardProductError' InvalidFieldFormat: $ref: '#/components/examples/InvalidFieldFormat' InvalidFieldLength: $ref: '#/components/examples/InvalidFieldLength' InvalidFieldValue: $ref: '#/components/examples/InvalidFieldValue' MissingRequiredField: $ref: '#/components/examples/MissingRequiredField' Unauthorized: description: Unauthorized to access the resource. headers: Correlation-Id: $ref: '#/components/headers/Correlation-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorWrapper' examples: Unauthorized: $ref: '#/components/examples/Unauthorized' PlanCreateInvalidInput: description: Invalid Input while processing Plan API. content: application/json: schema: $ref: '#/components/schemas/ErrorWrapper' examples: TransactionAmountMisMatch: $ref: '#/components/examples/TransactionAmountMisMatch' TransactionDateMisMatch: $ref: '#/components/examples/TransactionDateMisMatch' InvalidTransactionCurrency: $ref: '#/components/examples/InvalidTransactionCurrency' BlankPAN: $ref: '#/components/examples/BlankPAN' NonNumericPAN: $ref: '#/components/examples/NonNumericPAN' InvalidPANLength: $ref: '#/components/examples/InvalidPANLength' InvalidTokenPAN: $ref: '#/components/examples/InvalidTokenPAN' PANMisMatch: $ref: '#/components/examples/PANMisMatch' InvalidLengthMerchantName: $ref: '#/components/examples/InvalidLengthMerchantName' InvalidLengthMerchantURL: $ref: '#/components/examples/InvalidLengthMerchantURL' InvalidMerchantURL: $ref: '#/components/examples/InvalidMerchantURL' InvalidAcquirerId: $ref: '#/components/examples/InvalidAcquirerId' InvalidLengthAcquirerId: $ref: '#/components/examples/InvalidLengthAcquirerId' InvalidCountryCode: $ref: '#/components/examples/InvalidCountryCode' InvalidLengthMcc: $ref: '#/components/examples/InvalidLengthMcc' InvalidLengthMerchantId: $ref: '#/components/examples/InvalidLengthMerchantId' InvalidMerchantId: $ref: '#/components/examples/InvalidMerchantId' InvalidAmountType: $ref: '#/components/examples/InvalidAmountType' InvalidLengthSTAN: $ref: '#/components/examples/InvalidLengthSTAN' NonNumericSTAN: $ref: '#/components/examples/NonNumericSTAN' InvalidLengthRRN: $ref: '#/components/examples/InvalidLengthRRN' NonNumericRRN: $ref: '#/components/examples/NonNumericRRN' InvalidLengthAuthCode: $ref: '#/components/examples/InvalidLengthAuthCode' NonNumericAuthCode: $ref: '#/components/examples/NonNumericAuthCode' InvalidTransactionLinkId: $ref: '#/components/examples/InvalidTransactionLinkId' InvalidTransmissionDateTime: $ref: '#/components/examples/InvalidTransmissionDateTime' InvalidLocalTransactionDateTime: $ref: '#/components/examples/InvalidLocalTransactionDateTime' InvalidFrequency: $ref: '#/components/examples/InvalidFrequency' InvalidPresentedOffersDSP: $ref: '#/components/examples/InvalidPresentedOffersDSP' InvalidPresentedOffersDRNG: $ref: '#/components/examples/InvalidPresentedOffersDRNG' InstallmentPlan: content: application/json: examples: Initiated Plan with Consumer Selected Offer: $ref: '#/components/examples/InitiatedPlanOfferSelected' Initiated Plan with Lender Selected Offer: $ref: '#/components/examples/InitiatedPlanProviderSelected' Approved Plan: $ref: '#/components/examples/ApprovedPlan' Rejected Plan: $ref: '#/components/examples/RejectedPlan' schema: $ref: '#/components/schemas/InstallmentPlan' description: 'The plan is found and returned based on plan ID. ' ForbiddenError: description: This response code is returned when API or resource access is not approved for the client. content: application/json: schema: $ref: '#/components/schemas/ErrorWrapper' examples: ForbiddenError: $ref: '#/components/examples/ForbiddenError' NotFound: description: Not Found. headers: Correlation-Id: $ref: '#/components/headers/Correlation-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorWrapper' examples: NotFound: $ref: '#/components/examples/NotFound' PlanCreated: headers: Location: schema: type: string description: The URL that the client should poll for a response status. Refer to GET /plans/{plan_id}. content: application/json: examples: Carded Installment Plan: description: This example shows a successful response for 'Mastercard Installments Payment Services product which includes planID & status. value: planId: 3d56f5a7-db48-41f0-875e-30920e8465f3 status: CREATED schema: $ref: '#/components/schemas/CreatedInstallmentPlan' description: A new plan is created. examples: InitiatedPlanProviderSelected: description: This example shows no offer selection by a consumer during checkout. Transaction Offers and ProviderId are specified instead. Lenders can view the consumer information, merchant information, and transaction information to determine installment eligibility. value: consumer: email: doe.jane@example.com isdCode: '1' mobile: '5551231234' merchant: acceptor: '100234' country: USA mcc: '1711' name: Decor shop planId: 3d56f5a7-db48-41f0-875e-30920e8465f3 providerId: 218b9962-1355-44e4-8a16-f911363fd849 status: CREATED transaction: amount: 400.11 currency: USD transactionOffers: - offerId: '12345678' - offerId: '87654321' PANMisMatch: description: PAN does not match with Offer. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: pan.match Description: Provided PAN does not match with offer. Recoverable: false Details: PAN does not match with Offer. ApprovedPlan: description: This example shows a consumer-selected plan that has been approved by a lender. The lender can view the status of the plan after the approval. value: consumer: email: doe.jane@example.com isdCode: '1' mobile: '5551231234' merchant: acceptor: '100234' country: USA mcc: '1711' name: Decor shop offerId: '24092019' transactionOffers: - offerId: '24092019' - offerId: '87654321' planId: 3d56f5a7-db48-41f0-875e-30920e8465f3 planInstallmentInformation: apr: 1.92 currency: USD frequency: 15DAYS installmentAmount: 166.79 installmentFee: 0 tenure: 3 totalAmount: 500.37 providerId: 218b9962-1355-44e4-8a16-f911363fd849 scheduledRepayments: - amount: 166.79 dueDate: '2022-05-30' installmentNumber: 1 - amount: 166.79 dueDate: '2022-06-13' installmentNumber: 2 - amount: 166.79 dueDate: '2022-06-27' installmentNumber: 3 status: APPROVED transaction: amount: 400.11 currency: USD BlankPAN: description: Blank PAN sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: PAN is present and is blank or null. Recoverable: false Details: PAN cannot blank or empty. TransactionDateMisMatch: description: Provided transaction date does not match with Offer. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Provided transaction date does not match with offer. Recoverable: false Details: Mismatch in Transaction Date. InvalidFieldFormat: value: Errors: Error: - Source: Mastercard Installments API's ReasonCode: invalid.request.body.parameter Description: Field format or type is invalid Recoverable: false Details: '' MissingRequiredField: value: Errors: Error: - Source: Mastercard Installments API's ReasonCode: invalid.request.body.parameter Description: One or more of the required fields are missing Recoverable: false Details: '' InvalidLengthMerchantId: description: Incorrect Length for Merchant Id provided in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Incorrect Merchant Id length. Recoverable: false Details: Merchant id should not be lesser than 1 and greater than 15 in length. InvalidLengthSTAN: description: Incorrect length for STAN sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Incorrect STAN length. Recoverable: false Details: STAN should not be less than 1 or greater than 6. Please provide a valid STAN. InvalidTransmissionDateTime: description: Incorrect datetime format for TransmissionDateTime field sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Invalid datetime format. Recoverable: false Details: Transmission date and time should be in 'YYYY-MM-DD hh:mm:ss' format only. InvalidLocalTransactionDateTime: description: Incorrect datetime format for LocalTransactionDateTime field sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Invalid datetime format. Recoverable: false Details: Local Transaction date and time should be in 'YYYY-MM-DD hh:mm:ss' format only. NonNumericSTAN: description: Non-Numeric STAN sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Non-Numeric STAN. Recoverable: false Details: STAN should be numeric only. InitiatedPlanOfferSelected: description: This example shows a consumer selected plan during checkout when OfferId is available. Lenders can view the plan information consumer information, merchant information, and transaction information to determine installment eligibility. value: consumer: email: doe.jane@example.com isdCode: '1' mobile: '5551231234' merchant: acceptor: '100234' country: USA mcc: '1711' name: Decor shop offerId: '24092019' transactionOffers: - offerId: '24092019' - offerId: '87654321' planId: 3d56f5a7-db48-41f0-875e-30920e8465f3 planInstallmentInformation: apr: 1.92 currency: USD frequency: 15DAYS installmentAmount: 166.79 installmentFee: 0 tenure: 3 totalAmount: 500.37 providerId: 218b9962-1355-44e4-8a16-f911363fd849 scheduledRepayments: - amount: 166.79 dueDate: '2022-05-30' installmentNumber: 1 - amount: 166.79 dueDate: '2022-06-13' installmentNumber: 2 - amount: 166.79 dueDate: '2022-06-27' installmentNumber: 3 status: CREATED transaction: amount: 400.11 currency: USD InvalidLengthMerchantURL: description: Incorrect Merchant URL Length sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Incorrect Merchant URL length. Recoverable: false Details: Merchant URL should not be lesser that 1 and greater than 50 in length. TransactionAmountMisMatch: description: Provided transaction amount does not match with Offer. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Provided transaction amount does not match with offer. Recoverable: false Details: Mismatch in Transaction Amount. InvalidFieldLength: value: Errors: Error: - Source: Mastercard Installments API's ReasonCode: invalid.request.body.parameter Description: Field length is out of bound Recoverable: false Details: '' InvalidPresentedOffersDRNG: description: Presented offers is required, along with the offer ID, if the Provider Carded Product Use Case includes 'during purchase'. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Both OfferId and TransactionOffers must be present for this provider - Value must not be null Recoverable: false Details: Invalid input request for cardedInstallments. NonNumericPAN: description: Non Numeric PAN sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: PAN is present and is non numeric. Recoverable: false Details: PAN should be numeric only. InvalidLengthMcc: description: Incorrect Length for Mcc provided in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Merchant Category Code is invalid. Length must match 4. Recoverable: false Details: Merchant Category Code length must be 4. Unauthorized: description: Unauthorized to access the resource. value: Errors: Error: - Source: mci-installments-offers-eligibilities-api ReasonCode: unauthorized Description: Unauthorized to access the resource. Recoverable: false Details: '' NotFound: description: URI/Resource not found. value: Errors: Error: - Source: mci-installments-offers-eligibilities-api ReasonCode: not.found Description: URI/Resource not found. Recoverable: false Details: '' NonNumericRRN: description: Non-Numeric RRN sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Non-Numeric RRN. Recoverable: false Details: RRN should be numeric only. InvalidLengthAuthCode: description: Incorrect length for Auth Code sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Incorrect Auth Code length. Recoverable: false Details: Authorization code should be 6 digits in length. Please provide a valid Authorization code. RejectedPlan: description: This example shows a consumer-selected plan that has been declined by a lender. Lenders can view the status of the plan after the decline. value: consumer: email: doe.jane@example.com isdCode: '1' mobile: '5551231234' merchant: acceptor: '100234' country: USA mcc: '1711' name: Decor shop offerId: '24092019' transactionOffers: - offerId: '24092019' - offerId: '87654321' planId: 3d56f5a7-db48-41f0-875e-30920e8465f3 planInstallmentInformation: apr: 1.92 currency: USD frequency: 15DAYS installmentAmount: 166.79 installmentFee: 0 tenure: 3 totalAmount: 500.37 providerId: 218b9962-1355-44e4-8a16-f911363fd849 rejectReasonCode: LENDER_DRIVEN_REJECTION rejectReasonDetail: Customer's credit score is insufficient. scheduledRepayments: - amount: 166.79 dueDate: '2022-05-30' installmentNumber: 1 - amount: 166.79 dueDate: '2022-06-13' installmentNumber: 2 - amount: 166.79 dueDate: '2022-06-27' installmentNumber: 3 status: DECLINED transaction: amount: 400.11 currency: USD InvalidLengthRRN: description: Incorrect Length for RRN sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Incorrect RRN length. Recoverable: false Details: RRN should be 12 digits in length. Please provide a valid RRN. InvalidTransactionLinkId: description: Transaction link id is present and is more than 22 in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Invalid Transaction Link Id. Recoverable: false Details: Transaction link id should not be greater than 22. Please provide a valid transaction link id. InvalidPANLength: description: Incorrect length of PAN sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Incorrect PAN length. Recoverable: false Details: PAN should not be less than 11 and greater than 19 in length. Please provide a valid PAN. InvalidMerchantId: description: Merchant Id in request is invalid. value: Errors: Error: - Source: mci-installments-offers-eligibilities-api ReasonCode: merchant.merchantId Description: size must be between 1 and 15 Recoverable: false Details: '' InvalidMerchantURL: description: Merchant URL in request is invalid. value: Errors: Error: - Source: mci-installments-offers-eligibilities-api ReasonCode: merchant.url Description: size must be between 1 and 50 Recoverable: false Details: '' InvalidTokenPAN: description: Invalid Token PAN sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Detokenization failed due to incorrect DPAN. Recoverable: false Details: PAN provided is invalid. InvalidLengthMerchantName: description: Incorrect Merchant Name Length sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Merchant Name validation failed-Value has incorrect length. Recoverable: false Details: Merchant name should not be greater than 100 in length. InvalidTransactionCurrency: description: Provided transaction currency is not valid. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Currency Not Supported. Recoverable: false Details: Invalid transaction currency. NonNumericAuthCode: description: Non-Numeric Auth Code value sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Invalid Auth Code. Recoverable: false Details: . InvalidAcquirerId: description: Acquirer Id in request is invalid. value: Errors: Error: - Source: mci-installments-offers-eligibilities-api ReasonCode: merchant.acquirerId Description: size must be between 1 and 6 Recoverable: false Details: '' InvalidFrequency: description: Invalid frequency sent in the Plan API request for Installments on Cards. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Invalid frequency - 15DAYS. Recoverable: false Details: Frequency not valid for Installments on Card. InvalidLengthAcquirerId: description: Incorrect Length for Acquirer Id provided in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Incorrect Acquirer Id length. Recoverable: false Details: Acquirer Id should not be less than 1 and greater than 6 in length. Please provide a valid Acquirer Id. MethodNotAllowed: value: Errors: Error: - Source: Mastercard Installments API's ReasonCode: method.not.allowed Description: Method is not allowed Recoverable: false InvalidCardProductError: value: Errors: Error: - Source: Mastercard Installments API's ReasonCode: invalid.request.parameter Description: Product SPP is not available for the IND country Recoverable: false Details: '' ForbiddenError: value: Errors: Error: - Source: Mastercard Installments API's ReasonCode: forbidden Description: Your account is not approved to access the API or resource, kindly contact your Mastercard associate to get approval. Recoverable: false Details: '' InvalidFieldValue: value: Errors: Error: - Source: Mastercard Installments API's ReasonCode: invalid.request.body.parameter Description: Value doesn't exist / doesn't meet specified range Recoverable: false Details: '' InvalidCountryCode: description: Provided Country Code in request is invalid value: Errors: Error: - Source: mci-installments-offers-eligibilities-api ReasonCode: invalid.request.parameter Description: Country Code Not Supported Recoverable: false Details: '' InvalidAmountType: description: Incorrect value for Amount Type field sent in the Plan API request for **Installments on Cards**. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Incorrect value for Amount Type. Recoverable: false Details: Amount type must be 'PURCHASE' OR 'FINAL'. InvalidPresentedOffersDSP: description: Presented offers is required, along with the offer ID, if the client is classified as a distribution partner. value: Errors: Error: - Source: mci-installment-bnpl-plans-api ReasonCode: invalid.request.parameter Description: Both OfferId and TransactionOffers must be present for this client - Value must not be null Recoverable: false Details: Invalid input request for cardedInstallments. schemas: PlanIdField: type: string format: uuid description: A unique identifier assigned to an installment plan. example: 3d56f5a7-db48-41f0-875e-30920e8465f3 maxLength: 36 minLength: 36 SensitiveDataField: type: object description: "Mandatory for Carded Installments\n - Plain payload which contains Consumer Primary Account Number in encrypted format, refer example 'Carded Installments Offers Request Plain' to see payload (sensitiveData object) in plain format.\n - Represented as the concatenation of the Base64 encoded JWE Protected Header, JWE Encrypted Key, JWE Initialization Vector, JWE Ciphertext, and JWE Authentication Tag separated by '.'" properties: consumer: properties: primaryAccountNumber: type: number description: Consumer Credit or Debit card number (PAN) to offer Installments (ISO-DE2). This field can contain both funding and tokenized PAN. For 'Carded Installments', this will be mandatory parameter. maxLength: 19 minLength: 11 example: 5110921032063789 required: - primaryAccountNumber ErrorList: type: array minItems: 1 items: $ref: '#/components/schemas/Error' OfferIdField: type: string description: Unique identifier for installment offers. This is mandatory for 'Mastercard Installments Payment Services product. example: '24092019' maxLength: 64 minLength: 8 TransactionOffer: type: object properties: offerId: type: string description: unique identifier for installment offers. example: '24092019' maxLength: 64 minLength: 8 required: - offerId MerchantPlan: type: object properties: acceptor: type: string description: Merchant acceptor identifier. example: '100234' maxLength: 100 minLength: 1 country: type: string description: Country code in ISO 3166 alpha 3 format. example: USA maxLength: 3 minLength: 3 mcc: type: string description: Merchant Category Code. example: '1711' maxLength: 4 minLength: 4 name: type: string description: Merchant name for plan. example: Decor shop maxLength: 100 minLength: 1 required: - country - mcc CardedTransaction: allOf: - $ref: '#/components/schemas/Transaction' - type: object properties: amountType: type: string description: Transaction amount type. Possible values can be PURCHASE, FINAL. example: PURCHASE stan: description: The System Trace Audit Number (STAN) for this transaction. (ISO DE-11). type: string minLength: 1 maxLength: 6 example: 123456 rrn: description: The Retrieval Reference Number (RRN) for this transaction. (ISO DE-37). type: string minLength: 0 maxLength: 12 example: 123456123456 authorizationCode: description: Value generated by the issuing bank in response to a proposal to transfer funds (ISO DE-38). type: string minLength: 0 maxLength: 6 example: 123456 localDateTime: description: Transaction local date. [Date and Time RFC](https://datatracker.ietf.org/doc/html/rfc3339). (ISO DE-12, ISO DE-13). If amount type is purchase then populate purchase date time else populate ISO transaction date time. type: string example: '2023-01-01T00:00:00Z' transmissionDateTime: description: Transaction transmission date. [Date and Time RFC](https://datatracker.ietf.org/doc/html/rfc3339). (ISO DE-7). type: string example: '2023-01-01T00:00:00Z' transactionLinkId: description: Unique Value generated by Mastercard to track the transaction (ISO DE-105). type: string minLength: 0 maxLength: 22 example: 123456dasda123456 required: - amountType ScheduledRepayments: type: array description: This object will be populated only when consumer offer selection is enabled. items: $ref: '#/components/schemas/ScheduledRepayment' maxItems: 99 CreatedInstallmentPlan: type: object properties: planId: $ref: '#/components/schemas/PlanIdField' status: $ref: '#/components/schemas/StatusField' Errors: title: Errors type: object description: Error object which returns the list of Error objects. required: - Error properties: Error: $ref: '#/components/schemas/ErrorList' StatusField: type: string description: 'Current status of a plan. One of: CREATED, APPROVED, DECLINED, TIMED_OUT.' example: CREATED maxLength: 12 minLength: 7 InstallmentPlan: type: object properties: consumer: $ref: '#/components/schemas/Consumer' merchant: $ref: '#/components/schemas/MerchantPlan' offerId: $ref: '#/components/schemas/OfferIdField' planId: $ref: '#/components/schemas/PlanIdField' planInstallmentInformation: $ref: '#/components/schemas/PlanInstallmentInformation' providerId: $ref: '#/components/schemas/ProviderIdField' rejectReasonCode: type: string description: Describes the reason for plan rejection. Mandatory for when status is DECLINED. Following are the reject reason codes:[ CONSUMER_AUTH_FAIL, CONSUMER_APPLICATION_FAIL, CONSUMER_CANCELLATION, LENDER_DRIVEN_REJECTION, LENDER_SYSTEM_ERROR, OTHER_REASON ] example: CONSUMER_CANCELLATION maxLength: 30 minLength: 12 rejectReasonDetail: type: string description: Indicates detailed information about reject reason. example: Credit score is too low maxLength: 5000 minLength: 0 scheduledRepayments: $ref: '#/components/schemas/ScheduledRepayments' status: $ref: '#/components/schemas/StatusField' transaction: $ref: '#/components/schemas/Transaction' transactionOffers: $ref: '#/components/schemas/TransactionOffers' required: - merchant - planId - providerId - status - transaction PlanSchedulePayments: type: array description: List of installments as per Schedule payments. items: $ref: '#/components/schemas/SchedulePayment' maxItems: 99 CardedPlanInstallmentInformation: allOf: - $ref: '#/components/schemas/PlanInstallmentInformation' - type: object properties: firstInstallmentAmount: type: number format: double description: Amount to be paid for the first installment. example: 100 exclusiveMaximum: false exclusiveMinimum: false maximum: 1000000000000000 minimum: 0 otherInstallmentAmount: type: number format: double description: Subsequent Installment amount with minor unit according to ISO 4217. example: 200 maximum: 1000000000000000 minimum: 0 feeValue: type: number format: double description: Fees values based on type it can be either Fixed amount or Percentage to applied in transaction amount. This is mandatory for 'Mastercard Installments Payment Services product. example: 2.05 exclusiveMaximum: false exclusiveMinimum: false maximum: 1000000000000000 minimum: 0 PlanMerchant: type: object properties: country: type: string description: Country code in ISO 3166 alpha 3 format. example: USA maxLength: 3 minLength: 3 mcc: type: string description: Merchant Category Code. example: '1711' maxLength: 4 minLength: 4 url: description: URL for the Merchant. type: string minLength: 1 maxLength: 50 example: www.globexdecor.com acquirerId: description: Acquiring Institution ID Code to identifies the acquiring institution. (ISO DE-32). type: string minLength: 1 maxLength: 6 example: '456789' merchantId: description: Merchant ID assigned by Acquirer. (ISO DE-42). type: string minLength: 1 maxLength: 15 example: '456789' Transaction: type: object properties: amount: $ref: '#/components/schemas/Amount' currency: type: string description: Currency code according to ISO 4217. example: USD maxLength: 3 minLength: 3 required: - amount - currency TransactionOffers: type: array description: A list of offers presented to the consumer. This is a mandatory field for During Purchase use case of Mastercard Installments Payment Services. items: $ref: '#/components/schemas/TransactionOffer' maxItems: 50 OfferTransactionIdField: type: string description: Unique identifier for installment offers presentment transaction. It will be snowflake identifier format. example: '1763137029152964608' minLength: 8 maxLength: 40 CardedMerchant: allOf: - $ref: '#/components/schemas/PlanMerchant' - type: object properties: name: description: Merchant legal name or "doing business as" name. For 'Mastercard Installments Payment Services', this will be optional parameter. type: string minLength: 1 maxLength: 100 example: Globex Decor url: description: URL for the Merchant . type: string minLength: 1 maxLength: 50 example: www.globexdecor.com acquirerId: description: Acquiring Institution ID Code to identifies the acquiring institution. (ISO DE-32). type: string minLength: 1 maxLength: 6 example: '456789' merchantId: description: Merchant ID assigned by Acquirer. (ISO DE-42). type: string minLength: 1 maxLength: 15 example: '456789' PlanPost: type: object properties: offerTransactionId: $ref: '#/components/schemas/OfferTransactionIdField' merchant: $ref: '#/components/schemas/CardedMerchant' offerId: $ref: '#/components/schemas/OfferIdField' planInstallmentInformation: $ref: '#/components/schemas/CardedPlanInstallmentInformation' providerId: $ref: '#/components/schemas/ProviderIdField' schedulePayments: $ref: '#/components/schemas/PlanSchedulePayments' transaction: $ref: '#/components/schemas/CardedTransaction' sensitiveData: $ref: '#/components/schemas/SensitiveDataField' transactionOffers: $ref: '#/components/schemas/TransactionOffers' required: - providerId - transaction - offerTransactionId ErrorWrapper: title: ErrorWrapper type: object description: The error response object which gets returned in case of any error. required: - Errors properties: Errors: $ref: '#/components/schemas/Errors' PlanInstallmentInformation: type: object description: This object is mandatory for **Mastercard Installments Payment Services**. properties: apr: type: number format: double description: Annual Percentage Rate (APR). example: 25.03 exclusiveMaximum: false exclusiveMinimum: false maximum: 200 minimum: 0 currency: type: string description: Currency code according to ISO 4217. example: USD maxLength: 3 minLength: 3 frequency: type: string description: Frequency of installment (single installment time duration).It will be one of the [WEEKLY, BIWEEKLY, MONTHLY] example: BIWEEKLY maxLength: 20 minLength: 3 firstInstallmentAmount: type: number format: double description: Amount to be paid for the first installment. example: 100 exclusiveMaximum: false exclusiveMinimum: false maximum: 1000000000000000 minimum: 0 otherInstallmentAmount: type: number format: double description: Subsequent Installment amount with minor unit according to ISO 4217. example: 200 maximum: 1000000000000000 minimum: 0 feeValue: type: number format: double description: Fees values based on type it can be either Fixed amount or Percentage to applied in transaction amount. example: 2.05 exclusiveMaximum: false exclusiveMinimum: false maximum: 1000000000000000 minimum: 0 tenure: type: integer format: int32 description: Total number of installments for an offer. Offer tenure. example: 2 maximum: 99 minimum: 2 totalAmount: type: number format: double description: The total amount owed by the cardholder on an installment purchase inclusive of fees, tax and interest for the installment plan. example: 200 exclusiveMaximum: false exclusiveMinimum: false maximum: 1000000000000000 minimum: 0 required: - frequency - tenure Amount: type: number format: double description: Amount to be paid in an installment. example: 100 exclusiveMaximum: false exclusiveMinimum: false maximum: 9999999999999.99 minimum: 0 SchedulePayment: type: object description: Schedule Payments of the offer selected by cardholder. This object is mandatory for **Mastercard Installments Payment Services**. properties: installmentAmount: type: number format: double description: Amount to be paid in an installment. This is mandatory for 'Mastercard Installments Payment Services product. example: 100 exclusiveMaximum: false exclusiveMinimum: false maximum: 1000000000000000 minimum: 0 dueDate: type: string description: Due date for an installment. This is mandatory for 'Mastercard Installments Payment Services product. example: 2023-5-21 maxLength: 10 minLength: 8 installmentNumber: type: integer format: int32 description: Number of an installment. This is mandatory for 'Mastercard Installments Payment Services product. example: 1 maximum: 99 minimum: 1 ProviderIdField: type: string format: uuid description: Provider ID is internal ID generated by Configuration API. example: 3d56f5a7-db48-41f0-875e-30920e8465f3 maxLength: 36 minLength: 36 ScheduledRepayment: type: object properties: amount: $ref: '#/components/schemas/Amount' dueDate: type: string description: Due date for an installment. example: 2022-5-21 maxLength: 10 minLength: 8 installmentNumber: type: integer format: int32 description: Number of an installment. example: 1 maximum: 99 minimum: 1 Consumer: type: object properties: email: type: string description: Consumer's email address. Hashed for pre-approved consumer, raw for consumer without pre-approval. example: jane.doe@example.com maxLength: 254 minLength: 5 isdCode: type: string description: ISD code of the consumer's mobile number. example: '1' maxLength: 5 minLength: 1 mobile: type: string description: Consumer's mobile number. Hashed for pre-approved consumer, raw for consumer without pre-approval. example: '5550009999' maxLength: 64 minLength: 4 providerConsumerId: type: string format: uuid description: Unique user ID provided by the Installment Program Provider. This is specific to the provider. (External user/consumer id). Applicable only for pre-approved consumers. example: 3d56f5a7-db48-41f0-875e-30920e8465f3 maxLength: 36 minLength: 36 Error: title: Error type: object description: Error object which contains details about the Error. required: - Source - ReasonCode - Description - Recoverable properties: Source: type: string description: The application name that generated this error. minLength: 1 maxLength: 100 example: Mastercard Installments APIs ReasonCode: type: string description: A unique constant identifying the error case encountered during request processing. minLength: 1 maxLength: 100 example: invalid.request.parameter Description: type: string description: Short description of the ReasonCode field. minLength: 10 maxLength: 1000 example: One of the request parameters is invalid, try again with the correct request. Recoverable: type: boolean description: Indicates whether this error will always be returned for this request, or retrying could change the outcome. example: false Details: type: string description: (Optional) Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors. minLength: 0 maxLength: 5000 example: paymentCardId size must be between 36 and 36 requestBodies: PlanPostRequestBody: content: application/json: examples: Carded Installment Plan Plain: description: Typical request for 'Mastercard Installments Payment Services with plain payload. Please note that the client needs to encrypt sensitiveData field using Mastercard provided JWE encryption libraries before calling the API. Refer to the example, Carded Installment Plan Encrypted (only for Reference), to understand how the resulting payload should look like after performing encryption value: offerTransactionId: '1763137029152964608' merchant: name: Globex Decor country: USA mcc: 1711 merchantId: 1234856 url: https://www.globexdecor.com acquirerId: 856478 offerId: '24092019' transactionOffers: - offerId: '24092019' - offerId: '87654321' planInstallmentInformation: apr: 0 currency: USD frequency: BIWEEKLY firstInstallmentAmount: 66.67 otherInstallmentAmount: 66.67 feeValue: 0 tenure: 6 totalAmount: 400 providerId: 218b9962-1355-44e4-8a16-f911363fd849 schedulePayments: - installmentAmount: 66.67 dueDate: '2023-05-30' installmentNumber: 1 - installmentAmount: 66.67 dueDate: '2023-06-13' installmentNumber: 2 - installmentAmount: 66.67 dueDate: '2023-06-27' installmentNumber: 3 - installmentAmount: 66.67 dueDate: '2023-07-11' installmentNumber: 4 - installmentAmount: 66.67 dueDate: '2023-07-25' installmentNumber: 5 - installmentAmount: 66.67 dueDate: '2023-08-08' installmentNumber: 6 transaction: amountType: PURCHASE amount: 400 currency: USD stan: 123456 rrn: 123456123456 authorizationCode: 123456 localDateTime: '2023-01-01T00:00:00Z' transmissionDateTime: '2023-01-01T00:00:00Z' transactionLinkId: '1234567890' sensitiveData: consumer: primaryAccountNumber: 5110921032063789 Carded Installments Plan Encrypted (only for reference): description: Typical Plan request for 'Mastercard Installments Payment Services showing indicative payload after performing JWE encryption on sensitiveData field. value: offerTransactionId: '1763137029152964608' merchant: name: Globex Decor country: USA mcc: 1711 merchantId: 1234856 url: https://www.globexdecor.com acquirerId: 856478 offerId: '24092019' transactionOffers: - offerId: '24092019' - offerId: '87654321' planInstallmentInformation: apr: 0 currency: USD frequency: BIWEEKLY firstInstallmentAmount: 66.67 otherInstallmentAmount: 66.67 feeValue: 0 tenure: 6 totalAmount: 400 providerId: 218b9962-1355-44e4-8a16-f911363fd849 schedulePayments: - installmentAmount: 66.67 dueDate: '2023-05-30' installmentNumber: 1 - installmentAmount: 66.67 dueDate: '2023-06-13' installmentNumber: 2 - installmentAmount: 66.67 dueDate: '2023-06-27' installmentNumber: 3 - installmentAmount: 66.67 dueDate: '2023-07-11' installmentNumber: 4 - installmentAmount: 66.67 dueDate: '2023-07-25' installmentNumber: 5 - installmentAmount: 66.67 dueDate: '2023-08-08' installmentNumber: 6 transaction: amountType: PURCHASE amount: 400 currency: USD stan: 123456 rrn: 123456123456 authorizationCode: 123456 localDateTime: '2023-01-01T00:00:00Z' transmissionDateTime: '2023-01-01T00:00:00Z' transactionLinkId: '1234567890' encryptedValue: eyJjdHkiOiI8bWEtZW5jLWtleS1hbGlhcz4iLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.SoSsDIDCNrT5aDFzZrQiLhY3dB87Kx-j0q52ShlJR62nZ3T4lKZ1RAPLkTH3QRQi017lUoVbr20c9qfHEKe4fCV6MOpdFyZM0LcYk3N6xfYBm_UL2X7bH2ihr9FYY-60UWE3A-or1W6boClZnTcwXhhJUnsgTYuf5Xr7WB32ludIS-OK3oPOU-pz_uN-OQurhj8zCMKCnQPEOis56LecRjp2-hW0LcAkN4HcMO_S_Gd34nXcCIbzGHWJFAjkIfdVTfVSEkXEq0qMID8CYMnvPA_GbiUU-fPh25cHDK8M_QGhrMZAdvA_QTDfvhq_8uVl6aJ7LhB9FI3iLyu-mqKmuw.hh8vNhwA4plS_Mk-.VHCbABQCav5DkhK5E4i37ccb.sUut6LTwK7JJ3SVMi-2Fng schema: $ref: '#/components/schemas/PlanPost' required: true parameters: plan_id: description: Unique identifier for plan in: path name: plan_id required: true schema: type: string format: uuid example: 3d56f5a7-db48-41f0-875e-30920e8465f3 CorrelationIdHeaderParameter: description: Client correlation id for request tracing. Optional parameter. If not provided, the API will create a new one and propagate it to all downstream systems. in: header name: Correlation-Id required: false schema: type: string format: uuid example: 3d56f5a7-db48-41f0-875e-30920e8465f3 maxLength: 36 minLength: 36 headers: Correlation-Id: description: Correlation-Id response header to trace the request. schema: type: string required: true example: 44dc28d6-cf59-11ec-9d64-0242ac120002