{"_id":"5b1e945d5d19ab000334eeb6","project":"57336fd5a6a9c40e00e13a0b","version":{"_id":"5b1972b45952df0003e8a725","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"5addef809a4b8c0003207f4c","createdAt":"2018-04-23T14:36:48.535Z","releaseDate":"2018-04-23T14:36:48.535Z","categories":["5b1972b45952df0003e8a6e3","5b1972b45952df0003e8a6e4","5b1972b45952df0003e8a6e5","5b1972b45952df0003e8a6e6","5b1972b45952df0003e8a6e7","5b1972b45952df0003e8a6e8","5b1972b45952df0003e8a6e9","5b1972b45952df0003e8a6ea"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"3.26 Release","version_clean":"8976.0.0-Basics","version":"8976-Basics"},"category":{"_id":"5b1972b45952df0003e8a6ea","version":"5b1972b45952df0003e8a725","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","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-06-11T15:25:17.829Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"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 will need to obtain your shoppers 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* [BuyNow Hosted Solutions](#section-implementing-card-on-file-with-buynow-merchants) \n\n###Supported cards:\n\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 to your checkout page \n\nThis is where your shoppers will 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/0364223-Store_my_card.png\",\n        \"Store my card.png\",\n        282,\n        22,\n        \"#e1e1e0\"\n      ],\n      \"sizing\": \"smart\"\n    }\n  ]\n}\n[/block]\nThe result from this approval box will be 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 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 values of this parameter are “true” or “false” with the default value set as “true.”\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 identify if the subscription is a regularly scheduled event. \n\nThe expected values for this parameter are “true” or “false” with the default value set as \"false.\" A common use case for a \"create merchant managed subscription\", with scheduled=**false** would be having your shopper’s stored value account automatically “topped off” if the account balance drops below a specified amount. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"For [regularly scheduled 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) \\\\managed by BlueSnap, you do not need to populate these parameters as we will automatically set them to “true.”\"\n}\n[/block]\n###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   <card-transaction-type>AUTH_CAPTURE</card-transaction-type>\\n   <recurring-transaction>ECOMMERCE</recurring-transaction>\\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  \\\"amount\\\": 45, \\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"scheduled\\\": false,\\n  \\\"payerInfo\\\": {\\n    \\\"firstName\\\": \\\"John\\\",\\n    \\\"lastName\\\": \\\"Doe\\\",\\n    \\\"zip\\\": \\\"12345\\\",\\n    \\\"country\\\": \\\"us\\\"\\n  },\\n  \\\"paymentSource\\\": {\\n    \\\"creditCardInfo\\\": {\\n      \\\"creditCard\\\": {\\n        \\\"expirationYear\\\": \\\"2023\\\",\\n        \\\"securityCode\\\": \\\"111\\\",\\n        \\\"expirationMonth\\\": \\\"05\\\",\\n        \\\"cardNumber\\\": 4012000033330026\\n      }\\n    }\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"JSON\"\n    },\n    {\n      \"code\": \"<charge xmlns=\\\"http://ws.plimus.com\\\">\\n  <amount>45</amount>\\n  <currency>USD</currency>\\n  <scheduled>false</scheduled>\\n  <payer-info>\\n    <first-name>John</first-name>\\n    <last-name>Doe</last-name>\\n    <zip>12345</zip>\\n    <country>us</country>\\n  </payer-info>\\n  <payment-source>\\n    <credit-card-info>\\n      <credit-card>\\n        <card-number>4012000033330026</card-number>\\n        <security-code>111</security-code>\\n        <expiration-month>05</expiration-month>\\n        <expiration-year>2023</expiration-year>\\n      </credit-card>\\n    </credit-card-info>\\n  </payment-source>\\n</charge>\",\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 to your checkout page \n\nThis is where your shoppers will 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/be26a7a-Store_my_card.png\",\n        \"Store my card.png\",\n        282,\n        22,\n        \"#e1e1e0\"\n      ]\n    }\n  ]\n}\n[/block]\nThe result from this approval box will be 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 following parameters 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* **scheduled **– Use with [Create Subscription Charge](https://developers.bluesnap.com/v8976-Extended/docs/create-subscription-charge) and [Retrieve Subscription Charge](https://developers.bluesnap.com/v8976-Extended/docs/retrieve-subscription-charge) to identify if the transaction is a regularly scheduled event. The expected values for this parameter are “true” or “false.”  \n\nThe default value for [Create Subscription Charge](https://developers.bluesnap.com/v8976-Extended/docs/create-subscription-charge) is “false.” A common use case for this scenario would be having a shopper’s stored value automatically “topped off,” if the account balance drops below a specified amount. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"For [regularly scheduled subscriptions](https://developers.bluesnap.com/v8976-Extended/docs/create-subscription-charge) managed by BlueSnap, you do not need to populate this parameter as we will automatically set it to “true.”\"\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 BuyNow Merchants\"\n}\n[/block]\nIf you’re using our [BuyNow Hosted Solutions](https://support.bluesnap.com/docs/intro-hosted-checkout), you will notice a few changes on your checkout page.\n\n* A checkbox will display for shoppers to 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/b6abde3-Store_my_card.png\",\n        \"Store my card.png\",\n        282,\n        22,\n        \"#e1e1e0\"\n      ]\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 will be 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 will 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 will need to obtain your shoppers 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 to your checkout page

This is where your shoppers will provide their consent to have their payment information stored for future transactions; for example:

The result from this approval box will be 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 following parameters with your transaction requests:

The expected values for this parameter are “true” or “false” with the default value set as "false." A common use case for a "create merchant managed subscription", with scheduled=false would be having your shopper’s stored value account automatically “topped off” if the account balance drops below a specified amount.

Note:

For regularly scheduled subscriptions and merchant-managed subscriptions \managed by BlueSnap, you do not need to populate these parameters as we will automatically set them to “true.”

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">
   <card-transaction-type>AUTH_CAPTURE</card-transaction-type>
   <recurring-transaction>ECOMMERCE</recurring-transaction>
   <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>
{
  "amount": 45, 
  "currency": "USD",
  "scheduled": false,
  "payerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "zip": "12345",
    "country": "us"
  },
  "paymentSource": {
    "creditCardInfo": {
      "creditCard": {
        "expirationYear": "2023",
        "securityCode": "111",
        "expirationMonth": "05",
        "cardNumber": 4012000033330026
      }
    }
  }
}
<charge xmlns="http://ws.plimus.com">
  <amount>45</amount>
  <currency>USD</currency>
  <scheduled>false</scheduled>
  <payer-info>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <zip>12345</zip>
    <country>us</country>
  </payer-info>
  <payment-source>
    <credit-card-info>
      <credit-card>
        <card-number>4012000033330026</card-number>
        <security-code>111</security-code>
        <expiration-month>05</expiration-month>
        <expiration-year>2023</expiration-year>
      </credit-card>
    </credit-card-info>
  </payment-source>
</charge>

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 to your checkout page

This is where your shoppers will provide their consent to have their payment information stored; for example:

The result from this approval box will be 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 following parameters with your transaction requests:

The default value for Create Subscription Charge is “false.” A common use case for this scenario would be having a shopper’s stored value automatically “topped off,” if the account balance drops below a specified amount.

Note:

For regularly scheduled subscriptions managed by BlueSnap, you do not need to populate this parameter as we will automatically set it to “true.”

Implementing Card on File with BuyNow Merchants

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

  • A checkbox will display for shoppers to 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 will be 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 will 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