Build API Docs with Apidog
  1. Example: Mastercard
Build API Docs with Apidog
  • Overview
  • REST API Documentations
    • Basics
      • API-Design First Approach
      • Specify an endpoint
      • Components
      • Common parameters
      • Global parameters
      • Schemas
        • Overview
        • Create a new schema
        • Build a schema
        • Generate Schemas from JSON etc.
    • Advanced features
      • Custom endpoint fields
      • Endpoint status
      • Appearance of parameter lists
      • Endpoint unique idenfication
    • Example: Pet Store
      • Get user info
      • Find pet by ID
      • Add a new pet to the store
      • Update an existing pet
      • Deletes a pet
      • Finds Pets by status
  • SOAP API Documentations
    • How to Use Apidog to Write SOAP API Documentation
    • Example: WebService
      • WebService: Number To Words
      • SOAP: Add integers
      • SOAP/WSDL: Ebay
    • Example: Mastercard
      • Purchase Request
      • Submit a purchase request
        POST
  • GraphQL Documentation
    • How to Write GraphQL API Documentation Using Apidog
    • Example: Github
      • Introduction to GraphQL
      • Queries
      • Public schema
  • WebSocket Documentations
    • How to Use Apidog to Write WebSocket API Documentation
    • Example: Coinbase
      • Overview
      • Channel
  • SSE API Documentations
    • Example: Anthropic
      • Streaming Messages
      • Messages
  • gRPC API Documentations
    • How to Use Apidog for gRPC API Documentation and Testing
    • Example: Proto Documentation
      • Protocol Documentation
  1. Example: Mastercard

Submit a purchase request

POST
/soap
Submit a purchase request to generate a Virtual Card Number (VCN).
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request POST '/soap' \
--header 'Idempotency-Key: Any random UUID set in HTTP Request Header	' \
--header 'Content-Type: text/xml' \
--data-raw '<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-wss-wssecurity-utility-1.0.xsd">
		<ser:submitPurchaseRequestRequest>
			<ser:SubmitPurchaseRequest>
				<ser:RCNData>
					<ser1:rcnId>13800</ser1:rcnId>
					<ser1:rcnAlias>Sandbox Card</ser1:rcnAlias>
				</ser:RCNData>
				<ser:dataSourceId>4272</ser:dataSourceId>
				<ser:companyId>427521</ser:companyId>
				<ser:validFor>12</ser:validFor>
				<ser:description>My Purchase Request</ser:description>
				<ser:TemplateDetails2>
					<ser:templateId>21680</ser:templateId>
					<ser:fullTemplateRuleDetails>
						<ser:ruleName>My Rule</ser:ruleName>
						<ser:ruleType>A</ser:ruleType>
						<ser:templateControl xsi:type="ser:VelocityControlType2"
							xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
							<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:templateControl xsi:type="ser:templateValidityPeriodControl2"
							xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
							<ser:from>2020-04-04</ser:from>
							<ser:to>2020-12-26</ser:to>
							<ser:timeZone>Europe/London</ser:timeZone>
							<ser:strictPreAuthCheck>false</ser:strictPreAuthCheck>
							<ser:negate>false</ser:negate>
						</ser:templateControl>
					</ser:fullTemplateRuleDetails>
					<ser:templateCustomField>
						<ser:templateCustomField>
							<ser1:customFieldName>Purchase Type</ser1:customFieldName>
							<ser1:customFieldValue>Airlines</ser1:customFieldValue>
						</ser:templateCustomField>
					</ser:templateCustomField>
				</ser:TemplateDetails2>
				<ser:supplierDetails>
					<ser:supplierId>14100</ser:supplierId>
				</ser:supplierDetails>
           <ser:disableCardImage>N</ser:disableCardImage>
			</ser:SubmitPurchaseRequest>
		</ser:submitPurchaseRequestRequest>
	</soapenv:Body>
</soapenv:Envelope>'
Response Response Example
Sample response without ICMP enabled
<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>

Request

Header Params
Idempotency-Key
string 
optional
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.
Example:
Any random UUID set in HTTP Request Header
Content-Type
string 
optional
Example:
text/xml
Body Params application/xml
ser:SubmitPurchaseRequest
object 
required
Submit a purchase request to generate a Virtual Card Number (VCN).
ser:RCNData
object 
required
RCN details to create a VCN.
You can use the getRealCards call to get the RCN details.
ser:dataSourceId
integer 
required
Obtained through the getDataSource call.
ser:companyId
string 
required
ID of your company. You can use the getCompanies call to get a list of company IDs to create purchase requests for.
ser:validFor
integer 
required
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.
ser:description
string 
required
Add a description up to 80 characters describing the purchase request.
ser:TemplateDetails2
object 
required
Contains the template ID and the rule details.
ser:supplierDetails
object 
required
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.
ser:disableCardImage
string 
required
ser:addendaDataExpected
boolean 
optional
Specify Y or N if you want to add the invoice addenda record to a purchase request. Refer the Addenda chapter for more details.
s
boolean 
required
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.
Examples

Responses

🟢200Success
application/xml
Body
ns2:getPurchaseRequestDetail
object 
optional
ns2:purchaseRequestId
string 
required
Application assigned ID for each purchase request.
ns2:requestStatus
string 
required
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
object 
required
ns2:vcnInformation
object 
required
ns2:cardImage
string 
required
HTML code for the VCN card image.
ns2:supplierDetails
object 
required
Modified at 2025-03-25 07:12:44
Previous
Purchase Request
Next
How to Write GraphQL API Documentation Using Apidog
Built with