{"_id":"59525a4328e9ae004b965939","category":{"_id":"59525a4328e9ae004b965923","version":"59525a4328e9ae004b96591c","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-03T20:45:01.593Z","from_sync":false,"order":6,"slug":"topics","title":"Guides"},"user":"560d5913af97231900938124","project":"57336fd5a6a9c40e00e13a0b","parentDoc":null,"version":{"_id":"59525a4328e9ae004b96591c","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2017-06-27T13:14:43.386Z","releaseDate":"2017-06-27T13:14:43.386Z","categories":["59525a4328e9ae004b96591d","59525a4328e9ae004b96591e","59525a4328e9ae004b96591f","59525a4328e9ae004b965920","59525a4328e9ae004b965921","59525a4328e9ae004b965922","59525a4328e9ae004b965923"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"v.3.22.0 release","version_clean":"8976.0.0-Basics","version":"8976-Basics"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-18T13:40:19.122Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":9,"body":"[MasterPass](https://masterpass.com) is a digital wallet that securely stores a shopper's payment and shipping details. It supports all major credit and debit card types, including MasterCard, Visa, American Express, Discover, Diners, and JCB. You may wish to offer MasterPass in order to increase conversions across devices, including mobile devices.\n\nThe MasterPass payment method is automatically available to you with the Payment API.\n\n*The shopper experience with MasterPass* \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/qxNLUV5qRY2jcQc9DHRw_MasterPass_API_checkout_flow.png\",\n        \"MasterPass_API_checkout_flow.png\",\n        \"869\",\n        \"333\",\n        \"#e04123\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n#Supported Markets\nMasterPass is available for merchants in the following countries (updated 2/2017). \n[block:html]\n{\n  \"html\": \"<div>\\n   <ul class=\\\"cols\\\">\\n     <li>Australia</li>\\n     <li>Belgium</li>\\n     <li>Brazil </li>\\n     <li>Canada </li>\\n     <li>China </li>\\n     <li>Colombia</li>\\n     <li>Czech Republic</li>\\n     <li>France</li>\\n     <li>Germany</li>\\n     <li>Greece</li>\\n     <li>Hong Kong</li>\\n     <li>Hungary</li>\\n   </ul>\\n\\n   <ul class=\\\"cols\\\">\\n      <li>India</li>\\n   \\t <li>Ireland</li>\\n     <li>Israel </li>\\n     <li>Italy</li>\\n     <li>Japan</li>\\n     <li>New Zealand</li>\\n     <li>Poland</li>\\n     <li>Romania</li>\\n     <li>Russian Federation</li>\\n     <li>Singapore</li>\\n     <li>Slovak Republic</li>\\n     <li>South Africa</li>\\n   </ul>\\n  \\n   <ul class=\\\"cols\\\">\\n     <li>South Korea</li> \\n     <li>Spain</li>\\n     <li>Sweden</li>\\n     <li>Switzerland</li>\\n     <li>Taiwan</li>\\n     <li>Turkey</li>\\n     <li>Ukraine</li>\\n     <li>United Arab Emirates</li>\\n     <li>United Kingdom</li>\\n     <li>United States</li>\\n\\n   </ul>\\n</div>\\n\\n<style>\\n  .cols {\\ndisplay:inline-block;\\nvertical-align:top;\\n}\\n</style>\"\n}\n[/block]\nItems purchased with MasterPass can be shipped to any country, as long as that country is not listed on the U.S. Department of Treasury Office of Foreign Assets Control (OFAC) sanctioned list. For more information, click [here](https://www.treasury.gov/resource-center/sanctions/Programs/Pages/Programs.aspx). \n\n#Implementing MasterPass via the API\nThese steps describe how to implement MasterPass in either the Payment API or Extended Payment API:\n  * [Step 1: Add the MasterPass button to your checkout form](#section-step-1-add-the-masterpass-button-to-your-checkout-form)\n  * [Step 2: Send the Create Wallet request to receive fields for the MasterPass lightbox](#section-step-2-send-the-create-wallet-request-to-receive-fields-for-the-masterpass-lightbox)\n  * [Step 3: Add scripts and call the handleBuyWithMasterPass JS function ](#section-step-3-add-scripts-and-call-the-handlebuywithmasterpass-js-function)\n  * [Step 4: Shopper completes MasterPass step](#section-step-4-shopper-completes-masterpass-step)\n  * [Step 5: Get the wallet ID and retrieve wallet details](#section-step-6-get-final-shopper-confirmation)\n  * [Step 6: Get final shopper confirmation](#section-step-7-process-the-transaction)\n  * Step 7: Process the transaction:\n    * [In the Payment API](#section-in-the-payment-api)\n    * [In the Extended Payment API](#section-in-the-extended-payment-api)\n\n##Step 1: Add the MasterPass button to your checkout form\nAdd the MasterPass button to your checkout form. The example below shows the link for the US English button. For a full list of MasterPass buttons per country and language, [see this document](https://developer.mastercard.com/documentation/masterpass-merchant-integration#masterpass-checkout-button-and-acceptance-marks).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Upon implementing MasterPass, please comply with the [MasterPass branding requirements](https://developer.mastercard.com/documentation/masterpass-merchant-integration#masterpass-checkout-button-and-acceptance-marks).\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div id=\\\"checkoutButtonDiv\\\" onClick=\\\"createWallet();\\\">\\n  <a href=\\\"#\\\"> \\n    <img src=\\\"https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png\\\" alt=\\\"Buy with MasterPass\\\">\\n  </a>\\n</div>\",\n      \"language\": \"html\",\n      \"name\": \"MasterPass button in checkout form\"\n    }\n  ]\n}\n[/block]\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Step 2: Send the Create Wallet request to receive fields for the MasterPass lightbox\nWhen the shopper clicks the MasterPass button, you will need to provide some parameters and get the fields required to launch the MasterPass lightbox.\n\nTo do this, send a [Create Wallet](/v4.0/docs/create-wallet) request with the wallet type set to MASTERPASS, and include the `originUrl` and `returnUrl`. For more information, see the [wallet](/v4.0/docs/wallet) resource.\n\nThis request should be sent to: `services/2/wallets`\n\nFollowing is a sample Create Wallet request:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"walletType\\\": \\\"MASTERPASS\\\",\\n    \\\"originUrl\\\": \\\"http://www.originURL.com\\\",\\n    \\\"returnUrl\\\": \\\"http://www.returnURL.com\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create Wallet request for MasterPass\"\n    }\n  ]\n}\n[/block]\nUpon success, you will receive a response similar to the following, with the `walletToken`, `merchantCheckoutId`, and `allowedCardTypes`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"allowedCardTypes\\\": \\\"master,amex,diners,discover,visa\\\",\\n    \\\"walletType\\\": \\\"MASTERPASS\\\",\\n    \\\"merchantCheckoutId\\\": \\\"a4a6w4vkqzjnzikhr6ihj1ikqnlqhu5ymb\\\",\\n    \\\"walletToken\\\": \\\"f9babd23df00acc9b049ac4694d2344f8f73f4e8\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create Wallet response for MasterPass\"\n    }\n  ]\n}\n[/block]\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Step 3: Add scripts and call the handleBuyWithMasterPass JS function \nPut the scripts below in the header of your checkout form page. When you receive the response to your Create Wallet request, add the fields from the response into the `handleBuyWithMasterPass` JS function and then call the function.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<meta http-equiv=\\\"Content-Type\\\"\\tcontent=\\\"text/html; charset=windows-1255\\\">\\n<script type=\\\"text/javascript\\\" src=\\\"Scripts/jquery-1.5.1.js\\\"></script>\\n<script type=\\\"text/javascript\\\" src=\\\"https://sandbox.masterpass.com/lightbox/Switch/integration/MasterPass.client.js\\\"></script>\\n<script>\\n\\tfunction handleBuyWithMasterPass() {\\n\\t\\tMasterPass.client.checkout({\\n\\t\\t\\t\\\"requestToken\\\" : \\\"${data.requestToken}\\\",\\n\\\"callbackUrl\\\" : \\\"https://sandbox.bluesnap.com/services/WalletCallbackServlet?wallet_type=MASTERPASS\\\",\\n\\t\\t\\t\\\"merchantCheckoutId\\\" : \\\"${data.merchantCheckoutId}\\\",\\n\\t\\t\\t\\\"allowedCardTypes\\\" : \\\"${data.allowedCardTypes}\\\",\\n\\t\\t\\t\\\"cancelCallback\\\" : \\\"${data.callbackDomain}\\\",\\n\\t\\t\\t\\\"version\\\" : \\\"v6\\\"\\n\\t\\t});\\n\\t}\\n</script>\",\n      \"language\": \"html\",\n      \"name\": \"handleBuyWithMasterPass function\"\n    }\n  ]\n}\n[/block]\nFields:\n  * **requestToken**: Insert the wallet token\n  * **callbackUrl**: Use the URL shown in the example above\n  * **merchantCheckoutId**: Insert the merchant checkout ID\n  * **allowedCardTypes**: Insert the allowed card types\n  * **cancelCallback**: Insert the URL where the shopper should be redirected if they cancel out of the MasterPass lightbox\n  * **version**: Use the version shown in the example above\n\n**Note: In production, the MasterPass URL should be changed to: `https://www.masterpass.com/lightbox/Switch/integration/MasterPass.client.js`**\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Step 4: Shopper completes MasterPass step\nOnce you call the `handleBuyWithMasterPass` JS function, the MasterPass lightbox opens. The shopper logs in to MasterPass or creates a new MasterPass account. The shopper then confirms payment, billing and shipping info, and clicks Finish Shopping upon completion. The lightbox will show a processing indication until the you redirect the shopper to the review order page (step 6 below).\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Step 5: Get the wallet ID and retrieve wallet details\nWhen the shopper completes the MasterPass step, BlueSnap sends a GET request to the return URL you specified. The request includes an `operation=success/failure` parameter, to indicate whether the transaction was successful in MasterPass.\n\nIf `operation=success`, BlueSnap sends the wallet ID. For example:\n`https://www.merchant.com/WalletServlet?operation=success&walletId=546`\n**Make sure to obtain this wallet ID, as you will need it to complete the rest of the process.**\n\nIf `operation=failure`, BlueSnap sends the error name, code, and description. For example:\n`https://www.merchant.com/WalletServlet?operation=failure&errorName=WALLET_PROCESSING_FAILURE&code=23003&description=Wallet processor is currently unavailable, please try again later`\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Step 6: Get final shopper confirmation\nIf the shopper has successfully completed the MasterPass step, send a [Retrieve Wallet](/v4.0/docs/retrieve-wallet) request to get the wallet details, including the shopper's information. \n\nThis request should be sent to: `services/2/wallets/{walletId}`\n\nInsert the ID of the wallet in the request URL. For example:\n`services/2/wallets/546`\n\nIn the response, you will receive the `wallet` resource with the shopper's payment, shipping and billing info. For more information, see the [wallet](/v4.0/docs/wallet) resource.\n\nRedirect the shopper to a confirmation page and display the information from the wallet, in order to get the shopper's final approval for the purchase and payment.\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Step 7: Process the transaction\nOnce you have the shopper's final approval, you are ready to process the transaction. Follow the steps below for the Payment API or the Extended Payment API.\n\n###In the Payment API\nThere are two different ways to do this:\n\n**Option 1. Create or update a Vaulted Shopper with the wallet info, and then use the vaulted shopper ID in the Auth Capture or Auth Only request**\n\nYou can save the shopper's information from the wallet by including it in a [Create Vaulted Shopper](/v2.1/docs/create-vaulted-shopper) or [Update Vaulted Shopper](/v2.1/docs/update-vaulted-shopper) request.\n\nThen just send a standard [Auth Only](/v2.1/docs/auth-only) or [Auth Capture](/v2.1/docs/auth-capture) request with the vaulted shopper ID.\n\n**Option 2. Add the wallet ID directly in your Auth Capture or Auth Only request**\n\nYou can instead include the wallet ID directly in an [Auth Only](/v2.1/docs/auth-only) or [Auth Capture](/v2.1/docs/auth-capture) request. \n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"walletId\\\": 21,\\n    \\\"amount\\\": 35,\\n    \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Auth Capture with wallet ID\"\n    }\n  ]\n}\n[/block]\n###In the Extended Payment API\nThere are two different ways to do this:\n\n**Option 1. Create or update a Shopper with the wallet info, and then use the shopper ID in the Create Order with Existing Shopper or Create Shopping Context request**\n\nYou can save the shopper's information from the wallet by including it in a [Create Shopper](/v3.0/docs/create-shopper) or [Update Shopper](/v3.0/docs/update-shopper) request.\n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<shopper xmlns=\\\"http://ws.plimus.com\\\">\\n  <web-info>\\n    <ip>62.219.121.253</ip>\\n  </web-info>\\n  <shopper-info>\\n    <store-id>11580</store-id>\\n    <shopper-currency>USD</shopper-currency>\\n  </shopper-info>\\n  <wallet-id>21</wallet-id>\\n</shopper>\",\n      \"language\": \"xml\",\n      \"name\": \"Create Shopper with wallet ID\"\n    }\n  ]\n}\n[/block]\nThen just send a standard [Create Order with Existing Shopper](/v3.0/docs/create-order) or [Create Shopping Context](/v3.0/docs/create-shopping-context) request with the shopper ID.\n\n**Option 2. Add the wallet ID directly in Create Order and New Shopper request**\n\nYou can instead include the wallet ID directly in a [Create Order and New Shopper](/v3.0/docs/create-shopper-and-order) request.\n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<batch-order xmlns=\\\"http://ws.plimus.com\\\">\\n  <shopper xmlns=\\\"http://ws.plimus.com\\\">\\n    <web-info>\\n     <ip>62.219.121.253</ip>\\n    </web-info>\\n    <shopper-info>\\n      <store-id>11580</store-id>\\n      <shopper-currency>USD</shopper-currency>\\n    </shopper-info>\\n    <wallet-id>21</wallet-id>\\n  </shopper>\\n  <order>\\n    <ordering-shopper>\\n        <web-info>\\n        <ip>62.219.121.253</ip>\\n        <remote-host>www.merchant.com</remote-host>\\n        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n      </web-info>\\n    </ordering-shopper>\\n    <cart>\\n      <cart-item>\\n        <sku>\\n        <sku-id>2183716</sku-id>\\n        </sku>\\n        <quantity>1</quantity>\\n      </cart-item>\\n    </cart>\\n    <expected-total-price>\\n      <amount>10</amount>\\n      <currency>USD</currency>\\n    </expected-total-price>\\n  </order>\\n</batch-order>\",\n      \"language\": \"xml\",\n      \"name\": \"Create Order and New Shopper with wallet ID\"\n    }\n  ]\n}\n[/block]\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>","excerpt":"","slug":"masterpass","type":"basic","title":"MasterPass"}

MasterPass is a digital wallet that securely stores a shopper's payment and shipping details. It supports all major credit and debit card types, including MasterCard, Visa, American Express, Discover, Diners, and JCB. You may wish to offer MasterPass in order to increase conversions across devices, including mobile devices.

The MasterPass payment method is automatically available to you with the Payment API.

The shopper experience with MasterPass

Supported Markets

MasterPass is available for merchants in the following countries (updated 2/2017).

  • Australia
  • Belgium
  • Brazil
  • Canada
  • China
  • Colombia
  • Czech Republic
  • France
  • Germany
  • Greece
  • Hong Kong
  • Hungary
  • India
  • Ireland
  • Israel
  • Italy
  • Japan
  • New Zealand
  • Poland
  • Romania
  • Russian Federation
  • Singapore
  • Slovak Republic
  • South Africa
  • South Korea
  • Spain
  • Sweden
  • Switzerland
  • Taiwan
  • Turkey
  • Ukraine
  • United Arab Emirates
  • United Kingdom
  • United States

Items purchased with MasterPass can be shipped to any country, as long as that country is not listed on the U.S. Department of Treasury Office of Foreign Assets Control (OFAC) sanctioned list. For more information, click here.

Implementing MasterPass via the API

These steps describe how to implement MasterPass in either the Payment API or Extended Payment API:

Step 1: Add the MasterPass button to your checkout form

Add the MasterPass button to your checkout form. The example below shows the link for the US English button. For a full list of MasterPass buttons per country and language, see this document.

Upon implementing MasterPass, please comply with the MasterPass branding requirements.

<div id="checkoutButtonDiv" onClick="createWallet();">
  <a href="#"> 
    <img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png" alt="Buy with MasterPass">
  </a>
</div>



Back to Top

Step 2: Send the Create Wallet request to receive fields for the MasterPass lightbox

When the shopper clicks the MasterPass button, you will need to provide some parameters and get the fields required to launch the MasterPass lightbox.

To do this, send a Create Wallet request with the wallet type set to MASTERPASS, and include the originUrl and returnUrl. For more information, see the wallet resource.

This request should be sent to: services/2/wallets

Following is a sample Create Wallet request:

{
    "walletType": "MASTERPASS",
    "originUrl": "http://www.originURL.com",
    "returnUrl": "http://www.returnURL.com"
}

Upon success, you will receive a response similar to the following, with the walletToken, merchantCheckoutId, and allowedCardTypes:

{
    "allowedCardTypes": "master,amex,diners,discover,visa",
    "walletType": "MASTERPASS",
    "merchantCheckoutId": "a4a6w4vkqzjnzikhr6ihj1ikqnlqhu5ymb",
    "walletToken": "f9babd23df00acc9b049ac4694d2344f8f73f4e8"
}



Back to Top

Step 3: Add scripts and call the handleBuyWithMasterPass JS function

Put the scripts below in the header of your checkout form page. When you receive the response to your Create Wallet request, add the fields from the response into the handleBuyWithMasterPass JS function and then call the function.

<meta http-equiv="Content-Type"	content="text/html; charset=windows-1255">
<script type="text/javascript" src="Scripts/jquery-1.5.1.js"></script>
<script type="text/javascript" src="https://sandbox.masterpass.com/lightbox/Switch/integration/MasterPass.client.js"></script>
<script>
	function handleBuyWithMasterPass() {
		MasterPass.client.checkout({
			"requestToken" : "${data.requestToken}",
"callbackUrl" : "https://sandbox.bluesnap.com/services/WalletCallbackServlet?wallet_type=MASTERPASS",
			"merchantCheckoutId" : "${data.merchantCheckoutId}",
			"allowedCardTypes" : "${data.allowedCardTypes}",
			"cancelCallback" : "${data.callbackDomain}",
			"version" : "v6"
		});
	}
</script>

Fields:

  • requestToken: Insert the wallet token
  • callbackUrl: Use the URL shown in the example above
  • merchantCheckoutId: Insert the merchant checkout ID
  • allowedCardTypes: Insert the allowed card types
  • cancelCallback: Insert the URL where the shopper should be redirected if they cancel out of the MasterPass lightbox
  • version: Use the version shown in the example above

Note: In production, the MasterPass URL should be changed to: https://www.masterpass.com/lightbox/Switch/integration/MasterPass.client.js



Back to Top

Step 4: Shopper completes MasterPass step

Once you call the handleBuyWithMasterPass JS function, the MasterPass lightbox opens. The shopper logs in to MasterPass or creates a new MasterPass account. The shopper then confirms payment, billing and shipping info, and clicks Finish Shopping upon completion. The lightbox will show a processing indication until the you redirect the shopper to the review order page (step 6 below).



Back to Top

Step 5: Get the wallet ID and retrieve wallet details

When the shopper completes the MasterPass step, BlueSnap sends a GET request to the return URL you specified. The request includes an operation=success/failure parameter, to indicate whether the transaction was successful in MasterPass.

If operation=success, BlueSnap sends the wallet ID. For example:
https://www.merchant.com/WalletServlet?operation=success&walletId=546
Make sure to obtain this wallet ID, as you will need it to complete the rest of the process.

If operation=failure, BlueSnap sends the error name, code, and description. For example:
https://www.merchant.com/WalletServlet?operation=failure&errorName=WALLET_PROCESSING_FAILURE&code=23003&description=Wallet processor is currently unavailable, please try again later



Back to Top

Step 6: Get final shopper confirmation

If the shopper has successfully completed the MasterPass step, send a Retrieve Wallet request to get the wallet details, including the shopper's information.

This request should be sent to: services/2/wallets/{walletId}

Insert the ID of the wallet in the request URL. For example:
services/2/wallets/546

In the response, you will receive the wallet resource with the shopper's payment, shipping and billing info. For more information, see the wallet resource.

Redirect the shopper to a confirmation page and display the information from the wallet, in order to get the shopper's final approval for the purchase and payment.



Back to Top

Step 7: Process the transaction

Once you have the shopper's final approval, you are ready to process the transaction. Follow the steps below for the Payment API or the Extended Payment API.

In the Payment API

There are two different ways to do this:

Option 1. Create or update a Vaulted Shopper with the wallet info, and then use the vaulted shopper ID in the Auth Capture or Auth Only request

You can save the shopper's information from the wallet by including it in a Create Vaulted Shopper or Update Vaulted Shopper request.

Then just send a standard Auth Only or Auth Capture request with the vaulted shopper ID.

Option 2. Add the wallet ID directly in your Auth Capture or Auth Only request

You can instead include the wallet ID directly in an Auth Only or Auth Capture request.

For example:

{
    "walletId": 21,
    "amount": 35,
    "recurringTransaction": "ECOMMERCE",
    "currency": "USD",
    "cardTransactionType": "AUTH_CAPTURE"
}

In the Extended Payment API

There are two different ways to do this:

Option 1. Create or update a Shopper with the wallet info, and then use the shopper ID in the Create Order with Existing Shopper or Create Shopping Context request

You can save the shopper's information from the wallet by including it in a Create Shopper or Update Shopper request.

For example:

<shopper xmlns="http://ws.plimus.com">
  <web-info>
    <ip>62.219.121.253</ip>
  </web-info>
  <shopper-info>
    <store-id>11580</store-id>
    <shopper-currency>USD</shopper-currency>
  </shopper-info>
  <wallet-id>21</wallet-id>
</shopper>

Then just send a standard Create Order with Existing Shopper or Create Shopping Context request with the shopper ID.

Option 2. Add the wallet ID directly in Create Order and New Shopper request

You can instead include the wallet ID directly in a Create Order and New Shopper request.

For example:

<batch-order xmlns="http://ws.plimus.com">
  <shopper xmlns="http://ws.plimus.com">
    <web-info>
     <ip>62.219.121.253</ip>
    </web-info>
    <shopper-info>
      <store-id>11580</store-id>
      <shopper-currency>USD</shopper-currency>
    </shopper-info>
    <wallet-id>21</wallet-id>
  </shopper>
  <order>
    <ordering-shopper>
        <web-info>
        <ip>62.219.121.253</ip>
        <remote-host>www.merchant.com</remote-host>
        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
      </web-info>
    </ordering-shopper>
    <cart>
      <cart-item>
        <sku>
        <sku-id>2183716</sku-id>
        </sku>
        <quantity>1</quantity>
      </cart-item>
    </cart>
    <expected-total-price>
      <amount>10</amount>
      <currency>USD</currency>
    </expected-total-price>
  </order>
</batch-order>