Example Request

curl -X GET https://api.Capstonesandbox.com/user/v3/account/whoAmI \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

Example 200 Response

{
  "cognitoSub": "g52679a2-tan5-4a56-b6gc-2592aedd373e",
  "firstName": "John",
  "lastName": "Doe",
  "userName": "jdoe@yourwebsite.com",
  "accessRights": {
    "merchantIds": {
      "100039": "A"
    },
    "role": "A"
  },
  "dateLastModified": "2019-03-08T00:58:27.893Z",
  "dateCreated": "2018-09-27T14:27:39.626Z",
  "enabled": true,
  "phone": "15555555555",
  "notifications": false
}

Example

$ echo -n myname@Capstone.com:mypassword | base64
bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk

Example

Authorization: Basic bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk

Example

curl -X get https://api.Capstonesandbox.com/user/v3/account/whoAmI \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk'

Save Card Iframe with Simple Login

https://retail.Capstonesandbox.com/?simpleLogin=4f211fde-d135-4c91-afbc-bcdb73c0c504&settings={%22uiOptions%22:{%22saveCard%22:true} }

Save Card Iframe without Simple Login

https://retail.Capstonesandbox.com/?settings={%22uiOptions%22:{%22saveCard%22:true} }

Run Transaction Iframe with Simple Login

https://retail.Capstonesandbox.com/?simpleLogin=4f211fde-d135-4c91-afbc-bcdb73c0c504

Run Transaction Iframe without Simple Login

https://retail.Capstonesandbox.com/

Save Card Iframe without Simple Login

https://retail.Capstonesandbox.com/?settings={%22uiOptions%22:{%22saveCard%22:true} }

Run Transaction Iframe with Simple Login and a Default Amount of $20

https://retail.Capstonesandbox.com/?simpleLogin={key}&settings={%22processingOptions%22:{%22amountDefault%22:"20"} }

Example Request

curl -X POST https://api.Capstonesandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {},
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "processingOptions": {
    "retryOnSoftDecline": true
  }
}'

Example Request

curl -X POST https://api.Capstonesandbox.com/subscription/v3 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "payment": {
    "data": {
      "amount": 19.99,
      "currency": "USD",
      "customer": {
        "customerRef": "RP006"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    },
    "processingOptions": {
      "retryOnSoftDecline": true
    }
  },
  "schedule": {
    "interval": "week",
    "intervalCount": 2
  }
}'

Example Request

curl -X POST https://api.Capstonesandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "processingOptions": {
    "verifyAvs": 3
  }
}'

Example Request

curl -X POST https://api.Capstonesandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "processingOptions": {
    "verifyAvs": 3
  }
}'

Example Request

curl -X POST https://api.Capstonesandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "processingOptions": {
    "verifyAvs": 3
  }
}'

Example 200 Response

{
  "token": {...},
  "card": {...},
  "data": {...},
  "avsResults": {
    "matchAddress": true,
    "matchPostal": true,
    "gatewayResponse": {...}
  },
  "cardType": "visa"
}

Example one-time-use token Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.Capstonesandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

Example

<script type='text/javascript' src='https://api.Capstonesandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170'></script>

Example 200 Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.Capstonesandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

Example

<script type='text/javascript' src='https://api.Capstonesandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170'></script>

Example Request

curl -X POST https://api.Capstonesandbox.com/pay/v3/saveCard \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20"
  },
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19"
}'

Example 200 Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.Capstonesandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

Example

<script type='text/javascript' src='https://api.Capstonesandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170'></script>

Example Request

curl -X POST https://api.Capstonesandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD"
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}'

Example Request

curl -X POST https://api.Capstonesandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD"
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}'

Example Request

curl -X POST https://api.Capstonesandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "uiOptions": {
    "css": "https://tester.Capstonesandbox.com/static/ecom-example1.css"
  }
}'

Example 200 Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.Capstonesandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

Example Request

curl -X GET https://api.Capstonesandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
  -H 'Accept: application/json' \
  -H 'One-time-use Token: API_KEY'

Basic Subscription

curl -X POST https://api.Capstonesandbox.com/subscription/v3 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "payment": {
    "data": {
      "amount": 19.99,
      "currency": "USD",
      "customer": {
        "customerRef": "RP006"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    }
  },
  "schedule": {
    "interval": "week",
    "intervalCount": 2
  }
}'

Subscription with initial billing period

curl -X POST https://api.Capstonesandbox.com/subscription/v3 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "payment": {
    "data": {
      "amount": 25,
      "currency": "USD",
      "customer": {
        "customerRef": "RP006"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 1,
    "dateInitialBillingEnd": "2021-10-05",
    "initialBillingAmount": 15
  }
}'

Example Request

curl -X POST https://api.Capstonesandbox.com/webhook/v3/config \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "merchantId": "100039",
  "webhooks": {
    "SUBSCRIPTION_DETAILS": {
      "url": "https://your-company-webhook-url-here.com"
    }
  }
}'

PAY PLAN WITH TRANSACTION AMOUNT

curl -X POST https://api.Capstonesandbox.com/subscription/v3 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "payment": {
    "data": {
      "amount": 10,
      "currency": "USD",
      "customer": {
        "customerRef": "RP006"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    }
  },
  "schedule": {
    "balance": 100,
    "interval": "month",
    "intervalCount": 1
  }
}'

PAY PLAN WITH DURATION

curl -X POST https://api.Capstonesandbox.com/subscription/v3 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "payment": {
    "data": {
      "currency": "USD",
      "customer": {
        "customerRef": "RP006"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    }
  },
  "schedule": {
    "balance": 100,
    "duration": 5,
    "interval": "month",
    "intervalCount": 1
  }
}'

EXAMPLE REQUEST

curl -X POST https://api.Capstonesandbox.com/webhook/v3/config \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "merchantId": "100039",
  "webhooks": {
    "SUBSCRIPTION_DETAILS": {
      "url": "https://your-company-webhook-url-here.com"
    }
  }
}'

Example

window.addEventListener('message', function messageListener(event) {
    if (event.origin === iframeDomain) {
        if (event.data.event === 'error' || event.data.event === 'success' || event.data.event === 'processed') {
        // handle success or error messages
        }
        if (event.data.event === 'loaded') {
        //handle form loaded state
        }
        if (event.data.event === 'cardSaved') {
        //handle cardSaved
        }
        console.log(event.data.event);
    }
});

Full API Reference

Payments API Reference

E-commerce

One-time-use Token

Code samples

curl -X POST https://api.capstonesandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "card": {
    "businessNumber": "1234567890",
    "cardHolderName": "John H Doe",
    "classification": "business",
    "expirationMonth": "12",
    "expirationYear": "20",
    "password": "12"
  },
  "data": {
    "allowedCardTypes": [
      "visa"
    ],
    "currency": "USD",
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderDate": "2021-08-26",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "processingOptions": {
    "checkFraud": false,
    "verboseResponse": true,
    "verifyAvs": 2,
    "verifyCvc": false,
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>",
    "webhookUrl": ""
  },
  "shouldUpdateCard": true,
  "uiOptions": {
    "css": "https://tester.capstonesandbox.com/example1.css",
    "customTextUrl": "",
    "displaySubmitButton": true,
    "hideBilling": {
      "hideAddressOne": false,
      "hideAddressTwo": false,
      "hideCity": false,
      "hideCountry": false,
      "hidePostal": false,
      "hidePhone": false,
      "hideState": false
    },
    "hideCvc": true,
    "limitCountriesTo": [
      "US"
    ],
    "requireCvc": false
  }
}'

POST /pay/v3/token

A token from this endpoint is necessary prior to loading any e-commerce iframe. The available and required parameters differ based on the iframe to be loaded. See the dropdown below to see which parameters are available and required for each iframe. All processing options and UI options for your iframes must be sent in the body of this request. Any data (ex. card or customer information) you wish to be pre-filled in your iframe forms must also be sent in this request. Any parameter included here will be overwritten if the same parameter is included in the iframe’s event body.

Note: Once a token has been used to submit an iframe it cannot be used to load another. You must request a new one-time-use token prior to submitting each iframe.

Body parameter

{
  "card": {
    "businessNumber": "1234567890",
    "cardHolderName": "John H Doe",
    "classification": "business",
    "expirationMonth": "12",
    "expirationYear": "20",
    "password": "12"
  },
  "data": {
    "allowedCardTypes": [
      "visa"
    ],
    "currency": "USD",
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderDate": "2021-08-26",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "processingOptions": {
    "checkFraud": false,
    "verboseResponse": true,
    "verifyAvs": 2,
    "verifyCvc": false,
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>",
    "webhookUrl": ""
  },
  "shouldUpdateCard": true,
  "uiOptions": {
    "css": "https://tester.capstonesandbox.com/example1.css",
    "customTextUrl": "",
    "displaySubmitButton": true,
    "hideBilling": {
      "hideAddressOne": false,
      "hideAddressTwo": false,
      "hideCity": false,
      "hideCountry": false,
      "hidePostal": false,
      "hidePhone": false,
      "hideState": false
    },
    "hideCvc": true,
    "limitCountriesTo": [
      "US"
    ],
    "requireCvc": false
  }
}

Example responses

200 Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.capstonesandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

The one-time-use token

Name	Type	Required	Restrictions	Description
expiration	string	false	none	The date and time at which the one-time-use token will expire, in ISO 8601 format.
fraudUrl	string	false	none	The URL to be used for device fingerprinting
token	string	false	none	Your one-time-use token

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Save Card Token

Code samples

curl -X POST https://api.capstonesandbox.com/pay/v3/saveCard \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardType": "visa",
    "securityCode": 927
  },
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "data": {
    "currency": "USD",
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "shouldUpdateCard": true,
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
    "firstSix": "479300",
    "lastFour": "3313"
  }
}'

POST /pay/v3/saveCard

Allows you to securely save a card token without a browser or using your own form. You may save a new card by including the card object or add existing TokenEx card token for use in Capstone by including the token object.

Note: Processing options must be sent in the request for a one-time-use token.

Body parameter

{
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardType": "visa",
    "securityCode": 927
  },
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "data": {
    "currency": "USD",
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "shouldUpdateCard": true,
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
    "firstSix": "479300",
    "lastFour": "3313"
  }
}

Parameters

Name	In	Type	Required	Description
card	body	cardData	true	Credit card information
cardHolderName	body	cardHolderName	true	The cardholder's name as it appears on the card
encryptedNumber	body	string	true	The encrypted card number.
expirationMonth	body	expirationMonth	true	The month in which the card will expire
expirationYear	body	expirationYear	true	The two-digit year in which the card will expire
cardType	body	cardType	false	The card type. This information is required when saving a card through your own form. May be any of the following: visa mastercard discover amex
securityCode	body	securityCode	false	The CVC code on the back of the card
token	body	token	true	A one-time-use token.
data	body	object	false	Additional optional data
currency	body	currency	false	The three-character ISO currency code for the transaction.
customer	body	customerCardToken	false	Customer information to be used in checking fraud or sent to the processing gateway, when applicable
billToAddressOne	body	billToAddressOne	false	The street address on file with the credit card provider
billToAddressTwo	body	billToAddressTwo	false	Additional street address information, if required
billToCity	body	billToCity	false	The city on file with the credit card provider
billToCountry	body	billToCountry	false	The two-character (Alpha-2) ISO country code
billToPhone	body	billToPhone	false	The billing phone number
billToPostal	body	billToPostal	false	The postal code on file with the credit card provider
billToState	body	billToState	false	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
birthDate	body	birthDate	false	The customer's date of birth. Use any of the following formats for the date: Four-digit month, 2-digit month and day, separated with hyphens: YYYY-MM-DD. For example, 2001-08-26 ISO-8601 date expressed in UTC. For example, 2001-08-26T13:35:00Z UNIX date (as an integer representing seconds). For example, 998854500
createdAtDate	body	createdAtDate	false	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
customerRef	body	customerRef	false	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
email	body	email	false	The customer's email address
firstName	body	firstName	false	The customer's first name, as it appears on the credit card
invoice	body	invoice	false	The invoice number
lastName	body	lastName	false	The customer's last name, as it appears on the credit card
orderNumber	body	orderNumber	false	The order number
phone	body	phone	false	The customer's phone number
shipToAddressOne	body	shipToAddressOne	false	The shipping address, if different from the billing address
shipToAddressTwo	body	shipToAddressTwo	false	Additional shipping address information, if required
shipToCity	body	shipToCity	false	The shipping city
shipToCountry	body	shipToCountry	false	The two-character (Alpha-2) ISO country code
shipToPhone	body	shipToPhone	false	The shipping phone number
shipToPostal	body	shipToPostal	false	The shipping postal code
shipToState	body	shipToState	false	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
customFields	body	customFields	false	Custom fields that can be used to pass additional strings along to the gateway. These fields will not be stored by Capstone. Notes: Do not use custom fields to store sensitive data. Some information may be escaped and may not be usable in custom fields.
exampleKey	body	string	false	You may use any key as a custom field. Values must be strings.
shouldUpdateCard	body	shouldUpdateCard	false	The card's account updater enrollment tag When true, the card or e-check token is tagged for registration with account updater Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information
tokenex	body	tokenexCard	false	A previously saved TokenEx card token. (Use this option if you have pre-existing TokenEx tokens you would like to start using through Capstone.) Conditionally Required if the card.encryptedNumber is not included
token	body	string	false	The TokenEx card token. Conditionally Required if the card.encryptedNumber is not included
firstSix	body	string	false	The first six digits of the card number
lastFour	body	string	false	The last four digits of the card number

Example responses

200 Response

