openapi: 3.0.3 info: description: >- Mastercard SRC Click to Pay Push Provisioning using the b2b enroll API version: 1.0.0 title: "Click To Pay Push Provisioning Enroll API" termsOfService: 'https://developer.mastercard.com/terms-of-use' contact: name: API Support email: apisupport@mastercard.com url: https://developer.mastercard.com/support license: name: mastercard - confidential servers: - url: 'https://sandbox.api.mastercard.com/src/api/digital/payments' description: Sandbox server - url: 'https://api.mastercard.com/src/api/digital/payments' description: Production server security: - xOpenApiClientId: [] paths: /cards: post: summary: "Enrolls consumer into SRC for Click to Pay." description: "The Card Enrollment operation enrolls a Mastercard card into an SRC Profile for a specified Mastercard SRC Click to Pay." operationId: "putCard" parameters: - $ref: "#/components/parameters/xOpenApiClientId" requestBody: content: application/json: schema: $ref: "#/components/schemas/EnrollCardRequest" description: "Card Enrollment request" required: true responses: '200': description: "OK, enrolled card details included in the response body\n" content: application/json: schema: $ref: "#/components/schemas/EnrollCardResponse" '400': description: "Bad request\n\n" content: application/json: schema: $ref: "#/components/schemas/Error" example: "//INVALID_ARGUMENT\n{\n \"code\": 400,\n \"status\": \"INVALID_ARGUMENT\",\n \"message\": \"Cannot process the request because it is malformed or has incorrect/missing fields or values.\",\n \"details\": [\n {\n \"reason\" : \"CANNOT_BE_NULL\",\n \"source\": \"correlation-id\",\n \"message\": \"correlation-id is required\",\n \"sourceType\":\"BODY\"\n }\n ]\n}\n//INVALID_STATE\n{\n \"code\": 400,\n \"status\": \"INVALID_STATE\",\n \"message\": \"Request cannot be executed due to the incorrect field value.\",\n \"details\": [\n {\n \"reason\" : \"INVALID_VALUE\",\n \"source\": \"srcClientId\",\n \"message\": \"srcClientId is not valid\",\n \"sourceType\":\"BODY\"\n }\n ]\n\n}\n" '401': $ref: "#/components/responses/Unauthorized" '403': $ref: "#/components/responses/Forbidden" '500': $ref: "#/components/responses/InternalServerError" components: parameters: xOpenApiClientId: in: "header" name: "x-openapi-clientid" example: "TXSqXE0wyWM8-ulyk6eRAzt7Qh43PjQ97wm759Gx27ab025c" description: "Open API Key to make server to server calls to Mastercard SRC" required: true schema: type: "string" schemas: ComplianceSettings: type: "object" description: "Container for Consent data." required: - "privacy" - "tnc" properties: privacy: $ref: "#/components/schemas/privacyConsent" tnc: $ref: "#/components/schemas/tncConsent" privacyConsent: type: "object" description: "Container for Consumer's consent status. There are individual consents for Privacy " required: - "latestVersionUri" properties: latestVersionUri: description: "The URI of the latest version." type: "string" example: "https://www.mastercard.com/global/click-to-pay/country-listing/privacy.html" tncConsent: type: "object" description: "Container for Consumer's consent status. There are individual consents forTerms and Conditions" required: - "latestVersionUri" properties: latestVersionUri: description: "The URI of the latest version." type: "string" example: "https://www.mastercard.com/global/click-to-pay/country-listing/terms.html" Consumer: type: "object" required: - "consumerIdentity" - "mobileNumber" - "countryCode" - "languageCode" - "firstName" - "lastName" properties: consumerIdentity: $ref: "#/components/schemas/ConsumerIdentity" mobileNumber: $ref: "#/components/schemas/PhoneNumber" countryCode: description: "Consumer-provided country code. ISO 3166 alpha 2 country code." example: "US" type: "string" languageCode: description: "Consumer-provided language choice. ISO 639-1 Code." example: "en" type: "string" firstName: description: "Consumer-provided first name." example: "John" type: "string" maxLength: 30 lastName: description: "Consumer-provided last name." example: "Doe" type: "string" maxLength: 30 ConsumerIdentity: required: - "identityType" - "identityValue" type: "object" properties: identityType: $ref: "#/components/schemas/ConsumerIdentityType" identityValue: description: "Consumer Identity value that corresponds to the Consumer Identity Type. Is used to locate information within the SRC Profile" example: "johndoe@mail.com" maxLength: 255 type: "string" ConsumerIdentityType: description: "Type of Consumer Identity transmitted or collected: \n EMAIL_ADDRESS - Email address associated with the Cardholder. This value is Cardholder generated and represents contact or notification data." type: "string" enum: - "EMAIL_ADDRESS" example: "EMAIL_ADDRESS" ConsumerStatus: description: "Consumer profile status. The consume profile status will be active at the time of enrollment to Click to Pay" type: "string" enum: - "ACTIVE" - "SUSPENDED" - "LOCKED" DigitalCardData: description: "Digital card data." type: "object" properties: status: $ref: "#/components/schemas/DigitalCardStatus" descriptorName: description: "Represents the card brand." maxLength: 64 example: "mastercard" type: "string" artUri: maxLength: 1024 description: "URI that houses the Card Art image to be used for presentation purposes." example: "https://assets.mastercard.com/card-art/combined-image-asset/MyBank-mastercard.png" type: "string" iscobranded: type: boolean description: "Indicates whether the card is co-branded" example: true maxLength: 8 coBrandedName: type: "string" description: "Indicates whether the card is co-branded" example: "MyBank" maxLength: 128 DigitalCardStatus: description: "State of the Digital Card at any given time at the Secure Card on File System.\n ACTIVE: Token is active \n SUSPENDED: Token is suspended by the issuer. Please note that this card status is never returned when the Enroll Card endpoint (POST /cards) is called. \n CANCELLED: Token is deleted by the issuer. Please note that this card status is never returned when the Enroll Card endpoint (POST /cards) is called." type: "string" enum: - "ACTIVE" - "SUSPENDED" - "CANCELLED" EnrollCardRequest: type: "object" required: - "srcClientId" - "serviceId" - "consumer" - "complianceSettings" properties: srcClientId: format: "UUID" pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" description: "Identifies the connecting client, e.g. SRCI, DCF, SRC-PI" type: "string" example: eccbf087-f159-4d69-b31d-00bec75c0474 srcCorrelationId: $ref: "#/components/schemas/SrcCorrelationId" serviceId: description: "Identifies a relevant / requested service (program) supported by the SRC System" pattern: "^[0-9a-zA-Z#_-]*$" type: "string" example: SRC consumer: $ref: "#/components/schemas/Consumer" complianceSettings: $ref: "#/components/schemas/ComplianceSettings" cardSource: $ref: "#/components/schemas/Origin" enrolmentReferenceData: $ref: "#/components/schemas/EnrolmentReferenceData" encryptedCard: description: | __Conditional__: encryptedCard must be passed for FPAN based enrollment. The card must be encrypted per the following schema ('#/components/schemas/Card'). Please see enrolmentReferenceData for alternative forms of enrollment. example: eyJraWQiOiIxNDkxMjMtc3JjLWZwYW4tZW5jcnlwdGlvbiIsImVuYyI6IkExMjhHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ.t7tkgd4CLzpCpfsvF1PpcSIw17LsVtDcocx8wtcfUNqamnN4-nylI9Qm_aZcMgh3McxGHoY7gJl-DP4prUEbQrOvaSJTtV8lLIWA_i5ixPh6RPeDBDrfu8Ef0xb7rxmWZwtTS8C5U3wo0WHYu7GNigvWWhxOqr1v1fLLaKkMfPJ_I0A86BzmTjVICsaaErHthidXZnep4-VUQr0PEe7aqQS43I4CZ7Ak0N8jrlD3UqO4wKnPKPLNNxFlCMZm8KvkOzo7dWWZi2DYJ5Ea2bkp26LKZ21Rr5Mhv14uf2BoThKHRI8rKFgTQ3mxsU6vfSv2sHdZBE631IvqX-H2RIWejg.dwkXT7-xNIDI3Vut.Yf_XqDTW4y3xuj36HCXNj_7GYkOSixpM12KHWeiqV662X3ta87mseetyPIVQP0KJ3zW_GmMYuycrXuekbye7N6UcOVQBENHsINkge4iUjcJp_1imNbPlNnaGHCPdXjjyh5FFvQFoucGquCyyoAqEXOEw1KFjs2x8r5fk4goNFxr5W8XdPnGkIdbzKo3-eMUZ_YZ0pePGB3VIdez6f7cBJk_6rZoaDS9k4OJsqjCuNEFC-_7ZU6zAveYaeGGAM3eMBPFgXMUY_xyd9B4VXHyUv1oSOp3do76x3xS8fLY5AkJtkIoIjgvvEiysoIzybxyS1I2vbOy1Ox-RW_dJ2jd_yLa3EOc.PvmkAIOJdBrcPQeKdxOsEw type: string EnrollCardResponse: type: "object" required: - "srcCorrelationId" - "maskedCard" properties: srcCorrelationId: $ref: "#/components/schemas/SrcCorrelationId" maskedCard: $ref: "#/components/schemas/MaskedCard" maskedConsumer: $ref: "#/components/schemas/MaskedConsumer" EnrolmentReferenceData: type: "object" description: "EnrolmentReferenceData must be passed for PUSH_ACCOUNT_RECEIPT based enrollment." required: - "enrolmentReferenceId" - "enrolmentReferenceType" properties: enrolmentReferenceId: description: "This identifier is used in cross-program enrolment and the value depends on the defined EnrolmentReferenceType." maxLength: 256 example: "DM4MMC000000000BGKEJIMXUMLORTSJ2NWTCSNSQP6I4RQ659" type: "string" enrolmentReferenceType: description: | Type of enrolment reference. __Conditional__: Is expected when enrolmentReferenceData is passed * `PUSH_ACCOUNT_RECEIPT` - enrolment reference type associated with the receipt that represents the pushed account details following push provisioning of the card. type: "string" enum: - "PUSH_ACCOUNT_RECEIPT" example: PUSH_ACCOUNT_RECEIPT Card: type: object required: - primaryAccountNumber properties: primaryAccountNumber: description: "A variable length, ISO/IEC 7812-compliant account number that is generated within account ranges and associated with a BIN by an Issuer." example: 5204731600014780 minLength: 16 maxLength: 20 type: string panExpirationMonth: description: "Expiration month of the card, expressed as a two-digit calendar month." example: 10 minLength: 2 maxLength: 2 type: string panExpirationYear: description: "Expiration year of the card, expressed as a four-digit calendar year." example: 2022 minLength: 4 maxLength: 4 type: string cardSecurityCode: description: Card Verification Value 2 (CVV2). example: 123 minLength: 3 maxLength: 6 type: string description: Object for card data. Error: properties: errordetail: description: List of Errors items: $ref: '#/components/schemas/ErrorDetail' type: array message: description: Error message details type: string example: correlation-id is required reason: type: string description: Explanation of the reason for the error example: CANNOT_BE_NULL status: description: HTTP response status codes. example: 400 format: int32 type: integer required: - message - reason - status type: object ErrorDetail: properties: message: type: string description: Message displayed as result of error. example: correlation-id is required reason: type: string description: Explanation of the reason for the error. example: CANNOT_BE_NULL source: type: string description: Parameter that has the error. example: correlation-id sourceType: $ref: '#/components/schemas/sourceType' type: object sourceType: description: Source of error enum: - BODY - HEADER - PATH - QUERY example: BODY type: string MaskedAddress: properties: addressId: description: Identifier used to point to the address. example: 0e01ac3a-d5ba-41ea-a5fd-2b75d585734b pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ type: string city: description: Masked city name. example: N** Y*** type: string countryCode: description: Consumer-provided country code. ISO 3166 alpha 2 country code. example: US type: string createTime: description: Timestamp in UTC when the address was created example: '2021-10-07T13:44:45.385Z' type: string lastUsedTime: description: Timestamp in UTC when the address was last used. example: '2021-06-03T23:54:28.728Z' type: string line1: description: First line of the address. example: 1** S*** A***** type: string line2: description: Second line of the address. example: T** C***** type: string line3: description: Third line of the address. example: S*** S***** type: string name: description: Masked name of the consumer example: M*** Sc****t type: string state: description: Consumer-provided state. example: N* type: string zip: description: Masked zip or postal code. example: '1****' type: string required: - addressId type: object MaskedCard: type: "object" required: - "panLastFour" - "dateOfCardCreated" - "panBin" - "srcDigitalCardId" - digitalCardData properties: srcDigitalCardId: description: Unique Identifier of the Card. Reference representing the PAN or Payment Token that enables a non-SRCPI entity to identify the underlying PAN. pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ type: string example: 68bf50ec-0e8b-414f-8cfc-63e9c3fb9d48 panBin: description: First significant digits of the PAN included in an unmasked form. format: numeric type: string example: "520473" panLastFour: description: Attribute of the Payment Card that represents the Last four digits of the PAN included in an unmasked form. format: numeric type: string example: "4601" tokenUniqueReference: description: The unique reference allocated to a new Token. Serves as a unique identifier for all subsequent queries or management functions relating to this Token. example: DM4MMC0000000001cd2826c715b7475bb089b7622366ebe4 type: string tokenLastFour: description: Last four digits of the Payment Token included in an unmasked form. format: numeric type: string example: "7217" tokenExpirationMonth: description: Expiration month of the Payment Token included in an unmasked form. format: numeric type: string example: "11" tokenExpirationYear: description: Expiration year of the Payment Token included in an unmasked form. format: numeric type: string example: "2026" digitalCardData: $ref: "#/components/schemas/DigitalCardData" panExpirationMonth: description: Expiration month of the Payment Card expressed as a two-digit calendar month used for presentation purposes. format: MM maxLength: 2 minLength: 2 type: string example: "05" panExpirationYear: description: Expiration year of the Payment Card expressed as four-digit calendar year, used for presentation purposes. format: YYYY maxLength: 4 minLength: 4 type: string example: "2022" paymentCardDescriptor: description: Conveys the card brand, and will be a free-form string, to be defined within an SRC Programme. type: string example: mastercard paymentCardType: description: Conveys the card type. Example, CREDIT, DEBIT, PREPAID. type: string example: CREDIT dateOfCardCreated: description: Date (in UTC) when card was enrolled into the Secure Card on File system. example: '2021-11-25T14:51:03.811Z' format: datetime type: string countryCode: description: Consumer-provided country code. ISO 3166 alpha 2 country code. example: US type: string serviceId: description: Identifies a relevant / requested service (program). This ID is assigned by Mastercard. example: '#serviceId_providedbyMastercard' type: string maskedBillingAddress: $ref: '#/components/schemas/MaskedAddress' paymentAccountReference: description: A non-financial reference assigned to each unique PAN and used to link a Payment Account represented by that PAN to affiliated Payment Tokens. example: 5001EUMYTT3AESCZGUEC77KPCLETI type: string MaskedConsumer: properties: complianceSettings: type: "object" description: "Container for Consent data." required: - "privacy" - "tnc" properties: privacy: type: "object" properties: acceptedVersion: type: string description: "Accepted version for Mastercard's Privacy consent by Consumer on issuer APP " example: "4.0" tnc: type: "object" properties: acceptedVersion: type: string description: "Accepted version for Mastercard's tnc consent by Consumer on issuer APP " example: "2.2" countryCode: description: Consumer-provided country code. ISO 3166 alpha 2 country code. example: US type: string dateConsumerAdded: description: Date (in UTC) Consumer was added to the Secure Card on File system. example: '2021-11-25T14:51:03.811Z' format: datetime type: string dateConsumerLastUsed: description: Date (in UTC) Consumer last transacted in the Secure Card on File system. example: '2021-11-25T14:51:03.811Z' format: datetime type: string languageCode: description: Consumer-provided language choice. ISO 639-1 Code. type: string example: en maskedConsumerIdentity: $ref: '#/components/schemas/MaskedConsumerIdentity' maskedEmailAddress: type: string description: Masked emailAddress of the Consumer. example: j*****3@gmail.com maskedFirstName: description: Masked first name of the Consumer. type: string example: J*** maskedFullName: description: Masked full name of the Consumer. type: string example: J*** D** maskedLastName: description: Masked last name of the Consumer. type: string example: D** maskedMobileNumber: $ref: '#/components/schemas/PhoneNumber' srcConsumerId: description: SRC Consumer Reference Identifier as generated by the Secure Card on File system. example: '6aaafa30-a7b2-4687-b6b7-387f8fff0311' pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ type: string status: $ref: '#/components/schemas/ConsumerStatus' required: - dateConsumerAdded - maskedConsumerIdentity type: object MaskedConsumerIdentity: properties: identityType: $ref: '#/components/schemas/ConsumerIdentityType' maskedIdentityValue: description: Masked Consumer Identifier value. For example, masked email address or masked mobile phone number. example: k*****i@mail.com type: string required: - identityType - maskedIdentityValue type: object Origin: description: | Entity enrolling the card: * `CARDHOLDER` - Card added by cardholder * `MERCHANT` - Enrollment of an existing card at the merchant site * `ISSUER` - Card added by issuer via Push Provisioning/Token Connect * `WALLET` - Enrollment of a card stored on file by Commerce Platforms enum: - CARDHOLDER - ISSUER - MERCHANT - WALLET type: string PhoneNumber: description: Phone number. properties: countryCode: description: Phone number country code. International calling code format. Numbers only. Without the plus sign. example: 1 type: string phoneNumber: description: Phone number without country code. Numbers only. example: 5555555555 type: string required: - countryCode - phoneNumber type: object SrcCorrelationId: description: "Correlation ID is for tracking the request. It will be used for troubleshooting any issue during enrollment. If not present in request, new Correlation ID will be generated and sent back in response." type: "string" pattern: "^([0-9a-f]{8}.)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" example: "6b45c47e-70d6-470f-a0a6-c0fccb7e3a43" responses: BadRequest: description: "Bad request, see error object for details\n" content: application/json: schema: $ref: "#/components/schemas/Error" Forbidden: description: "Forbidden, see error object for details, e.g. client identity (origin) not validated\n" content: application/json: schema: $ref: "#/components/schemas/Error" InternalServerError: description: "Internal server error, see error object for details\n" content: application/json: schema: $ref: "#/components/schemas/Error" example: "{\n \"code\": 500,\n \"status\": \"INTERNAL\",\n \"message\": \"Internal server error. Something went wrong while processing the request.\"\n}\n" NotFound: description: "Not found, see error object for details.\n" content: application/json: schema: $ref: "#/components/schemas/Error" ServiceUnavailable: description: "This response should be used for temporary conditions and the Retry-After HTTP header should, if possible, contain the estimated time for the recovery of the service.\n" content: application/json: schema: $ref: "#/components/schemas/Error" Unauthorized: description: "Unauthorized, see error object for details, e.g. authorization token validation failure\n" content: application/json: schema: $ref: "#/components/schemas/Error" securitySchemes: xOpenApiClientId: type: "apiKey" in: "header" name: "x-openapi-clientid" description: "Open API key to make the server to server call to Mastercard SRC System."