swagger: '2.0' info: title: Mastercard Bill Payment Validator Account Opening Approvals 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: Approvals description: The API provides ability for the lender to approve a BNPL loan during purchase. paths: /approvals: post: tags: - Approvals summary: Approve or decline an installment plan. x-mastercard-api-encrypted: true description: This API will be used by the provider to approve or decline a plan. This endpoint uses [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. operationId: planApproval parameters: - $ref: '#/components/parameters/Sync' requestBody: $ref: '#/components/requestBodies/PlanApprovalParameters' responses: '200': $ref: '#/components/responses/PSPData' '202': $ref: '#/components/responses/Accepted' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ForbiddenError' '406': $ref: '#/components/responses/NotAcceptableHeader' /approvals/{plan_id}: get: tags: - Approvals summary: Get the status of checkout and callback URL to PSP (Payment service provider). description: This API will be used by the provider to get the status of checkout and callback URL to PSP (Payment service provider). This API should be used within 24 hours from the time the approval was posted. operationId: getPlanApprovalStatus parameters: - $ref: '#/components/parameters/plan_id' responses: '200': $ref: '#/components/responses/CompletionPSPData' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFound' '406': $ref: '#/components/responses/NotAcceptableHeader' components: responses: CompletionPSPData: description: Success response content: application/json: schema: $ref: '#/components/schemas/CompletionPSPData' examples: Completed: $ref: '#/components/examples/ApprovedCompleted' In Progress: $ref: '#/components/examples/ApprovedInProgress' Accepted: description: The request was successful and will be processed asynchronously. headers: Location: schema: type: string description: The URL that the client should poll for a response status. Refer to GET /approvals/{plan_id}. 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' NotAcceptableHeader: description: This response code is returned when a user enters anything except application/json in the Accept header. content: application/json: schema: $ref: '#/components/schemas/ErrorWrapper' examples: NotAcceptableHeader: $ref: '#/components/examples/NotAcceptableHeader' 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' PSPData: description: Success response. Returns only if the sync parameter is true. content: application/json: schema: $ref: '#/components/schemas/PSPData' 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' 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' examples: ApprovedInProgress: description: Approval processing is in progress. value: status: IN_PROGRESS ApprovedCompleted: description: Approval processing is completed value: status: COMPLETED callbackUrl: https://src.mastercard.com?action=COMPLETED&checkoutResponse=EncryptedData 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: '' ConsumerSelectedOffer: description: This example shows a consumer-selected offer that is approved by the lender. value: planId: 3d56f5a7-db48-41f0-875e-30920e8465f3 status: APPROVED approvedAmount: 300 approvedCurrency: USD paymentAuthorization: primaryAccountNumber: '5110921032063789' panExpirationMonth: 08 panExpirationYear: '2022' cardSecurityCode: '123' cardholderFullName: John Doe cardholderFirstName: John cardholderLastName: Doe billingAddress: line1: 5 Street Drive line2: Apartment 123 line3: Southampton city: O'Fallon state: MO countryCode: US zip: '123456' LenderSelectedOffer: description: This example shows an offer approved by the lender. The offer in this case is selected by the consumer on the lenders experience. value: planId: 3d56f5a7-db48-41f0-875e-30920e8465f3 status: APPROVED offerId: '24092019' approvedAmount: 300 approvedCurrency: USD paymentAuthorization: primaryAccountNumber: '5110921032063789' panExpirationMonth: 08 panExpirationYear: '2022' cardSecurityCode: '123' cardholderFullName: John Doe cardholderFirstName: John cardholderLastName: Doe billingAddress: line1: 5 Street Drive line2: Apartment 123 line3: Southampton city: O'Fallon state: MO countryCode: US zip: '123456' InvalidFieldLength: value: Errors: Error: - Source: Mastercard Installments API's ReasonCode: invalid.request.body.parameter Description: Field length is out of bound 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: '' InvalidFieldFormat: value: Errors: Error: - Source: Mastercard Installments API's ReasonCode: invalid.request.body.parameter Description: Field format or type is invalid Recoverable: false Details: '' 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: '' NotAcceptableHeader: value: Errors: Error: - Source: Mastercard Installments API's ReasonCode: not.acceptable.header Description: Accept header value is not application/json. Recoverable: false Details: '' Declined: description: This example shows an installment loan request being declined. value: planId: 3d56f5a7-db48-41f0-875e-30920e8465f3 status: DECLINED rejectReasonCode: LENDER_DRIVEN_REJECTION rejectReasonDetail: Credit score is too low 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: '' 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: '' schemas: PlanApprovalParameters: type: object required: - planId - status properties: planId: description: A unique identifier assigned to an installment plan. type: string format: uuid example: 3d56f5a7-db48-41f0-875e-30920e8465f3 status: type: string description: Plan approval status. It will be either APPROVED or DECLINED. enum: - APPROVED - DECLINED example: APPROVED offerId: description: 'Installment Program Provider''s offer identifier generated by Mastercard. This ID is generated at the time of setup on MC Connect UI when the Lender creates an Offer. The lender must provide the offer ID if the consumer offer selection is disabled. The offer ID provided must be one of the offer IDs retrieved via Plan API. ' type: string format: string minLength: 8 maxLength: 8 example: '24092019' rejectReasonCode: type: string description: Describes the reason for plan rejection. Mandatory for when the status is DECLINED. enum: - CONSUMER_AUTH_FAIL - CONSUMER_APPLICATION_FAIL - CONSUMER_CANCELLATION - LENDER_DRIVEN_REJECTION - LENDER_SYSTEM_ERROR - OTHER_REASON example: CONSUMER_APPLICATION_FAIL rejectReasonDetail: type: string description: Indicates detailed information about the reason for rejection. minLength: 0 maxLength: 5000 example: No credit or credit score too low approvedAmount: description: The total approved amount owed by the consumer on an installment purchase, inclusive of fees and interest, for the installment plan. This field is required if the status is APPROVED. type: number format: double example: 300 minimum: 0 maximum: 999999999999999 approvedCurrency: description: Alphanumeric currency code as per ISO 4217. This field is required if the status is APPROVED. type: string minLength: 3 maxLength: 3 example: USD paymentAuthorization: description: This block is required in the event that the status is APPROVED. type: object required: - primaryAccountNumber - panExpirationMonth - panExpirationYear - cardSecurityCode - billingAddress properties: primaryAccountNumber: type: string minLength: 9 maxLength: 19 description: 'Primary Account Number. A variable length, ISO/IEC 7812-compliant account number is generated within account ranges associated with a BIN, by a Card Issuer. ' example: '5555111122223333' panExpirationMonth: type: string minLength: 2 maxLength: 2 description: The expiration month of the card, expressed as a two-digit calendar month. example: 08 panExpirationYear: type: string minLength: 4 maxLength: 4 description: The expiration year of the Card, expressed as a four-digit calendar year. example: '2022' cardSecurityCode: type: string minLength: 3 maxLength: 4 description: Card security code example: '123' cardholderFullName: type: string maxLength: 60 description: Cardholders Name. This field is optional if cardholderFirstName and cardholderLastName are used. example: John Doe cardholderFirstName: type: string maxLength: 30 description: Cardholders First Name. This field is optional if cardholderFullName is used. example: John cardholderLastName: type: string maxLength: 30 description: Cardholders Last Name. This field is optional if cardholderFullName is used. example: Doe billingAddress: type: object required: - line1 - city - state - countryCode - zip description: Cardholders Billing Address. properties: line1: type: string maxLength: 60 description: Address line 1 example: 5 Street Drive line2: type: string maxLength: 75 description: Address line 2 example: Apartment 123 line3: type: string maxLength: 75 description: Address line 3 example: Southampton city: type: string maxLength: 50 description: City of residence example: O'Fallon state: type: string maxLength: 30 description: State of Residence example: MO countryCode: description: Address country code in ISO 3166 alpha 2 format. type: string minLength: 2 maxLength: 2 pattern: ^[a-zA-Z]{2}$ example: US zip: description: Address zip/postal code type: string maxLength: 16 example: '123456' PSPData: type: object properties: callbackUrl: description: PSP (Payment service provider) callback URL with checkout response. This URL will expire after 24 hours from the time the approval is posted. type: string example: https://src.mastercard.com#%7B%22action%22%3A%22COMPLETED%22%2C%22checkoutResponse%22%3AEncryptedData%7D 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' CompletionPSPData: allOf: - $ref: '#/components/schemas/PSPData' - type: object required: - status properties: status: description: Indicates the status of processing. It will be either IN_PROGRESS or COMPLETED. type: string example: IN_PROGRESS Errors: title: Errors type: object description: Error object which returns the list of Error objects. required: - Error properties: Error: $ref: '#/components/schemas/ErrorList' ErrorList: type: array minItems: 1 items: $ref: '#/components/schemas/Error' 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: PlanApprovalParameters: required: true content: application/json: schema: $ref: '#/components/schemas/PlanApprovalParameters' examples: Approved Consumer Selected Offer: $ref: '#/components/examples/ConsumerSelectedOffer' Approved Lender Selected Offer: $ref: '#/components/examples/LenderSelectedOffer' Declined Offer: $ref: '#/components/examples/Declined' 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 Sync: in: query description: Indicates whether the request is synchronous (the default value is false) or asynchronous. name: sync schema: type: boolean example: true headers: Correlation-Id: description: Correlation-Id response header to trace the request. schema: type: string required: true example: 44dc28d6-cf59-11ec-9d64-0242ac120002