{
  "card": {
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe"
  },
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    }
  },
  "kountResponse": {
    "status": "success",
    "rules": "{\"VERS\":\"0630\",\"MODE\":\"Q\",\"TRAN\":\"7V7D0V1BMKPX\",\"MERC\":\"717000\",\"SESS\":\"3bbb89edcd5742f18e2502ebb2bbb18b\",\"ORDR\":\"14233\",\"AUTO\":\"A\",\"SCOR\":\"29\",\"GEOX\":\"US\",\"BRND\":\"VISA\",\"REGN\":null,\"NETW\":\"N\",\"KAPT\":\"N\",\"CARDS\":\"1\",\"DEVICES\":\"1\",\"EMAILS\":\"1\",\"VELO\":\"0\",\"VMAX\":\"0\",\"SITE\":\"DEFAULT\",\"DEVICE_LAYERS\":\"....\",\"FINGERPRINT\":null,\"TIMEZONE\":null,\"LOCALTIME\":\" \",\"REGION\":null,\"COUNTRY\":null,\"PROXY\":null,\"JAVASCRIPT\":null,\"FLASH\":null,\"COOKIES\":null,\"HTTP_COUNTRY\":null,\"LANGUAGE\":null,\"MOBILE_DEVICE\":null,\"MOBILE_TYPE\":null,\"MOBILE_FORWARDER\":null,\"VOICE_DEVICE\":null,\"PC_REMOTE\":null,\"RULES_TRIGGERED\":0,\"COUNTERS_TRIGGERED\":0,\"REASON_CODE\":null,\"MASTERCARD\":\"\",\"DDFS\":null,\"DSR\":null,\"UAS\":null,\"BROWSER\":null,\"OS\":null,\"PIP_IPAD\":null,\"PIP_LAT\":null,\"PIP_LON\":null,\"PIP_COUNTRY\":null,\"PIP_REGION\":null,\"PIP_CITY\":null,\"PIP_ORG\":null,\"IP_IPAD\":null,\"IP_LAT\":null,\"IP_LON\":null,\"IP_COUNTRY\":null,\"IP_REGION\":null,\"IP_CITY\":null,\"IP_ORG\":null,\"WARNING_COUNT\":0}"
  },
  "merchantId": "100100",
  "shouldUpdateCard": true,
  "token": {
    "firstSix": "479300",
    "lastFour": "3313",
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
card	object	false	none	Card information
expirationMonth	string	false	none	The month in which the card will expire
expirationYear	string	false	none	The two-digit year in which the card will expire
cardHolderName	string	false	none	The cardholder's name as it appears on the card
data	object	false	none	Additional data, if provided in the request
customer	object	false	none	Customer information returned when checking fraud or from the processing gateway, when applicable.
billToAddressOne	string	false	none	The street address on file with the credit card provider
billToAddressTwo	string	false	none	Additional street address information, if required
billToCity	string	false	none	The city on file with the credit card provider
billToCountry	string	false	none	The two-character (Alpha-2) ISO country code
billToPhone	string	false	none	The billing phone number
billToPostal	string	false	none	The postal code on file with the credit card provider
billToState	string	false	none	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
birthDate	string	false	none	The customer's date of birth. The format returned matches the format used in the request that created the Card Token.
createdAtDate	string	false	none	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
customerRef	string	false	none	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
email	string	false	none	The customer's email address
firstName	string	false	none	The customer's first name, as it appears on the credit card
invoice	string	false	none	The invoice number
lastName	string	false	none	The customer's last name, as it appears on the credit card
orderNumber	string	false	none	The order number
phone	string	false	none	The customer's phone number
shipToAddressOne	string	false	none	The shipping address, if different from the billing address
shipToAddressTwo	string	false	none	Additional shipping address information, if required
shipToCity	string	false	none	The shipping city
shipToCountry	string	false	none	The two-character (Alpha-2) ISO country code
shipToPhone	string	false	none	The shipping phone number
shipToPostal	string	false	none	The shipping postal code
shipToState	string	false	none	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
kountResponse	object	false	none	Fraud data and rules
status	string	false	none	Will be one of three possible statuses: 'success', 'review', 'decline.' See our Fraud tutorial for more information
rules	string	false	none	Kount-specific information, including rules triggered. See our Fraud tutorial for more information
merchantId	string	false	none	The merchant ID (MID)
shouldUpdateCard	boolean	false	none	The card's account updater enrollment tag When true, the card or e-check token is tagged for registration with account updater Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information
token	object	false	none	Card token information
firstSix	string	false	none	The first six digits of the card number
lastFour	string	false	none	The last four digits of the card number
token	string	false	none	The saved card token

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Save Card Token Iframe

Code samples

curl -X GET https://api.capstonesandbox.com/pay/v3/saveCard?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
  -H 'Accept: application/json' \
  -H 'One-time-use Token: API_KEY'

GET /pay/v3/saveCard

Returns an iframe that can be used to securely save a credit card token.

Parameters

Name	In	Type	Required	Description
token	query	string	true	Your one-time-use token

Example responses

200 Response

"<html>A save card form</html>"

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Run Card Transaction

Code samples

curl -X POST https://api.capstonesandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderDate": "2021-08-26",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "description": "test purchase",
    "descriptor": "",
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "noShow": false,
      "roomNumber": 14,
      "roomRate": 143.99
    }
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
    "firstSix": "479300",
    "lastFour": "3313"
  },
  "card": {
    "businessNumber": "1234567890",
    "cardHolderName": "John H Doe",
    "cardType": "visa",
    "classification": "business",
    "expirationMonth": "12",
    "expirationYear": "20",
    "password": "12",
    "securityCode": 927
  },
  "installment": {
    "period": 10
  },
  "isAuthOnly": false,
  "processingOptions": {
    "checkFraud": false,
    "customerRedirectUrl": "https://your-ecommerce-website.example.com",
    "merchantId": "100039",
    "paymentOptionTag": "switch",
    "saveCardToken": true,
    "shouldUseFingerprint": true,
    "verboseResponse": true,
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>",
    "webhookUrl": ""
  }
}'

POST /pay/v3/process

Allows you to securely process a card transaction without a browser.

Body parameter

{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderDate": "2021-08-26",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "description": "test purchase",
    "descriptor": "",
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "noShow": false,
      "roomNumber": 14,
      "roomRate": 143.99
    }
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
    "firstSix": "479300",
    "lastFour": "3313"
  },
  "card": {
    "businessNumber": "1234567890",
    "cardHolderName": "John H Doe",
    "cardType": "visa",
    "classification": "business",
    "expirationMonth": "12",
    "expirationYear": "20",
    "password": "12",
    "securityCode": 927
  },
  "installment": {
    "period": 10
  },
  "isAuthOnly": false,
  "processingOptions": {
    "checkFraud": false,
    "customerRedirectUrl": "https://your-ecommerce-website.example.com",
    "merchantId": "100039",
    "paymentOptionTag": "switch",
    "saveCardToken": true,
    "shouldUseFingerprint": true,
    "verboseResponse": true,
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>",
    "webhookUrl": ""
  }
}

Parameters

Name	In	Type	Required	Description
data	body	dataExtended	true	Transaction data
amount	body	amount	true	The transaction amount
currency	body	currency	true	The three-character ISO currency code for the transaction.
cart	body	cart	false	Items purchased in the transaction
items	body	[item]	false	Details about items in the shopping cart
item	body	itemItem	false	Item number or code
description	body	descriptionItem	false	A description of the item
quantity	body	quantity	false	The quantity sold
price	body	price	false	The price per item
type	body	transactionType	false	The transaction type
customer	body	customer	false	Customer information to be used in checking fraud or sent to the processing gateway, when applicable
billToAddressOne	body	billToAddressOne	false	The street address on file with the credit card provider
billToAddressTwo	body	billToAddressTwo	false	Additional street address information, if required
billToCity	body	billToCity	false	The city on file with the credit card provider
billToCountry	body	billToCountry	false	The two-character (Alpha-2) ISO country code
billToPhone	body	billToPhone	false	The billing phone number
billToPostal	body	billToPostal	false	The postal code on file with the credit card provider
billToState	body	billToState	false	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
birthDate	body	birthDate	false	The customer's date of birth. Use any of the following formats for the date: Four-digit month, 2-digit month and day, separated with hyphens: YYYY-MM-DD. For example, 2001-08-26 ISO-8601 date expressed in UTC. For example, 2001-08-26T13:35:00Z UNIX date (as an integer representing seconds). For example, 998854500
createdAtDate	body	createdAtDate	false	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
customerRef	body	customerRef	false	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
email	body	email	false	The customer's email address
firstName	body	firstName	false	The customer's first name, as it appears on the credit card
invoice	body	invoice	false	The invoice number
lastName	body	lastName	false	The customer's last name, as it appears on the credit card
orderDate	body	orderDate	false	The date of the customer's order. Use any of the following formats for the date: Four-digit month, 2-digit month and day, separated with hyphens: YYYY-MM-DD. For example, 2021-08-26 ISO-8601 date expressed in UTC. For example, 2021-08-26T13:35:18Z UNIX date (as an integer representing seconds). For example, 1630006518 Note: This is NOT a quick way to schedule a transaction. Specifying a date in the future does not cause the order to be run automatically at the indicated date or time.
orderNumber	body	orderNumber	false	The order number
phone	body	phone	false	The customer's phone number
shipToAddressOne	body	shipToAddressOne	false	The shipping address, if different from the billing address
shipToAddressTwo	body	shipToAddressTwo	false	Additional shipping address information, if required
shipToCity	body	shipToCity	false	The shipping city
shipToCountry	body	shipToCountry	false	The two-character (Alpha-2) ISO country code
shipToPhone	body	shipToPhone	false	The shipping phone number
shipToPostal	body	shipToPostal	false	The shipping postal code
shipToState	body	shipToState	false	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
customFields	body	customFields	false	Custom fields that can be used to pass additional strings along to the gateway. These fields will not be stored by Capstone. Notes: Do not use custom fields to store sensitive data. Some information may be escaped and may not be usable in custom fields.
exampleKey	body	string	false	You may use any key as a custom field. Values must be strings.
description	body	descriptionTransaction	false	A description of the transaction
descriptor	body	descriptor	false	Include this parameter to dynamically change the descriptor on the customer's statement. If this parameter is not included, the default descriptor (as set up on the merchant account that is originating the transactions) will be used. When applicable, this information will be passed along to gateway. Contact integration support if you have any questions about this parameter
lodging	body	lodging	false	Lodging data (related to hotels, motels, inns, etc.)
advanceDeposit	body	boolean	false	Set to true if the customer paid a deposit in advance of their reservation
checkInDate	body	string	false	The customer's check in date in standard ISO date format
checkOutDate	body	string	false	The customer's check out date in standard ISO date format
noShow	body	boolean	false	Set to true if the customer failed to show up to their reservation
roomNumber	body	number	false	The customer's room number
roomRate	body	number	false	The room's rate, per day
tokenex	body	tokenexRunCard	true	A previously saved card token.
token	body	string	true	A Capstone card token.
firstSix	body	string	false	The first six digits of the card number
lastFour	body	string	false	The last four digits of the card number
card	body	object	false	Credit card information
businessNumber	body	businessNumber	false	A string containing 10 digits
cardHolderName	body	cardHolderName	false	The cardholder's name as it appears on the card
cardType	body	cardType	false	The card type. This information is required when saving a card through your own form. May be any of the following: visa mastercard discover amex
classification	body	classification	false	Possible values must be exactly as shown below: personal business
expirationMonth	body	expirationMonth	false	The month in which the card will expire
expirationYear	body	expirationYear	false	The two-digit year in which the card will expire
password	body	password	false	A string containing two digits
securityCode	body	securityCode	false	The CVC code on the back of the card
installment	body	installment	false	Creates an installment associated with the transaction. For a list of supported gateways, contact integration support.
period	body	integer	false	Values depend on the gateway being used. Contact integration support for assistance.
isAuthOnly	body	isAuthOnly	false	Set to true to run an auth only transaction
processingOptions	body	processingOptionsRunTransaction	false	Processing Options
checkFraud	body	checkFraud	false	Set to false to opt out of sending a request to Kount. Note: During testing you may trigger specific Kount responses by including any of the values shown here
customerRedirectUrl	body	string	false	The URL to which the customer will be redirected after completing a 3D Secure authentication. The customer will be sent here whether the transaction succeeds or fails. This URL must use the HTTPS protocol.
merchantId	body	merchantId	false	The merchant ID (MID)
paymentOptionTag	body	paymentOptionTag	false	A custom value used to route transactions to a specific gateway or merchant account. Contact integration support to designate a paymentOptionTag for a given merchant account.
saveCardToken	body	saveCardToken	false	Set to false to opt out of saving a card token when a transaction is run
shouldUseFingerprint	body	shouldUseFingerprint	false	This parameter applies when a device fingerprint was created while saving a card token. The card's stored fingerprint will be used by default, but you may choose not to use it by setting this parameter to false. Note: To change your merchant's default setting, contact integration support
verboseResponse	body	verboseResponse	false	Set to true to include additional information in the response
webhookFailUrl	body	webhookFailUrl	false	The URL to which Capstone will send the results of a failed transaction
webhookUrl	body	webhookUrl	false	The URL to which Capstone will send the results of the transaction. (If not provided you will need to use the results of the HTTP request, either from the browser or your server)

Example responses

200 Response

{
  "amount": 34.25,
  "authCode": "035410",
  "card": {
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardType": "visa",
    "cardHolder": "John H Doe"
  },
  "currency": "USD",
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD",
    "customer": {
      "customerRef": "RP006",
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "email": "jdoe@yourwebsite.com",
      "phone": "1555555555",
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToState": "PA",
      "billToPostal": "18503",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "orderDate": "2021-08-26",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    },
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "noShow": false,
      "roomNumber": 14,
      "roomRate": 143.99
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "gatewayResponse": {
    "gatewayName": "nmi",
    "refNumber": "3107885809"
  },
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "kountResponse": {
    "status": "success",
    "rules": "{\"VERS\":\"0630\",\"MODE\":\"Q\",\"TRAN\":\"7V7D0V1BMKPX\",\"MERC\":\"717000\",\"SESS\":\"3bbb89edcd5742f18e2502ebb2bbb18b\",\"ORDR\":\"14233\",\"AUTO\":\"A\",\"SCOR\":\"29\",\"GEOX\":\"US\",\"BRND\":\"VISA\",\"REGN\":null,\"NETW\":\"N\",\"KAPT\":\"N\",\"CARDS\":\"1\",\"DEVICES\":\"1\",\"EMAILS\":\"1\",\"VELO\":\"0\",\"VMAX\":\"0\",\"SITE\":\"DEFAULT\",\"DEVICE_LAYERS\":\"....\",\"FINGERPRINT\":null,\"TIMEZONE\":null,\"LOCALTIME\":\" \",\"REGION\":null,\"COUNTRY\":null,\"PROXY\":null,\"JAVASCRIPT\":null,\"FLASH\":null,\"COOKIES\":null,\"HTTP_COUNTRY\":null,\"LANGUAGE\":null,\"MOBILE_DEVICE\":null,\"MOBILE_TYPE\":null,\"MOBILE_FORWARDER\":null,\"VOICE_DEVICE\":null,\"PC_REMOTE\":null,\"RULES_TRIGGERED\":0,\"COUNTERS_TRIGGERED\":0,\"REASON_CODE\":null,\"MASTERCARD\":\"\",\"DDFS\":null,\"DSR\":null,\"UAS\":null,\"BROWSER\":null,\"OS\":null,\"PIP_IPAD\":null,\"PIP_LAT\":null,\"PIP_LON\":null,\"PIP_COUNTRY\":null,\"PIP_REGION\":null,\"PIP_CITY\":null,\"PIP_ORG\":null,\"IP_IPAD\":null,\"IP_LAT\":null,\"IP_LON\":null,\"IP_COUNTRY\":null,\"IP_REGION\":null,\"IP_CITY\":null,\"IP_ORG\":null,\"WARNING_COUNT\":0}"
  },
  "merchantId": "100039",
  "token": {
    "firstSix": "479300",
    "lastFour": "3313",
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "transactionStatus": "pending",
  "transactionType": "sale"
}

Responses

Status	Meaning	Description
200	OK	Success
400	Bad Request	Bad Request
401	Unauthorized	Unauthorized

Response Schema

Status Code 400

Name	Type	Required	Restrictions	Description
error	integer	false	none	Capstone's error code
message	string	false	none	The reason for the failure to authenticate
gatewayResponse	object	false	none	The failure response from the gateway. Details will vary by gateway
gatewayName	string	false	none	The gateway name
refNum	string	false	none	The gateway's reference number
status	string	false	none	The transaction status
merchantId	string	false	none	The merchant ID

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Run Card Transaction Iframe

Code samples

curl -X GET https://api.capstonesandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
  -H 'Accept: application/json' \
  -H 'One-time-use Token: API_KEY'

GET /pay/v3

Returns an iframe that can be used to securely run a credit or debit card transaction.

Parameters

Name	In	Type	Required	Description
token	query	string	true	Your one-time-use token. This is a query parameter.

Example responses

200 Response

"<html>A run transaction form</html>"

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Save E-check Token

Code samples

curl -X POST https://api.capstonesandbox.com/pay/v3/saveECheck \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  },
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToState": "PA",
      "billToPostal": "18503",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "companyName": "Green Thumb Lawn Care",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "tokenex": {
    "token": "585436789",
    "customerRefNumber": "74771a19-3c28-4c27-83c6-9",
    "lastFour": "1111"
  }
}'

POST /pay/v3/saveECheck

Allows you to securely save bank account information without a browser or using your own form. You may save a new e-check by including the card object or add existing TokenEx e-check token for use in Capstone by including the token object.

Note: Processing options must be sent in the request for a one-time-use token.

Body parameter

{
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  },
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToState": "PA",
      "billToPostal": "18503",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "companyName": "Green Thumb Lawn Care",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "tokenex": {
    "token": "585436789",
    "customerRefNumber": "74771a19-3c28-4c27-83c6-9",
    "lastFour": "1111"
  }
}

Parameters

