{"_id":"5c6c238ff7d5480039535599","project":"57336fd5a6a9c40e00e13a0b","version":{"_id":"5c6c238ff7d54800395355a0","project":"57336fd5a6a9c40e00e13a0b","__v":1,"forked_from":"5beb278ac442ab0213f009cf","createdAt":"2018-04-23T14:36:48.535Z","releaseDate":"2018-04-23T14:36:48.535Z","categories":["5c6c238ff7d548003953555d","5c6c238ff7d548003953555e","5c6c238ff7d548003953555f","5c6c238ff7d5480039535560","5c6c238ff7d5480039535561","5c6c238ff7d5480039535562","5beb278ac442ab0213f00990","5c6c238ff7d5480039535563","5c3f542c12c4ac004bc51718","5c928dba4aa821001ae4f050"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Main","version_clean":"8976.0.0-Basics","version":"8976-Basics"},"category":{"_id":"5c6c238ff7d5480039535563","version":"5c6c238ff7d54800395355a0","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-03T20:45:01.593Z","from_sync":false,"order":7,"slug":"topics","title":"Guides"},"user":"5b155c2c3fbcd30003e76908","githubsync":"","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-06-11T15:25:17.829Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"As part of a continued commitment to a cardholder’s security, the card brands have introduced guidelines on how your shopper’s payment information can be stored and used.  If you have repeat shoppers, or offer subscriptions, you must obtain your shopper's consent to store their card information for future purchases and then flag each transaction as a single purchase or as a regularly scheduled subscription.\n\nThis guide is intended to provide guidance for implementing this functionality with:\n\n* [Payment API](#section-implementing-card-on-file-with-payment-api)\n* [Extended API](#section-implementing-card-on-file-with-extended-api)\n* [Hosted Solutions](#section-implementing-card-on-file-with-buynow-merchants)  \n\n###Supported cards:\n* Visa\n* MasterCard\n* Discover\n* Diners\n[block:api-header]\n{\n  \"title\": \"Implementing Card on File with Payment API\"\n}\n[/block]\nIf you’re using our [Payment API](https://developers.bluesnap.com/v8976-JSON/docs), here are the instructions on how to implement Card on File as it relates to the storage and use of your shopper’s data.\n\n##Step 1: Add a shopper approval box using the Payment API\n\nYou must add this box to your checkout page. This is where your shoppers provide their consent to have their payment information stored for future transactions. For example:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/92a36d0-securely_store_card.png\",\n        \"securely_store_card.png\",\n        576,\n        136,\n        \"#c6c7c7\"\n      ],\n      \"sizing\": \"smart\",\n      \"border\": true\n    }\n  ]\n}\n[/block]\nThe result from this approval box is used to populate a new “*store card*” parameter. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"If the products you sell do not require a recurring payment, or if you prefer not to store your shopper’s payment information, you can omit this approval box and set this value to “false.”\"\n}\n[/block]\n##Step 2: Include parameters with your transaction requests\nFor the Payment API, you must send the following parameters with your transaction requests:\n\n* **store card** — Use with [Auth](https://developers.bluesnap.com/v8976-JSON/docs/auth-only) or [Auth/Capture](https://developers.bluesnap.com/v8976-JSON/docs/auth-capture) requests to indicate if the shopper provided permissions to store their payment data. The expected value of this parameter is `true` or `false`; `true` is the default value.\n\n* **scheduled** — Use with [Create Merchant-Managed Subscription](https://developers.bluesnap.com/v8976-JSON/docs/create-merchant-managed-subscription) and [Retrieve Specific Subscription](https://developers.bluesnap.com/v8976-JSON/docs/retrieve-specific-subscription) to specify if the subscription is a regularly-scheduled event. The expected value of this parameter is `true` or `false`; `true` is the default value.\nYou might use this to have your shopper’s account automatically “topped off” when the account balance drops below a specified amount. For example, you would use \"Create Merchant-Managed Subscription\" with `scheduled`=`false` to charge the shopper's card $25 when their account balance is less than $10. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"For [BlueSnap-managed subscriptions](https://developers.bluesnap.com/v8976-XML/docs/create-subscription) and [merchant-managed subscriptions](https://developers.bluesnap.com/v8976-XML/docs/create-merchant-managed-subscription), we automatically set both parameters to `true`.  You only need to change the values if you want a different workflow.\"\n}\n[/block]\n###Payment API Code samples\n\nTo perform a standard JSON [Auth/Capture](https://developers.bluesnap.com/v8976-JSON/docs/auth-capture) or XML [Auth/Capture](https://developers.bluesnap.com/v8976-XML/docs/auth-capture):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 11,\\n    \\\"storeCard\\\": true,\\n    \\\"softDescriptor\\\": \\\"DescTest\\\",\\n    \\\"cardHolderInfo\\\": {\\n        \\\"firstName\\\": \\\"test first name\\\",\\n        \\\"lastName\\\": \\\"test last name\\\", \\n      \\t\\\"zip\\\": \\\"123456\\\"\\n    },\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"creditCard\\\": {\\n        \\\"expirationYear\\\": \\\"2023\\\",\\n        \\\"securityCode\\\": \\\"837\\\",\\n        \\\"expirationMonth\\\": \\\"02\\\",\\n        \\\"cardNumber\\\": \\\"4263982640269299\\\"\\n    },\\n    \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"JSON\"\n    },\n    {\n      \"code\": \"<card-transaction xmlns=\\\"http://ws.plimus.com\\\">\\n   <soft-descriptor>DescTest</soft-descriptor>\\n   <store-card>true</store-card>\\n   <amount>11.00</amount>\\n   <currency>USD</currency>\\n   <card-holder-info>\\n       <first-name>test first name</first-name>\\n       <last-name>test last name</last-name>\\n       <zip>123456</zip>\\n   </card-holder-info>\\n   <credit-card>\\n      <card-number>4263982640269299</card-number>\\n      <security-code>837</security-code>\\n      <expiration-month>02</expiration-month>\\n      <expiration-year>2023</expiration-year>\\n   </credit-card>\\n</card-transaction>\",\n      \"language\": \"xml\",\n      \"name\": \"XML\"\n    }\n  ]\n}\n[/block]\nTo \"top off\" an account, use a JSON [Create Merchant-Managed Subscription](https://developers.bluesnap.com/v8976-JSON/docs/create-merchant-managed-subscription) or XML [Create Merchant-Managed Subscription](https://developers.bluesnap.com/v8976-XML/docs/create-merchant-managed-subscription):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n    \\\"transactionId\\\": \\\"1019988199\\\",\\n    \\\"softDescriptor\\\": \\\"BLS*DescTest\\\",\\n    \\\"amount\\\": 11,\\n    \\\"usdAmount\\\": 11,\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"cardHolderInfo\\\": {\\n        \\\"firstName\\\": \\\"test first name\\\",\\n        \\\"lastName\\\": \\\"test last name\\\",\\n        \\\"zip\\\": \\\"123456\\\"\\n    },\\n    \\\"vaultedShopperId\\\": 23902603,\\n    \\\"creditCard\\\": {\\n        \\\"cardLastFourDigits\\\": \\\"9299\\\",\\n        \\\"cardType\\\": \\\"VISA\\\",\\n        \\\"cardSubType\\\": \\\"CREDIT\\\",\\n        \\\"cardCategory\\\": \\\"PLATINUM\\\",\\n        \\\"binCategory\\\": \\\"CONSUMER\\\",\\n        \\\"cardRegulated\\\": \\\"N\\\",\\n        \\\"issuingBank\\\": \\\"ALLIED IRISH BANKS PLC\\\",\\n        \\\"issuingCountryCode\\\": \\\"ie\\\"\\n    },\\n    \\\"processingInfo\\\": {\\n        \\\"processingStatus\\\": \\\"success\\\",\\n        \\\"cvvResponseCode\\\": \\\"MA\\\",\\n        \\\"avsResponseCodeZip\\\": \\\"U\\\",\\n        \\\"avsResponseCodeAddress\\\": \\\"U\\\",\\n        \\\"avsResponseCodeName\\\": \\\"U\\\"\\n    },\\n    \\\"fraudResultInfo\\\": {\\n        \\\"deviceDataCollector\\\": \\\"N\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"JSON\"\n    },\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\" standalone=\\\"yes\\\"?>\\n<card-transaction xmlns=\\\"http://ws.plimus.com\\\">\\n    <card-transaction-type>AUTH_CAPTURE</card-transaction-type>\\n    <transaction-id>1019988369</transaction-id>\\n    <soft-descriptor>BLS&#x2a;DescTest</soft-descriptor>\\n    <amount>11.00</amount>\\n    <usd-amount>11.00</usd-amount>\\n    <currency>USD</currency>\\n    <card-holder-info>\\n        <first-name>test first name</first-name>\\n        <last-name>test last name</last-name>\\n        <zip>123456</zip>\\n    </card-holder-info>\\n    <vaulted-shopper-id>23902609</vaulted-shopper-id>\\n    <credit-card>\\n        <card-last-four-digits>9299</card-last-four-digits>\\n        <card-type>VISA</card-type>\\n        <card-sub-type>CREDIT</card-sub-type>\\n        <card-category>PLATINUM</card-category>\\n        <bin-category>CONSUMER</bin-category>\\n        <card-regulated>N</card-regulated>\\n        <issuing-bank>ALLIED IRISH BANKS PLC</issuing-bank>\\n        <issuing-country-code>ie</issuing-country-code>\\n    </credit-card>\\n    <processing-info>\\n        <processing-status>success</processing-status>\\n        <cvv-response-code>MA</cvv-response-code>\\n        <avs-response-code-zip>U</avs-response-code-zip>\\n        <avs-response-code-address>U</avs-response-code-address>\\n        <avs-response-code-name>U</avs-response-code-name>\\n    </processing-info>\\n    <fraud-result-info>\\n        <device-data-collector>N</device-data-collector>\\n    </fraud-result-info>\\n</card-transaction>\",\n      \"language\": \"xml\",\n      \"name\": \"XML\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n[block:api-header]\n{\n  \"title\": \"Implementing Card on File with Extended API\"\n}\n[/block]\nIf you’re using our [Extended Payment API](https://developers.bluesnap.com/v8976-Extended/docs), here are the instructions on how to implement Card on File as it relates to the storage and use of your shopper’s data.\n\n##Step 1: Add a shopper approval box using the Extended API\n\nYou must add this box to your checkout page. This is where your shoppers provide their consent to have their payment information stored. For example:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8c9c664-securely_store_card.png\",\n        \"securely_store_card.png\",\n        576,\n        136,\n        \"#c6c7c7\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\nThe result from this approval box are used to populate a new “store-card” parameter.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"If the products you sell do not require a recurring payment, or if you prefer not to store your shopper’s payment information, you can omit this approval box and set this value to “false.”\"\n}\n[/block]\n##Step 2: Include the store-card parameter with your transaction requests\nFor the Extended API, you must send the following parameter with your transaction requests:\n\n* **store-card**– Use with [Create Order and New Shopper](https://developers.bluesnap.com/v8976-Extended/docs/create-shopper-and-order) and [Create Shopping Context](https://developers.bluesnap.com/v8976-Extended/docs/create-shopping-context) requests to indicate if the shopper provided permissions to store their payment data. The expected values of this parameter are “true” or “false” with the default value set as “true.”\n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n[block:api-header]\n{\n  \"title\": \"Implementing Card on File with Hosted Solutions\"\n}\n[/block]\nIf you’re using our [Hosted Solutions](https://support.bluesnap.com/docs/intro-hosted-checkout), you notice a few changes on your checkout page.\n\n* A checkbox lets shoppers authorize the storage of their payment information for future purchases. For example:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ffe878d-securely_store_card.png\",\n        \"securely_store_card.png\",\n        576,\n        136,\n        \"#c6c7c7\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\n* If the product being purchased is subscription/recurring based, this checkbox is mandatory and needs to be checked by the shopper to proceed with the order. The “Submit” button is disabled and a message to the shopper displays: “Your credit card must be stored in order to run recurring transactions.”\n\n* If the shopper is *not* purchasing a recurring product, the checkbox is optional. If the shopper does not check the box, we do not store the shopper’s payment information.\n\n* If a cart includes multiple items and there is at least one recurring product, the checkbox is **mandatory.**\n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>","excerpt":"","slug":"card-on-file","type":"basic","title":"Card on File"}

As part of a continued commitment to a cardholder’s security, the card brands have introduced guidelines on how your shopper’s payment information can be stored and used. If you have repeat shoppers, or offer subscriptions, you must obtain your shopper's consent to store their card information for future purchases and then flag each transaction as a single purchase or as a regularly scheduled subscription.

This guide is intended to provide guidance for implementing this functionality with:

Supported cards:

  • Visa
  • MasterCard
  • Discover
  • Diners

Implementing Card on File with Payment API

If you’re using our Payment API, here are the instructions on how to implement Card on File as it relates to the storage and use of your shopper’s data.

Step 1: Add a shopper approval box using the Payment API

You must add this box to your checkout page. This is where your shoppers provide their consent to have their payment information stored for future transactions. For example:

The result from this approval box is used to populate a new “store card” parameter.

Note:

If the products you sell do not require a recurring payment, or if you prefer not to store your shopper’s payment information, you can omit this approval box and set this value to “false.”

Step 2: Include parameters with your transaction requests

For the Payment API, you must send the following parameters with your transaction requests:

  • store card — Use with Auth or Auth/Capture requests to indicate if the shopper provided permissions to store their payment data. The expected value of this parameter is true or false; true is the default value.

  • scheduled — Use with Create Merchant-Managed Subscription and Retrieve Specific Subscription to specify if the subscription is a regularly-scheduled event. The expected value of this parameter is true or false; true is the default value.
    You might use this to have your shopper’s account automatically “topped off” when the account balance drops below a specified amount. For example, you would use "Create Merchant-Managed Subscription" with scheduled=false to charge the shopper's card $25 when their account balance is less than $10.

Note:

For BlueSnap-managed subscriptions and merchant-managed subscriptions, we automatically set both parameters to true. You only need to change the values if you want a different workflow.

Payment API Code samples

To perform a standard JSON Auth/Capture or XML Auth/Capture:

{
    "amount": 11,
    "storeCard": true,
    "softDescriptor": "DescTest",
    "cardHolderInfo": {
        "firstName": "test first name",
        "lastName": "test last name", 
      	"zip": "123456"
    },
    "currency": "USD",
    "creditCard": {
        "expirationYear": "2023",
        "securityCode": "837",
        "expirationMonth": "02",
        "cardNumber": "4263982640269299"
    },
    "cardTransactionType": "AUTH_CAPTURE"
}
<card-transaction xmlns="http://ws.plimus.com">
   <soft-descriptor>DescTest</soft-descriptor>
   <store-card>true</store-card>
   <amount>11.00</amount>
   <currency>USD</currency>
   <card-holder-info>
       <first-name>test first name</first-name>
       <last-name>test last name</last-name>
       <zip>123456</zip>
   </card-holder-info>
   <credit-card>
      <card-number>4263982640269299</card-number>
      <security-code>837</security-code>
      <expiration-month>02</expiration-month>
      <expiration-year>2023</expiration-year>
   </credit-card>
</card-transaction>
{
    "cardTransactionType": "AUTH_CAPTURE",
    "transactionId": "1019988199",
    "softDescriptor": "BLS*DescTest",
    "amount": 11,
    "usdAmount": 11,
    "currency": "USD",
    "cardHolderInfo": {
        "firstName": "test first name",
        "lastName": "test last name",
        "zip": "123456"
    },
    "vaultedShopperId": 23902603,
    "creditCard": {
        "cardLastFourDigits": "9299",
        "cardType": "VISA",
        "cardSubType": "CREDIT",
        "cardCategory": "PLATINUM",
        "binCategory": "CONSUMER",
        "cardRegulated": "N",
        "issuingBank": "ALLIED IRISH BANKS PLC",
        "issuingCountryCode": "ie"
    },
    "processingInfo": {
        "processingStatus": "success",
        "cvvResponseCode": "MA",
        "avsResponseCodeZip": "U",
        "avsResponseCodeAddress": "U",
        "avsResponseCodeName": "U"
    },
    "fraudResultInfo": {
        "deviceDataCollector": "N"
    }
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<card-transaction xmlns="http://ws.plimus.com">
    <card-transaction-type>AUTH_CAPTURE</card-transaction-type>
    <transaction-id>1019988369</transaction-id>
    <soft-descriptor>BLS&#x2a;DescTest</soft-descriptor>
    <amount>11.00</amount>
    <usd-amount>11.00</usd-amount>
    <currency>USD</currency>
    <card-holder-info>
        <first-name>test first name</first-name>
        <last-name>test last name</last-name>
        <zip>123456</zip>
    </card-holder-info>
    <vaulted-shopper-id>23902609</vaulted-shopper-id>
    <credit-card>
        <card-last-four-digits>9299</card-last-four-digits>
        <card-type>VISA</card-type>
        <card-sub-type>CREDIT</card-sub-type>
        <card-category>PLATINUM</card-category>
        <bin-category>CONSUMER</bin-category>
        <card-regulated>N</card-regulated>
        <issuing-bank>ALLIED IRISH BANKS PLC</issuing-bank>
        <issuing-country-code>ie</issuing-country-code>
    </credit-card>
    <processing-info>
        <processing-status>success</processing-status>
        <cvv-response-code>MA</cvv-response-code>
        <avs-response-code-zip>U</avs-response-code-zip>
        <avs-response-code-address>U</avs-response-code-address>
        <avs-response-code-name>U</avs-response-code-name>
    </processing-info>
    <fraud-result-info>
        <device-data-collector>N</device-data-collector>
    </fraud-result-info>
</card-transaction>

Implementing Card on File with Extended API

If you’re using our Extended Payment API, here are the instructions on how to implement Card on File as it relates to the storage and use of your shopper’s data.

Step 1: Add a shopper approval box using the Extended API

You must add this box to your checkout page. This is where your shoppers provide their consent to have their payment information stored. For example:

The result from this approval box are used to populate a new “store-card” parameter.

Note:

If the products you sell do not require a recurring payment, or if you prefer not to store your shopper’s payment information, you can omit this approval box and set this value to “false.”

Step 2: Include the store-card parameter with your transaction requests

For the Extended API, you must send the following parameter with your transaction requests:

  • store-card– Use with Create Order and New Shopper and Create Shopping Context requests to indicate if the shopper provided permissions to store their payment data. The expected values of this parameter are “true” or “false” with the default value set as “true.”

Back to Top

Implementing Card on File with Hosted Solutions

If you’re using our Hosted Solutions, you notice a few changes on your checkout page.

  • A checkbox lets shoppers authorize the storage of their payment information for future purchases. For example:
  • If the product being purchased is subscription/recurring based, this checkbox is mandatory and needs to be checked by the shopper to proceed with the order. The “Submit” button is disabled and a message to the shopper displays: “Your credit card must be stored in order to run recurring transactions.”

  • If the shopper is not purchasing a recurring product, the checkbox is optional. If the shopper does not check the box, we do not store the shopper’s payment information.

  • If a cart includes multiple items and there is at least one recurring product, the checkbox is mandatory.

Back to Top