{"_id":"59dfa8f45c0bae001c2e8af3","category":{"_id":"59dfa8f45c0bae001c2e8ae9","version":"59dfa8f45c0bae001c2e8ae8","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-01T16:04:11.135Z","from_sync":false,"order":0,"slug":"welcome","title":"Quickstart"},"project":"57336fd5a6a9c40e00e13a0b","parentDoc":null,"user":"560d5913af97231900938124","version":{"_id":"59dfa8f45c0bae001c2e8ae8","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2017-10-12T17:40:04.535Z","releaseDate":"2017-10-12T17:40:04.535Z","categories":["59dfa8f45c0bae001c2e8ae9","59dfa8f45c0bae001c2e8aea","59dfa8f45c0bae001c2e8aeb","59dfa8f45c0bae001c2e8aec","59dfa8f45c0bae001c2e8aed","59dfa8f45c0bae001c2e8aee","59dfa8f45c0bae001c2e8aef","59dfa8f45c0bae001c2e8af0"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"3.23. Release","version_clean":"8976.0.0-Basics","version":"8976-Basics"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-18T19:33:49.270Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"This tutorial will walk you through the essentials of using the Payment API to process payments, including:\n  * Making your first credit card charge, using the Auth Capture API call\n  * Reviewing the API response and possible errors\n  * Additional powerful features you may want to use, like vaulted shoppers, metadata, and PayPal support\n  * Tips for testing\n\nThis tutorial assumes that you are using BlueSnap's Hosted Payment Fields to collect shopper credit card information. If you don't yet have an app or form where you collect shopper payment details, [go to this tutorial](doc:build-a-form), where we'll walk you through setting up a checkout form.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Need a BlueSnap account?\",\n  \"body\": \"You will need a BlueSnap account in order to get your API credentials and start sending requests from your server. If you don't have an account yet, you can [sign up for one here](http://home.bluesnap.com/get-started/).\\n\\nIf you just want to try out API requests and see responses without setting up your server or getting an account, you can do that right here in the documentation, using our API Explorer tool. Jump into any of the API endpoints and go to the **Try it here!** section. You can try out different parameters and test credit card numbers to see exactly how your test scenario would work.\"\n}\n[/block]\n##Step 1: Send an Auth Capture request\nIn order to process payments, you will send requests to the API from your server, using your own server-side language like Java, Ruby, Python, or another. The example in this tutorial provides just the JSON content of the request, which you will need to send as specified by your server-side language.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"JSON and XML supported\",\n  \"body\": \"This tutorial shows JSON examples. The API also supports XML - for more info, see [Payment API (XML)](/v2.0/docs).\"\n}\n[/block]\n###Auth Capture request overview\nIn this example, you'll create an [Auth Capture](/v2.1/docs/auth-capture) request containing the payment information you collected from the shopper.\n\nAn Auth Capture performs two actions via a single request:\n  * **authorize**: checks whether a credit card is valid and has the funds to complete a specific transaction (i.e. purchase)\n  * **capture**: submits the authorized transaction for settlement (i.e. payment by the shopper)\n\nThe request includes the [cardTransaction](/v2.1/docs/card-transaction) resource, which contains information about the transaction, such as the transaction type, amount, and currency.\n\nThis tutorial assumes that you are using BlueSnap's [Hosted Payment Fields](/v4.0/docs/hosted-payment-fields) to collect shopper credit card information, so the request must also include your Hosted Payment Fields token.\n\n###Example Auth Capture request\nBelow is an example of a simple Auth Capture request with a Hosted Payment Fields token. This request contains the basic information required to process a one-time payment using a credit card. For more details and additional examples of this request, see [Auth Capture](/v2.1/docs/auth-capture).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 50,\\n    \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n    \\\"cardHolderInfo\\\": {\\n        \\\"firstName\\\": \\\"Jane\\\",\\n        \\\"lastName\\\": \\\"Shopper\\\"\\n    },\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n    \\\"pfToken\\\": \\\"abcde12345**********\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Auth Capture Request\"\n    }\n  ]\n}\n[/block]\n###Sending the request\nOnce you have built the request, send it to the transactions endpoint in the Payment API. In the BlueSnap sandbox environment, this is the URL for the transactions endpoint:\n`https://sandbox.bluesnap.com/services/2/transactions`\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Step 2: Response and error handling\nAfter you send the request, if all goes well, you will receive a 200 OK response with content similar to the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 50,\\n    \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n    \\\"processingInfo\\\": {\\n        \\\"avsResponseCodeAddress\\\": \\\"M\\\",\\n        \\\"processingStatus\\\": \\\"success\\\",\\n        \\\"cvvResponseCode\\\": \\\"MA\\\",\\n        \\\"avsResponseCodeName\\\": \\\"U\\\",\\n        \\\"avsResponseCodeZip\\\": \\\"M\\\"\\n    },\\n    \\\"cardHolderInfo\\\": {\\n        \\\"firstName\\\": \\\"Jane\\\",\\n        \\\"lastName\\\": \\\"Shopper\\\"\\n    },\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"creditCard\\\": {\\n        \\\"cardLastFourDigits\\\": 1111,\\n        \\\"cardSubType\\\": \\\"CREDIT\\\",\\n        \\\"cardType\\\": \\\"VISA\\\"\\n    },\\n    \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n    \\\"transactionId\\\": 38486450\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Auth Capture Response - 200 OK\"\n    }\n  ]\n}\n[/block]\nThe response includes:\n  * `processingInfo` = details about the processing status and results of CVV/AVS checks\n  * `transactionId` = a unique ID that BlueSnap assigns to this transaction\nIf an issue occurs, whether a validation error with the information you sent, an error from the processor, or another type of issue, you will instead receive an HTTP 400 or 500 response with a BlueSnap error code and description. For more information, see [Error handling overview](/v2.1/docs/error-handling-overview).\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Step 3: Power tools: vaulted shoppers, metadata, PayPal, digital wallets, and more\nNow that you know how to send a basic transaction, there are some more options you'll want to take advantage of in order to optimize payment processing according to your business needs. Here are a few key ones:\n\n###Vaulted shoppers\nMake the checkout process smoother and payment processing easier by saving shopper details in BlueSnap and getting an ID that represents that shopper's profile. You can then use that ID to retrieve the shopper's details or process transactions. See [Create Vaulted Shopper](/v2.1/docs/create-vaulted-shopper).\n\n###Metadata\nPass any data you wish along with the transaction. This can be useful if you want to send tax or shipping information, or details about the product such as size or color. See [Metadata](/v2.1/docs/metadata).\n\n###PayPal\nMany merchants wish to offer shoppers the ability to pay seamlessly via PayPal, one of the most common payment methods. BlueSnap makes it easy to accept PayPal by simply connecting your PayPal and BlueSnap accounts and then using our dedicated API calls for PayPal transactions. See [PayPal](doc:paypal).\n\n###Digital wallets\nBlueSnap supports digital wallets, like Apple Pay, MasterPass, and Visa Checkout, that enable your shoppers to make fast and easy payments across all their devices. These wallets securely store the shopper's payment and shipping details and support all major credit and debit card types, including MasterCard, Visa, American Express, Discover, and more.\nFor more information, see:\n  * [Apple Pay Guide](/v1.0/docs/apple-pay)\n  * [MasterPass Guide](/v1.0/docs/masterpass)\n  * [Visa Checkout Guide](/v1.0/docs/visa-checkout)\n\n###More tutorials\nSee these tutorials for more tips about getting the most out of the Payment API:\n  * [Subscriptions guide](/v2.1/docs/subscription-management)\n  * [Returning shopper tutorial](/v2.1/docs/returning-shopper-tutorial) \n  * [Enabling and Disabling Cards](https://support.bluesnap.com/docs/payment-method-setup#section-enable-disable-specific-cards)\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Step 4: Testing\n\n###Test credit card numbers\nWhen you are creating test requests, it is recommended to the use the test credit card numbers we provide, which are designed to generate specific success or failure responses. See [Test credit card numbers](doc:test-credit-cards).\n\n###Locating transactions in the Merchant Console\nOnce you have sent a transaction and received a response, you can also go into the Merchant Console to verify that the order has appeared there.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The order record will be found only if you sent the transaction request from the same account that you used in order to log in to the Merchant Console. It will not appear if you sent the request through the API Explorer in this documentation.\"\n}\n[/block]\n1. In the Merchant Console, go to **Transactions > Find a Transaction**.\n2. In the field next to **Reference Number**, enter the value from the `transactionId` field in the response you received from the API. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/48b97da-FindTransaction.png\",\n        \"FindTransaction.png\",\n        838,\n        302,\n        \"#f1f1f1\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n3. Click **Locate**, and then the order record will appear. It includes details such as the price, quantity, shopper information, options to resend the receipt or Instant Payment Notification, and more.\n\n<br>\n<a class=\"btn btn-primary\" href=\"/docs/prepare-for-launch\" role=\"button\">You're ready to Launch & Get Paid!</a>","excerpt":"Once you have securely collected your shopper's payment information, you can use BlueSnap's Payment API and your server-side code to start processing payments.","slug":"make-a-payment-payment-api","type":"basic","title":"Charge a Card"}

Charge a Card

Once you have securely collected your shopper's payment information, you can use BlueSnap's Payment API and your server-side code to start processing payments.

This tutorial will walk you through the essentials of using the Payment API to process payments, including:

  • Making your first credit card charge, using the Auth Capture API call
  • Reviewing the API response and possible errors
  • Additional powerful features you may want to use, like vaulted shoppers, metadata, and PayPal support
  • Tips for testing

This tutorial assumes that you are using BlueSnap's Hosted Payment Fields to collect shopper credit card information. If you don't yet have an app or form where you collect shopper payment details, go to this tutorial, where we'll walk you through setting up a checkout form.

Need a BlueSnap account?

You will need a BlueSnap account in order to get your API credentials and start sending requests from your server. If you don't have an account yet, you can sign up for one here.

If you just want to try out API requests and see responses without setting up your server or getting an account, you can do that right here in the documentation, using our API Explorer tool. Jump into any of the API endpoints and go to the Try it here! section. You can try out different parameters and test credit card numbers to see exactly how your test scenario would work.

Step 1: Send an Auth Capture request

In order to process payments, you will send requests to the API from your server, using your own server-side language like Java, Ruby, Python, or another. The example in this tutorial provides just the JSON content of the request, which you will need to send as specified by your server-side language.

JSON and XML supported

This tutorial shows JSON examples. The API also supports XML - for more info, see Payment API (XML).

Auth Capture request overview

In this example, you'll create an Auth Capture request containing the payment information you collected from the shopper.

An Auth Capture performs two actions via a single request:

  • authorize: checks whether a credit card is valid and has the funds to complete a specific transaction (i.e. purchase)
  • capture: submits the authorized transaction for settlement (i.e. payment by the shopper)

The request includes the cardTransaction resource, which contains information about the transaction, such as the transaction type, amount, and currency.

This tutorial assumes that you are using BlueSnap's Hosted Payment Fields to collect shopper credit card information, so the request must also include your Hosted Payment Fields token.

Example Auth Capture request

Below is an example of a simple Auth Capture request with a Hosted Payment Fields token. This request contains the basic information required to process a one-time payment using a credit card. For more details and additional examples of this request, see Auth Capture.

{
    "amount": 50,
    "recurringTransaction": "ECOMMERCE",
    "cardHolderInfo": {
        "firstName": "Jane",
        "lastName": "Shopper"
    },
    "currency": "USD",
    "cardTransactionType": "AUTH_CAPTURE",
    "pfToken": "abcde12345**********"
}

Sending the request

Once you have built the request, send it to the transactions endpoint in the Payment API. In the BlueSnap sandbox environment, this is the URL for the transactions endpoint:
https://sandbox.bluesnap.com/services/2/transactions



Back to Top

Step 2: Response and error handling

After you send the request, if all goes well, you will receive a 200 OK response with content similar to the following:

{
    "amount": 50,
    "recurringTransaction": "ECOMMERCE",
    "processingInfo": {
        "avsResponseCodeAddress": "M",
        "processingStatus": "success",
        "cvvResponseCode": "MA",
        "avsResponseCodeName": "U",
        "avsResponseCodeZip": "M"
    },
    "cardHolderInfo": {
        "firstName": "Jane",
        "lastName": "Shopper"
    },
    "currency": "USD",
    "creditCard": {
        "cardLastFourDigits": 1111,
        "cardSubType": "CREDIT",
        "cardType": "VISA"
    },
    "cardTransactionType": "AUTH_CAPTURE",
    "transactionId": 38486450
}

The response includes:

  • processingInfo = details about the processing status and results of CVV/AVS checks
  • transactionId = a unique ID that BlueSnap assigns to this transaction
    If an issue occurs, whether a validation error with the information you sent, an error from the processor, or another type of issue, you will instead receive an HTTP 400 or 500 response with a BlueSnap error code and description. For more information, see Error handling overview.



Back to Top

Step 3: Power tools: vaulted shoppers, metadata, PayPal, digital wallets, and more

Now that you know how to send a basic transaction, there are some more options you'll want to take advantage of in order to optimize payment processing according to your business needs. Here are a few key ones:

Vaulted shoppers

Make the checkout process smoother and payment processing easier by saving shopper details in BlueSnap and getting an ID that represents that shopper's profile. You can then use that ID to retrieve the shopper's details or process transactions. See Create Vaulted Shopper.

Metadata

Pass any data you wish along with the transaction. This can be useful if you want to send tax or shipping information, or details about the product such as size or color. See Metadata.

PayPal

Many merchants wish to offer shoppers the ability to pay seamlessly via PayPal, one of the most common payment methods. BlueSnap makes it easy to accept PayPal by simply connecting your PayPal and BlueSnap accounts and then using our dedicated API calls for PayPal transactions. See PayPal.

Digital wallets

BlueSnap supports digital wallets, like Apple Pay, MasterPass, and Visa Checkout, that enable your shoppers to make fast and easy payments across all their devices. These wallets securely store the shopper's payment and shipping details and support all major credit and debit card types, including MasterCard, Visa, American Express, Discover, and more.
For more information, see:

More tutorials

See these tutorials for more tips about getting the most out of the Payment API:



Back to Top

Step 4: Testing

Test credit card numbers

When you are creating test requests, it is recommended to the use the test credit card numbers we provide, which are designed to generate specific success or failure responses. See Test credit card numbers.

Locating transactions in the Merchant Console

Once you have sent a transaction and received a response, you can also go into the Merchant Console to verify that the order has appeared there.

The order record will be found only if you sent the transaction request from the same account that you used in order to log in to the Merchant Console. It will not appear if you sent the request through the API Explorer in this documentation.

  1. In the Merchant Console, go to Transactions > Find a Transaction.
  2. In the field next to Reference Number, enter the value from the transactionId field in the response you received from the API.
  1. Click Locate, and then the order record will appear. It includes details such as the price, quantity, shopper information, options to resend the receipt or Instant Payment Notification, and more.



You're ready to Launch & Get Paid!