Name	In	Type	Required	Description
bank	body	bank	true	Bank account information
accountHolderName	body	accountHolderName	true	The account holder's name
routingNumber	body	routingNumber	true	The bank account's routing number
encryptedBankAccountNumber	body	string	false	The encrypted bank account number. This value is used to create a TokenEx e-check token. Conditionally Required if tokenex.token is not included.
token	body	ott	true	Your one-time-use token
data	body	object	false	Additional optional data
customer	body	customerECheck	false	Customer information to be used in checking fraud or sent to the processing gateway, when applicable
billToAddressOne	body	billToAddressOne	false	The street address on file with the credit card provider
billToAddressTwo	body	billToAddressTwo	false	Additional street address information, if required
billToCity	body	billToCity	false	The city on file with the credit card provider
billToState	body	billToState	false	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
billToPostal	body	billToPostal	false	The postal code on file with the credit card provider
billToCountry	body	billToCountry	false	The two-character (Alpha-2) ISO country code
billToPhone	body	billToPhone	false	The billing phone number
companyName	body	companyName	false	This field may be included if the bank account being used for payment is a business account
createdAtDate	body	createdAtDate	false	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
customerRef	body	customerRef	false	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
email	body	email	false	The customer's email address
firstName	body	firstName	false	The customer's first name, as it appears on the credit card
invoice	body	invoice	false	The invoice number
lastName	body	lastName	false	The customer's last name, as it appears on the credit card
orderNumber	body	orderNumber	false	The order number
phone	body	phone	false	The customer's phone number
shipToAddressOne	body	shipToAddressOne	false	The shipping address, if different from the billing address
shipToAddressTwo	body	shipToAddressTwo	false	Additional shipping address information, if required
shipToCity	body	shipToCity	false	The shipping city
shipToState	body	shipToState	false	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
shipToPostal	body	shipToPostal	false	The shipping postal code
shipToCountry	body	shipToCountry	false	The two-character (Alpha-2) ISO country code
shipToPhone	body	shipToPhone	false	The shipping phone number
customFields	body	customFields	false	Custom fields that can be used to pass additional strings along to the gateway. These fields will not be stored by Capstone. Notes: Do not use custom fields to store sensitive data. Some information may be escaped and may not be usable in custom fields.
exampleKey	body	string	false	You may use any key as a custom field. Values must be strings.
tokenex	body	tokenexECheckSave	false	The TokenEx e-check token. (Use this option if you have pre-existing TokenEx tokens you would like to start using through Capstone). Conditionally Required if the bank.encryptedBankAccountNumber is not included.
token	body	string	false	A previously saved TokenEx e-check token. (Use this option if you have pre-existing TokenEx tokens you would like to start using through Capstone). Conditionally Required if bank.encryptedBankAccountNumber is not included.
customerRefNumber	body	string	false	The customer reference number
lastFour	body	string	false	The last four digits of the account number

Example responses

200 Response

{
  "token": {
    "lastFour": "1111",
    "token": "aafb1033-599a-4392-859e-f98033fc37f5"
  },
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "companyName": "Green Thumb Lawn Care",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    }
  },
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151"
  },
  "merchantId": "100100"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
token	object	false	none	E-check token information
lastFour	string	false	none	The last four digits of the account number
token	string	false	none	The e-check token
data	object	false	none	Additional data, if provided in the request
customer	object	false	none	Customer information returned when checking fraud or from the processing gateway, when applicable.
billToAddressOne	string	false	none	The street address on file with the credit card provider
billToAddressTwo	string	false	none	Additional street address information, if required
billToCity	string	false	none	The city on file with the credit card provider
billToCountry	string	false	none	The two-character (Alpha-2) ISO country code
billToPhone	string	false	none	The billing phone number
billToPostal	string	false	none	The postal code on file with the credit card provider
billToState	string	false	none	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
companyName	string	false	none	This field may be included if the bank account being used for payment is a business account
createdAtDate	string	false	none	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
customerRef	string	false	none	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
email	string	false	none	The customer's email address
firstName	string	false	none	The customer's first name, as it appears on the credit card
invoice	string	false	none	The invoice number
lastName	string	false	none	The customer's last name, as it appears on the credit card
orderNumber	string	false	none	The order number
phone	string	false	none	The customer's phone number
shipToAddressOne	string	false	none	The shipping address, if different from the billing address
shipToAddressTwo	string	false	none	Additional shipping address information, if required
shipToCity	string	false	none	The shipping city
shipToCountry	string	false	none	The two-character (Alpha-2) ISO country code
shipToPhone	string	false	none	The shipping phone number
shipToPostal	string	false	none	The shipping postal code
shipToState	string	false	none	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
bank	object	false	none	Bank information
accountHolderName	string	false	none	The account holder's name
routingNumber	string	false	none	The bank account's routing number
merchantId	string	false	none	The merchant ID (MID)

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Save E-check Token Iframe

Code samples

curl -X GET https://api.capstonesandbox.com/pay/v3/saveECheck?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
  -H 'Accept: text/html' \
  -H 'One-time-use Token: API_KEY'

GET /pay/v3/saveECheck

Returns an iframe that can be used to securely save a bank account information.

Parameters

Name	In	Type	Required	Description
token	query	string	true	Your one-time-use token. This is a query parameter.

Example responses

200 Response

"<html>A save e-check form</html>"

401 Response

{
  "message": "Unauthorized"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Run E-check Transaction

Code samples

curl -X POST https://api.capstonesandbox.com/pay/v3/processECheck \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToState": "PA",
      "billToPostal": "18503",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "companyName": "Green Thumb Lawn Care",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "settlementCurrency": "CAD"
  },
  "tokenex": {
    "token": "aafb1033-599a-4392-859e-f98033fc37f5",
    "customerRefNumber": "74771a19-3c28-4c27-83c6-9",
    "lastFour": "1111"
  },
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151"
  },
  "processingOptions": {
    "merchantId": "100039",
    "verboseResponse": true,
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>",
    "webhookUrl": ""
  }
}'

POST /pay/v3/processECheck

Allows you to securely process an e-check transaction without a browser.

Body parameter

{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToState": "PA",
      "billToPostal": "18503",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "companyName": "Green Thumb Lawn Care",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "settlementCurrency": "CAD"
  },
  "tokenex": {
    "token": "aafb1033-599a-4392-859e-f98033fc37f5",
    "customerRefNumber": "74771a19-3c28-4c27-83c6-9",
    "lastFour": "1111"
  },
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151"
  },
  "processingOptions": {
    "merchantId": "100039",
    "verboseResponse": true,
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>",
    "webhookUrl": ""
  }
}

Parameters

Name	In	Type	Required	Description
data	body	dataECheck	true	Transaction data
amount	body	amount	true	The transaction amount
currency	body	currency	true	The three-character ISO currency code for the transaction.
cart	body	cart	false	Items purchased in the transaction
items	body	[item]	false	Details about items in the shopping cart
item	body	itemItem	false	Item number or code
description	body	descriptionItem	false	A description of the item
quantity	body	quantity	false	The quantity sold
price	body	price	false	The price per item
type	body	transactionType	false	The transaction type
customer	body	customerECheck	false	Customer information to be used in checking fraud or sent to the processing gateway, when applicable
billToAddressOne	body	billToAddressOne	false	The street address on file with the credit card provider
billToAddressTwo	body	billToAddressTwo	false	Additional street address information, if required
billToCity	body	billToCity	false	The city on file with the credit card provider
billToState	body	billToState	false	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
billToPostal	body	billToPostal	false	The postal code on file with the credit card provider
billToCountry	body	billToCountry	false	The two-character (Alpha-2) ISO country code
billToPhone	body	billToPhone	false	The billing phone number
companyName	body	companyName	false	This field may be included if the bank account being used for payment is a business account
createdAtDate	body	createdAtDate	false	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
customerRef	body	customerRef	false	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
email	body	email	false	The customer's email address
firstName	body	firstName	false	The customer's first name, as it appears on the credit card
invoice	body	invoice	false	The invoice number
lastName	body	lastName	false	The customer's last name, as it appears on the credit card
orderNumber	body	orderNumber	false	The order number
phone	body	phone	false	The customer's phone number
shipToAddressOne	body	shipToAddressOne	false	The shipping address, if different from the billing address
shipToAddressTwo	body	shipToAddressTwo	false	Additional shipping address information, if required
shipToCity	body	shipToCity	false	The shipping city
shipToState	body	shipToState	false	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
shipToPostal	body	shipToPostal	false	The shipping postal code
shipToCountry	body	shipToCountry	false	The two-character (Alpha-2) ISO country code
shipToPhone	body	shipToPhone	false	The shipping phone number
customFields	body	customFields	false	Custom fields that can be used to pass additional strings along to the gateway. These fields will not be stored by Capstone. Notes: Do not use custom fields to store sensitive data. Some information may be escaped and may not be usable in custom fields.
exampleKey	body	string	false	You may use any key as a custom field. Values must be strings.
settlementCurrency	body	settlementCurrency	false	The currency in which the transaction will be settled
tokenex	body	tokenexECheck	true	The e-check token.
token	body	string	true	A previously saved e-check token.
customerRefNumber	body	string	false	The customer reference number
lastFour	body	string	false	The last four digits of the account number
bank	body	object	false	Bank account information
accountHolderName	body	accountHolderName	false	The account holder's name
routingNumber	body	routingNumber	false	The bank account's routing number
processingOptions	body	processingOptionsRunECheckTransaction	false	Processing Options
merchantId	body	merchantId	false	The merchant ID (MID)
verboseResponse	body	verboseResponse	false	Set to true to include additional information in the response
webhookFailUrl	body	webhookFailUrl	false	The URL to which Capstone will send the results of a failed transaction
webhookUrl	body	webhookUrl	false	The URL to which Capstone will send the results of the transaction. (If not provided you will need to use the results of the HTTP request, either from the browser or your server)

Example responses

200 Response

{
  "amount": 34.25,
  "authCode": "035410",
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "******6789",
    "accountNumber": "***********6789"
  },
  "currency": "USD",
  "data": {
    "amount": 29.99,
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "currency": "USD",
    "customFields": {
      "exampleKey": "Example string"
    },
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "companyName": "Green Thumb Lawn Care",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "noShow": false,
      "roomNumber": 14,
      "roomRate": 143.99
    },
    "settlementCurrency": "CAD"
  },
  "gatewayResponse": {
    "gatewayName": "nmi",
    "refNumber": "3107885809"
  },
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "merchantId": "100039",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "transactionStatus": "pending",
  "transactionType": "sale"
}

Responses

Status	Meaning	Description
200	OK	success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

The response from a successful payment

Name	Type	Required	Restrictions	Description
amount	number	false	none	The transaction amount
authCode	string	false	none	The authorization code
bank	object	false	none	Bank account information
accountHolderName	string	false	none	The account holder's name
routingNumber	string	false	none	The masked routing number
accountNumber	string	false	none	The masked bank account number
currency	string	false	none	The three-character ISO currency code for the transaction.
data	object	false	none	Transaction data
amount	number	false	none	The transaction amount
cart	object	false	none	Items purchased in the transaction
items	array	false	none	Details about items in the shopping cart
item	string	false	none	Item number or code
description	string	false	none	A description of the item
quantity	integer	false	none	The quantity sold
price	number	false	none	The price per item
type	string	false	none	The transaction type
currency	string	false	none	The three-character ISO currency code for the transaction.
customFields	object	false	none	Custom fields that can be used to pass additional strings along to the gateway. These fields will not be stored by Capstone. Notes: Do not use custom fields to store sensitive data. Some information may be escaped and may not be usable in custom fields.
exampleKey	string	false	none	You may use any key as a custom field. Values must be strings.
customer	object	false	none	Customer information returned when checking fraud or from the processing gateway, when applicable.
billToAddressOne	string	false	none	The street address on file with the credit card provider
billToAddressTwo	string	false	none	Additional street address information, if required
billToCity	string	false	none	The city on file with the credit card provider
billToCountry	string	false	none	The two-character (Alpha-2) ISO country code
billToPhone	string	false	none	The billing phone number
billToPostal	string	false	none	The postal code on file with the credit card provider
billToState	string	false	none	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
companyName	string	false	none	This field may be included if the bank account being used for payment is a business account
createdAtDate	string	false	none	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
customerRef	string	false	none	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
email	string	false	none	The customer's email address
firstName	string	false	none	The customer's first name, as it appears on the credit card
invoice	string	false	none	The invoice number
lastName	string	false	none	The customer's last name, as it appears on the credit card
orderNumber	string	false	none	The order number
phone	string	false	none	The customer's phone number
shipToAddressOne	string	false	none	The shipping address, if different from the billing address
shipToAddressTwo	string	false	none	Additional shipping address information, if required
shipToCity	string	false	none	The shipping city
shipToCountry	string	false	none	The two-character (Alpha-2) ISO country code
shipToPhone	string	false	none	The shipping phone number
shipToPostal	string	false	none	The shipping postal code
shipToState	string	false	none	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
lodging	object	false	none	Lodging data (related to hotels, motels, inns, etc.)
advanceDeposit	boolean	false	none	Set to true if the customer paid a deposit in advance of their reservation
checkInDate	string	false	none	The customer's check in date in standard ISO date format
checkOutDate	string	false	none	The customer's check out date in standard ISO date format
noShow	boolean	false	none	Set to true if the customer failed to show up to their reservation
roomNumber	number	false	none	The customer's room number
roomRate	number	false	none	The room's rate, per day
settlementCurrency	string	false	none	The currency in which the transaction will be settled
gatewayResponse	object	false	none	Gateway-specific information. Details will vary by gateway. Do NOT code to any information included in this object
gatewayName	string	false	none	The name of the gateway
refNumber	string	false	none	The gateway's reference number
id	string	false	none	Capstone Payment ID
merchantId	string	false	none	The merchant ID through which the transaction was processed
transactionDate	string	false	none	The transaction date and time
transactionStatus	string	false	none	The transaction status
transactionType	string	false	none	The transaction type

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Run E-check Transaction Iframe

Code samples

curl -X GET https://api.capstonesandbox.com/pay/v3/processECheck?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
  -H 'Accept: text/html' \
  -H 'One-time-use Token: API_KEY'

GET /pay/v3/processECheck

Returns an iframe that can be used to securely process an e-check transaction

Parameters

Name	In	Type	Required	Description
token	query	string	true	Your one-time-use token. This is a query parameter.

Example responses

200 Response

"<html>A process e-check form</html>"

401 Response

{
  "message": "Unauthorized"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Void Transaction

Code samples

curl -X POST https://api.capstonesandbox.com/pay/v3/void \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMwOTg2MjEzOTYiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzA5ODYyMTM5NiIsImN1cnJlbmN5IjoiVVNEIn0"
}'

POST /pay/v3/void

Allows you to void a credit card transaction using the Capstone Payment ID. The entire process is as follows:

1. A transaction using the Run Card Transaction endpoint occurs.
2. Retrieve the id from the response. This is the Capstone Payment ID.
3. Include that id in the body of your request to this endpoint in order to void the transaction.

Body parameter

{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMwOTg2MjEzOTYiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzA5ODYyMTM5NiIsImN1cnJlbmN5IjoiVVNEIn0"
}

Parameters

Name	In	Type	Required	Description
id	body	string	true	The Capstone Payment ID. (To void a transaction through this endpoint it must have been captured through the Capstone Payment API)

Example responses

200 Response

{
  "authCode": "035410",
  "currency": "USD",
  "data": {
    "currency": "USD",
    "settlementCurrency": "CAD"
  },
  "gatewayResponse": {
    "gatewayName": "nmi",
    "refNumber": "3107885809"
  },
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "merchantId": "100100",
  "message": "success",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "transactionStatus": "pending",
  "transactionType": "sale"
}

Responses

Status	Meaning	Description
200	OK	Success
400	Bad Request	Bad Request
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
authCode	string	false	none	The authorization code
currency	string	false	none	The three-character ISO currency code for the transaction.
data	object	false	none	Transaction data
currency	string	false	none	The three-character ISO currency code for the transaction.
settlementCurrency	string	false	none	The currency in which the transaction will be settled
gatewayResponse	object	false	none	Gateway-specific information. Details will vary by gateway. Do NOT code to any information included in this object
gatewayName	string	false	none	The name of the gateway
refNumber	string	false	none	The gateway's reference number
id	string	false	none	Capstone Payment ID
merchantId	string	false	none	The merchant ID through which the transaction was originally run
message	string	false	none	A message from Capstone about the state of the request.
transactionDate	string	false	none	The transaction date and time
transactionStatus	string	false	none	The transaction status
transactionType	string	false	none	The transaction type

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Capture Transaction

Code samples

curl -X POST https://api.capstonesandbox.com/pay/v3/capture \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMwOTg2MjEzOTYiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzA5ODYyMTM5NiIsImN1cnJlbmN5IjoiVVNEIn0",
  "data": {
    "amount": 5.15
  }
}'

POST /pay/v3/capture

Allows you to capture an auth only transaction. To do so:

1. Run an auth only transaction using the Run Card Transaction endpoint.
2. Retrieve the id from the response. This is the Capstone Payment ID.
3. Include that id in the body of your request to this endpoint.

Body parameter

{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMwOTg2MjEzOTYiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzA5ODYyMTM5NiIsImN1cnJlbmN5IjoiVVNEIn0",
  "data": {
    "amount": 5.15
  }
}

Parameters

Name	In	Type	Required	Description
id	body	string	true	The Capstone Payment ID
data	body	object	true	Transaction data
amount	body	number	true	The amount of the auth only transaction you wish to capture. Is not required to be the full amount

