# Submit a purchase request

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /soap:
    post:
      summary: Submit a purchase request
      deprecated: false
      description: Submit a purchase request to generate a Virtual Card Number (VCN).
      tags:
        - 'SOAP API Documentations/Example: Mastercard'
      parameters:
        - name: Idempotency-Key
          in: header
          description: >-
            1. The header key Idempotency-Key is optional.

            2. If the header key Idempotency-Key is added then it should be
            non-null and non-empty.

            3. Max length of key is 80 chars.

            4. It is recommended that the key is UUID and generated randomly.
          required: false
          example: "Any random UUID set in HTTP Request Header\t"
          schema:
            type: string
        - name: Content-Type
          in: header
          description: ''
          required: false
          example: text/xml
          schema:
            type: string
      requestBody:
        content:
          application/xml:
            schema:
              type: object
              properties:
                ser:SubmitPurchaseRequest:
                  type: object
                  properties:
                    ser:RCNData:
                      type: object
                      properties:
                        ser1:rcnId:
                          type: string
                        ser1:rcnAlias:
                          type: string
                      required:
                        - ser1:rcnId
                        - ser1:rcnAlias
                      x-apidog-orders:
                        - ser1:rcnId
                        - ser1:rcnAlias
                      description: >-
                        RCN details to create a VCN.

                        You can use the getRealCards call to get the RCN
                        details.
                    ser:dataSourceId:
                      type: integer
                      description: "Obtained through the getDataSource call.\t"
                    ser:companyId:
                      type: string
                      description: "ID of your company. You can use the getCompanies call to get a list of company IDs to create purchase requests for.\t"
                    ser:validFor:
                      type: integer
                      description: "By default, the VCN is valid for 24 months (a different default value can be configured for the company) from the date it’s created. You can use this parameter to specify the number of months between 01 and 24. This parameter decides the VCN expiry date.\t"
                    ser:description:
                      type: string
                      description: "Add a description up to 80 characters describing the purchase request.\t"
                    ser:TemplateDetails2:
                      type: object
                      properties:
                        ser:templateId:
                          type: string
                        ser:fullTemplateRuleDetails:
                          type: object
                          properties:
                            ser:ruleName:
                              type: string
                            ser:ruleType:
                              type: string
                            ser:templateControl:
                              type: array
                              items:
                                type: object
                                properties:
                                  ser:maxTrans:
                                    type: string
                                  ser:cumulativeLimit:
                                    type: string
                                  ser:period:
                                    type: string
                                  ser:currencyType:
                                    type: string
                                  ser:currencyCode:
                                    type: string
                                  ser:endDate:
                                    type: string
                                  ser:from:
                                    type: string
                                  ser:to:
                                    type: string
                                  ser:timeZone:
                                    type: string
                                  ser:strictPreAuthCheck:
                                    type: string
                                  ser:negate:
                                    type: string
                                x-apidog-orders:
                                  - ser:maxTrans
                                  - ser:cumulativeLimit
                                  - ser:period
                                  - ser:currencyType
                                  - ser:currencyCode
                                  - ser:endDate
                                  - ser:from
                                  - ser:to
                                  - ser:timeZone
                                  - ser:strictPreAuthCheck
                                  - ser:negate
                          required:
                            - ser:ruleName
                            - ser:ruleType
                            - ser:templateControl
                          x-apidog-orders:
                            - ser:ruleName
                            - ser:ruleType
                            - ser:templateControl
                        ser:templateCustomField:
                          type: object
                          properties:
                            ser:templateCustomField:
                              type: object
                              properties:
                                ser1:customFieldName:
                                  type: string
                                ser1:customFieldValue:
                                  type: string
                              required:
                                - ser1:customFieldName
                                - ser1:customFieldValue
                              x-apidog-orders:
                                - ser1:customFieldName
                                - ser1:customFieldValue
                          required:
                            - ser:templateCustomField
                          x-apidog-orders:
                            - ser:templateCustomField
                      required:
                        - ser:templateId
                        - ser:fullTemplateRuleDetails
                        - ser:templateCustomField
                      x-apidog-orders:
                        - ser:templateId
                        - ser:fullTemplateRuleDetails
                        - ser:templateCustomField
                      description: "Contains the template ID and the rule details.\t"
                    ser:supplierDetails:
                      type: object
                      properties:
                        ser:supplierId:
                          type: string
                      required:
                        - ser:supplierId
                      x-apidog-orders:
                        - ser:supplierId
                      description: "Details of a supplier to send the VCN details. SupplierDetails is not required for SubmitPurchaseRequest API calls for Mastercard® In Control for Mobile Payments (ICMP) enabled purchase requests made through the ICCP API. SupplierDetails is still required for ICCP-only purchase requests.\t"
                    ser:disableCardImage:
                      type: string
                    "ser:addendaDataExpected\t":
                      type: boolean
                      description: "Specify Y or N if you want to add the invoice addenda record to a purchase request. Refer the Addenda chapter for more details.\t"
                    s:
                      type: boolean
                      description: >-
                        Set Y to disable card image in the Purchase Request
                        Creation API response. Set N to include the card image.

                        Where the disableCardImage parameter is included in API
                        requests and a valid value is passed, this value will
                        override any settings configured in the user interface
                        at Purchase Template, Company Site Configuration or
                        Program Options level.
                  required:
                    - ser:RCNData
                    - ser:dataSourceId
                    - ser:companyId
                    - ser:validFor
                    - ser:description
                    - ser:TemplateDetails2
                    - ser:supplierDetails
                    - ser:disableCardImage
                    - s
                  x-apidog-orders:
                    - ser:RCNData
                    - ser:dataSourceId
                    - ser:companyId
                    - ser:validFor
                    - ser:description
                    - ser:TemplateDetails2
                    - ser:supplierDetails
                    - ser:disableCardImage
                    - "ser:addendaDataExpected\t"
                    - s
                  description: >-
                    Submit a purchase request to generate a Virtual Card Number
                    (VCN).
              required:
                - ser:SubmitPurchaseRequest
              x-apidog-orders:
                - ser:SubmitPurchaseRequest
              xml:
                name: soapenv:Envelope
            examples:
              '1':
                value: "<soapenv:Envelope\n\txmlns:ser=\"http://mastercard.com/sd/pc2/service\"\n\txmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\"\n\txmlns:ser1=\"http://mastercard.com/sd/pc/service\">\n\t<soapenv:Header/>\n\t<soapenv:Body\n\t\txmlns:wsu=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd\">\n\t\t<ser:submitPurchaseRequestRequest>\n\t\t\t<ser:SubmitPurchaseRequest>\n\t\t\t\t<ser:RCNData>\n\t\t\t\t\t<ser1:rcnId>13800</ser1:rcnId>\n\t\t\t\t\t<ser1:rcnAlias>Sandbox Card</ser1:rcnAlias>\n\t\t\t\t</ser:RCNData>\n\t\t\t\t<ser:dataSourceId>4272</ser:dataSourceId>\n\t\t\t\t<ser:companyId>427521</ser:companyId>\n\t\t\t\t<ser:validFor>12</ser:validFor>\n\t\t\t\t<ser:description>My Purchase Request</ser:description>\n\t\t\t\t<ser:TemplateDetails2>\n\t\t\t\t\t<ser:templateId>21680</ser:templateId>\n\t\t\t\t\t<ser:fullTemplateRuleDetails>\n\t\t\t\t\t\t<ser:ruleName>My Rule</ser:ruleName>\n\t\t\t\t\t\t<ser:ruleType>A</ser:ruleType>\n\t\t\t\t\t\t<ser:templateControl xsi:type=\"ser:VelocityControlType2\"\n\t\t\t\t\t\t\txmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">\n\t\t\t\t\t\t\t<ser:maxTrans>1</ser:maxTrans>\n\t\t\t\t\t\t\t<ser:cumulativeLimit>149.54</ser:cumulativeLimit>\n\t\t\t\t\t\t\t<ser:period>C</ser:period>\n\t\t\t\t\t\t\t<ser:currencyType>B</ser:currencyType>\n\t\t\t\t\t\t\t<ser:currencyCode>840</ser:currencyCode>\n\t\t\t\t\t\t\t<ser:endDate>2020-12-26-05:00</ser:endDate>\n\t\t\t\t\t\t</ser:templateControl>\n\t\t\t\t\t\t<ser:templateControl xsi:type=\"ser:templateValidityPeriodControl2\"\n\t\t\t\t\t\t\txmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">\n\t\t\t\t\t\t\t<ser:from>2020-04-04</ser:from>\n\t\t\t\t\t\t\t<ser:to>2020-12-26</ser:to>\n\t\t\t\t\t\t\t<ser:timeZone>Europe/London</ser:timeZone>\n\t\t\t\t\t\t\t<ser:strictPreAuthCheck>false</ser:strictPreAuthCheck>\n\t\t\t\t\t\t\t<ser:negate>false</ser:negate>\n\t\t\t\t\t\t</ser:templateControl>\n\t\t\t\t\t</ser:fullTemplateRuleDetails>\n\t\t\t\t\t<ser:templateCustomField>\n\t\t\t\t\t\t<ser:templateCustomField>\n\t\t\t\t\t\t\t<ser1:customFieldName>Purchase Type</ser1:customFieldName>\n\t\t\t\t\t\t\t<ser1:customFieldValue>Airlines</ser1:customFieldValue>\n\t\t\t\t\t\t</ser:templateCustomField>\n\t\t\t\t\t</ser:templateCustomField>\n\t\t\t\t</ser:TemplateDetails2>\n\t\t\t\t<ser:supplierDetails>\n\t\t\t\t\t<ser:supplierId>14100</ser:supplierId>\n\t\t\t\t</ser:supplierDetails>\n           <ser:disableCardImage>N</ser:disableCardImage>\n\t\t\t</ser:SubmitPurchaseRequest>\n\t\t</ser:submitPurchaseRequestRequest>\n\t</soapenv:Body>\n</soapenv:Envelope>"
                summary: Sample request without ICMP enabled
              '2':
                value: |-
                  <soapenv:Envelope
                     xmlns:ser="http://mastercard.com/sd/pc2/service"
                     xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                     xmlns:ser1="http://mastercard.com/sd/pc/service">
                     <soapenv:Header/>
                     <soapenv:Body
                        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd">
                        <ser:submitPurchaseRequestRequest>
                           <ser:SubmitPurchaseRequest>
                              <ser:RCNData>
                              <ser1:rcnId>29875</ser1:rcnId>
                              <ser1:rcnAlias>MY RCN ALIAS</ser1:rcnAlias>
                              </ser:RCNData>
                              <ser:dataSourceId>4272</ser:dataSourceId>
                              <ser:companyId>481710</ser:companyId>
                              <ser:validFor>12</ser:validFor>
                              <ser:description>A Purchase Request</ser:description>
                              <ser:TemplateDetails2>
                                 <ser:templateId>43137</ser:templateId>
                                 <ser:fullTemplateRuleDetails>
                                    <ser:ruleName>My First Rule</ser:ruleName>
                                    <ser:ruleType>A</ser:ruleType>
                                    <ser:templateControl
                                       xsi:type="ser:VelocityControlType2"
                                       xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">
                                       <ser:maxTrans>1</ser:maxTrans>
                                       <ser:cumulativeLimit>149.54</ser:cumulativeLimit>
                                       <ser:period>C</ser:period>
                                       <ser:currencyType>B</ser:currencyType>
                                       <ser:currencyCode>840</ser:currencyCode>
                                       <ser:endDate>2020-12-26-05:00</ser:endDate>
                                    </ser:templateControl>
                                 </ser:fullTemplateRuleDetails>
                                 <ser:templateCustomField>
                                    <ser:templateCustomField>
                                       <ser1:customFieldName>Purchase Type</ser1:customFieldName>
                                       <ser1:customFieldValue>Test1</ser1:customFieldValue>
                                    </ser:templateCustomField>
                                 </ser:templateCustomField>
                              </ser:TemplateDetails2>
                              <ser:userDetails>
                                 <ser:firstName>First-Name</ser:firstName>
                                 <ser:lastName>Last-Name</ser:lastName>
                                 <ser:email>Email-Address@mastercard.com</ser:email>
                                 <ser:mobileCountryCode>+1</ser:mobileCountryCode>
                                 <ser:mobileNumber>1111111111</ser:mobileNumber>
                              </ser:userDetails>
                              <ser:vcnDelivery>EMAIL</ser:vcnDelivery>
                           </ser:SubmitPurchaseRequest>
                        </ser:submitPurchaseRequestRequest>
                     </soapenv:Body>
                  </soapenv:Envelope>
                summary: Sample request with ICMP enabled
      responses:
        '200':
          description: ''
          content:
            application/xml:
              schema:
                type: object
                properties:
                  ns2:getPurchaseRequestDetail:
                    type: object
                    properties:
                      ns2:purchaseRequestId:
                        type: string
                        description: "Application assigned ID for each purchase request.\t"
                      ns2:requestStatus:
                        type: string
                        description: >-
                          Approved: The purchase request is approved and the VCN
                          is ready to use.

                          Canceled: The purchase request and the VCN are no
                          longer in use.

                          Draft: The purchase request has not yet been
                          submitted.
                      ns2:PurchaseRequestTemplateDetails:
                        type: object
                        properties:
                          ns2:templateId:
                            type: string
                          ns2:fullTemplateRuleDetails:
                            type: object
                            properties:
                              ns2:ruleName:
                                type: string
                              ns2:ruleType:
                                type: string
                              ns2:templateControl:
                                type: object
                                properties:
                                  ns2:maxTrans:
                                    type: string
                                  ns2:cumulativeLimit:
                                    type: string
                                  ns2:period:
                                    type: string
                                  ns2:availableBalance:
                                    type: string
                                  ns2:currencyType:
                                    type: string
                                  ns2:endDate:
                                    type: string
                                required:
                                  - ns2:maxTrans
                                  - ns2:cumulativeLimit
                                  - ns2:period
                                  - ns2:availableBalance
                                  - ns2:currencyType
                                  - ns2:endDate
                                x-apidog-orders:
                                  - ns2:maxTrans
                                  - ns2:cumulativeLimit
                                  - ns2:period
                                  - ns2:availableBalance
                                  - ns2:currencyType
                                  - ns2:endDate
                            required:
                              - ns2:ruleName
                              - ns2:ruleType
                              - ns2:templateControl
                            x-apidog-orders:
                              - ns2:ruleName
                              - ns2:ruleType
                              - ns2:templateControl
                          ns2:templateCustomField:
                            type: object
                            properties:
                              ns2:templateCustomField:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    customFieldName:
                                      type: string
                                    customFieldValue:
                                      type: string
                                  required:
                                    - customFieldName
                                    - customFieldValue
                                  x-apidog-orders:
                                    - customFieldName
                                    - customFieldValue
                            required:
                              - ns2:templateCustomField
                            x-apidog-orders:
                              - ns2:templateCustomField
                        required:
                          - ns2:templateId
                          - ns2:fullTemplateRuleDetails
                          - ns2:templateCustomField
                        x-apidog-orders:
                          - ns2:templateId
                          - ns2:fullTemplateRuleDetails
                          - ns2:templateCustomField
                      ns2:vcnInformation:
                        type: object
                        properties:
                          ns2:Id:
                            type: string
                          ns2:Pan:
                            type: string
                          ns2:Expiry:
                            type: string
                          ns2:Avv:
                            type: string
                          ns2:Status:
                            type: string
                          ns2:EVCNIndicator:
                            type: string
                        required:
                          - ns2:Id
                          - ns2:Pan
                          - ns2:Expiry
                          - ns2:Avv
                          - ns2:Status
                          - ns2:EVCNIndicator
                        x-apidog-orders:
                          - ns2:Id
                          - ns2:Pan
                          - ns2:Expiry
                          - ns2:Avv
                          - ns2:Status
                          - ns2:EVCNIndicator
                      ns2:cardImage:
                        type: string
                        description: "HTML code for the VCN card image.\t"
                      ns2:supplierDetails:
                        type: object
                        properties:
                          ns2:supplierId:
                            type: string
                          ns2:notifySupplier:
                            type: string
                        required:
                          - ns2:supplierId
                          - ns2:notifySupplier
                        x-apidog-orders:
                          - ns2:supplierId
                          - ns2:notifySupplier
                    required:
                      - ns2:purchaseRequestId
                      - ns2:requestStatus
                      - ns2:PurchaseRequestTemplateDetails
                      - ns2:vcnInformation
                      - ns2:cardImage
                      - ns2:supplierDetails
                    x-apidog-orders:
                      - ns2:purchaseRequestId
                      - ns2:requestStatus
                      - ns2:PurchaseRequestTemplateDetails
                      - ns2:vcnInformation
                      - ns2:cardImage
                      - ns2:supplierDetails
                x-apidog-orders:
                  - ns2:getPurchaseRequestDetail
                xml:
                  name: soapenv:Envelope
              examples:
                '1':
                  summary: Sample response without ICMP enabled
                  value: >-
                    <soapenv:Envelope
                    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
                       <soapenv:Body>
                          <ns2:getPurchaseRequestDetail xmlns="http://mastercard.com/sd/pc/service"
                             xmlns:ns2="http://mastercard.com/sd/pc2/service">
                             <ns2:purchaseRequestId>5293</ns2:purchaseRequestId>
                             <ns2:requestStatus>Approved</ns2:requestStatus>
                             <ns2:PurchaseRequestTemplateDetails>
                                <ns2:templateId>1907</ns2:templateId>
                                <ns2:fullTemplateRuleDetails>
                                   <ns2:ruleName>1</ns2:ruleName>
                                   <ns2:ruleType>A</ns2:ruleType>
                                   <ns2:templateControl xsi:type="ns2:VelocityControlType2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                                      <ns2:maxTrans>10</ns2:maxTrans>
                                      <ns2:cumulativeLimit>1000.0</ns2:cumulativeLimit>
                                      <ns2:period>D</ns2:period>
                                      <ns2:availableBalance>1000.0</ns2:availableBalance>
                                      <ns2:currencyType>B</ns2:currencyType>
                                      <ns2:endDate>2014-11-12</ns2:endDate>
                                   </ns2:templateControl>
                                </ns2:fullTemplateRuleDetails>
                                <ns2:templateCustomField>
                                   <ns2:templateCustomField>
                                      <customFieldName>Purchase Type</customFieldName>
                                      <customFieldValue>Contracted Services</customFieldValue>
                                   </ns2:templateCustomField>
                                   <ns2:templateCustomField>
                                      <customFieldName>CDF1</customFieldName>
                                      <customFieldValue/>
                                   </ns2:templateCustomField>
                                   <ns2:templateCustomField>
                                      <customFieldName>CDF2</customFieldName>
                                      <customFieldValue/>
                                   </ns2:templateCustomField>
                                   <ns2:templateCustomField>
                                      <customFieldName>CDF3</customFieldName>
                                      <customFieldValue/>
                                   </ns2:templateCustomField>
                                   <ns2:templateCustomField>
                                      <customFieldName>CDF4</customFieldName>
                                      <customFieldValue/>
                                   </ns2:templateCustomField>
                                </ns2:templateCustomField>
                             </ns2:PurchaseRequestTemplateDetails>
                             <ns2:vcnInformation>
                                <ns2:Id>3653</ns2:Id>
                                <ns2:Pan>541275XXXXXX9999</ns2:Pan>
                                <ns2:Expiry>1611</ns2:Expiry>
                                <ns2:Avv>664</ns2:Avv>
                                <ns2:Status>S</ns2:Status>
                                <ns2:EVCNIndicator>false</ns2:EVCNIndicator>
                             </ns2:vcnInformation>
                             <ns2:cardImage>Card Image in HTML code</ns2:cardImage>
                             <ns2:supplierDetails>
                                <ns2:supplierId>850</ns2:supplierId>
                                <ns2:notifySupplier>false</ns2:notifySupplier>
                             </ns2:supplierDetails>
                          </ns2:getPurchaseRequestDetail>
                       </soapenv:Body>
                    </soapenv:Envelope>
                '2':
                  summary: Sample response with ICMP enabled
                  value: >-
                    <S:Envelope
                    xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
                       <S:Body>
                          <ns2:getPurchaseRequestDetail xmlns="http://mastercard.com/sd/pc/service" xmlns:ns2="http://mastercard.com/sd/pc2/service">
                             <ns2:purchaseRequestId>90370</ns2:purchaseRequestId>
                             <ns2:requestStatus>Approved</ns2:requestStatus>
                             <ns2:PurchaseRequestTemplateDetails>
                                <ns2:templateId>108291</ns2:templateId>
                                <ns2:fullTemplateRuleDetails>
                                   <ns2:ruleName>B</ns2:ruleName>
                                   <ns2:ruleType>A</ns2:ruleType>
                                   <ns2:templateControl xsi:type="ns2:VelocityControlType2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                                      <ns2:maxTrans>5</ns2:maxTrans>
                                      <ns2:cumulativeLimit>6345.0</ns2:cumulativeLimit>
                                      <ns2:period>D</ns2:period>
                                      <ns2:availableBalance>6345.0</ns2:availableBalance>
                                      <ns2:currencyType>B</ns2:currencyType>
                                      <ns2:endDate>2023-08-16</ns2:endDate>
                                   </ns2:templateControl>
                                </ns2:fullTemplateRuleDetails>
                                <ns2:templateCustomField>
                                   <ns2:templateCustomField>
                                      <customFieldName>Purchase Type</customFieldName>
                                      <customFieldValue>Airlines</customFieldValue>
                                   </ns2:templateCustomField>
                                </ns2:templateCustomField>
                             </ns2:PurchaseRequestTemplateDetails>
                             <ns2:vcnInformation>
                                <ns2:Id>39306</ns2:Id>
                                <ns2:Pan>5522448030968415</ns2:Pan>
                                <ns2:Expiry>2508</ns2:Expiry>
                                <ns2:Avv>384</ns2:Avv>
                                <ns2:Status>S</ns2:Status>
                                <ns2:EVCNIndicator>false</ns2:EVCNIndicator>
                             </ns2:vcnInformation>
                             <ns2:addenda>
                                <tripLeg/>
                                <railDetail/>
                                <travelAgency/>
                             </ns2:addenda>
                             <ns2:userDetails>
                                <ns2:firstName>mockfirstname</ns2:firstName>
                                <ns2:lastName>mocklastname</ns2:lastName>
                                <ns2:email>mockemail@test.com</ns2:email>
                                <ns2:mobileCountryCode>+1</ns2:mobileCountryCode>
                                <ns2:mobileNumber>204567890</ns2:mobileNumber>
                             </ns2:userDetails>
                             <ns2:vcnDelivery>EMAIL</ns2:vcnDelivery>
                          </ns2:getPurchaseRequestDetail>
                       </S:Body>
                    </S:Envelope>
          headers: {}
          x-apidog-name: Success
      security: []
      x-apidog-folder: 'SOAP API Documentations/Example: Mastercard'
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/849209/apis/api-15123596-run
components:
  schemas: {}
  securitySchemes: {}
servers: []
security: []

```