Example responses

200 Response

{
  "amount": 15.25,
  "authCode": "035410",
  "currency": "USD",
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD"
  },
  "gatewayResponse": {
    "gatewayName": "nmi",
    "refNumber": "3107885809"
  },
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "merchantId": "100100",
  "message": "success",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "transactionStatus": "pending",
  "transactionType": "sale"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
amount	number	false	none	The amount to be captured
authCode	string	false	none	The authorization code
currency	string	false	none	The three-character ISO currency code for the transaction.
data	object	false	none	Transaction data
amount	number	false	none	The transaction amount
currency	string	false	none	The three-character ISO currency code for the transaction.
settlementCurrency	string	false	none	The currency in which the transaction will be settled
gatewayResponse	object	false	none	Gateway-specific information. Details will vary by gateway. Do NOT code to any information included in this object
gatewayName	string	false	none	The name of the gateway
refNumber	string	false	none	The gateway's reference number
id	string	false	none	Capstone Payment ID
merchantId	string	false	none	The merchant ID through which the transaction was originally run
message	string	false	none	A message from Capstone about the state of the request.
transactionDate	string	false	none	The transaction date and time
transactionStatus	string	false	none	The transaction status
transactionType	string	false	none	The transaction type

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Refund Transaction

Code samples

curl -X POST https://api.capstonesandbox.com/pay/v3/refund \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMwOTg2MjEzOTYiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzA5ODYyMTM5NiIsImN1cnJlbmN5IjoiVVNEIn0",
  "data": {
    "amount": 2.5
  }
}'

POST /pay/v3/refund

Allows you to refund a credit card transaction using the Capstone Payment ID. To do so:

1. Run a transaction using the Run Credit Card Transaction endpoint.
2. Retrieve the id from the response. This is the Capstone Payment ID.
3. Include that id in the body of your request to this endpoint.

Body parameter

{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMwOTg2MjEzOTYiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzA5ODYyMTM5NiIsImN1cnJlbmN5IjoiVVNEIn0",
  "data": {
    "amount": 2.5
  }
}

Parameters

Name	In	Type	Required	Description
id	body	string	true	The Capstone Payment ID. (To void a transaction through this endpoint it must have been captured through the Capstone Payment API)
data	body	object	true	none
amount	body	number	true	The amount of the transaction you wish to refund. Is not required to be the full amount, but may not exceed it

Example responses

200 Response

{
  "amount": 15.25,
  "authCode": "035410",
  "currency": "USD",
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD"
  },
  "gatewayResponse": {
    "gatewayName": "nmi",
    "refNumber": "3107885809"
  },
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "merchantId": "100100",
  "message": "success",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "transactionStatus": "pending",
  "transactionType": "sale"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
amount	number	false	none	The amount to be refunded
authCode	string	false	none	The authorization code
currency	string	false	none	The three-character ISO currency code for the transaction.
data	object	false	none	Transaction data
amount	number	false	none	The transaction amount
currency	string	false	none	The three-character ISO currency code for the transaction.
settlementCurrency	string	false	none	The currency in which the transaction will be settled
gatewayResponse	object	false	none	Gateway-specific information. Details will vary by gateway. Do NOT code to any information included in this object
gatewayName	string	false	none	The name of the gateway
refNumber	string	false	none	The gateway's reference number
id	string	false	none	Capstone Payment ID
merchantId	string	false	none	The merchant ID through which the transaction was originally run
message	string	false	none	none
transactionDate	string	false	none	The transaction date and time
transactionStatus	string	false	none	The transaction status
transactionType	string	false	none	The transaction type

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Get Card Token

Code samples

curl -X GET https://api.capstonesandbox.com/pay/v3/vault/card/{cardToken} \
  -H 'Accept: application/json'

GET /pay/v3/vault/card/{cardToken}

Allows you to view details of a specific card token.

Parameters

Name	In	Type	Required	Description
cardToken	path	string	true	The card token you wish to view. This is a path parameter.

Example responses

200 Response

{
  "accountUpdaterStatus": "isExcluded",
  "card": {
    "expirationMonth": "07",
    "expirationYear": "2022",
    "cardHolderName": "Jane Doe"
  },
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    }
  },
  "dateCreated": "2019-07-31T17:02:39.035Z",
  "dateLastModified": "2019-07-31T18:33:30.660Z",
  "merchantId": "100100",
  "shouldUpdateCard": true,
  "tokenex": {
    "cardType": "visa",
    "firstSix": "479300",
    "lastFour": "3313",
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
accountUpdaterStatus	string	false	none	The card's account updater status. For a list of possible values and meanings, see the Account Updater Card Status table.
card	object	false	none	Card information
expirationMonth	string	false	none	The month in which the saved card expires
expirationYear	string	false	none	The year in which the saved card expires
cardHolderName	string	false	none	The cardholder's name, as it appears on the card
data	object	false	none	Additional data attached to the card token
customer	object	false	none	Customer information returned when checking fraud or from the processing gateway, when applicable.
billToAddressOne	string	false	none	The street address on file with the credit card provider
billToAddressTwo	string	false	none	Additional street address information, if required
billToCity	string	false	none	The city on file with the credit card provider
billToCountry	string	false	none	The two-character (Alpha-2) ISO country code
billToPhone	string	false	none	The billing phone number
billToPostal	string	false	none	The postal code on file with the credit card provider
billToState	string	false	none	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
birthDate	string	false	none	The customer's date of birth. The format returned matches the format used in the request that created the Card Token.
createdAtDate	string	false	none	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
customerRef	string	false	none	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
email	string	false	none	The customer's email address
firstName	string	false	none	The customer's first name, as it appears on the credit card
invoice	string	false	none	The invoice number
lastName	string	false	none	The customer's last name, as it appears on the credit card
orderNumber	string	false	none	The order number
phone	string	false	none	The customer's phone number
shipToAddressOne	string	false	none	The shipping address, if different from the billing address
shipToAddressTwo	string	false	none	Additional shipping address information, if required
shipToCity	string	false	none	The shipping city
shipToCountry	string	false	none	The two-character (Alpha-2) ISO country code
shipToPhone	string	false	none	The shipping phone number
shipToPostal	string	false	none	The shipping postal code
shipToState	string	false	none	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
dateCreated	string	false	none	The date and time when the record of this card was created.
dateLastModified	string	false	none	The date and time at which the record of this card was last modified.
merchantId	string	false	none	The merchant account under which the card token is saved
shouldUpdateCard	boolean	false	none	The card's account updater enrollment tag When true, the card or e-check token is tagged for registration with account updater Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information
tokenex	object	false	none	The card token
cardType	string	false	none	The card type. This information is required when saving a card through your own form. May be any of the following: visa mastercard discover amex
firstSix	string	false	none	The first six digits of the card number
lastFour	string	false	none	The last four digits of the card number
token	string	false	none	The TokenEx card token

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Edit Card Token

Code samples

curl -X PUT https://api.capstonesandbox.com/pay/v3/vault/card/{cardToken} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "card": {
    "cardHolderName": "Jane Doe",
    "expirationMonth": "12",
    "expirationYear": "22"
  },
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    }
  },
  "shouldUpdateCard": true
}'

PUT /pay/v3/vault/card/{cardToken}

Allows you to edit the expiration date, account updater status, and customer information for an existing token.

Use this endpoint to register/deregister card tokens with the account updater service.

Note: Cards registered with the account updater service may take up to 72 hours to be deregistered.

Body parameter

{
  "card": {
    "cardHolderName": "Jane Doe",
    "expirationMonth": "12",
    "expirationYear": "22"
  },
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    }
  },
  "shouldUpdateCard": true
}

Parameters

Name	In	Type	Required	Description
cardToken	path	string	true	The card token you wish to edit. (Sent as a path parameter).
card	body	object	false	Card information you wish to edit. Only provided fields will be edited
cardHolderName	body	string	false	The updated cardholder name
expirationMonth	body	string	false	The updated expiration month
expirationYear	body	string	false	The updated expiration year
data	body	object	false	Optional data you wish to edit. Only provided fields will be edited
customer	body	customerCardToken	false	Customer information to be used in checking fraud or sent to the processing gateway, when applicable
billToAddressOne	body	billToAddressOne	false	The street address on file with the credit card provider
billToAddressTwo	body	billToAddressTwo	false	Additional street address information, if required
billToCity	body	billToCity	false	The city on file with the credit card provider
billToCountry	body	billToCountry	false	The two-character (Alpha-2) ISO country code
billToPhone	body	billToPhone	false	The billing phone number
billToPostal	body	billToPostal	false	The postal code on file with the credit card provider
billToState	body	billToState	false	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
birthDate	body	birthDate	false	The customer's date of birth. Use any of the following formats for the date: Four-digit month, 2-digit month and day, separated with hyphens: YYYY-MM-DD. For example, 2001-08-26 ISO-8601 date expressed in UTC. For example, 2001-08-26T13:35:00Z UNIX date (as an integer representing seconds). For example, 998854500
createdAtDate	body	createdAtDate	false	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
customerRef	body	customerRef	false	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
email	body	email	false	The customer's email address
firstName	body	firstName	false	The customer's first name, as it appears on the credit card
invoice	body	invoice	false	The invoice number
lastName	body	lastName	false	The customer's last name, as it appears on the credit card
orderNumber	body	orderNumber	false	The order number
phone	body	phone	false	The customer's phone number
shipToAddressOne	body	shipToAddressOne	false	The shipping address, if different from the billing address
shipToAddressTwo	body	shipToAddressTwo	false	Additional shipping address information, if required
shipToCity	body	shipToCity	false	The shipping city
shipToCountry	body	shipToCountry	false	The two-character (Alpha-2) ISO country code
shipToPhone	body	shipToPhone	false	The shipping phone number
shipToPostal	body	shipToPostal	false	The shipping postal code
shipToState	body	shipToState	false	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
shouldUpdateCard	body	shouldUpdateCard	false	The card's account updater enrollment tag When true, the card or e-check token is tagged for registration with account updater Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information

Example responses

200 Response

{
  "accountUpdaterStatus": "isExcluded",
  "card": {
    "cardHolderName": "Jane Doe",
    "expirationMonth": "07",
    "expirationYear": "2022"
  },
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    }
  },
  "dateCreated": "2019-07-31T17:02:39.035Z",
  "dateLastModified": "2019-07-31T18:33:30.660Z",
  "merchantId": "100100",
  "shouldUpdateCard": true,
  "tokenex": {
    "cardType": "visa",
    "firstSix": "479300",
    "lastFour": "3313",
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "originalCard": {
    "cardHolderName": "Jane Doe",
    "expirationMonth": "07",
    "expirationYear": "2019"
  }
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
accountUpdaterStatus	string	false	none	The card's account updater status. For a list of possible values and meanings, see the Account Updater Card Status table.
card	object	false	none	Card information
cardHolderName	string	false	none	The cardholder's name, as it appears on the card
expirationMonth	string	false	none	The month in which the saved card expires
expirationYear	string	false	none	The year in which the saved card expires
data	object	false	none	Additional data attached to the card token
customer	object	false	none	Customer information returned when checking fraud or from the processing gateway, when applicable.
billToAddressOne	string	false	none	The street address on file with the credit card provider
billToAddressTwo	string	false	none	Additional street address information, if required
billToCity	string	false	none	The city on file with the credit card provider
billToCountry	string	false	none	The two-character (Alpha-2) ISO country code
billToPhone	string	false	none	The billing phone number
billToPostal	string	false	none	The postal code on file with the credit card provider
billToState	string	false	none	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
birthDate	string	false	none	The customer's date of birth. The format returned matches the format used in the request that created the Card Token.
createdAtDate	string	false	none	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
customerRef	string	false	none	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
email	string	false	none	The customer's email address
firstName	string	false	none	The customer's first name, as it appears on the credit card
invoice	string	false	none	The invoice number
lastName	string	false	none	The customer's last name, as it appears on the credit card
orderNumber	string	false	none	The order number
phone	string	false	none	The customer's phone number
shipToAddressOne	string	false	none	The shipping address, if different from the billing address
shipToAddressTwo	string	false	none	Additional shipping address information, if required
shipToCity	string	false	none	The shipping city
shipToCountry	string	false	none	The two-character (Alpha-2) ISO country code
shipToPhone	string	false	none	The shipping phone number
shipToPostal	string	false	none	The shipping postal code
shipToState	string	false	none	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
dateCreated	string	false	none	The date and time at which the card was created
dateLastModified	string	false	none	The date and time at which the card was last modified
merchantId	string	false	none	The merchant account under which the card token is saved
shouldUpdateCard	boolean	false	none	The card's account updater enrollment tag When true, the card or e-check token is tagged for registration with account updater Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information
tokenex	object	false	none	The card token
cardType	string	false	none	The card type. This information is required when saving a card through your own form. May be any of the following: visa mastercard discover amex
firstSix	string	false	none	The first six digits of the card number
lastFour	string	false	none	The last four digits of the card number
token	string	false	none	The TokenEx card token
originalCard	object	false	none	Original card details
cardHolderName	string	false	none	The cardholder's name, as it appears on the card
expirationMonth	string	false	none	The month in which the saved card expires
expirationYear	string	false	none	The year in which the saved card expires

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Delete Card Tokens

Code samples

curl -X POST https://api.capstonesandbox.com/pay/v3/deleteToken \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "tokens": [
    "p6711abg-41fd-m56a-81a1-t0k3n287799b"
  ]
}'

POST /pay/v3/deleteToken

Allows you to delete card tokens from the card vault.

Note: Cards registered with the account updater service may take up to 72 hours to be removed.</p?

Body parameter

{
  "tokens": [
    "p6711abg-41fd-m56a-81a1-t0k3n287799b"
  ]
}

Parameters

Name	In	Type	Required	Description
tokens	body	[string]	true	An array of card tokens

Example responses

200 Response

[
  {
    "error": "",
    "key": "p6711abg-41fd-m56a-81a1-t0k3n287799b",
    "message": "Successfully removed from vault",
    "status": "success"
  }
]

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	array	false	none	none
error	string	false	none	The error message, if applicable
key	string	false	none	The card token that has been deleted
message	string	false	none	A message indicating the status of the request
status	string	false	none	The status of the request

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Get Currency Rates

Code samples

curl -X GET https://api.capstonesandbox.com/pay/v3/getCurrencyRates \
  -H 'Accept: application/json'

GET /pay/v3/getCurrencyRates

Retrieves a list of currencies and their current conversion rates for all currencies configured in your account. This endpoint is not available for all merchant accounts. To enable your merchant account for retrieving the currency rates, contact Integration Support.

Example responses

200 Response

[
  {
    "currency": "USD",
    "merchantId": "100039",
    "paymentOptionTag": [
      "myGatewayGBP"
    ],
    "rate": "1.2209524"
  }
]

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

An array of all currencies and their conversion rates

Name	Type	Required	Restrictions	Description
anonymous	array	false	none	An array of all currencies and their conversion rates
currency	string	false	none	The three-character ISO currency code.
merchantId	string	false	none	The merchant ID (MID) for which this currency is enabled.
paymentOptionTag	array	false	none	A list of all payment option tags for which this currency is enabled for given merchant ID
rate	string	false	none	The current conversion rate from the listed currency to USD

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Retail

Simple Login

Code samples

curl -X POST https://api.capstonesandbox.com/auth/v3/createSimpleLogin \
  -H 'Accept: application/json'

POST /auth/v3/createSimpleLogin

Simple Login allows trusted users to proceed directly to the retail/MOTO Iframe without entering a Capstone username and password. This option is useful for cases in which multiple users will be using a single Capstone account. It can also save time for internal users by eliminating the need to enter a username and password upon each use.

Example responses

200 Response

{
  "exp": 1550600014,
  "jwt": "t3jraWQiOiI3V2JrOFdSVVliMVljR2p3Mlhwd2swR3lIRWt6THcwVDRqckVhNVVVTjBnPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI4YWYzZTQwZC02Y2I0LTQ0ZWQtOWRlZS0yN2Y3NmNmNDc0YmMiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfVlVEN21MeWNqIiwiY3VzdG9tOmFjY291bnRJZCI6ImVjN2NiOWJhLWQwMmQtNDhkYS1hY2I3LWI2ZWQ3YmJiZWQwMiIsImNvZ25pdG86dXNlcm5hbWUiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIiwiYXVkIjoiNDBtZWQ2YnNybDZ1aWpnMmpmZzQwcmJzOGkiLCJldmVudF9pZCI6IjE0YmU5MWFjLTM0NjctMTFlOS9iNDZjLWMxMjdjYTkzZjA3NCIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNTUwNTk1Mjk0LCJleHAiOjE1NTA1OTg4OTRsImN1c3RvbTphY2Nlc3NSaWdodHMiOiJ7XCJtZXJjaGFudElkc1wiOntcIjEwMDAzOVwiOlwiQVwiLFwiMTAwMDQxXCI6XCJBXCIsXCI1MTU3OTQwMDAwMTM1MDRcIjpcIkFcIixcIjkyMzYwMDAwMTEyNDUwM1wiOlwiQVwiLFwiOTIzNTAwMDAxNDMyNzQyXCI6XCJBXCIsXCI1MTM0ODUwMDAwMDAwMThcIjpcIkFcIixcIjkyMzYwMDAwODEyNjYxMFwiOlwiQVwiLFwiOTIzNjAwMDAzMTYzODEwXCI6XCJBXCJ9LFwicm9sZVwiOlwiQVwifSIsImlhdCI6MTU1MDU5NTI5NCwiZW1haWwiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIn0.OEEZarSzbSLpxUM55UKmycYtAAWEtm__XUJdqBJ9QPSF_8sdLIL9EXBF8cLarhv3DoLqeWKUpieNgfcME2IsIc8amDXitvJtJe3STQtI_zaJwAibBxJhFKQRLRCrIe3kpslVJPuw3OeST54QcseifLlA64bxNaveXygja7aejwINueE4_Nj0NEzcFGZoYHgNB6br6Ksbjgx-z_SiFIZ1XHS-eOMnBoCIVWjFr3FY9IbfnQf4v0c0AFWKt9mOpjYracSqOHHmSER7GuaMBNrHxfbe0kHVh6hvnrzh10SEnTsF573qbP1R_aZA_Uh80MOLB0UvPWWFzzyP4GniNc3zLw",
  "key": "4f211fde-d135-4c91-afbc-bcdb73c0c504",
  "refreshToken": "t3jjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.CejuLZHvZcrISuiwE7N4xg7EYq6ArivbyNwDVE2X7eTdr7CTO4l5udgc9ZUV1byTe1r3eLN_szbte1nlaimbQj5ZcJpim1zmW5pkk7aFVF-WcnLjIBVPilp6bLW8gsZaB04WErDjwzt4r7Bxnz6YnmLM7e3V15ZVkY6GLFqgrUF9Tb9UOFbCDD_H8qe1AdFktVeeVgefekJew3RuZ8p2BnKWejt1BcyMUnYY-QgaLm3TzUpd14PRbdvOfBG3D9KmJCnZ_6H9sQ5FUirqsF_U6eXNppE1QXZdjhFg4oic791Kq5rXU2xbMI9ggeFoGIjLLP0Keb0iT66NwXpf50-h4w.eUOjohgz3zXTJWHH.IBQMMiNKtbAZ02r0QGXJXw_zM2c3epH5LGtdZxIVUReMRr5CLm-ptE7zaFTK0D1tpUHcVonqiDuXyc09IN0IO4jL32QqQjgeG-V9LBYgpr1xV3qyc5TR-L2VNHjJt3A3SbJsIzxHDqKLucJw2N0WaiOgLb577q8B8lu0pLCpOV_POlUiT4BLAvycMCKkgUCDrejyjzR39ofCUqtZKuMglXanUfVE3hC0OaNOMpl65N_utjuf9vzklyZZRQMTgokQ7V0yp0VSpCC6D_zNBvwTPUKHVFyMrzEC4wJZ9uOtIS9h9rv_HywpwrPqHYajsGYNrv7QvHE1Kg80I73CbL0owW-J5bKEbgImqkahNVhBoFJejnvN3PEr9zthNey15Q_utOUFUkR0Po9GH6fnXFXxQnIC7c2hQ4lgjV2wR3WGzEiE5L0aNLF1Cnjyn-t1VZxQHG2uiyiT1aIUFBPbItTkVPjKhkFKf7AfXqOTAl52VFdBPpFdbG5Ecwfm_4ZGgO_4KJnLcb7qMQuEI6G20xelkPD2NHIpdS9gHx7XIlyfiBPkvq3YEKMtOQQbRAQ_Hcy7leeZnSyPgq65Bnsn22xZ4NG5bSshSEEMlq5lbOV4-dzBGV8SA6dOeNHR7GeQvSr1XQ89sBloJlMKJLe9WL0fYhkY6u-MbmecvMoU1OrC4mvIv-0l53TIeeGDMtn8UkcaSxQG7HBEqcQlvaFAxGaol7kiDPlAMxdp11lnk0ix3G0M74xHRFpZalIFtUAPm2xEVFJLWlwLqalRgJpO70asiw9QJ_pi0HERT5N_wCXraxeQyNrknNmi157ih5yP7SGm7MXrSVUOHu6GIBZktAfP8IURhJNQZfSk3Do_up1vUBPN7yLNumqPq2PWH3CgFXle3nDaQYCVsVkGU-FZTy7KLIbKc2EStkOFOCPiYYSoD8h1-C8kclCeIKFLDFQIo7weJyIGjQqV_pY9HEPQivgXw6X1ti711x0YZ2bhl9tPuUEtXeja7hGAxLnrU4QqHr2iS58J9F5NMVc6LlK_NcExLzrlnQBJws7urmDkV_yoOtCRadxVuAxVCYqfAh8X4gzQ7LQMT27pFeV98iCvAmkhWx4RpAmFYHmacUJIXUVXKe6eTlN27gsYir1H9SrkbFgjOjvoUBj5p-mn-mMathsdAbRtlryJEjfCzAfBWis-7d4GsxCZGQnCJ0NezIP50_2dCPyzpgYcUwt4E4kHIA5-SBOLWneULDPz7VpRJxKv8BaYxOZuotnV2zz2nwB3vlDWK1h6cgRfMT8o8iphcUMxdZdjd-FElzNCdQ.SDQXbyIYZu6_jdCeAzTzoA",
  "username": "youremail@cmsonline.com"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
exp	integer	false	none	The expiration time of the Simple Login
jwt	string	false	none	The JSON Web Token
key	string	false	none	The simple login key
refreshToken	string	false	none	The refresh token
username	string	false	none	The simple login username

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Get Terminal List

Code samples

curl -X GET https://api.capstonesandbox.com/pay/v3/getTerminalList \
  -H 'Accept: application/json'

GET /pay/v3/getTerminalList

Retrieves a list of available terminals.
Note: Terminals must be configured by integration support before they are available for processing. If you do not see a terminal in the list retrieved here, contact Integration Support for assistance.

Example responses

200 Response

[
  {
    "gatewayLabel": "...2e21,...5ee7",
    "gatewayName": "yourGateway",
    "gatewayType": 110,
    "merchantId": "103002",
    "merchantName": "Test Merchant",
    "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19",
    "terminalName": "Terminal 1",
    "terminalSerialNumber": "84937213"
  }
]

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

An array of available terminals

Name	Type	Required	Restrictions	Description
anonymous	array	false	none	An array of available terminals
gatewayLabel	string	false	none	The gateway label
gatewayName	string	false	none	The gateway name
gatewayType	integer	false	none	The gateway type
merchantId	string	false	none	The merchant ID configured for this gateway
merchantName	string	false	none	The merchant name
terminalId	string	false	none	The Capstone Terminal ID
terminalName	string	false	none	The terminal name
terminalSerialNumber	string	false	none	The terminal serial number

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Process from Terminal

Code samples

curl -X POST https://api.capstonesandbox.com/pay/v3/processFromTerminal \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "data": {
    "amount": "13.45"
  },
  "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19"
}'

POST /pay/v3/processFromTerminal

Initiates a terminal transaction. For more information on how to process through EMV, see the steps in Run a Terminal Transaction.

Body parameter

{
  "data": {
    "amount": "13.45"
  },
  "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19"
}

Parameters

Name	In	Type	Required	Description
data	body	object	true	Transaction data
amount	body	string	true	The transaction amount
terminalId	body	string	false	An ID used to identify a specific terminal. For a list of terminal IDs see the Get Terminal List endpoint.

Example responses

200 Response

{
  "terminalRequestId": "64ea267f-2766-49b8-9e0e-aeb91b2fe722",
  "terminalRequestStatus": "initialized"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
terminalRequestId	string	false	none	An ID used to identify a transaction initiated using a terminal
terminalRequestStatus	string	false	none	The status of the transaction initiated using a terminal

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Terminal Transaction Status

Code samples

curl -X GET https://api.capstonesandbox.com/pay/v3/processFromTerminal/{terminalRequestId} \
  -H 'Accept: application/json'

GET /pay/v3/processFromTerminal/{terminalRequestId}

Checks the status of a transaction run through the terminal.

Parameters

Name	In	Type	Required	Description
terminalRequestId	path	string	true	The terminal request ID. Found in the response of Process from Terminal endpoint. This is submitted as a path parameter.

Example responses

200 Response

{
  "gatewayResponse": {
    "gatewayName": "yourGateway"
  },
  "terminalRequestId": "64ea267f-2766-49b8-9e0e-aeb91b2fe722",
  "terminalRequestStatus": "initialized"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized
490	Unknown	Error

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
gatewayResponse	object	false	none	Gateway-specific information. Details will vary by gateway. Do NOT code to any information included in this object
gatewayName	string	false	none	The name of the gateway
terminalRequestId	string	false	none	An ID used to identify a transaction initiated using a terminal
terminalRequestStatus	string	false	none	The status of the transaction initiated using a terminal

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Status Code 490

Name	Type	Required	Restrictions	Description
message	string	false	none	The response message
error	integer	false	none	The error code, if applicable
gatewayResponse	object	false	none	Gateway-specific information. Details will vary by gateway. Do NOT code to any information included in this object
gatewayName	string	false	none	The name of the gateway

Subscriptions

Create Subscription

Code samples

curl -X POST https://api.capstonesandbox.com/subscription/v3 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "payment": {
    "data": {
      "paymentMethod": "card",
      "amount": 29.99,
      "currency": "USD",
      "customer": {
        "customerRef": "RP006",
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "createdAtDate": "2005-03-01",
        "email": "jdoe@yourwebsite.com",
        "orderDate": "2021-08-26",
        "phone": "1555555555",
        "billToAddressOne": "2147 West Silverlake Drive",
        "billToAddressTwo": "Apt 42",
        "billToCity": "Scranton",
        "billToState": "PA",
        "billToPostal": "18503",
        "billToCountry": "US",
        "billToPhone": "1555555555",
        "shipToAddressOne": "1725 Slough Avenue",
        "shipToAddressTwo": "Suite 200",
        "shipToCity": "Scranton",
        "shipToState": "PA",
        "shipToPostal": "18505",
        "shipToCountry": "US",
        "shipToPhone": "1555555555"
      },
      "cart": {
        "items": [
          {
            "item": "913261",
            "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
            "quantity": 8,
            "price": 16.49,
            "type": "sale"
          }
        ]
      },
      "lodging": {
        "advanceDeposit": true,
        "checkInDate": "2018-12-31",
        "checkOutDate": "2019-01-05",
        "noShow": false,
        "roomNumber": 14,
        "roomRate": 143.99
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": ""
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313",
      "customerRefNumber": "74771a19-3c28-4c27-83c6-9"
    },
    "isAuthOnly": false,
    "processingOptions": {
      "checkFraud": false,
      "merchantId": "100039",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0,
    "balance": 95,
    "duration": 5,
    "dateInitialBillingEnd": "2021-06-01",
    "initialBillingAmount": "8.99"
  }
}'

POST /subscription/v3

Creates a recurring payment. A successful request to this endpoint will process an intial transaction and schedule recurring transactions. All transactions will be processed with the values provided in the payment object. Scheduled transaction will be run according to the values provided in the schedule object.

Note: This service is in beta. Contact integration support if you would like to use this feature.

Body parameter

{
  "payment": {
    "data": {
      "paymentMethod": "card",
      "amount": 29.99,
      "currency": "USD",
      "customer": {
        "customerRef": "RP006",
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "createdAtDate": "2005-03-01",
        "email": "jdoe@yourwebsite.com",
        "orderDate": "2021-08-26",
        "phone": "1555555555",
        "billToAddressOne": "2147 West Silverlake Drive",
        "billToAddressTwo": "Apt 42",
        "billToCity": "Scranton",
        "billToState": "PA",
        "billToPostal": "18503",
        "billToCountry": "US",
        "billToPhone": "1555555555",
        "shipToAddressOne": "1725 Slough Avenue",
        "shipToAddressTwo": "Suite 200",
        "shipToCity": "Scranton",
        "shipToState": "PA",
        "shipToPostal": "18505",
        "shipToCountry": "US",
        "shipToPhone": "1555555555"
      },
      "cart": {
        "items": [
          {
            "item": "913261",
            "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
            "quantity": 8,
            "price": 16.49,
            "type": "sale"
          }
        ]
      },
      "lodging": {
        "advanceDeposit": true,
        "checkInDate": "2018-12-31",
        "checkOutDate": "2019-01-05",
        "noShow": false,
        "roomNumber": 14,
        "roomRate": 143.99
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": ""
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313",
      "customerRefNumber": "74771a19-3c28-4c27-83c6-9"
    },
    "isAuthOnly": false,
    "processingOptions": {
      "checkFraud": false,
      "merchantId": "100039",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0,
    "balance": 95,
    "duration": 5,
    "dateInitialBillingEnd": "2021-06-01",
    "initialBillingAmount": "8.99"
  }
}

Parameters

Name	In	Type	Required	Description
payment	body	object	true	Payment information for the initial transaction and for recurring (scheduled) transactions
data	body	object	true	Transaction data
paymentMethod	body	string	false	Payment method. Set to eCheck to run e-check transactions
amount	body	number	true	The amount that will be charged during each recurring transaction.
currency	body	currency	true	The three-character ISO currency code for the transaction.
customer	body	object	true	Customer information to be used in checking fraud or sent to the processing gateway, when applicable
customerRef	body	customerRef	true	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
firstName	body	firstName	false	The customer's first name, as it appears on the credit card
lastName	body	lastName	false	The customer's last name, as it appears on the credit card
invoice	body	invoice	false	The invoice number
orderNumber	body	orderNumber	false	The order number
birthDate	body	birthDate	false	The customer's date of birth. Use any of the following formats for the date: Four-digit month, 2-digit month and day, separated with hyphens: YYYY-MM-DD. For example, 2001-08-26 ISO-8601 date expressed in UTC. For example, 2001-08-26T13:35:00Z UNIX date (as an integer representing seconds). For example, 998854500
createdAtDate	body	createdAtDate	false	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
email	body	email	false	The customer's email address
orderDate	body	orderDate	false	The date of the customer's order. Use any of the following formats for the date: Four-digit month, 2-digit month and day, separated with hyphens: YYYY-MM-DD. For example, 2021-08-26 ISO-8601 date expressed in UTC. For example, 2021-08-26T13:35:18Z UNIX date (as an integer representing seconds). For example, 1630006518 Note: This is NOT a quick way to schedule a transaction. Specifying a date in the future does not cause the order to be run automatically at the indicated date or time.
phone	body	phone	false	The customer's phone number
billToAddressOne	body	billToAddressOne	false	The street address on file with the credit card provider
billToAddressTwo	body	billToAddressTwo	false	Additional street address information, if required
billToCity	body	billToCity	false	The city on file with the credit card provider
billToState	body	billToState	false	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
billToPostal	body	billToPostal	false	The postal code on file with the credit card provider
billToCountry	body	billToCountry	false	The two-character (Alpha-2) ISO country code
billToPhone	body	billToPhone	false	The billing phone number
shipToAddressOne	body	shipToAddressOne	false	The shipping address, if different from the billing address
shipToAddressTwo	body	shipToAddressTwo	false	Additional shipping address information, if required
shipToCity	body	shipToCity	false	The shipping city
shipToState	body	shipToState	false	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
shipToPostal	body	shipToPostal	false	The shipping postal code
shipToCountry	body	shipToCountry	false	The two-character (Alpha-2) ISO country code
shipToPhone	body	shipToPhone	false	The shipping phone number
cart	body	cart	false	Items purchased in the transaction
items	body	[item]	false	Details about items in the shopping cart
item	body	itemItem	false	Item number or code
description	body	descriptionItem	false	A description of the item
quantity	body	quantity	false	The quantity sold
price	body	price	false	The price per item
type	body	transactionType	false	The transaction type
lodging	body	lodging	false	Lodging data (related to hotels, motels, inns, etc.)
advanceDeposit	body	boolean	false	Set to true if the customer paid a deposit in advance of their reservation
checkInDate	body	string	false	The customer's check in date in standard ISO date format
checkOutDate	body	string	false	The customer's check out date in standard ISO date format
noShow	body	boolean	false	Set to true if the customer failed to show up to their reservation
roomNumber	body	number	false	The customer's room number
roomRate	body	number	false	The room's rate, per day
customFields	body	customFields	false	Custom fields that can be used to pass additional strings along to the gateway. These fields will not be stored by Capstone. Notes: Do not use custom fields to store sensitive data. Some information may be escaped and may not be usable in custom fields.
exampleKey	body	string	false	You may use any key as a custom field. Values must be strings.
description	body	string	false	A description of the transaction
descriptor	body	descriptor	false	Include this parameter to dynamically change the descriptor on the customer's statement. If this parameter is not included, the default descriptor (as set up on the merchant account that is originating the transactions) will be used. When applicable, this information will be passed along to gateway. Contact integration support if you have any questions about this parameter
tokenex	body	object	true	A previously saved card or e-check token
token	body	string	true	The card token or e-check token
firstSix	body	string	false	The first six digits of the card number
lastFour	body	string	false	The last four digits of the card number or bank account number
customerRefNumber	body	string	false	The customer reference number
isAuthOnly	body	boolean	false	Set to true to run an auth only transaction. (This applies to the initial transaction and scheduled transactions.) Note: Auth only transactions must be captured in your own code base. To authorize and capture scheduled transactions set this value to false, or update it to false after the initial transaction has been processed
processingOptions	body	object	false	Processing Options
checkFraud	body	checkFraud	false	Set to false to opt out of sending a request to Kount. Note: During testing you may trigger specific Kount responses by including any of the values shown here
merchantId	body	merchantId	false	The merchant ID (MID)
paymentOptionTag	body	paymentOptionTag	false	A custom value used to route transactions to a specific gateway or merchant account. Contact integration support to designate a paymentOptionTag for a given merchant account.
shouldUseFingerprint	body	shouldUseFingerprint	false	This parameter applies when a device fingerprint was created while saving a card token. The card's stored fingerprint will be used by default, but you may choose not to use it by setting this parameter to false. Note: To change your merchant's default setting, contact integration support
verboseResponse	body	verboseResponse	false	Set to true to include additional information in the response
webhookUrl	body	webhookUrl	false	The URL to which Capstone will send the results of the transaction. (If not provided you will need to use the results of the HTTP request, either from the browser or your server)
webhookFailUrl	body	webhookFailUrl	false	The URL to which Capstone will send the results of a failed transaction
schedule	body	scheduleRequest	false	The schedule for recurring transactions
interval	body	interval	false	The schedule's time period. Possible values: day, week, month, year
intervalCount	body	intervalCount	false	The number of intervals that will pass between transactions. See the subscription schedule examples table for examples of how the interval and interval count create the subscription schedule.
balance	body	integer	false	The total amount to be charged over the course of the pay plan
duration	body	integer	false	The duration of the pay plan. This is the number of transactions that will run before the pay plan terminates. If amount is not provided the duration will also be used to calculate the amount to be charged during each transaction
dateInitialBillingEnd	body	dateInitialBillingEnd(date)	false	The date at which the initial billing period will end. Transactions prior to this date will be run for the initial billing amount. Transactions after this date will be run for the subscription amount
initialBillingAmount	body	initialBillingAmount	false	The transaction amount during the initial billing period.

Example responses

200 Response

{
  "customerRef": "RP006",
  "accountId": "27592004",
  "id": "e80d63dd-a77b-407a-9124-42acf00740dd",
  "payment": {
    "isAuthOnly": true,
    "data": {
      "amount": 29.99,
      "cart": {
        "items": [
          {
            "item": "913261",
            "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
            "quantity": 8,
            "price": 16.49,
            "type": "sale"
          }
        ]
      },
      "currency": "USD",
      "customer": {
        "customerRef": "RP006",
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "createdAtDate": "2005-03-01",
        "email": "jdoe@yourwebsite.com",
        "phone": "1555555555",
        "billToAddressOne": "2147 West Silverlake Drive",
        "billToAddressTwo": "Apt 42",
        "billToCity": "Scranton",
        "billToState": "PA",
        "billToPostal": "18503",
        "billToCountry": "US",
        "billToPhone": "1555555555",
        "orderDate": "2021-08-26",
        "shipToAddressOne": "1725 Slough Avenue",
        "shipToAddressTwo": "Suite 200",
        "shipToCity": "Scranton",
        "shipToState": "PA",
        "shipToPostal": "18505",
        "shipToCountry": "US",
        "shipToPhone": "1555555555"
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": "",
      "lodging": {
        "advanceDeposit": true,
        "checkInDate": "2018-12-31",
        "checkOutDate": "2019-01-05",
        "noShow": false,
        "roomNumber": 14,
        "roomRate": 143.99
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313"
    },
    "processingOptions": {
      "checkFraud": false,
      "merchantId": "100039",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0,
    "balance": 0,
    "initialBalance": 50,
    "duration": 5,
    "dateInitialBillingEnd": "2021-06-01",
    "initialBillingAmount": "8.99"
  },
  "paymentResponse": {
    "amount": 34.25,
    "authCode": "035410",
    "card": {
      "expirationMonth": "12",
      "expirationYear": "20",
      "cardType": "visa",
      "cardHolder": "John H Doe"
    },
    "currency": "USD",
    "data": {
      "amount": 29.99,
      "currency": "USD",
      "settlementCurrency": "CAD",
      "customer": {
        "customerRef": "RP006",
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "createdAtDate": "2005-03-01",
        "email": "jdoe@yourwebsite.com",
        "phone": "1555555555",
        "billToAddressOne": "2147 West Silverlake Drive",
        "billToAddressTwo": "Apt 42",
        "billToCity": "Scranton",
        "billToState": "PA",
        "billToPostal": "18503",
        "billToCountry": "US",
        "billToPhone": "1555555555",
        "orderDate": "2021-08-26",
        "shipToAddressOne": "1725 Slough Avenue",
        "shipToAddressTwo": "Suite 200",
        "shipToCity": "Scranton",
        "shipToState": "PA",
        "shipToPostal": "18505",
        "shipToCountry": "US",
        "shipToPhone": "1555555555"
      },
      "cart": {
        "items": [
          {
            "item": "913261",
            "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
            "quantity": 8,
            "price": 16.49,
            "type": "sale"
          }
        ]
      },
      "lodging": {
        "advanceDeposit": true,
        "checkInDate": "2018-12-31",
        "checkOutDate": "2019-01-05",
        "noShow": false,
        "roomNumber": 14,
        "roomRate": 143.99
      },
      "customFields": {
        "exampleKey": "Example string"
      }
    },
    "gatewayResponse": {
      "gatewayName": "nmi",
      "refNumber": "3107885809"
    },
    "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
    "kountResponse": {
      "status": "success",
      "rules": "{\"VERS\":\"0630\",\"MODE\":\"Q\",\"TRAN\":\"7V7D0V1BMKPX\",\"MERC\":\"717000\",\"SESS\":\"3bbb89edcd5742f18e2502ebb2bbb18b\",\"ORDR\":\"14233\",\"AUTO\":\"A\",\"SCOR\":\"29\",\"GEOX\":\"US\",\"BRND\":\"VISA\",\"REGN\":null,\"NETW\":\"N\",\"KAPT\":\"N\",\"CARDS\":\"1\",\"DEVICES\":\"1\",\"EMAILS\":\"1\",\"VELO\":\"0\",\"VMAX\":\"0\",\"SITE\":\"DEFAULT\",\"DEVICE_LAYERS\":\"....\",\"FINGERPRINT\":null,\"TIMEZONE\":null,\"LOCALTIME\":\" \",\"REGION\":null,\"COUNTRY\":null,\"PROXY\":null,\"JAVASCRIPT\":null,\"FLASH\":null,\"COOKIES\":null,\"HTTP_COUNTRY\":null,\"LANGUAGE\":null,\"MOBILE_DEVICE\":null,\"MOBILE_TYPE\":null,\"MOBILE_FORWARDER\":null,\"VOICE_DEVICE\":null,\"PC_REMOTE\":null,\"RULES_TRIGGERED\":0,\"COUNTERS_TRIGGERED\":0,\"REASON_CODE\":null,\"MASTERCARD\":\"\",\"DDFS\":null,\"DSR\":null,\"UAS\":null,\"BROWSER\":null,\"OS\":null,\"PIP_IPAD\":null,\"PIP_LAT\":null,\"PIP_LON\":null,\"PIP_COUNTRY\":null,\"PIP_REGION\":null,\"PIP_CITY\":null,\"PIP_ORG\":null,\"IP_IPAD\":null,\"IP_LAT\":null,\"IP_LON\":null,\"IP_COUNTRY\":null,\"IP_REGION\":null,\"IP_CITY\":null,\"IP_ORG\":null,\"WARNING_COUNT\":0}"
    },
    "merchantId": "100039",
    "token": {
      "firstSix": "479300",
      "lastFour": "3313",
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    },
    "transactionDate": "2019-01-15T13:19:39.329Z",
    "transactionStatus": "pending",
    "transactionType": "sale"
  },
  "userName": "jdoe@yourwebsite.com",
  "dateCreated": "2020-04-28T19:19:33.183Z",
  "dateLastModified": "2020-04-28T19:19:33.185Z",
  "dateLastRun": "2020-04-28T18:50:04.866Z",
  "dateNextRun": "2020-07-28"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Details on the subscription schedule

Name	Type	Required	Restrictions	Description
customerRef	string	false	none	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
accountId	string	false	none	Your Capstone account number
id	string	false	none	The subscription ID
payment	object	false	none	Payment information for future payments. To update this information, send a request to the Update Subscription endpoint
isAuthOnly	boolean	false	none	Will be true if future transactions are set to authorize only. Will be false if future transactions are set to authorize and capture
data	object	true	none	Transaction data
amount	number	false	none	The transaction amount
cart	object	false	none	Items purchased in the transaction
items	array	false	none	Details about items in the shopping cart
item	string	false	none	Item number or code
description	string	false	none	A description of the item
quantity	integer	false	none	The quantity sold
price	number	false	none	The price per item
type	string	false	none	The transaction type
currency	string	false	none	The three-character ISO currency code for the transaction.
customer	object	false	none	Customer information returned when checking fraud or from the processing gateway, when applicable.
customerRef	string	false	none	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
firstName	string	false	none	The customer's first name, as it appears on the credit card
lastName	string	false	none	The customer's last name, as it appears on the credit card
invoice	string	false	none	The invoice number
orderNumber	string	false	none	The order number
birthDate	string	false	none	The customer's date of birth. The format returned matches the format used in the request that created the subscription.
createdAtDate	string	false	none	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
email	string	false	none	The customer's email address
phone	string	false	none	The customer's phone number
billToAddressOne	string	false	none	The street address on file with the credit card provider
billToAddressTwo	string	false	none	Additional street address information, if required
billToCity	string	false	none	The city on file with the credit card provider
billToState	string	false	none	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
billToPostal	string	false	none	The postal code on file with the credit card provider
billToCountry	string	false	none	The two-character (Alpha-2) ISO country code
billToPhone	string	false	none	The billing phone number
orderDate	string	false	none	The date of the customer's order. The format returned matches the format used in the request.
shipToAddressOne	string	false	none	The shipping address, if different from the billing address
shipToAddressTwo	string	false	none	Additional shipping address information, if required
shipToCity	string	false	none	The shipping city
shipToState	string	false	none	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
shipToPostal	string	false	none	The shipping postal code
shipToCountry	string	false	none	The two-character (Alpha-2) ISO country code
shipToPhone	string	false	none	The shipping phone number
customFields	object	false	none	Custom fields that can be used to pass additional strings along to the gateway. These fields will not be stored by Capstone. Notes: Do not use custom fields to store sensitive data. Some information may be escaped and may not be usable in custom fields.
exampleKey	string	false	none	You may use any key as a custom field. Values must be strings.
description	string	false	none	A description of the transaction
descriptor	string	false	none	Include this parameter to dynamically change the descriptor on the customer's statement. If this parameter is not included, the default descriptor (as set up on the merchant account that is originating the transactions) will be used. When applicable, this information will be passed along to gateway. Contact integration support if you have any questions about this parameter
lodging	object	false	none	Lodging data (related to hotels, motels, inns, etc.)
advanceDeposit	boolean	false	none	Set to true if the customer paid a deposit in advance of their reservation
checkInDate	string	false	none	The customer's check in date in standard ISO date format
checkOutDate	string	false	none	The customer's check out date in standard ISO date format
noShow	boolean	false	none	Set to true if the customer failed to show up to their reservation
roomNumber	number	false	none	The customer's room number
roomRate	number	false	none	The room's rate, per day
tokenex	object	true	none	Card token information
token	string	false	none	The card token that will be used to process future transactions
firstSix	string	false	none	The first six digits of the card number
lastFour	string	false	none	The last four digits of the card number
processingOptions	object	false	none	Processing Options
checkFraud	boolean	false	none	Set to false to opt out of sending a request to Kount. Note: During testing you may trigger specific Kount responses by including any of the values shown here
merchantId	string	false	none	The merchant ID (MID)
paymentOptionTag	string	false	none	A custom value used to route transactions to a specific gateway or merchant account. Contact integration support to designate a paymentOptionTag for a given merchant account.
shouldUseFingerprint	boolean	false	none	This parameter applies when a device fingerprint was created while saving a card token. The card's stored fingerprint will be used by default, but you may choose not to use it by setting this parameter to false. Note: To change your merchant's default setting, contact integration support
verboseResponse	boolean	false	none	Set to true to include additional information in the response
webhookUrl	string	false	none	The URL to which Capstone will send the results of the transaction. (If not provided you will need to use the results of the HTTP request, either from the browser or your server)
webhookFailUrl	string	false	none	The URL to which Capstone will send the results of a failed transaction
schedule	object	false	none	The schedule for recurring transactions
interval	string	false	none	The schedule's time period. Possible values: day, week, month, year
intervalCount	integer	false	none	The number of intervals that will pass between transactions. See the subscription schedule examples table for examples of how the interval and interval count create the subscription schedule.
balance	integer	false	none	The current balance of the pay plan
initialBalance	integer	false	none	The starting balance of the pay plan
duration	integer	false	none	The duration of the pay plan as defined when the pay plan was created
dateInitialBillingEnd	string	false	none	The date at which the initial billing period will end. Transactions prior to this date will be run for the initial billing amount. Transactions after this date will be run for the subscription amount
initialBillingAmount	string	false	none	The transaction amount during the initial billing period.
paymentResponse	object	false	none	The response from a successful payment. (In the case of a subscription, this is the response of the initial transaction)
amount	number	false	none	The transaction amount
authCode	string	false	none	The authorization code
card	object	false	none	Credit card information
expirationMonth	string	false	none	The month in which the card will expire
expirationYear	string	false	none	The two-digit year in which the card will expire
cardType	string	false	none	The card type. This information is required when saving a card through your own form. May be any of the following: visa mastercard discover amex
cardHolder	string	false	none	The cardholder's name as it appears on the card
currency	string	false	none	The three-character ISO currency code for the transaction.
data	object	false	none	Transaction data
amount	number	false	none	The transaction amount
currency	string	false	none	The three-character ISO currency code for the transaction.
settlementCurrency	string	false	none	The currency in which the transaction will be settled
customer	object	false	none	Customer information returned when checking fraud or from the processing gateway, when applicable.
cart	object	false	none	Items purchased in the transaction
lodging	object	false	none	Lodging data (related to hotels, motels, inns, etc.)
customFields	object	false	none	Custom fields that can be used to pass additional strings along to the gateway. These fields will not be stored by Capstone. Notes: Do not use custom fields to store sensitive data. Some information may be escaped and may not be usable in custom fields.
gatewayResponse	object	false	none	Gateway-specific information. Details will vary by gateway. Do NOT code to any information included in this object
gatewayName	string	false	none	The name of the gateway
refNumber	string	false	none	The gateway's reference number
id	string	false	none	Capstone Payment ID
kountResponse	object	false	none	Fraud data and rules
status	string	false	none	Will be one of three possible statuses: 'success', 'review', 'decline.' See our Fraud tutorial for more information
rules	string	false	none	Kount-specific information, including rules triggered. See our Fraud tutorial for more information
merchantId	string	false	none	The merchant ID through which the transaction was processed
token	object	false	none	The card token used to process the transaction
firstSix	string	false	none	The first six digits of the card number
lastFour	string	false	none	The last four digits of the card number
token	string	false	none	The TokenEx card token
transactionDate	string	false	none	The transaction date and time
transactionStatus	string	false	none	The transaction status
transactionType	string	false	none	The transaction type
userName	string	false	none	The username of the account through which the subscription was created
dateCreated	string	false	none	The date and time the subscription was created
dateLastModified	string	false	none	The date and time the subscription was last modified
dateLastRun	string	false	none	The date and time a payment in this subscription was last run
dateNextRun	string	false	none	The date a payment in this subscription is next scheduled to run

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Update Subscription

Code samples

curl -X PUT https://api.capstonesandbox.com/subscription/v3/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "payment": {
    "isAuthOnly": true,
    "data": {
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "createdAtDate": "2005-03-01",
        "email": "jdoe@yourwebsite.com",
        "orderDate": "2021-08-26",
        "phone": "1555555555",
        "billToAddressOne": "2147 West Silverlake Drive",
        "billToAddressTwo": "Apt 42",
        "billToCity": "Scranton",
        "billToState": "PA",
        "billToPostal": "18503",
        "billToCountry": "US",
        "billToPhone": "1555555555",
        "shipToAddressOne": "1725 Slough Avenue",
        "shipToAddressTwo": "Suite 200",
        "shipToCity": "Scranton",
        "shipToState": "PA",
        "shipToPostal": "18505",
        "shipToCountry": "US",
        "shipToPhone": "1555555555"
      },
      "cart": {
        "items": [
          {
            "item": "913261",
            "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
            "quantity": 8,
            "price": 16.49,
            "type": "sale"
          }
        ]
      },
      "lodging": {
        "advanceDeposit": true,
        "checkInDate": "2018-12-31",
        "checkOutDate": "2019-01-05",
        "noShow": false,
        "roomNumber": 14,
        "roomRate": 143.99
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": ""
    },
    "processingOptions": {
      "checkFraud": false,
      "merchantId": "100039",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0,
    "balance": 95,
    "duration": 5,
    "dateInitialBillingEnd": "2021-06-01",
    "initialBillingAmount": "8.99"
  }
}'

PUT /subscription/v3/{id}

Updates an existing payment subscription. Card token, currency, amount, and customer reference cannot be updated. If you need to change any of these values, delete the existing subscription and create a new one. The only user with rights to edit the subscription is the original creator.

Note: This service is in beta. Contact integration support if you would like to use this feature.

Body parameter

{
  "payment": {
    "isAuthOnly": true,
    "data": {
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "createdAtDate": "2005-03-01",
        "email": "jdoe@yourwebsite.com",
        "orderDate": "2021-08-26",
        "phone": "1555555555",
        "billToAddressOne": "2147 West Silverlake Drive",
        "billToAddressTwo": "Apt 42",
        "billToCity": "Scranton",
        "billToState": "PA",
        "billToPostal": "18503",
        "billToCountry": "US",
        "billToPhone": "1555555555",
        "shipToAddressOne": "1725 Slough Avenue",
        "shipToAddressTwo": "Suite 200",
        "shipToCity": "Scranton",
        "shipToState": "PA",
        "shipToPostal": "18505",
        "shipToCountry": "US",
        "shipToPhone": "1555555555"
      },
      "cart": {
        "items": [
          {
            "item": "913261",
            "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
            "quantity": 8,
            "price": 16.49,
            "type": "sale"
          }
        ]
      },
      "lodging": {
        "advanceDeposit": true,
        "checkInDate": "2018-12-31",
        "checkOutDate": "2019-01-05",
        "noShow": false,
        "roomNumber": 14,
        "roomRate": 143.99
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": ""
    },
    "processingOptions": {
      "checkFraud": false,
      "merchantId": "100039",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0,
    "balance": 95,
    "duration": 5,
    "dateInitialBillingEnd": "2021-06-01",
    "initialBillingAmount": "8.99"
  }
}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The subscription ID
payment	body	object	false	Payment information for future payments
isAuthOnly	body	boolean	false	true: sets all future transactions to authorize only. false: sets all future transactions to authorize and capture Note: Auth only transactions run on a schedule must be captured in your own code base. Default: The value set when the subscription was created
data	body	object	false	Transaction data
customer	body	object	false	Customer information to be used in checking fraud or sent to the processing gateway, when applicable
firstName	body	string	false	The customer's first name, as it appears on the credit card
lastName	body	string	false	The customer's last name, as it appears on the credit card
invoice	body	invoice	false	The invoice number
orderNumber	body	orderNumber	false	The order number
birthDate	body	birthDate	false	The customer's date of birth. Use any of the following formats for the date: Four-digit month, 2-digit month and day, separated with hyphens: YYYY-MM-DD. For example, 2001-08-26 ISO-8601 date expressed in UTC. For example, 2001-08-26T13:35:00Z UNIX date (as an integer representing seconds). For example, 998854500
createdAtDate	body	string	false	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
email	body	string	false	The customer's email address
orderDate	body	orderDate	false	The date of the customer's order. Use any of the following formats for the date: Four-digit month, 2-digit month and day, separated with hyphens: YYYY-MM-DD. For example, 2021-08-26 ISO-8601 date expressed in UTC. For example, 2021-08-26T13:35:18Z UNIX date (as an integer representing seconds). For example, 1630006518 Note: This is NOT a quick way to schedule a transaction. Specifying a date in the future does not cause the order to be run automatically at the indicated date or time.
phone	body	string	false	The customer's phone number
billToAddressOne	body	string	false	The street address on file with the credit card provider
billToAddressTwo	body	billToAddressTwo	false	Additional street address information, if required
billToCity	body	string	false	The city on file with the credit card provider
billToState	body	billToState	false	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
billToPostal	body	string	false	The postal code on file with the credit card provider
billToCountry	body	billToCountry	false	The two-character (Alpha-2) ISO country code
billToPhone	body	billToPhone	false	The billing phone number
shipToAddressOne	body	shipToAddressOne	false	The shipping address, if different from the billing address
shipToAddressTwo	body	shipToAddressTwo	false	Additional shipping address information, if required
shipToCity	body	shipToCity	false	The shipping city
shipToState	body	shipToState	false	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
shipToPostal	body	shipToPostal	false	The shipping postal code
shipToCountry	body	shipToCountry	false	The two-character (Alpha-2) ISO country code
shipToPhone	body	shipToPhone	false	The shipping phone number
cart	body	cart	false	Items purchased in the transaction
items	body	[item]	false	Details about items in the shopping cart
item	body	itemItem	false	Item number or code
description	body	descriptionItem	false	A description of the item
quantity	body	quantity	false	The quantity sold
price	body	price	false	The price per item
type	body	transactionType	false	The transaction type
lodging	body	lodging	false	Lodging data (related to hotels, motels, inns, etc.)
advanceDeposit	body	boolean	false	Set to true if the customer paid a deposit in advance of their reservation
checkInDate	body	string	false	The customer's check in date in standard ISO date format
checkOutDate	body	string	false	The customer's check out date in standard ISO date format
noShow	body	boolean	false	Set to true if the customer failed to show up to their reservation
roomNumber	body	number	false	The customer's room number
roomRate	body	number	false	The room's rate, per day
customFields	body	customFields	false	Custom fields that can be used to pass additional strings along to the gateway. These fields will not be stored by Capstone. Notes: Do not use custom fields to store sensitive data. Some information may be escaped and may not be usable in custom fields.
exampleKey	body	string	false	You may use any key as a custom field. Values must be strings.
description	body	string	false	A description of the transaction
descriptor	body	descriptor	false	Include this parameter to dynamically change the descriptor on the customer's statement. If this parameter is not included, the default descriptor (as set up on the merchant account that is originating the transactions) will be used. When applicable, this information will be passed along to gateway. Contact integration support if you have any questions about this parameter
processingOptions	body	object	false	Processing Options
checkFraud	body	checkFraud	false	Set to false to opt out of sending a request to Kount. Note: During testing you may trigger specific Kount responses by including any of the values shown here
merchantId	body	merchantId	false	The merchant ID (MID)
paymentOptionTag	body	paymentOptionTag	false	A custom value used to route transactions to a specific gateway or merchant account. Contact integration support to designate a paymentOptionTag for a given merchant account.
shouldUseFingerprint	body	shouldUseFingerprint	false	This parameter applies when a device fingerprint was created while saving a card token. The card's stored fingerprint will be used by default, but you may choose not to use it by setting this parameter to false. Note: To change your merchant's default setting, contact integration support
verboseResponse	body	verboseResponse	false	Set to true to include additional information in the response
webhookUrl	body	webhookUrl	false	The URL to which Capstone will send the results of the transaction. (If not provided you will need to use the results of the HTTP request, either from the browser or your server)
webhookFailUrl	body	webhookFailUrl	false	The URL to which Capstone will send the results of a failed transaction
schedule	body	scheduleRequest	false	The schedule for recurring transactions
interval	body	interval	false	The schedule's time period. Possible values: day, week, month, year
intervalCount	body	intervalCount	false	The number of intervals that will pass between transactions. See the subscription schedule examples table for examples of how the interval and interval count create the subscription schedule.
balance	body	integer	false	The total amount to be charged over the course of the pay plan
duration	body	integer	false	The duration of the pay plan. This is the number of transactions that will run before the pay plan terminates. If amount is not provided the duration will also be used to calculate the amount to be charged during each transaction
dateInitialBillingEnd	body	dateInitialBillingEnd(date)	false	The date at which the initial billing period will end. Transactions prior to this date will be run for the initial billing amount. Transactions after this date will be run for the subscription amount
initialBillingAmount	body	initialBillingAmount	false	The transaction amount during the initial billing period.

Example responses

200 Response

{
  "customerRef": "RP006",
  "active": true,
  "accountId": "27592004",
  "id": "e80d63dd-a77b-407a-9124-42acf00740dd",
  "payment": {
    "isAuthOnly": true,
    "data": {
      "amount": 29.99,
      "cart": {
        "items": [
          {
            "item": "913261",
            "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
            "quantity": 8,
            "price": 16.49,
            "type": "sale"
          }
        ]
      },
      "currency": "USD",
      "customer": {
        "customerRef": "RP006",
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "createdAtDate": "2005-03-01",
        "email": "jdoe@yourwebsite.com",
        "phone": "1555555555",
        "billToAddressOne": "2147 West Silverlake Drive",
        "billToAddressTwo": "Apt 42",
        "billToCity": "Scranton",
        "billToState": "PA",
        "billToPostal": "18503",
        "billToCountry": "US",
        "billToPhone": "1555555555",
        "orderDate": "2021-08-26",
        "shipToAddressOne": "1725 Slough Avenue",
        "shipToAddressTwo": "Suite 200",
        "shipToCity": "Scranton",
        "shipToState": "PA",
        "shipToPostal": "18505",
        "shipToCountry": "US",
        "shipToPhone": "1555555555"
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": "",
      "lodging": {
        "advanceDeposit": true,
        "checkInDate": "2018-12-31",
        "checkOutDate": "2019-01-05",
        "noShow": false,
        "roomNumber": 14,
        "roomRate": 143.99
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313"
    },
    "processingOptions": {
      "checkFraud": false,
      "merchantId": "100039",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0,
    "balance": 0,
    "initialBalance": 50,
    "duration": 5,
    "dateInitialBillingEnd": "2021-06-01",
    "initialBillingAmount": "8.99"
  },
  "userName": "jdoe@yourwebsite.com",
  "dateCreated": "2020-04-28T19:19:33.183Z",
  "dateLastModified": "2020-04-28T19:19:33.185Z",
  "dateLastRun": "2020-04-28T18:50:04.866Z",
  "dateNextRun": "2020-07-28"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Get Subscription

Code samples

curl -X GET https://api.capstonesandbox.com/subscription/v3/{id} \
  -H 'Accept: application/json'

GET /subscription/v3/{id}

Returns the payment information and schedule for an existing subscription.

Note: This service is in beta. Contact integration support if you would like to use this feature.

Parameters

Name	In	Type	Required	Description
id	path	string	true	The subscription ID

Example responses

200 Response

{
  "customerRef": "RP006",
  "active": true,
  "accountId": "27592004",
  "id": "e80d63dd-a77b-407a-9124-42acf00740dd",
  "payment": {
    "isAuthOnly": true,
    "data": {
      "amount": 29.99,
      "cart": {
        "items": [
          {
            "item": "913261",
            "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
            "quantity": 8,
            "price": 16.49,
            "type": "sale"
          }
        ]
      },
      "currency": "USD",
      "customer": {
        "customerRef": "RP006",
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "createdAtDate": "2005-03-01",
        "email": "jdoe@yourwebsite.com",
        "phone": "1555555555",
        "billToAddressOne": "2147 West Silverlake Drive",
        "billToAddressTwo": "Apt 42",
        "billToCity": "Scranton",
        "billToState": "PA",
        "billToPostal": "18503",
        "billToCountry": "US",
        "billToPhone": "1555555555",
        "orderDate": "2021-08-26",
        "shipToAddressOne": "1725 Slough Avenue",
        "shipToAddressTwo": "Suite 200",
        "shipToCity": "Scranton",
        "shipToState": "PA",
        "shipToPostal": "18505",
        "shipToCountry": "US",
        "shipToPhone": "1555555555"
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": "",
      "lodging": {
        "advanceDeposit": true,
        "checkInDate": "2018-12-31",
        "checkOutDate": "2019-01-05",
        "noShow": false,
        "roomNumber": 14,
        "roomRate": 143.99
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313"
    },
    "processingOptions": {
      "checkFraud": false,
      "merchantId": "100039",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0,
    "balance": 0,
    "initialBalance": 50,
    "duration": 5,
    "dateInitialBillingEnd": "2021-06-01",
    "initialBillingAmount": "8.99"
  },
  "userName": "jdoe@yourwebsite.com",
  "dateCreated": "2020-04-28T19:19:33.183Z",
  "dateLastModified": "2020-04-28T19:19:33.185Z",
  "dateLastRun": "2020-04-28T18:50:04.866Z",
  "dateNextRun": "2020-07-28"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Delete Subscription

Code samples

curl -X DELETE https://api.capstonesandbox.com/subscription/v3/{id} \
  -H 'Accept: application/json'

DELETE /subscription/v3/{id}

Deletes an existing payment subscription.

Note: This service is in beta. Contact integration support if you would like to use this feature.

Parameters

Name	In	Type	Required	Description
id	path	string	true	The subscription ID

Example responses

200 Response

{
  "customerRef": "RP006",
  "active": true,
  "accountId": "27592004",
  "id": "e80d63dd-a77b-407a-9124-42acf00740dd",
  "payment": {
    "isAuthOnly": true,
    "data": {
      "amount": 29.99,
      "cart": {
        "items": [
          {
            "item": "913261",
            "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
            "quantity": 8,
            "price": 16.49,
            "type": "sale"
          }
        ]
      },
      "currency": "USD",
      "customer": {
        "customerRef": "RP006",
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "createdAtDate": "2005-03-01",
        "email": "jdoe@yourwebsite.com",
        "phone": "1555555555",
        "billToAddressOne": "2147 West Silverlake Drive",
        "billToAddressTwo": "Apt 42",
        "billToCity": "Scranton",
        "billToState": "PA",
        "billToPostal": "18503",
        "billToCountry": "US",
        "billToPhone": "1555555555",
        "orderDate": "2021-08-26",
        "shipToAddressOne": "1725 Slough Avenue",
        "shipToAddressTwo": "Suite 200",
        "shipToCity": "Scranton",
        "shipToState": "PA",
        "shipToPostal": "18505",
        "shipToCountry": "US",
        "shipToPhone": "1555555555"
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": "",
      "lodging": {
        "advanceDeposit": true,
        "checkInDate": "2018-12-31",
        "checkOutDate": "2019-01-05",
        "noShow": false,
        "roomNumber": 14,
        "roomRate": 143.99
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313"
    },
    "processingOptions": {
      "checkFraud": false,
      "merchantId": "100039",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0,
    "balance": 0,
    "initialBalance": 50,
    "duration": 5,
    "dateInitialBillingEnd": "2021-06-01",
    "initialBillingAmount": "8.99"
  },
  "userName": "jdoe@yourwebsite.com",
  "dateCreated": "2020-04-28T19:19:33.183Z",
  "dateLastModified": "2020-04-28T19:19:33.185Z",
  "dateLastRun": "2020-04-28T18:50:04.866Z",
  "dateNextRun": "2020-07-28"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Get Customer Subscriptions

Code samples

curl -X GET https://api.capstonesandbox.com/subscription/v3/customerRef/{customerRef} \
  -H 'Accept: application/json'

GET /subscription/v3/customerRef/{customerRef}

Returns a list of subscriptions for a given customer reference.

Parameters

Name	In	Type	Required	Description
customerRef	path	string	true	The customer reference

Example responses

200 Response

[
  {
    "customerRef": "RP006",
    "active": true,
    "accountId": "27592004",
    "id": "e80d63dd-a77b-407a-9124-42acf00740dd",
    "payment": {
      "isAuthOnly": true,
      "data": {
        "amount": 29.99,
        "cart": {
          "items": [
            {
              "item": "913261",
              "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
              "quantity": 8,
              "price": 16.49,
              "type": "sale"
            }
          ]
        },
        "currency": "USD",
        "customer": {
          "customerRef": "RP006",
          "firstName": "John",
          "lastName": "Doe",
          "invoice": "IN0001",
          "orderNumber": "210058A",
          "birthDate": "1990-12-05",
          "createdAtDate": "2005-03-01",
          "email": "jdoe@yourwebsite.com",
          "phone": "1555555555",
          "billToAddressOne": "2147 West Silverlake Drive",
          "billToAddressTwo": "Apt 42",
          "billToCity": "Scranton",
          "billToState": "PA",
          "billToPostal": "18503",
          "billToCountry": "US",
          "billToPhone": "1555555555",
          "orderDate": "2021-08-26",
          "shipToAddressOne": "1725 Slough Avenue",
          "shipToAddressTwo": "Suite 200",
          "shipToCity": "Scranton",
          "shipToState": "PA",
          "shipToPostal": "18505",
          "shipToCountry": "US",
          "shipToPhone": "1555555555"
        },
        "customFields": {
          "exampleKey": "Example string"
        },
        "description": "test purchase",
        "descriptor": "",
        "lodging": {
          "advanceDeposit": true,
          "checkInDate": "2018-12-31",
          "checkOutDate": "2019-01-05",
          "noShow": false,
          "roomNumber": 14,
          "roomRate": 143.99
        }
      },
      "tokenex": {
        "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
        "firstSix": "479300",
        "lastFour": "3313"
      },
      "processingOptions": {
        "checkFraud": false,
        "merchantId": "100039",
        "paymentOptionTag": "switch",
        "shouldUseFingerprint": true,
        "verboseResponse": true,
        "webhookUrl": "",
        "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
      }
    },
    "schedule": {
      "interval": "month",
      "intervalCount": 0,
      "balance": 0,
      "initialBalance": 50,
      "duration": 5,
      "dateInitialBillingEnd": "2021-06-01",
      "initialBillingAmount": "8.99"
    },
    "userName": "jdoe@yourwebsite.com",
    "dateCreated": "2020-04-28T19:19:33.183Z",
    "dateLastModified": "2020-04-28T19:19:33.185Z",
    "dateLastRun": "2020-04-28T18:50:04.866Z",
    "dateNextRun": "2020-07-28"
  }
]

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

An array of subscription objects

Name	Type	Required	Restrictions	Description
anonymous	array	false	none	An array of subscription objects
customerRef	string	false	none	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
active	boolean	false	none	Will be true if the subscription is currently active
accountId	string	false	none	Your Capstone account number
id	string	false	none	The subscription ID
payment	object	false	none	Payment information for future payments
isAuthOnly	boolean	false	none	Will be true if future transactions are set to only authorize. Will be false if future transactions are scheduled to authorize and capture
data	object	true	none	Transaction data
amount	number	false	none	The transaction amount
cart	object	false	none	Items purchased in the transaction
items	array	false	none	Details about items in the shopping cart
item	string	false	none	Item number or code
description	string	false	none	A description of the item
quantity	integer	false	none	The quantity sold
price	number	false	none	The price per item
type	string	false	none	The transaction type
currency	string	false	none	The three-character ISO currency code for the transaction.
customer	object	false	none	Customer information returned when checking fraud or from the processing gateway, when applicable.
customerRef	string	false	none	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
firstName	string	false	none	The customer's first name, as it appears on the credit card
lastName	string	false	none	The customer's last name, as it appears on the credit card
invoice	string	false	none	The invoice number
orderNumber	string	false	none	The order number
birthDate	string	false	none	The customer's date of birth. The format returned matches the format used in the request that created the subscription.
createdAtDate	string	false	none	The date the customer was created in your system. Standard ISO date format. Note: This information is only used to allow you to more fully customize your fraud rules. Capstone does not store this data
email	string	false	none	The customer's email address
phone	string	false	none	The customer's phone number
billToAddressOne	string	false	none	The street address on file with the credit card provider
billToAddressTwo	string	false	none	Additional street address information, if required
billToCity	string	false	none	The city on file with the credit card provider
billToState	string	false	none	The state or province on file with the credit card provider. (If in the US, this must be the two-character state abbreviation)
billToPostal	string	false	none	The postal code on file with the credit card provider
billToCountry	string	false	none	The two-character (Alpha-2) ISO country code
billToPhone	string	false	none	The billing phone number
orderDate	string	false	none	The date of the customer's order. The format returned matches the format used in the request.
shipToAddressOne	string	false	none	The shipping address, if different from the billing address
shipToAddressTwo	string	false	none	Additional shipping address information, if required
shipToCity	string	false	none	The shipping city
shipToState	string	false	none	The shipping state or province. (If in the US, this must be the two-character state abbreviation)
shipToPostal	string	false	none	The shipping postal code
shipToCountry	string	false	none	The two-character (Alpha-2) ISO country code
shipToPhone	string	false	none	The shipping phone number
customFields	object	false	none	Custom fields that can be used to pass additional strings along to the gateway. These fields will not be stored by Capstone. Notes: Do not use custom fields to store sensitive data. Some information may be escaped and may not be usable in custom fields.
exampleKey	string	false	none	You may use any key as a custom field. Values must be strings.
description	string	false	none	A description of the transaction
descriptor	string	false	none	Include this parameter to dynamically change the descriptor on the customer's statement. If this parameter is not included, the default descriptor (as set up on the merchant account that is originating the transactions) will be used. When applicable, this information will be passed along to gateway. Contact integration support if you have any questions about this parameter
lodging	object	false	none	Lodging data (related to hotels, motels, inns, etc.)
advanceDeposit	boolean	false	none	Set to true if the customer paid a deposit in advance of their reservation
checkInDate	string	false	none	The customer's check in date in standard ISO date format
checkOutDate	string	false	none	The customer's check out date in standard ISO date format
noShow	boolean	false	none	Set to true if the customer failed to show up to their reservation
roomNumber	number	false	none	The customer's room number
roomRate	number	false	none	The room's rate, per day
tokenex	object	true	none	Card token information
token	string	false	none	The card token that will be used to process future transactions
firstSix	string	false	none	The first six digits of the card number
lastFour	string	false	none	The last four digits of the card number
processingOptions	object	false	none	Processing Options
checkFraud	boolean	false	none	Set to false to opt out of sending a request to Kount. Note: During testing you may trigger specific Kount responses by including any of the values shown here
merchantId	string	false	none	The merchant ID (MID)
paymentOptionTag	string	false	none	A custom value used to route transactions to a specific gateway or merchant account. Contact integration support to designate a paymentOptionTag for a given merchant account.
shouldUseFingerprint	boolean	false	none	This parameter applies when a device fingerprint was created while saving a card token. The card's stored fingerprint will be used by default, but you may choose not to use it by setting this parameter to false. Note: To change your merchant's default setting, contact integration support
verboseResponse	boolean	false	none	Set to true to include additional information in the response
webhookUrl	string	false	none	The URL to which Capstone will send the results of the transaction. (If not provided you will need to use the results of the HTTP request, either from the browser or your server)
webhookFailUrl	string	false	none	The URL to which Capstone will send the results of a failed transaction
schedule	object	false	none	The schedule for recurring transactions
interval	string	false	none	The schedule's time period. Possible values: day, week, month, year
intervalCount	integer	false	none	The number of intervals that will pass between transactions. See the subscription schedule examples table for examples of how the interval and interval count create the subscription schedule.
balance	integer	false	none	The current balance of the pay plan
initialBalance	integer	false	none	The starting balance of the pay plan
duration	integer	false	none	The duration of the pay plan as defined when the pay plan was created
dateInitialBillingEnd	string	false	none	The date at which the initial billing period will end. Transactions prior to this date will be run for the initial billing amount. Transactions after this date will be run for the subscription amount
initialBillingAmount	string	false	none	The transaction amount during the initial billing period.
userName	string	false	none	The username of the account through which the subscription was created
dateCreated	string	false	none	The date and time the subscription was created
dateLastModified	string	false	none	The date and time the subscription was last modified
dateLastRun	string	false	none	The date and time a payment in this subscription was last run
dateNextRun	string	false	none	The date a payment in this subscription is next scheduled to run

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Reporting API Reference

Deposits

Deposit Summary

Code samples

curl -X GET https://api.capstonesandbox.com/ach/v3 \
  -H 'Accept: application/json'

GET /ach/v3

Returns a summary of all deposits with the given range.

Parameters

Name	In	Type	Required	Description
limit	query	integer	false	The number of deposit summaries to return
offset	query	integer	false	The offset. Used to view deposit summaries further along the list
startDate	query	string	false	The start date. Format: YYYY-MM-DD
endDate	query	string	false	The end date. Format: YYYY-MM-DD
merchantIds	query	string	false	A list of merchant IDs

Example responses

200 Response

{
  "offset": 10,
  "limit": 1,
  "rows": [
    {
      "id": 3742052,
      "merchantId": "100039",
      "date": "2019-02-05",
      "dda": "*****5132",
      "amount": 4.92,
      "currencyId": "840",
      "createdAt": "2019-02-07T14:04:03.000Z",
      "updatedAt": "2019-02-07T14:04:03.000Z",
      "processor": {
        "id": 0,
        "originalId": 0,
        "processorType": 0
      },
      "details": [
        {
          "achDetailId": "MTAtNDE0MTQ0MS0xOTAyMTAtNTEzNDg1MDAwMzQ3MDEz",
          "type": 0,
          "thirdPartyFundedAmount": 0,
          "amount": 40.99,
          "currencyId": "840",
          "achSummaryId": 0,
          "processor": {
            "id": 1120391,
            "originalId": 8010050,
            "processorType": 0,
            "batchRef": "10000002711",
            "achDetailId": "MTAtNDE0MTQ0MS0xOTAyMTAtNTEzNDg1MDAwMzQ3MDEz"
          }
        }
      ]
    }
  ],
  "hasMore": true
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
offset	integer	false	none	The number of rows by which the data is offset
limit	integer	false	none	The limit on the number of rows
rows	array	false	none	An array of deposit summary objects
id	integer	false	none	A deposit summary ID
merchantId	string	true	none	The merchant ID
date	string	true	none	none
dda	string	false	none	The last four digits of the account number to which the ACH was deposited
amount	number	true	none	none
currencyId	string	true	none	none
createdAt	string	true	none	The date and time at which the deposit summary was created
updatedAt	string	true	none	The date and time at which the deposit summary was last updated
processor	object	false	none	Processor-specific information
id	integer	true	none	none
originalId	integer	true	none	none
processorType	integer	true	none	none
details	array	false	none	The details corresponding to this deposit
achDetailId	string	false	none	The deposit detail ID
type	integer	true	none	none
thirdPartyFundedAmount	number	false	none	none
amount	number	true	none	The deposit detail amount
currencyId	string	true	none	none
achSummaryId	integer	false	none	none
processor	object	false	none	Processor-specific information. Details will vary by processor. Do NOT code to any information included in this object
id	integer	true	none	none
originalId	integer	true	none	The original ID from the process
processorType	integer	true	none	The Capstone-assigned processor type
batchRef	string	false	none	The processor's batch reference number
achDetailId	string	false	none	The deposit detail ID
hasMore	boolean	false	none	Will be true if there are more records not included in the current response

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Dev Tools API Reference

Webhook Service

Merchant Configuration

Code samples

curl -X GET https://api.capstonesandbox.com/webhook/v3/config/{id} \
  -H 'Accept: application/json'

GET /webhook/v3/config/{id}

Returns a merchant's webhook configuration.

Parameters

Name	In	Type	Required	Description
id	path	string	true	The merchant ID

Example responses

200 Response

{
  "dateCreated": "2019-03-22T16:58:51.957Z",
  "webhooks": {
    "TRANSACTION_AUTHORIZED": {
      "url": "https://your-company-webhook-url-here.com"
    },
    "TRANSACTION_CAPTURED": {
      "url": "https://your-company-webhook-url-here.com"
    }
  },
  "merchantName": "My Company",
  "dateLastModified": "2019-04-04T18:54:58.011Z",
  "merchantId": "100039"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Configure Merchant

Code samples

curl -X POST https://api.capstonesandbox.com/webhook/v3/config \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "merchantId": "100039",
  "webhooks": {
    "TRANSACTION_AUTHORIZED": {
      "url": "https://your-company-webhook-url-here.com"
    }
  }
}'

POST /webhook/v3/config

Configures URLs for a merchant's webhooks to be sent.

Body parameter

{
  "merchantId": "100039",
  "webhooks": {
    "TRANSACTION_AUTHORIZED": {
      "url": "https://your-company-webhook-url-here.com"
    }
  }
}

Parameters

Name	In	Type	Required	Description
merchantId	body	string	true	The merchant ID to configure the webhook service
webhooks	body	object	true	none
TRANSACTION_AUTHORIZED	body	object	false	An object containing the webhook URL. Click here to see a possible list of keys.
url	body	string	false	The URL to which the webhook will be sent

Example responses

200 Response

{
  "merchantId": "100039",
  "webhooks": {
    "TRANSACTION_AUTHORIZED": {
      "url": "https://your-company-webhook-url-here.com"
    },
    "TRANSACTION_CAPTURED": {
      "url": "https://your-company-webhook-url-here.com"
    }
  },
  "dateLastModified": "2019-04-04T18:54:58.011Z",
  "dateCreated": "2019-03-22T16:58:51.957Z"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
merchantId	string	false	none	The merchant ID
webhooks	object	false	none	A list of all the webhooks currently configured. Keys are the webhook event types
TRANSACTION_AUTHORIZED	object	false	none	Webhook will be sent when a transaction is authorized
url	string	false	none	The URL to which the webhook will be sent when a transaction has been authorized
TRANSACTION_CAPTURED	object	false	none	Webhook will be sent when a transaction is captured
url	string	false	none	The URL to which the webhook will be sent when a transaction has been captured
dateLastModified	string	false	none	The date and time the configuration was last modified
dateCreated	string	false	none	The date and time the configuration was created

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Merchant Secret

Code samples

curl -X GET https://api.capstonesandbox.com/webhook/v3/secret/{id} \
  -H 'Accept: application/json'

GET /webhook/v3/secret/{id}

Returns the merchant secret to be used in webhooks.

Parameters

Name	In	Type	Required	Description
id	path	string	true	The merchant ID

Example responses

200 Response

{
  "secret": "446946d5-bdd9-48c7-9504-0459d19c08e5"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
secret	string	false	none	The merchant secret to be used in verifying the webhook's signature

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request

Create Merchant Secret

Code samples

curl -X POST https://api.capstonesandbox.com/webhook/v3/secret \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
  "merchantId": "100039"
}'

POST /webhook/v3/secret

Creates a merchant secret to be used in webhooks.

Body parameter

{
  "merchantId": "100039"
}

Parameters

Name	In	Type	Required	Description
merchantId	body	string	true	The merchant ID to configure the webhook service

Example responses

200 Response

{
  "secret": "446946d5-bdd9-48c7-9504-0459d19c08e5"
}

Responses

Status	Meaning	Description
200	OK	Success
401	Unauthorized	Unauthorized

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
secret	string	false	none	The merchant secret to be used in verifying the webhook's signature

Status Code 401

Name	Type	Required	Restrictions	Description
message	string	false	none	A message from Capstone about the state of the request