Nelnet Payment Services
PaymentSpring has changed to Nelnet Payment Services.
Our company name changed from PaymentSpring to Nelnet Payment Services effective August 10, 2022.
This name change is an alignment with our overall Nelnet business.
Introduction
This document is the reference for the Nelnet Payment Services API. From it, you can build your integration or just get a better sense for how our system works and what it offers.
For a quick overview of our API and how to use it, consider our Getting Started.
Questions? Get in touch with us. We're happy to help.
Our Promise
Our API is our contract, and we will not remove fields, actions or change functionality to a versioned API. We test every update and change against our official library and rest documentation and tests to ensure consistency and reliability.
Authentication
You'll use your public and private Nelnet Payment Services Gateway API keys to authenticate with our API.
$ curl -u private-api-key: https://api.paymentspring.com/api/v1/customers
The public key can (and will likely) be exposed in client-side javascript as part of your tokenizer. This key is only used to create payment tokens (which in turn are used to either run one-time charges or to add payment methods to persisted customer records). There is no way to fetch sensitive data with your public key, so it can be safely exposed.
The private key must not be exposed publicly, as it is used for all other API interactions, including but not limited to issuing charges and refunds. This key should only ever exist on your server, and should never be exposed to client-side users.
All merchants have test API keys; these allow you to run test transactions while you build out your API integration (or simply explore our product).
Activated merchants will also have live API keys, which are used to run real transactions.
Records and activity from your test account will not carry over to your live account, and vice-versa; the two environments are completely separate.
When using the REST API, the API key is accepted through the username in the HTTP basic auth credentials system; you will not provide a password.
Where can I get my API keys?
API keys can be found in the Merchant Dashboard.
- Log in to https://dashboard.paymentspring.com.
- Click Account in the navigation menu on the left.
- You’ll see your current API keys at the bottom of the page. We only allow these keys to show once for security reasons.
- Click Generate New Keys. You can choose to expire the current keys now or in 1 hour.
- You will see the new set of keys. Save them now, for they will be redacted the next time you visit this page. You can always generate news keys.
Test Card Numbers
When in test mode, you can use the following sample credit cards. They will function just like real credit cards, but all payments will be simulated. Do not use real credit cards in test mode, and make sure you don’t use these sample credit cards in live mode.
CARD | TYPE NUMBER | CSC | EXPIRATION |
---|---|---|---|
Visa | 4111111111111111 | 999 | 08/2022 |
Amex | 345829002709133 | 9997 | 08/2022 |
Discover | 6011010948700474 | 999 | 08/2022 |
Mastercard | 5499740000000057 | 999 | 08/2022 |
When in test mode, you can use the following sample bank accounts. They will function just like real bank accounts, but all payments will be simulated. Do not use real bank account numbers in test mode, and make sure you don’t use these sample bank accounts in live mode.
ACCOUNT NUMBER | ROUTING NUMBER | ACCOUNT HOLDER NAME | ACCOUNT TYPE |
---|---|---|---|
123456789 | 021000021 | Any Value | Checking or Savings |
In test mode, submit a charge using one of these amounts and you’ll receive a predictable error. Use this to make sure you are handling processor errors properly for things like invalid cards, expired cards, and possible fraud scenarios.
Bank Account
AMOUNT (IN CENTS) | ERROR MESSAGE |
---|---|
12 | Return (R01) - Insufficent Funds (will update at 2a CT) |
Credit Cards
In test mode, you can submit a charge using one of these amounts to simulate the type of response you will receive in the case of a card decline error. In all cases the error code will be the same but the messaging may vary. Error code messages are not guaranteed and therefor should not be used for error type validation.
AMOUNT (IN CENTS) | ERROR CODE | ERROR MESSAGE |
---|---|---|
73-100 | 99820 | <Processor Specific Error Message> |
Nelnet Payment Services Tokenizer Script
In order to use the tokenizer, you’ll need to include it in your HTML.
<script type="text/javascript"
src="https://checkout.paymentspring.com/js/paymentspring-tokenizer.js">
</script>
From there, you can invoke the script like so:
// You'll find this API key in your account settings.
var publicKey = "your-public-api-key"
// We'll need to build this from our form -- in this case,
// we've hard-coded with test account information. You'll
// usually scrape this information from a form using
// Javascript and will then, instead of the normal form
// submission, you'll create the token and if it's
// successful you'll submit the charge or create/edit the
// customer.
//
// Per above, the keys here should be the same as the params
// in the token-creation endpoint. The values will the the
// actual data.
var paymentData = {
// This is from our test card numbers
"card_owner_name": "Grace Hopper",
"card_number": "4111111111111111",
"card_exp_month": "12",
"card_exp_year": "2029"
}
// If we wanted to submit ACH information instead, we can
// do so like this instead:
// var paymentData = {
// "token_type": "bank_account",
// "bank_account_number": "1234567890",
// "bank_routing_number": "100004058",
// "bank_account_holder_first_name": "Grace",
// "bank_account_holder_last_name": "Hopper",
// "bank_account_type": "checking"
// }
//
// We can also pass in Address information. See the token creation
// documentation (link above) for guidance on how to do that.
// We need to register a callback to use the tokenizer;
// this is a function that gets called once the tokenizer
// is done fetching the token. Typically, it'll do things
// like submit the form (as well as wipe relevant PAN data).
//
// This callback function is illustrative only; it simply
// writes to the console log.
//
// You will need to create your own.
function callbackFunction(response) {
console.log("In the callback");
console.log(response);
return response;
}
// Finally, we get our response.
var token =
paymentspring.generateToken(publicKey, paymentData, callbackFunction);
console.log(token);
If token creation is unsuccessful (an invalid card number, for example), you’ll get back an error response like so:
callbackFunction({
"errors": [
{
"code": "11112",
"message": "Invalid card number or improper format."
}
]
});
Your response from this call should look like this, assuming successful token creation:
callbackFunction({
"id": "24daa814b0",
"class": "token",
"card_type": "visa",
"card_owner_name": "Grace Hopper",
"last_4": "1111",
"card_exp_month": 12,
"card_exp_year": 2029
});
Nelnet Payment Services makes use of tokens (usually by way of our JSONP endpoint) to securely submit customer payment information.
From a practical standpoint, what this means is that:
- You submit the payment information to our API through our tokenizer script.
- Gateway accepts that payment information, encrypts it, and assigns it a token
ID. The token is just a string, like
8ab6f4da7
, corresponding to some encrypted payment data. We keep the payment data encrypted securely, and you store the token on your server if you so desire. - You create a new transaction, or create or update a customer record, and send along that token to the appropriate API endpoint.
- The end result is much higher security for you and your customers. And since there is no way to turn that token string back into payment information (for example, a credit card number, you can safely store and transmit tokens.
For more about tokens, check out this video about our tokenization process.
Tokens expire either when used (to run a transaction or to add a payment method to a customer) or after 15 minutes.
How to use the Tokenizer Script
This guide assumes that you are already comfortable authenticating on our API with public and private keys, and that you have signed up for an account.
You should serve this file from our CDN on each page load instead of bundling it into your assets for the most secure interaction. This guarantees that you're using the latest and most secure version, and that you remain PCI-compliant.
The tokenizer takes three arguments:
- Your public API key
- An object-literal with payment data. The keys for this object should be the parameter names (as specified in the token endpoint). The values, of course, will be the actual data. See the code sample for an example.
- Your callback function. This function will be called upon response from the server.
You can create both credit-card tokens and bank-account tokens. See the Token Creation documentation for more information.
The token_id
is the only part that you definitely will need, though you may
store the other parts of the token response if you want to.
You’ll need to make sure you can correctly handle that error response. We perform nominal validation of payment data (for example, ensuring that credit card numbers are present and pass the Luhn check) on token creation, but only so far as to ensure that the required values are present and well-formed.
We can feel comfortable exposing our public API key in our javascript (client-side actions, really) because someone who has it can only create tokens; they cannot do anything else. Our private API keys should never be exposed to the end user, as someone with a private API key can do anything they want with an account.
When do I tokenize?
Any time you’re transmitting customer payment data (card numbers, bank account numbers, and so on), you should use tokens.
More generally, any time you’re creating a customer, editing a customer’s payment methods, or charging a card, you should be using the tokens.
Doing so will keep you from having to transmit sensitive customer information through your server, which in turn will help protect you and your customers from fraud and malicious activity.
Tokens
Create a Token With JSONP
CREATE A TOKEN WITH JSONP
Sample Request:
# Tokenization should take place on the client side. Please see JavaScript tab for a code example for this endpoint.
// Tokenization should take place on the client side. Please see JavaScript tab for a code example for this endpoint.
# Tokenization should take place on the client side. Please see JavaScript tab for a code example for this endpoint.
// Build the prototype
window.paymentspring = (function () {
function PaymentSpring() {
this.script = null;
this.callback = null;
this.key = null;
}
// Generate the token:
//
// Params:
// + public_key: your Nelnet Payment Services public API key (can be sandbox or live)
// + paymentInfo: JSON object literal with params matching the documentation
// https://paymentspring.com/developers/#create-a-token-with-jsonp
// + callback: this function will be called upon completion of the
// tokenization process
//
// Returns:
// JSON object literal formatted like so:
// {
// "id": "24daa814b0",
// "class": "token",
// "card_type": "visa",
// "card_owner_name": "John Doe",
// "last_4": "1111",
// "card_exp_month": 1,
// "card_exp_year": 2020
// }
PaymentSpring.prototype.generateToken = function (public_key, paymentInfo, callback) {
if (this.script) return;
if(public_key.length != 63) {
alert("This is not a public key!");
} else {
this.key = public_key;
}
this.callback = callback;
this.script = document.createElement("script");
this.script.type = "text/javascript";
this.script.id = "tempscript";
this.script.src = "https://api.paymentspring.com/api/v1/tokens/jsonp?"
+ this.buildQueryString(paymentInfo)
+ "&public_api_key=" + this.key
+ "&callback=paymentspring.onComplete";
document.body.appendChild(this.script);
};
// Turn our incoming JSON params into a URI encoded query string
//
// We naively iterate over key/value pairs here, and do not do any validation
// at this level.
//
// Params:
// + cardInfo: Object literal, corresponding to JSONP token creation params
// https://paymentspring.com/developers/#create-a-token-with-jsonp
//
// Returns:
// Formatted query string
PaymentSpring.prototype.buildQueryString = function(cardInfo) {
var str = [];
// At the end of this step, we'll have something like this:
// [ 'foo=bar', 'bar=hello%20friend' ]
for(var key in cardInfo) {
// We only want info from the actual submitted card info, instead of any
// prototype it might belong to.
if (cardInfo.hasOwnProperty(key)) {
str.push(encodeURIComponent(key) + "=" + encodeURIComponent(cardInfo[key]));
}
}
output = str.join("&");
return output;
};
// On completion, run this function and call the callback
PaymentSpring.prototype.onComplete = function(data) {
document.body.removeChild(this.script);
this.script = null;
this.callback(data);
};
return new PaymentSpring();
}());
# Tokenization should take place on the client side. Please see JavaScript tab for a code example for this endpoint.
Expected Response Data (from .generateToken in the example above):
{
"card_type": "visa",
"card_owner_name": "John Doe",
"last_4": "1111",
"card_exp_month": 1,
"card_exp_year": 2020,
"bin_brand": "VISA",
"bin_type": "CREDIT",
"bin_level": "BUSINESS",
"class": "token",
"token_type": "credit_card",
"id": "24daa814b0",
}
GET /tokens/jsonp
Creates a token using JSONP and a merchant’s public API key. This endpoint must be used if a token is being created via JavaScript. Be sure to use the “jsonp” format for your request. This token can then be used to create a customer or to make a one-time charge. If the token is used for a one-time charge, it is then disabled so it can not be used again.
Parameters
Parameter | Details |
---|---|
token_type | Determines if this token contains credit card information, or bank account information. It can be set to credit_card or bank_account. If omitted, the token is treated as if it contains credit card information. |
card_owner_name | Card owner name as it appears on card. This field is required if token_type is omitted or equals credit_card. |
card_number | Full credit card number of a valid card. This field is required if token_type is omitted or equals credit_card. |
card_exp_month | Expiration month of card as a number. January = 1, February = 2, etc. This field is required if token_type is omitted or equals credit_card. |
card_exp_year | Expiration year of card (example: 2018). This field is required if token_type is omitted or equals credit_card. |
bank_account_number | Bank account number. This field is required if token_type equals bank_account. |
bank_routing_number | Bank routing number. This field must be 9 digits. This field is required if token_type equals bank_account. |
bank_account_holder_first_name | First name of the bank account holder. This field is required if token_type equals bank_account. |
bank_account_holder_last_name | Last name of the bank account holder. This field is required if token_type equals bank_account. |
bank_account_type | Bank account type. This value must either be checking or savings. This field is required if token_type equals bank_account. |
bin_brand | Bank Identification Number brand (example: VISA, AMEX, Mastercard, etc.). Is a sequence of numbers in the card_number that determines the account brand. |
bin_type | The type of account information provided in a token (example: credit_card or bank_account, etc.). Value is dependent on the value of token_type. |
bin_level | The account purpose type (example: "BUSINESS"). |
address_1 | Address 1 to be saved on the record. |
address_2 | Address 2 to be saved on the record. |
city | City to be saved on the record. |
state | State, province, or region. |
zip | Zip or postal code to be saved on the record. |
country | 3-character country code, per ISO 3166, for the payer's country. Assumed to be "USA" by default, and required for any transactions outside the US. |
Error Codes
Error Code | Message |
---|---|
11112 | Invalid card number or improper format. |
11301 | Invalid Visa number. |
11303 | Invalid American Express number. |
11306 | Invalid Discover number. |
11305 | Invalid Diners Club number. |
11302 | Invalid Mastercard number. |
38501 | Amount must be sent as a number of cents greater than zero. |
234722 | Card security code (also called CVV on some cards) is either missing or invalid. |
TKN01 | Error processing your request (CODE: TKN01). Please retry. |
Retrieve a Token
Retrieve a Token
Sample Request:
import requests
url = "http://api.paymentspring.com/api/v1/tokens/0ad7b82870"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
response = requests.request("GET", url, headers=headers)
print(response.text)
var client = new RestClient("http://api.paymentspring.com/api/v1/tokens/0ad7b82870");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("http://api.paymentspring.com/api/v1/tokens/0ad7b82870")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.setRequestHeader("Authorization", "Basic " + btoa("your-private-api-key:"));
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("GET", "http://api.paymentspring.com/api/v1/tokens/0ad7b82870");
xhr.send(data);
curl -u private-api-key:
https://api.paymentspring.com/api/v1/tokens/62a987ed39
Expected Response Data:
{
"class": "token",
"token_type": "credit_card",
"id": "86c6a9466c",
"card_type": "visa",
"card_owner_name": "John Doe",
"last_4": "1111",
"card_exp_month": 1,
"card_exp_year": 2020
}
GET /tokens
Gets basic detail for a saved token.
Parameters
Parameter | Details |
---|---|
token_id | ID of the token you want to fetch. |
Error Codes
Error Code | Message |
---|---|
882719 | The token you specified could not be found. |
Charges
Charge a Token
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/charge' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"token": "01fc630146",
"amount": 2000,
"cvv": "999"
"send_receipt": false,
"zip": "68521"
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/charge")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"token\": \"01fc630146\",\"amount\": 1000,\"cvv\": 999,\"zip\": \"68521\",\"send_receipt\": false}"
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/charge");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"token\": \"01fc630146\",\"amount\": 1000,\"cvv\": 999,\"zip\": \"68521\",\"send_receipt\": false}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"charge"
],
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ token: '01fc630146', amount: 1000, cvv: 999, zip: '68521', send_receipt: false }));
req.end();
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\"token\": \"01fc630146\",\"amount\": 1000,\"cvv\": 999,\"zip\": \"68521\",\"send_receipt\": false}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,charge", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "transaction",
"id": "7248644c4708495abb0f50b3598e8963",
"payment_method": "credit_card",
"created_at": "2018-07-23T21:14:28.995Z",
"merchant_id": "9ccaa2022007_test",
"amount_authorized": 2001,
"amount_refunded": 0,
"amount_settled": 2001,
"amount_failed": 0,
"transaction_type": "sale",
"reference_number": "809213",
"description": null,
"card_type": "visa",
"card_number": "************1111",
"card_exp_month": "1",
"card_exp_year": "2020",
"authorized": true,
"settled": true,
"refunded": false,
"voided": false,
"system_trace": null,
"status": "SETTLED",
"customer_id": "4e49fb",
"receipt": {},
"company": "ABC Corp",
"website": "http://www.example.com",
"card_owner_name": "John Doe",
"email_address": "test@example.com",
"email": "test@example.com",
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"zip": "68521",
"country": "USA",
"phone": "",
"fax": "402-437-0100",
"csc_check": "0",
"avs_address_check": null,
"source": "web",
"successful": true,
"metadata": {
"bar": "baz"
},
"error_message": null,
"account_holder_name": "John Doe",
"recurring": false,
"processed_at": null,
"refunds": []
}
POST /charge
If you’ve created a token for the card, you can apply a charge directly to that token. Tokens are one-time-use only. All payer information should be put in the relevant fields of the token whenever possible.
Parameters
Parameter | Details |
---|---|
token | ID of saved token. |
amount | Amount in cents. |
cvv | Card Verification Value (also called csc). This field is required if merchant cvv verification is enabled for credit card transactions. |
zip | Zip or postal code. This field is required if merchant AVS Verification is enabled for credit card transactions. |
send_receipt | Boolean that will override your merchant and this customer’s settings for whether to send a receipt. |
receipt_template_id | ID for a receipt template that will override your merchant and this customer’s for which receipt template to use. |
email_address | Email address to which to send the email receipt. |
description | text description of charge |
metadata | JSON object literal with key-value pairs; these will be displayed as "custom fields" in the dashboard and as metadata in the serialized charge |
Error Codes
Error Code | Message |
---|---|
69201 | Please specify a valid token for this charge. |
69002 | One or more parameters were missing. Please make sure you enter a correct token and amount (in cents) and retry the transaction. |
59112 | Amount must be sent as a number of cents greater than zero. |
82004 | Card verification failed. |
CPCVV1 | Card verification failed. Card Issuer does not support CVV, while the Merchant requires it. |
CPCVV2 | Card verification failed. Please double check your card verification code. |
69005 | You need to specify an email_address with this transaction to send a receipt. |
69006 | The specified email address for the receipt is invalid. Please specify a valid email address. |
AVSZIP404 | Merchant requires zip code for AVS verification. |
Charge a Customer
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/charge' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"customer_id": "62a987ed39",
"amount": 2000,
"send_receipt": false
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/charge")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"customer_id\": \"4e49fb\",\"amount\": 2001,\"metadata\": {\"bar\": \"baz\"}}"
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/charge");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"customer_id\": \"4e49fb\",\"amount\": 2001,\"metadata\": {\"bar\": \"baz\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"charge"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ customer_id: '4e49fb', amount: 2001, metadata: { bar: 'baz' } }));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/charge)
payload = "{\"customer_id\": \"4e49fb\",\"amount\": 2001,\"metadata\": {\"bar\": \"baz\"}}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,charge", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "transaction",
"id": "7248644c4708495abb0f50b3598e8963",
"payment_method": "credit_card",
"created_at": "2018-07-23T21:14:28.995Z",
"merchant_id": "9ccaa2022007_test",
"amount_authorized": 2001,
"amount_refunded": 0,
"amount_settled": 2001,
"amount_failed": 0,
"transaction_type": "sale",
"reference_number": "809213",
"description": null,
"card_type": "visa",
"card_number": "************1111",
"card_exp_month": "1",
"card_exp_year": "2020",
"authorized": true,
"settled": true,
"refunded": false,
"voided": false,
"system_trace": null,
"status": "SETTLED",
"customer_id": "4e49fb",
"receipt": {},
"company": "ABC Corp",
"website": "http://www.example.com",
"card_owner_name": "John Doe",
"email_address": "test@example.com",
"email": "test@example.com",
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"zip": "68521",
"country": "USA",
"phone": "",
"fax": "402-437-0100",
"csc_check": "0",
"avs_address_check": null,
"source": "web",
"successful": true,
"metadata": {
"bar": "baz"
},
"error_message": null,
"account_holder_name": "John Doe",
"recurring": false,
"processed_at": null,
"refunds": []
}
POST /charge
If you’ve created a customer record with at least one payment method, you can then charge that customer using that customer’s ID. You can charge a customer using their credit card or bank account.
Parameters
Parameter | Details |
---|---|
customer_id | ID of saved customer. |
amount | Amount in cents. |
send_receipt | Boolean that will override your merchant and this customer’s settings for whether to send a receipt. |
receipt_template_id | ID for a receipt template that will override your merchant and this customer’s for which receipt template to use. |
description | text description for the transaction |
method_id | ID of the payment method you'd like to charge (if not present, will charge the default payment method of the customer). |
charge_bank_account | Boolean value, defaulting to false . If no method_id is specified, the customer's default payment method will be charged with this parameter as the switch to determine if we use the default ACH method or the default credit card. |
metadata | JSON object literal with key-value pairs; these will be displayed as "custom fields" in the dashboard and as metadata in the serialized charge. Any custom fields supplied here will be merged with whatever custom fields exist on the customer. |
Error Codes
Error Code | Message |
---|---|
34792 | Could not find payment token with id provided. |
99819 | Amount should be a positive number in cents. |
48291 | One or more parameters were missing. Please make sure you enter a correct customer_id and amount (in cents) and retry the transaction. |
59112 | Amount must be sent as a number of cents greater than zero. |
34798 | Please specify a valid customer_id for this charge. |
69005 | You need to specify an email_address with this transaction to send a receipt. |
69006 | The specified email address for the receipt is invalid. Please specify a valid email address. |
Retrieve a Charge
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/charge/cfec19d4327846febfee26504d6f407b
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/charge/cfec19d4327846febfee26504d6f407b")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/charge/cfec19d4327846febfee26504d6f407b");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"charge",
"cfec19d4327846febfee26504d6f407b"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/charge/cfec19d4327846febfee26504d6f407b")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("GET", "cfec19d4327846febfee26504d6f407b", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "transaction",
"id": "cfec19d4327846febfee26504d6f407b",
"payment_method": "credit_card",
"created_at": "2018-07-23T20:50:10.263Z",
"merchant_id": "9ccaa2022007_test",
"amount_authorized": 2001,
"amount_refunded": 0,
"amount_settled": 2001,
"amount_failed": 0,
"transaction_type": "sale",
"reference_number": "6672898",
"description": null,
"card_type": "visa",
"card_number": "************1111",
"card_exp_month": "1",
"card_exp_year": "2020",
"authorized": true,
"settled": true,
"refunded": false,
"voided": false,
"system_trace": null,
"status": "SETTLED",
"customer_id": "9c024a",
"receipt": {},
"company": "ABC Corp",
"website": "http://www.example.com",
"card_owner_name": "John Doe",
"email_address": "test@example.com",
"email": "test@example.com",
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"zip": "68521",
"country": "USA",
"phone": "",
"fax": "402-437-0100",
"csc_check": "0",
"avs_address_check": null,
"source": "web",
"successful": true,
"metadata": {},
"error_message": null,
"account_holder_name": "John Doe",
"recurring": false,
"processed_at": null,
"refunds": []
}
GET /charge/:id
Gets basic detail for a charge.
Parameters
Parameter | Details |
---|---|
charge_id | ID of the charge you want to fetch. |
Error Codes
Error Code | Message |
---|---|
69404 | Could not find charge with id provided. |
Refund a Charge
REFUND A CHARGE
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/charge/e8b63f39d0ae40a19c6ec5ff294d5b8c/cancel' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"amount": 2000
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/charge/e8b63f39d0ae40a19c6ec5ff294d5b8c/cancel")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"amount\": 2006}"
response = http.request(request)
puts response.read_body
var client = new RestClient("http://{{url}}charge/{{e8b63f39d0ae40a19c6ec5ff294d5b8c}}/cancel");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"amount\": 2006}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"charge"
"e8b63f39d0ae40a19c6ec5ff294d5b8c",
"cancel"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ amount: 2006 }));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/charge")
payload = "{\"amount\": 2006}"
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,charge,e8b63f39d0ae40a19c6ec5ff294d5b8c,cancel", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "transaction",
"id": "e8b63f39d0ae40a19c6ec5ff294d5b8c",
"payment_method": "credit_card",
"created_at": "2018-07-23T20:58:51.715Z",
"merchant_id": "9ccaa2022007_test",
"amount_authorized": 2006,
"amount_refunded": 2006,
"amount_settled": 2006,
"amount_failed": 0,
"transaction_type": "sale",
"reference_number": "3459851",
"description": null,
"card_type": "amex",
"card_number": "***********9133",
"card_exp_month": "8",
"card_exp_year": "2021",
"authorized": true,
"settled": true,
"refunded": true,
"voided": false,
"system_trace": null,
"status": "REFUNDED",
"customer_id": null,
"receipt": {},
"company": null,
"website": null,
"card_owner_name": "Ada Lovelace",
"email_address": null,
"email": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone": null,
"fax": null,
"csc_check": "0",
"avs_address_check": null,
"source": "web",
"successful": true,
"metadata": null,
"error_message": null,
"account_holder_name": "Ada Lovelace",
"recurring": false,
"processed_at": null,
"refunds": [
{
"amount": 2006,
"status": "settled",
"error_message": {},
"created_at": "2018-07-23T20:59:13.810Z"
}
]
}
POST /charge/:id/cancel
Refund a charge for a given amount.
Parameters
Parameter | Details |
---|---|
amount | Amount of charge to refund. Must be equal to or less than the amount originally charged. If missing or null , a full refund is issued |
Error Codes
Error Code | Message |
---|---|
38501 | Please enter the refund amount as a number of cents. |
59217 | Aggregate refund amount must be less than or equal to the original transaction amount. |
59216 | Transaction has already been fully refunded. |
List Transactions
LIST TRANSACTIONS
Sample Request:
curl -X GET 'https://api.paymentspring.com/api/v1/transactions' \
-u private-api-key: \
-d '{
"limit": 25,
"offset": 0
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/transactions")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/transactions");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"transactions"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/transactions")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "undefined", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"list": [
{
"class": "transaction",
"id": "e5fb751593864854a76195f60c361d7c",
"payment_method": "credit_card",
"created_at": "2017-11-21T16:16:21.361Z",
"merchant_id": "5bcadf893357_test",
"amount_authorized": 2000,
"amount_refunded": 2000,
"amount_settled": 2000,
"amount_failed": 0,
"transaction_type": "sale",
"reference_number": "7836799",
"description": null,
"card_type": "discover",
"card_number": "************0474",
"card_exp_month": "1",
"card_exp_year": "2020",
"authorized": true,
"settled": true,
"refunded": true,
"voided": false,
"system_trace": null,
"status": "REFUNDED",
"customer_id": "c73b8f",
"receipt": {},
"company": "ABC Corp",
"website": "http://www.example.com",
"card_owner_name": "John Doe",
"email_address": "test@example.com",
"email": "test@example.com",
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"zip": "68521",
"country": "USA",
"phone": "402-437-0127",
"fax": "402-437-0100",
"csc_check": "0",
"avs_address_check": "0",
"source": "web",
"successful": true,
"metadata": null,
"error_message": null,
"account_holder_name": "John Doe",
"recurring": false,
"processed_at": null,
"new_record": false
}
],
"meta": {
"offset": "0",
"total_results": 1,
"limit": "25"
}
}
GET /transactions
Gets a list of the most recent transactions.
Parameters
Parameter | Details |
---|---|
limit | Maximum number of transactions to return. |
offset | Event index to begin returning transactions from, useful for pagination. |
Error Codes
Error Code | Message |
---|---|
1800 | Limit ‘limit’ is not a positive integer. |
1801 | Offset ‘offset’ is not a positive integer. |
1802 | Limit ‘limit’ is greater than 100. |
Transaction Search
Sample Request:
import json
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = {
'method_type': ['CreditCardTransaction', 'AchTransaction', 'CheckTransaction', 'ApplePayTransaction'],
'method_sub_type': ['visa', 'mastercard', 'discover', 'amex', 'dinersclub', 'checking', 'savings'],
'status': ['pending', 'settled', 'failed', 'cancelled', 'refunded'],
'start_date': '2018-08-28',
'end_date': '2018-10-12',
'source': ['web', 'mobile'],
'method_last_four': '1111',
'amount': '1000',
'search_term': '"donor_id": "12345"'
}
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v2,transactions,search", json.dumps(payload), headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v2/transactions/search");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.POST);
request.AddParameter("undefined", "{\n\t\"method_type\": [\"CreditCardTransaction\", \"AchTransaction\", \"CheckTransaction\", \"ApplePayTransaction\"],\n\t\"method_sub_type\": [\"visa\", \"mastercard\", \"discover\", \"amex\", \"dinersclub\", \"checking\", \"savings\"],\n\t\"status\": [\"pending\", \"settled\", \"failed\", \"cancelled\", \"refunded\"],\n\t\"start_date\": \"2018-08-28\",\n\t\"end_date\": \"2018-10-12\",\n\t\"source\": [\"web\", \"mobile\"],\n\t\"method_last_four\": \"1111\",\n\t\"amount\": \"1000\",\n\t\"search_term\": \"\\\"donor_id\\\": \\\"12345\\\"\"\n}", ParameterType.RequestBody);
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v2/transactions/search")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request.basic_auth 'your-private-api-key', ''
request["Content-Type"] = 'application/json'
request.body = {
method_type: ["CreditCardTransaction", "AchTransaction", "CheckTransaction", "ApplePayTransaction"],
method_sub_type: ["visa", "mastercard", "discover", "amex", "dinersclub", "checking", "savings"],
status: ["pending", "settled", "failed", "cancelled", "refunded"],
start_date: "2018-08-28",
end_date: "2018-10-12",
source: ["web", "mobile"],
method_last_four: "1111",
amount: "1000",
search_term: '"donor_id\": \"12345\"'
}.to_json
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v2",
"transactions",
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl -X POST 'https://api.paymentspring.com/api/v2/transactions/search' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"search_term": "john",
"page": 1
}'
Expected Response Data:
{
"list": [
{
"id": "1564280100e2409bb97837462c76a1b3",
"class": "transaction",
"payment_method": "credit_card",
"created_at": "2018-10-04T16:48:20.316Z",
"merchant_id": "8baddcef0843_test",
"amount_authorized": 1000,
"amount_refunded": 0,
"amount_settled": 1000,
"amount_failed": 0,
"transaction_type": "sale",
"reference_number": "3365374",
"description": null,
"card_type": "visa",
"card_number": "************1111",
"card_exp_month": "8",
"card_exp_year": "2021",
"authorized": true,
"settled": true,
"refunded": false,
"voided": false,
"system_trace": null,
"status": "SETTLED",
"customer_id": null,
"receipt": {},
"company": null,
"website": null,
"card_owner_name": "Ada Lovelace",
"email_address": null,
"email": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone": null,
"fax": null,
"csc_check": "0",
"avs_address_check": "0",
"source": "web",
"successful": true,
"metadata": {
"donor_id": "12345"
},
"error_message": null,
"account_holder_name": "Ada Lovelace",
"recurring": false,
"processed_at": null
}
],
"meta": {
"offset": 0,
"limit": 25,
"total_results": 1
}
}
POST v2/transactions/search
Search for transactions meeting the specified criteria. NOTE This is a v2
route, rather than a v1
route. You'll need to use
https://api.paymentspring.com/v2/transactions/search
as your endpoint.
Parameters
Parameter | Details |
---|---|
search_term | Customer name, company name, portion of metadata, or ID to search on. You can also search for exact metadata match with "key_name": "value" (note the quotation marks) |
method_type | An array containing zero or more of CreditCardTransaction , AchTransaction , CheckTransaction , and/or ApplePayTransaction |
method_sub_type | An array containing zero or more of visa , mastercard , amex , dinersclub , checking , savings |
start_date | First day to consider for transactions, expressed as YYYY-MM-DD |
end_date | Last day to consider for transactions, expressed as YYYY-MM-DD |
source | Array containing zero or more of web or mobile |
method_last_four | string for the last four digits of the payer's payment method |
amount | exact amount to match, expressed in cents (e.g. $10 would be expressed as 1000 |
Error Codes
Error Code | Message |
---|---|
20000 | Search term must be at least 3 characters. |
Schedule a Charge
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/charge' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"token": "01fc630146",
"amount": 2000,
"bill_on": "10/31/2018",
"send_receipt": false
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/charge")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"token\": \"01fc630146\",\"amount\": 1000,\"send_receipt\": false, \"bill_on\":\"10-31-2018\"}"
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/charge");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"token\": \"01fc630146\",\"amount\": 1000,\"send_receipt\": false, \"bill_on\":\"10/31/2018\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"charge"
],
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ token: '01fc630146', amount: 1000, send_receipt: false, bill_on: "2018/10/31" }));
req.end();
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\"token\": \"01fc630146\",\"amount\": 1000,\"send_receipt\": false,
\"bill_on\": \"10/31/2018\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,charge", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "scheduledtransaction",
"zip": null,
"city": null,
"state": null,
"token": "01fc640146",
"amount": "1000",
"company": null,
"website": null,
"metadata": "",
"address_1": null,
"address_2": null,
"fax_number": null,
"ip_address": "0.0.0.0",
"description": null,
"phone_number": null,
"send_receipt": "false",
"email_address": null,
"card_owner_name": null,
"charge_bank_account": null,
"receipt_template_id": null,
"bank_account_holder_last_name": null,
"bank_account_holder_first_name": null,
"id": "920f1da530ac43ab988f60626938700b",
"status": "unbilled",
"bill_on": "2018-10-31",
"created_at": "2018-10-08T19:55:27.479Z",
"updated_at": "2018-10-08T19:55:27.479Z",
"transaction_id": "",
"new_record": false
}
POST /charge
You can schedule a one-time payment for up to 30 days in the future. The
parameters are exactly the same as a regular charge, with the addition of
bill_on
(the date billing will occur).
Parameters
Parameter | Details |
---|---|
token | ID of saved token. |
amount | Amount in cents. |
send_receipt | Boolean that will override your merchant and this customer’s settings for whether to send a receipt. |
receipt_template_id | ID for a receipt template that will override your merchant and this customer’s for which receipt template to use. |
email_address | Email address to which to send the email receipt. |
description | text description of charge |
metadata | JSON object literal with key-value pairs; these will be displayed as "custom fields" in the dashboard and as metadata in the serialized charge |
bill_on | A date, represented as MM/DD/YYYY , up to 30 days in the future, for this transaction to be billed on. |
Error Codes
Error Code | Message |
---|---|
69201 | Please specify a valid token for this charge. |
69002 | One or more parameters were missing. Please make sure you enter a correct token and amount (in cents) and retry the transaction. |
59112 | Amount must be sent as a number of cents greater than zero. |
69005 | You need to specify an email_address with this transaction to send a receipt. |
69006 | The specified email address for the receipt is invalid. Please specify a valid email address. |
Retrieve a Scheduled Transaction
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/scheduled_transactions/cfec19d4327846febfee26504d6f407b
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/scheduled_transactions/cfec19d4327846febfee26504d6f407b")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/scheduled_transactions/cfec19d4327846febfee26504d6f407b");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"scheduled_transactions",
"cfec19d4327846febfee26504d6f407b"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/scheduled_transactions/cfec19d4327846febfee26504d6f407b")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("GET", "cfec19d4327846febfee26504d6f407b", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "scheduledtransaction",
"zip": null,
"city": null,
"state": null,
"token": "dd4a9bf63f",
"amount": "1000",
"company": null,
"website": null,
"metadata": "{\"donor_id\":\"12345\"}",
"address_1": null,
"address_2": null,
"fax_number": null,
"description": null,
"phone_number": null,
"send_receipt": "false",
"email_address": null,
"card_owner_name": null,
"charge_bank_account": null,
"receipt_template_id": null,
"bank_account_holder_last_name": null,
"bank_account_holder_first_name": null,
"id": "920f1da530ac43ab988f60626938700b",
"status": "unbilled",
"bill_on": "2018-10-12",
"created_at": "2018-10-08T19:55:27.479Z",
"updated_at": "2018-10-08T19:55:27.479Z",
"transaction_id": "",
"new_record": false
}
GET /scheduled_transactions/:id
Gets basic detail for a scheduled payment
Parameters
Parameter | Details |
---|---|
id | ID of the charge you want to fetch. |
Error Codes
Error Code | Message |
---|---|
69404 | Could not find charge with id provided. |
List Scheduled Transactions
Sample Request:
curl -X GET 'https://api.paymentspring.com/api/v1/scheduled_transactions' \
-u private-api-key: \
-d '{
"limit": 25,
"offset": 0
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/scheduled_transactions")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/scheduled_transactions");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"scheduled_transactions"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/scheduled_transactions")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "undefined", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"list": [
{
"class": "scheduledtransaction",
"zip": null,
"city": null,
"state": null,
"token": "dd4a9bf63f",
"amount": "1000",
"company": null,
"website": null,
"metadata": "{\"donor_id\":\"12345\"}",
"address_1": null,
"address_2": null,
"fax_number": null,
"description": null,
"phone_number": null,
"send_receipt": "false",
"email_address": null,
"card_owner_name": null,
"charge_bank_account": null,
"receipt_template_id": null,
"bank_account_holder_last_name": null,
"bank_account_holder_first_name": null,
"id": "920f1da530ac43ab988f60626938700b",
"status": "unbilled",
"bill_on": "2018-10-12",
"created_at": "2018-10-08T19:55:27.479Z",
"updated_at": "2018-10-08T19:55:27.479Z",
"transaction_id": "",
"new_record": false
}
],
"meta": {
"total_result": 1,
"limit": 25,
"offset": 0
}
}
GET /scheduled_transactions
Gets a list of the most recent scheduled transactions
Parameters
Parameter | Details |
---|---|
limit | Maximum number of transactions to return. |
offset | Event index to begin returning transactions from, useful for pagination. |
Error Codes
Error Code | Message |
---|---|
1800 | Limit ‘limit’ is not a positive integer. |
1801 | Offset ‘offset’ is not a positive integer. |
1802 | Limit ‘limit’ is greater than 100. |
Cancel Scheduled Charge
Sample Request:
curl -X POST -u private-api-key: https://api.paymentspring.com/api/v1/scheduled_transactions/920f1da530ac43ab988f60626938700b/cancel
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/scheduled_transactions/920f1da530ac43ab988f60626938700b/cancel")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/scheduled_transactions/920f1da530ac43ab988f60626938700b/cancel");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"scheduled_transactions",
"920f1da530ac43ab988f60626938700b",
"cancel"
],
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = ""
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,scheduled_transactions,920f1da530ac43ab988f60626938700b,cancel", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "scheduledtransaction",
"zip": null,
"city": null,
"state": null,
"token": "01fc640146",
"amount": "1000",
"company": null,
"website": null,
"metadata": "",
"address_1": null,
"address_2": null,
"fax_number": null,
"ip_address": "0.0.0.0",
"description": null,
"phone_number": null,
"send_receipt": "false",
"email_address": null,
"card_owner_name": null,
"charge_bank_account": null,
"receipt_template_id": null,
"bank_account_holder_last_name": null,
"bank_account_holder_first_name": null,
"id": "920f1da530ac43ab988f60626938700b",
"status": "cancelled",
"bill_on": "2018-10-31",
"created_at": "2018-10-08T19:55:27.479Z",
"updated_at": "2018-10-08T19:55:27.479Z",
"transaction_id": "",
"new_record": false
}
POST /scheduled_transactions/:id/cancel
Cancel a scheduled payment before it bills
Parameters
Parameter | Details |
---|
Error Codes
Error Code | Message |
---|
Receipts
All available receipt template tags are listed below:
Create a New Receipt
CREATE A NEW EMAIL RECEIPT
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/charge/62a987ed39/receipt' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"email_address": "test2@gmail.com"
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/charge/62a987ed39/receipt")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"receipt_type\": \"email\",\"email_address\": \"test2@example.com\",}"
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/charge/62a987ed39/receipt");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"receipt_type\": \"email\",\"email_address\": \"test2@example.com\",}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"charge",
"62a987ed39",
"receipt"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ receipt_type: 'email',
email_address: 'test2@example.com' }));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/charge")
payload = "{\"receipt_type\": \"email\",\"email_address\": \"test2@example.com\",}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "62a987ed39,receipt", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "receipt",
"receipt_type": "email",
"id": 80,
"created_at": "2014-03-07T16:28:58+00:00",
"merchant_id": "2a3478b8e320_test",
"transaction_id": "831ac5e923",
"email_address": "test2@example.com",
"receipt_template_id": "0",
"subject": "Test Company has received your payment",
"receipt_text": "Greeny\n"
}
CREATE A NEW SMS RECEIPT
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/charge/62a987ed39/receipt' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"receipt_type": "sms",
"phone_number": "5555555555"
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/charge/62a987ed39/receipt")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"receipt_type\": \"sms\",\"phone_number\": \"5555555555\",}"
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/charge/62a987ed39/receipt");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"receipt_type\": \"sms\",\"phone_number\": \"5555555555\",}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"charge",
"62a987ed39",
"receipt"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ receipt_type: 'sms',
phone_number: '5555555555' }));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/charge")
payload = "{\"receipt_type\": \"sms\",\"phone_number\": \"5555555555\",}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "62a987ed39,receipt", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "receipt",
"receipt_type": "sms",
"id": 80,
"created_at": "2014-03-07T16:28:58+00:00",
"merchant_id": "2a3478b8e320_test",
"transaction_id": "831ac5e923",
"phone_number": "5555555555",
"receipt_template_id": null,
"subject": null,
"receipt_text": "Greeny\n"
}
POST /charge/:id/receipt
Creates and sends a new receipt on an already existing transaction.
Parameters
Parameter | Details |
---|---|
receipt_type | Specifies how the receipt will be sent. If a value is not provided, an email receipt will be sent by default. Can be email or sms |
email_address | Email address to which to send the email receipt. |
receipt_template_id | ID for a receipt template that will override your merchant settings for which receipt template to use. Only applies for email receipts. |
phone_number | Phone number to which to send the sms receipt. This requires that receipt_type be set to sms . |
Error Codes
Error Code | Message |
---|---|
69005 | You need to specify an email_address with this transaction to send a receipt. |
69006 | The specified email address for the receipt is invalid. Please specify a valid email address. |
10302 | You must specify a phone_number to send a receipt by text message. |
69404 | Could not find charge with id provided. |
Delete a Receipt Template
DELETE A RECEIPT TEMPLATE
Sample Request:
curl -X DELETE 'https://api.paymentspring.com/api/v1/receipts/templates/62a987ed39' \
-u private-api-key:
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/receipts/templates/62a987ed39")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Delete.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/receipts/templates/62a987ed39");
var request = new RestRequest(Method.DELETE);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "DELETE",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"receipts",
"templates",
"62a987ed39"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/receipts")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("DELETE", "templates,62a987ed39", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"success": true
}
DELETE /receipts/templates/:id
Deletes a receipt template to be used for making receipts.
Parameters
Parameter | Details |
---|---|
id | ID of the receipt template to be destroyed |
Create a Receipt Template
CREATE A RECEIPT TEMPLATE
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/receipts/templates' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"receipt_text": "Test template text [Amount]<br><br>Thank you!",
"name": "Basic Template",
"subject": "thanks for the payment"
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/receipts/templates")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"receipt_text\": \"Test template text [Amount]<br><br>Thank you!\",\"name\": \"Basic Template\",\"subject\": \"thanks for the payment\"}"
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/receipts/templates");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"receipt_text\": \"Test template text [Amount]<br><br>Thank you!\",\"name\": \"Basic Template\",
\"subject\": \"thanks for the payment\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"receipts",
"templates"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ receipt_text: 'Test template text [Amount]<br><br>Thank you!',
name: 'Basic Template',
subject: 'thanks for the payment' }));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/receipts")
payload = "{\"receipt_text\": \"Test template text [Amount]<br><br>Thank you!\",\"name\": \"Basic Template\",\"subject\": \"thanks for the payment\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "templates", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"id": 5903,
"created_at": "2018-07-24T14:22:47.216Z",
"updated_at": "2018-07-24T14:22:47.216Z",
"merchant_id": 4632,
"receipt_text": "Test template text [Amount]<br><br>Thank you!",
"name": "Basic Template",
"subject": "thanks for the payment",
"class": "receipt_template"
}
POST /receipts/templates
Creates a receipt template to be used for making receipts. You have access to the following flags (make sure to include the square brackets):
[Description]
- this is the description provided for the transaction[TransactionID]
- the transaction's UUID, which you can query programmatically[Amount]
- amount, formatted in dollars[PaymentInfo]
- formatted payment information:Card Number: ************** 1234
Account Number: ********** 1234
[CustomerID]
- Custom ID for the customer[Last4]
- last 4 of the credit card number or bank account number[CustomerFirstName]
- First name of the customer, if provided[CustomerLastName]
- Last name of the customer, if provided[CustomerFullName]
- First and last name of the customer, if provided[CompanyName]
- Customer's company name, if provided[CustomerName]
- One of, in order:- Customer's company name
- Customer first and last name
- Cardholder name
[MerchantName]
- Name of the company[CardOwnerName]
- the payer name associated with the credit card or bank account[CreatedAt]
- Timestamp (UTC) for when the transaction was created
You can also include metadata fields in your receipt templates (assuming they are present in your transactions).
These are formatted as [Metadata/my field name]
. The important caveat is that
these custom field names cannot include the ]
character.
Any fields that are not present (for example, a missing metadata field) will simply be rendered as a blank space.
If you want to include new lines in the receipt template (assuming you are
communicating through the API), use break tags: <br>
.
Parameters
Parameter | Details |
---|---|
receipt_text | Text of the receipt template. |
name | Name of the receipt template. |
subject | Subject of the email for the receipt template. |
Error Codes
Error Code | Message |
---|---|
10302 | Please provide a receipt_text for the receipt template. |
Update a Receipt Template
UPDATE A RECEIPT TEMPLATE
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/receipts/templates/62a987ed39' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"receipt_text": "Test template text [Amount] [Description]",
"name": "Basic Template 2",
"subject": "thanks for the payment, [CustomerName]"
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/receipts/templates/62a987ed39")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"receipt_text\": \"Test template text [Amount]\",\"name\": \"Basic Template 2\",\"subject\": \"thanks again!\"}"
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/receipts/templates/62a987ed39");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"receipt_text\": \"Test template text [Amount]\",\"name\": \"Basic Template 2\",\"subject\": \"thanks again!\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"receipts",
"templates",
"62a987ed39"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ receipt_text: 'Test template text [Amount]',
name: 'Basic Template 2',
subject: 'thanks again!' }));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/receipts")
payload = "{\"receipt_text\": \"Test template text [Amount]\",\"name\": \"Basic Template 2\",\"subject\": \"thanks again!\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "templates,{{62a987ed39}}", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"id": 5904,
"created_at": "2018-07-24T14:42:16.760Z",
"updated_at": "2018-07-24T14:42:57.210Z",
"merchant_id": 4632,
"receipt_text": "Test template text [Amount]",
"name": "Basic Template 2",
"subject": "thanks again!",
"class": "receipt_template"
}
POST /receipts/templates/:id
Updates a receipt template to be used for making receipts.
Parameters
Parameter | Details |
---|---|
receipt_text | Text of the receipt template. |
name | Name of the receipt template. |
subject | Subject of the email for the receipt template. |
Retrieve a Receipt Template
RETRIEVE A RECEIPT TEMPLATE
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/receipts/templates/62a987ed39
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/receipts/templates/62a987ed39")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/receipts/templates/62a987ed39");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"receipts",
"templates",
"62a987ed39"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/receipts")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "templates,62a987ed39", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"id": 5904,
"created_at": "2018-07-24T14:42:16.760Z",
"updated_at": "2018-07-24T14:42:16.760Z",
"merchant_id": 4632,
"receipt_text": "Test template text [Amount]",
"name": "Basic Template",
"subject": "thanks for the payment",
"class": "receipt_template"
}
GET /receipts/templates/:id
Gets basic detail for a saved receipt template.
Parameters
Parameter | Details |
---|---|
id | ID of the receipt template you want to fetch. |
Error Codes
Error Code | Message |
---|---|
10300 | That receipt template was not found. |
Customers
Create a Customer
CREATE A CUSTOMER WITH A TOKEN
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\n \"company\": \"ABC Corp\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address_1\": \"123 Apple Street\",\n \"address_2\": \"Apt 101\",\n \"city\": \"Lincoln\",\n \"state\": \"NE\",\n \"zip\":\"68521\",\n \"phone\":\"402-437-0127\",\n \"fax\":\"402-437-0100\",\n \"website\":\"http://www.example.com\",\n \"country\": \"USA\",\n \"email\": \"test@example.com\",\n \"token\": \"token_id\",\n \"cvv\":\"999\" }"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v1,customers", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v1/customers");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\n \"company\": \"ABC Corp\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address_1\": \"123 Apple Street\",\n \"address_2\": \"Apt 101\",\n \"city\": \"Lincoln\",\n \"state\": \"NE\",\n \"zip\":\"68521\",\n \"phone\":\"402-437-0127\",\n \"fax\":\"402-437-0100\",\n \"website\":\"http://www.example.com\",\n \"country\": \"USA\",\n \"email\": \"test@example.com\",\n \"token\": \"token_id\",\n \"cvv\": \"999\" }", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/customers")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\n \"company\": \"ABC Corp\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address_1\": \"123 Apple Street\",\n \"address_2\": \"Apt 101\",\n \"city\": \"Lincoln\",\n \"state\": \"NE\",\n \"zip\":\"68521\",\n \"phone\":\"402-437-0127\",\n \"fax\":\"402-437-0100\",\n \"website\":\"http://www.example.com\",\n \"country\": \"USA\",\n \"email\": \"test@example.com\",\n \"token\":\"token_id\",\n \"cvv\":\"999\"}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ company: 'ABC Corp',
first_name: 'John',
last_name: 'Doe',
address_1: '123 Apple Street',
address_2: 'Apt 101',
city: 'Lincoln',
state: 'NE',
zip: '68521',
phone: '402-437-0127',
fax: '402-437-0100',
website: 'http://www.example.com',
country: 'USA',
email: 'test@example.com',
token: 'token_id',
cvv: '999' }));
req.end();
curl -X POST 'https://api.paymentspring.com/api/v1/customers' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"company": "ABC Corp",
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"zip": "68521",
"phone": "402-437-0127",
"fax": "402-437-0100",
"website": "http://www.example.com",
"country": "USA",
"email": "test@example.com",
"token": "token_id",
"cvv": "999"
}'
Expected Response Data:
{
"id": "03a827",
"created_at": "2017-12-05T15:51:16Z",
"updated_at": "2017-12-05T15:51:16Z",
"class": "customer",
"card_owner_name": "John Doe",
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"company": "ABC Corp",
"country": "USA",
"fax": "402-437-0127",
"first_name": "John",
"last_name": "Doe",
"email": "test@example.com",
"city": "Lincoln",
"phone": "402-437-0127",
"zip": "68521",
"state": "NE",
"website": "http://www.example.com",
"card_type": "visa",
"last_4": "1111",
"card_exp_month": 1,
"card_exp_year": 2020,
"default_receipts": false,
"default_receipt_template_id": null,
"bank_account_number_last_4": null,
"bank_routing_number": null,
"bank_account_holder_first_name": null,
"bank_account_holder_last_name": null,
"bank_account_type": null,
"default_method_id": "8f2a570d4605498399b3752870c1df93",
"methods": [
{
"id": "347ee36dd2b04fa0bac953963e5e70e6",
"class": "payment_method",
"method_type": "bank_account",
"bank_account_number_last_4": null,
"bank_routing_number": null,
"bank_account_holder_first_name": null,
"bank_account_holder_last_name": null,
"bank_account_type": null,
"customer_id": null,
"created_at": "2017-12-05T15:51:16.888Z",
"updated_at": "2017-12-05T15:51:16.904Z",
"company": "ABC Corp",
"address": {
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"country": "USA",
"zip": "68521",
"company": "ABC Corp"
}
},
{
"id": "8f2a570d4605498399b3752870c1df93",
"class": "payment_method",
"method_type": "credit_card",
"last_4": "1111",
"card_type": "visa",
"card_exp_month": 1,
"card_exp_year": 2020,
"card_owner_name": "John Doe",
"customer_id": null,
"created_at": "2017-12-05T15:51:16.849Z",
"updated_at": "2017-12-05T15:51:16.879Z",
"address": {
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"country": "USA",
"zip": "68521",
"company": "ABC Corp"
}
}
]
}
CREATE A CUSTOMER WITH NO PAYMENT INFORMATION
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/customers' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"company": "ABC Corp",
"first_name": "John",
"last_name": "Doe",
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"zip":"68521",
"phone":"402-437-0127",
"fax":"402-437-0100",
"website":"http://www.example.com",
"country": "USA",
"email": "test@example.com"
}'
Expected Response Data:
{
"id": "7a91ab",
"created_at": "2017-12-05T16:01:18Z",
"updated_at": "2017-12-05T16:01:18Z",
"class": "customer",
"card_owner_name": null,
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"company": "ABC Corp",
"country": "USA",
"fax": "402-437-0127",
"first_name": "John",
"last_name": "Doe",
"email": "test@example.com",
"city": "Lincoln",
"phone": "402-437-0127",
"zip": "68521",
"state": "NE",
"website": "http://www.example.com",
"card_type": "other",
"last_4": null,
"card_exp_month": null,
"card_exp_year": null,
"default_receipts": false,
"default_receipt_template_id": null,
"bank_account_number_last_4": null,
"bank_routing_number": null,
"bank_account_holder_first_name": null,
"bank_account_holder_last_name": null,
"bank_account_type": null,
"default_method_id": "2ab39e822af34c2e925d2395ed2d4a4b",
"methods": [
{
"id": "a3a51a6c0eed4438a874257bbb647546",
"class": "payment_method",
"method_type": "bank_account",
"bank_account_number_last_4": null,
"bank_routing_number": null,
"bank_account_holder_first_name": null,
"bank_account_holder_last_name": null,
"bank_account_type": null,
"customer_id": null,
"created_at": "2017-12-05T16:01:18.611Z",
"updated_at": "2017-12-05T16:01:18.626Z",
"company": "ABC Corp",
"address": {
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"country": "USA",
"zip": "68521",
"company": "ABC Corp"
}
},
{
"id": "2ab39e822af34c2e925d2395ed2d4a4b",
"class": "payment_method",
"method_type": "credit_card",
"last_4": null,
"card_type": "other",
"card_exp_month": null,
"card_exp_year": null,
"card_owner_name": null,
"csc_check": "0",
"customer_id": null,
"created_at": "2017-12-05T16:01:18.572Z",
"updated_at": "2017-12-05T16:01:18.595Z",
"address": {
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"country": "USA",
"zip": "68521",
"company": "ABC Corp"
}
}
]
}
POST /customers
Create and store a customer with payment information.
Parameters
Parameter | Details |
---|---|
company | Name of company to be saved on the record. |
first_name | First name to be saved on the record. |
last_name | Last name to be saved on the record. |
address_1 | Address 1 to be saved on the record. |
address_2 | Address 2 to be saved on the record. |
city | City to be saved on the record. |
state | State, province, or region to be saved on record |
zip | Zip or postal code to be saved on the record. This field is required if merchant AVS Verification is enabled for credit card transactions. |
country | 3-letter country code (per ISO 3166). Assumed to be "USA" unless otherwise specified. |
phone | Phone number to be saved on the record. |
fax | Fax number to be saved on the record. |
website | Website to be saved on the record. |
country | Country to be saved on the record. |
Email address to be saved on the record. | |
metadata | JSON object literal (or JSON encoded string) with key-value pairs. |
token | ID of the payment token; this will be stored as the default payment method on a customer |
cvv | Card Verification Value (also called csc). This field is required if merchant cvv verification is enabled for credit card transactions. |
Error Codes
Error Code | Message |
---|---|
81602 | Fax field is too long. |
81603 | First name is too long. |
81604 | Last name is too long. |
81606 | Phone number is too long. |
81607 | Website is too long. |
81608 | Custom ID is already taken. |
81609 | Customer email is invalid. |
81609 | Please use the two-character state abbreviation. |
23489 | Could not find specified token for merchant. |
82004 | Card verification failed. |
CPCVV1 | Card verification failed. Card Issuer does not support CVV, while the Merchant requires it. |
CPCVV2 | Card verification failed. Please double check your card verification code. |
AVSZIP404 | Merchant requires zip code for AVS verification. |
Retrieve a Customer
RETRIEVE A CUSTOMER
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("GET", "api,v1,customers,62a987ed39", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v1/customers/62a987ed39");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/customers/62a987ed39")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers",
"62a987ed39"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl -u private-api-key:
https://api.paymentspring.com/api/v1/customers/62a987ed39
Expected Response Data:
{
"id": "62a987ed39",
"created_at": "2017-11-20T19:12:20Z",
"updated_at": "2017-11-20T19:12:20Z",
"class": "customer",
"card_owner_name": null,
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"company": "ABC Corp",
"country": "USA",
"fax": "402-4370-0100",
"first_name": "John",
"last_name": "Doe",
"email": "test@example.com",
"city": "Lincoln",
"phone": "402-437-0127",
"zip": "68521",
"state": "NE",
"website": "http://www.example.com",
"card_type": "visa",
"last_4": "1111",
"card_exp_month": 1,
"card_exp_year": 2020,
"default_receipts": false,
"default_receipt_template_id": null,
"bank_account_number_last_4": "************6789",
"bank_routing_number": "104000058",
"bank_account_holder_first_name": "Ada",
"bank_account_holder_last_name": "Lovelace",
"bank_account_holder_full_name": "Ada Lovelace",
"bank_account_type": "checking",
"default_method_id": "15f219d37b5f4aabb8cdc5fa2a143e43",
"methods": [
{
"id": "ad77af999677462e83266e5b55cff340",
"class": "payment_method",
"method_type": "bank_account",
"bank_account_number_last_4": "************6789",
"bank_routing_number": "104000058",
"bank_account_holder_first_name": "Ada",
"bank_account_holder_last_name": "Lovelace",
"bank_account_holder_full_name": "Ada Lovelace",
"bank_account_type": "checking",
"customer_id": null,
"created_at": "2017-11-20T19:12:20.546Z",
"updated_at": "2017-11-20T19:12:20.563Z",
"company": "ABC Corp",
"address": {
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"country": "USA",
"zip": "68521",
"company": "ABC Corp"
}
},
{
"id": "15f219d37b5f4aabb8cdc5fa2a143e43",
"class": "payment_method",
"method_type": "credit_card",
"last_4": "1111",
"card_type": "visa",
"card_exp_month": "1",
"card_exp_year": "2020",
"card_owner_name": null,
"customer_id": null,
"created_at": "2017-11-20T19:12:20.503Z",
"updated_at": "2017-11-20T19:12:20.531Z",
"address": {
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"country": "USA",
"zip": "68521",
"company": "ABC Corp"
}
}
]
}
GET /customers/:id
Get a customer by using their ID number.
Parameters
Parameter | Details |
---|---|
id | ID of the customer you want to retrieve. |
Error Codes
Error Code | Message |
---|---|
17001 | Could not find the specified customer. |
List Customers
LIST CUSTOMERS
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("GET", "api,v1,customers?limit=25&offset=0", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v1/customers?limit=25&offset=0");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/customers?limit=25&offset=0")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers" + "?limit=25&offset=0"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl -X GET 'https://api.paymentspring.com/api/v1/customers' \
-u private-api-key: \
-d '{
"limit": 25,
"offset": 0
}'
Expected Response Data:
{
"list": [
{
"id": "cefc03",
"created_at": "2018-06-18T19:04:36Z",
"updated_at": "2018-06-18T19:04:36Z",
"class": "customer",
"card_owner_name": "Ada Lovelace",
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"company": "ABC Corp",
"country": "USA",
"fax": "402-437-0100",
"first_name": "John",
"last_name": "Doe",
"email": "test@example.com",
"city": "Lincoln",
"phone": "402-437-0127",
"zip": "68521",
"state": "NE",
"website": "http://www.example.com",
"card_type": "visa",
"last_4": "1111",
"card_exp_month": 8,
"card_exp_year": 2018,
"default_receipts": false,
"default_receipt_template_id": null,
"bank_account_number_last_4": "************6789",
"bank_routing_number": "104000058",
"bank_account_holder_first_name": "Ada",
"bank_account_holder_last_name": "Lovelace",
"bank_account_holder_full_name": "Ada Lovelace",
"bank_account_type": "checking",
"default_method_id": "9274c2c249e94e40823e4f7070454c79",
"metadata": {},
"methods": [
{
"id": "9274c2c249e94e40823e4f7070454c79",
"class": "payment_method",
"method_type": "credit_card",
"last_4": "1111",
"card_type": "visa",
"card_exp_month": 8,
"card_exp_year": 2018,
"card_owner_name": "Ada Lovelace",
"customer_id": null,
"created_at": "2018-06-18T19:04:43.868Z",
"updated_at": "2018-06-18T19:04:43.939Z",
"address": {
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"country": "USA",
"zip": "68521",
"company": "ABC Corp"
}
},
{
"id": "1d30a8e6b6db4b4aa84fd9c1939ad785",
"class": "payment_method",
"method_type": "bank_account",
"bank_account_number_last_4": "************6789",
"bank_routing_number": "104000058",
"bank_account_holder_first_name": "Ada",
"bank_account_holder_last_name": "Lovelace",
"bank_account_holder_full_name": "Ada Lovelace",
"bank_account_type": "checking",
"customer_id": null,
"created_at": "2018-06-18T19:04:44.026Z",
"updated_at": "2018-06-18T19:04:44.040Z",
"company": "ABC Corp",
"address": {
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"country": "USA",
"zip": "68521",
"company": "ABC Corp"
}
}
]
}
],
"meta": {
"limit": 25,
"offset": 0,
"total_results": 1
}
}
GET /customers
Gets a list of the most recently created customers.
Parameters
Parameter | Details |
---|---|
limit | Maximum number of customers to return. |
offset | Event index to begin returning customers from, useful for pagination. |
Error Codes
Error Code | Message |
---|---|
1800 | Limit ‘limit’ is not a positive integer. |
1801 | Offset ‘offset’ is not a positive integer. |
1802 | Limit ‘limit’ is greater than 100. |
Update a Customer
UPDATE A CUSTOMER
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\n \"company\": \"ABC Updated\",\n \"first_name\": \"John Updated\",\n \"last_name\": \"Doe Updated\",\n \"address_1\": \"123 Apple Street Updated\",\n \"address_2\": \"Apt 101 Updated\",\n \"city\": \"Lincoln Updated\",\n \"state\": \"KS\",\n \"zip\": \"68510\",\n \"phone\": \"402-437-1111\",\n \"fax\": \"402-437-2222\",\n \"website\": \"http://www.example.com/updated\",\n \"country\": \"USA\",\n \"email\": \"test@example.com\",\n \"token\": \"01fc630146\",\n \"cvv\": \"999\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v1,customers,c07b10", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v1/customers/c07b10");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\n \"company\": \"ABC Updated\",\n \"first_name\": \"John Updated\",\n \"last_name\": \"Doe Updated\",\n \"address_1\": \"123 Apple Street Updated\",\n \"address_2\": \"Apt 101 Updated\",\n \"city\": \"Lincoln Updated\",\n \"state\": \"KS\",\n \"zip\": \"68510\",\n \"phone\": \"402-437-1111\",\n \"fax\": \"402-437-2222\",\n \"website\": \"http://www.example.com/updated\",\n \"country\": \"USA\",\n \"email\": \"test@example.com\",\n \"token\": \"01fc630146\",\n \"cvv\": \"999\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/customers/c07b10")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\n \"company\": \"ABC Updated\",\n \"first_name\": \"John Updated\",\n \"last_name\": \"Doe Updated\",\n \"address_1\": \"123 Apple Street Updated\",\n \"address_2\": \"Apt 101 Updated\",\n \"city\": \"Lincoln Updated\",\n \"state\": \"KS\",\n \"zip\": \"68510\",\n \"phone\": \"402-437-1111\",\n \"fax\": \"402-437-2222\",\n \"website\": \"http://www.example.com/updated\",\n \"country\": \"USA\",\n \"email\": \"test@example.com\",\n \"token\": \"01fc630146\",\n \"cvv\": \"999\"}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers",
"c07b10"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ company: 'ABC Updated',
first_name: 'John Updated',
last_name: 'Doe Updated',
address_1: '123 Apple Street Updated',
address_2: 'Apt 101 Updated',
city: 'Lincoln Updated',
state: 'KS',
zip: '68510',
phone: '402-437-1111',
fax: '402-437-2222',
website: 'http://www.example.com/updated',
country: 'USA',
email: 'test@example.com',
token: '01fc630146',
cvv: '999' }));
req.end();
curl -X POST 'https://api.paymentspring.com/api/v1/customers/62a987ed39' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d'{
"company": "ABC Updated",
"first_name": "John Updated",
"last_name": "Doe Updated",
"address_1": "123 Apple Street Updated",
"address_2": "Apt 101 Updated",
"city": "Lincoln Updated",
"state": "KS",
"zip": "68510",
"phone": "402-437-1111",
"fax": "402-437-2222",
"website": "http://www.example.com/updated",
"country": "USA",
"email": "test@example.com",
"token": "01fc630146",
"cvv": "999"
}'
Expected Response Data:
{
"id": "62a987ed39",
"created_at": "2017-11-17T19:18:39Z",
"updated_at": "2017-11-17T19:18:39Z",
"class": "customer",
"card_owner_name": null,
"address_1": "123 Apple Street Updated",
"address_2": "Apt 101 Updated",
"company": "ABC Updated",
"country": "USA",
"fax": "402-437-2222",
"first_name": "John Updated",
"last_name": "Doe Updated",
"email": "test@example.com",
"city": "Lincoln Updated",
"phone": "402-437-1111",
"zip": "68510",
"state": "KS",
"website": "http://www.example.com/updated",
"card_type": "visa",
"last_4": "1111",
"card_exp_month": 5,
"card_exp_year": 2022,
"default_receipts": false,
"default_receipt_template_id": null,
"bank_account_number_last_4": null,
"bank_routing_number": null,
"bank_account_holder_first_name": null,
"bank_account_holder_last_name": null,
"bank_account_type": null,
"default_method_id": "a3be44be96eb4ea091f19228db1689e6",
"methods": [
{
"id": "8414465fbd884b38959e3c80f9c7c1a1",
"class": "payment_method",
"method_type": "bank_account",
"bank_account_number_last_4": null,
"bank_routing_number": null,
"bank_account_holder_first_name": null,
"bank_account_holder_last_name": null,
"bank_account_type": null,
"customer_id": null,
"created_at": "2017-11-17T19:18:39.853Z",
"updated_at": "2017-12-01T20:23:18.878Z",
"company": "ABC Updated",
"address": {
"address_1": "123 Apple Street Updated",
"address_2": "Apt 101 Updated",
"city": "Lincoln Updated",
"state": "KS",
"country": "USA",
"zip": "68510",
"company": "ABC Updated"
}
},
{
"id": "a3be44be96eb4ea091f19228db1689e6",
"class": "payment_method",
"method_type": "credit_card",
"last_4": "1111",
"card_type": "visa",
"card_exp_month": "5",
"card_exp_year": "2022",
"card_owner_name": null,
"csc_check": "0",
"customer_id": null,
"created_at": "2017-11-17T19:18:39.808Z",
"updated_at": "2017-12-01T20:23:18.858Z",
"address": {
"address_1": "123 Apple Street Updated",
"address_2": "Apt 101 Updated",
"city": "Lincoln Updated",
"state": "KS",
"country": "USA",
"zip": "68510",
"company": "ABC Updated"
}
}
]
}
POST /customers/:id
Update a customer’s information.
Parameters
Parameter | Details |
---|---|
company | Name of company to be saved on the record. |
first_name | First name to be saved on the record. |
last_name | Last name to be saved on the record. |
address_1 | Address 1 to be saved on the record. |
address_2 | Address 2 to be saved on the record. |
city | City to be saved on the record. |
state | State or province to be saved on the record (two character abbreviation only). |
zip | Zip or postal code to be saved on the record. This field is required if merchant AVS Verification is enabled for credit card transactions. |
phone | Phone number to be saved on the record. |
fax | Fax number to be saved on the record. |
website | Website to be saved on the record. |
country | Country to be saved on the record. |
Email address to be saved on the record. | |
metadata | JSON object literal (or JSON encoded string) with key-value pairs. |
token | Token to be saved on the record; this will override the default payment method |
cvv | Card Verification Value (also called csc). This field is required if merchant cvv verification is enabled for credit card transactions. |
Error Codes
Error Code | Message |
---|---|
17001 | Could not find the specified customer. |
81602 | Fax field is too long. |
81603 | First name is too long. |
81604 | Last name is too long. |
81606 | Phone number is too long. |
81607 | Website is too long. |
81608 | Custom ID is already taken. |
81609 | Customer email is invalid. |
81609 | Please use the two-character state abbreviation. |
23489 | Could not find specified token for merchant. |
82004 | Card verification failed. |
CPCVV1 | Card verification failed. Card Issuer does not support CVV, while the Merchant requires it. |
CPCVV2 | Card verification failed. Please double check your card verification code. |
AVSZIP404 | Merchant requires zip code for AVS verification. |
Delete a Customer
DELETE A CUSTOMER
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("DELETE", "api,v1,customers,62a987ed39", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("http://api.paymentspring.com/api/v1/customers/62a987ed39");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("http://api.paymentspring.com/api/v1/customers/62a987ed39")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Delete.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "DELETE",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers",
"62a987ed39"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl -u private-api-key:
https://api.paymentspring.com/api/v1/customers/62a987ed39
Expected Response Data:
{
"success": true
}
DELETE /customers
Delete a customer by using their ID number.
Parameters
Parameter | Details |
---|---|
id | ID of the customer you want to retrieve. |
Error Codes
Error Code | Message |
---|---|
17001 | Could not find the specified customer. |
Search Customers
SEARCH CUSTOMERS
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "search_term=john"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v1,customers,search?search_term=john&page=1", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v1/customers/search?search_term=john&page=1");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.POST);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/customers/search?search_term=john&page=2")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request.basic_auth 'your-private-api-key', ''
request["Content-Type"] = 'application/json'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers",
"search?search_term=john&page=2"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl -X POST 'https://api.paymentspring.com/api/v1/customers/search \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"search_term": "john",
"page": 1
}'
Expected Response Data:
{
"list": [
{
"id": "cefc03",
"created_at": "2018-06-18T19:04:36Z",
"updated_at": "2018-06-18T19:04:36Z",
"class": "customer",
"card_owner_name": "Ada Lovelace",
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"company": "ABC Corp",
"country": "USA",
"fax": "402-437-0100",
"first_name": "John",
"last_name": "Doe",
"email": "test@example.com",
"city": "Lincoln",
"phone": "402-437-0127",
"zip": "68521",
"state": "NE",
"website": "http://www.example.com",
"card_type": "visa",
"last_4": "1111",
"card_exp_month": 8,
"card_exp_year": 2018,
"default_receipts": false,
"default_receipt_template_id": null,
"bank_account_number_last_4": "************6789",
"bank_routing_number": "104000058",
"bank_account_holder_first_name": "Ada",
"bank_account_holder_last_name": "Lovelace",
"bank_account_holder_full_name": "Ada Lovelace",
"bank_account_type": "checking",
"default_method_id": "9274c2c249e94e40823e4f7070454c79",
"metadata": {},
"methods": [
{
"id": "9274c2c249e94e40823e4f7070454c79",
"class": "payment_method",
"method_type": "credit_card",
"last_4": "1111",
"card_type": "visa",
"card_exp_month": 8,
"card_exp_year": 2018,
"card_owner_name": "Ada Lovelace",
"customer_id": null,
"created_at": "2018-06-18T19:04:43.868Z",
"updated_at": "2018-06-18T19:04:43.939Z",
"address": {
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"country": "USA",
"zip": "68521",
"company": "ABC Corp"
}
},
{
"id": "1d30a8e6b6db4b4aa84fd9c1939ad785",
"class": "payment_method",
"method_type": "bank_account",
"bank_account_number_last_4": "************6789",
"bank_routing_number": "104000058",
"bank_account_holder_first_name": "Ada",
"bank_account_holder_last_name": "Lovelace",
"bank_account_holder_full_name": "Ada Lovelace",
"bank_account_type": "checking",
"customer_id": null,
"created_at": "2018-06-18T19:04:44.026Z",
"updated_at": "2018-06-18T19:04:44.040Z",
"company": "ABC Corp",
"address": {
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"country": "USA",
"zip": "68521",
"company": "ABC Corp"
}
}
]
}
],
"meta": {
"offset": 0,
"total_results": 1,
"limit": 25
}
}
POST /customers/search
Gets a list of customers who match a name, email address, company name or ID, or for whom your search query appears in the customer's metadata (as a key, as a value, or both).
Parameters
Parameter | Details |
---|---|
search_term | Customer name, company name or ID to search on. |
page | Page of search results to return (page size is 25). Invalid page numbers will return page 1. |
Error Codes
Error Code | Message |
---|---|
20000 | Search term must be at least 3 characters. |
Recurring Billings
Retry a Billing
RETRY A BILLING
Sample Request:
import http.client
conn = http.client.HTTPConnection('api,paymentspring,com')
payload = "{ 'id': '9823foid9822dfj' }"
encoded_auth = b64encode(b'private-api-key:').decode('ascii')
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request('POST', 'api,v1,billings,retry', payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode('utf-8'))
var client = new RestClient('https://api.paymentspring.com/api/v1/billings/retry');
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator('username', 'your-private-api-key', 'password', '');
request.AddHeader('Content-Type', 'application/json');
request.AddParameter('undefined', "{ 'id': '9823foid9822dfj' }", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI('https://api.paymentspring.com/api/v1/billings/retry')
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{ 'id': '9823foid9822dfj' }"
response = http.request(request)
puts response.read_body
var http = require('https');
var options = {
'method': 'POST',
'hostname': [
'api',
'paymentspring',
'com'
],
'path': [
'api',
'v1',
'billings',
'retry'
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on('data', function (chunk) {
chunks.push(chunk);
});
res.on('end', function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ id: '9823foid9822dfj' }));
req.end();
curl -X POST 'https://api.paymentspring.com/api/v1/billings/retry' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d "{ 'id': '9823foid9822dfj' }"
Sample Response Data:
{
"id": 000000,
"plan_id": 000000,
"subscription_id": 00000,
"merchant_id": "eftoij8765",
"customer_id": "0976cd",
"transaction_id": "9823049f-roif980we-viosuis",
"transaction_status": "submitted",
"amount": 1000,
"customer_display_name": "983990",
"metadata": "{}",
"created_at": "2018-10-31 02:01:19",
"updated_at": "2021-10-18 20:20:46.0000",
"status": "success",
"parent_id": null
}
POST /billings/retry
Retry a billing with a specified transaction_id.
Parameters
Parameter | Details |
---|---|
id | The transaction_id of the billing to be retried. |
Error Codes
Error Code | Message |
---|---|
10210 | A billing record with the provided transaction id was not found. |
10212 | Cannot retry the specified billing because it is not in failed status. |
Retrieve a Billing
RETRIEVE A BILLING
Sample Request:
import http.client
conn = http.client.HTTPConnection('api,paymentspring,com')
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request('GET', 'api,v1,billings,62a987ed39', headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode('utf-8'))
var client = new RestClient('https://api.paymentspring.com/api/v1/billings/62a987ed39');
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator('username', 'your-private-api-key', 'password', '');
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI('https://api.paymentspring.com/api/v1/billings/62a987ed39')
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require('https');
var options = {
'method': 'GET',
'hostname': [
'api',
'paymentspring',
'com'
],
'path': [
'api',
'v1',
'billings',
'62a987ed39'
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on('data', function (chunk) {
chunks.push(chunk);
});
res.on('end', function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl -u private-api-key:
https://api.paymentspring.com/api/v1/billings/62a987ed39
Sample Response Data:
{
"id": 000000,
"plan_id": 000000,
"subscription_id": 00000,
"merchant_id": "eftoij8765",
"customer_id": "0976cd",
"transaction_id": "9823049f-roif980we-viosuis",
"transaction_status": "submitted",
"amount": 1000,
"customer_display_name": "983990",
"metadata": "{}",
"created_at": "2018-10-31 02:01:19",
"updated_at": "2021-10-18 20:20:46.0000",
"status": "success",
"parent_id": null
}
GET /billings/:id
Get a billing by using its transaction_id number.
Parameters
Parameter | Details |
---|---|
transaction_id | transaction_id of the billing you want to retrieve. |
Error Codes
Error Code | Message |
---|---|
11000 | This billing id is not available with your merchant account. |
Payment Methods
Create a Customer Payment Method With a Token
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/customers/6e3d8d/methods' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"token": "1fb1756adb",
"method_type": "credit_card",
"cvv": "999",
"zip": "68521"
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/customers/6e3d8d/methods")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = {
method_type: 'credit_card',
token: '1fb1756adb',
cvv: '999',
zip: '68521'
}.to_json
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/customers/6e3db8/methods");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"method_type\":\"credit_card\", \"token\": \"1fb1756adb\", \"cvv\": \"999\", \"zip\": \"68521\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers",
"6e3db8",
"methods"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ method_type: "credit_card", token: "1fb1756adb", cvv: "999", zip: "68521" }));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/customers/6e3db8/methods")
payload = "{\"method_type\": \"credit_card\", \"token\": \"1fb1756adb\", \"cvv\": \"999\", \"zip\": \"68521\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,customers,6e3db8,methods", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"success": true,
"method": {
"class": "method",
"id": "ec24265321574b8e94d4dd7dee1d73b5",
"method_type": "credit_card",
"last_4": "1111",
"card_type": "visa",
"card_exp_month": 8,
"card_exp_year": 2018,
"card_owner_name": "Ada Lovelace",
"csc_check": "0",
"created_at": "2017-10-30T13:17:56.403Z",
"updated_at": "2017-10-30T13:17:56.425Z",
"address": {
"address_1": null,
"address_2": null,
"city": null,
"state": null,
"country": null,
"zip": "68521",
"company": null
}
}
}
POST /customers/:customer_id/methods
Creates a method using a token. This method can then be used to make customer payments.
Parameters
Parameter | Details |
---|---|
customer_id | The unique identifier of the customer to add a method. |
method_type | The type of method to create (credit_card or bank_account ). This should be the same as the type of token created. |
token | The unique identifier of the token to create the payment method. |
cvv | Card Verification Value (also called csc). This field is required if merchant cvv verification is enabled for credit card transactions. |
zip | Zip or postal code to be saved with the payment method. This field is required if merchant AVS Verification is enabled for credit card transactions. |
Error Codes
Error Code | Message |
---|---|
17001 | Could not find the specified customer. |
82001 | Method type not recognized. |
23489 | Could not find specified token for merchant. |
82004 | Card verification failed. |
CPCVV1 | Card verification failed. Card Issuer does not support CVV, while the Merchant requires it. |
CPCVV2 | Card verification failed. Please double check your card verification code. |
AVSZIP404 | Merchant requires zip code for AVS verification. |
List a Customer's Payment Methods
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/customers/6e3d8d/methods -XGET
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("GET", "api,v1,customers,6a3d8d,methods", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v1/customers/6e3d8d/methods/93aff8a9d49a403eb6d72328f277b3e5");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/customers/6e3d8d/methods")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers",
"6e3d8d",
"methods"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
Expected Response Data:
{
"success": true,
"list": [
{
"class": "method",
"id": "ec24265321574b8e94d4dd7dee1d73b5",
"method_type": "credit_card",
"last_4": "1111",
"card_type": "visa",
"card_exp_month": 8,
"card_exp_year": 2018,
"card_owner_name": "Ada Lovelace",
"created_at": "2017-10-30T13:17:56.403Z",
"updated_at": "2017-10-30T13:17:56.425Z",
"address": {
"address_1": null,
"address_2": null,
"city": null,
"state": null,
"country": null,
"zip": null,
"company": null
}
},
{
"class": "method",
"id": "93aff8a9d49a403eb6d72328f277b3e5",
"method_type": "bank_account",
"created_at": "2017-10-30T13:17:13.426Z",
"updated_at": "2017-10-30T13:17:13.453Z",
"bank_account_number_last_4": null,
"bank_routing_number": null,
"bank_account_holder_first_name": null,
"bank_account_holder_last_name": null,
"bank_account_type": null,
"company": null
}
]
}
GET /customers/:customer_id/methods
Gets a list of customer payment methods.
Parameters
Parameter | Details |
---|---|
customer_id | The unique identifier of the customer to list payment methods. |
Error Codes
Error Code | Message |
---|---|
17001 | Could not find the specified customer. |
Get a Customer Method
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/customers/6e3d8d/methods/93aff8a9d49a403eb6d72328f277b3e5
-XGET\
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("GET", "api,v1,customers,6a3d8d,methods,93aff8a9d49a403eb6d72328f277b3e5", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v1/customers/6e3d8d/methods/93aff8a9d49a403eb6d72328f277b3e5");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/customers/6e3d8d/methods/93aff8a9d49a403eb6d72328f277b3e5")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers",
"6e3d8d",
"methods",
"93aff8a9d49a403eb6d72328f277b3e5"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
Expected Response Data:
{
"success": true,
"method": {
"class": "method",
"id": "93aff8a9d49a403eb6d72328f277b3e5",
"method_type": "bank_account",
"created_at": "2017-10-30T13:17:13.426Z",
"updated_at": "2017-10-30T13:17:13.453Z",
"bank_account_number_last_4": null,
"bank_routing_number": null,
"bank_account_holder_first_name": null,
"bank_account_holder_last_name": null,
"bank_account_type": null,
"company": null
}
}
GET /customers/:customer_id/methods/:method_id
Get a specific customer payment method.
Parameters
Parameter | Details |
---|---|
customer_id | The unique identifier of the customer to fetch a payment method. |
method_id | The unique identifier of the payment method to fetch. |
Error Codes
Error Code | Message |
---|---|
17001 | Could not find the specified customer. |
82002 | Could not find the specified method. |
Delete a Customer Payment Method
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/customers/6e3d8d/methods/93aff8a9d49a403eb6d72328f277b3e5
-XDELETE
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("DELETE", "api,v1,customers,62a987ed39", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("http://api.paymentspring.com/api/v1/customers/6e3d8d/methods/93aff8a9d49a403eb6d72328f277b3e5");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("http://api.paymentspring.com/api/v1/customers/6e3d8d/methods/93aff8a9d49a403eb6d72328f277b3e5")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Delete.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "DELETE",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers",
"6e3d8d",
"methods",
"93aff8a9d49a403eb6d72328f277b3e5"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
Expected Response Data:
{
"success": true
}
DELETE /customers/:customer_id/methods/:method_id
Delete a specific customer payment method.
Parameters
Parameter | Details |
---|---|
customer_id | The unique identifier of the customer. |
method_id | The unique identifier of the payment method to delete. |
Error Codes
Error Code | Message |
---|---|
17001 | Could not find the specified customer. |
82002 | Could not find the specified method. |
82003 | Cannot delete a customer's default payment method. |
10208 | Method must not be in use by a subscription when deleted. |
17104 | Method must not have unbilled scheduled payments when deleted. |
18010 | An error occurred while attempting to delete the payment method. |
Update a Customer Payment Method
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/customers/6e3d8d/methods/93aff8a9d49a403eb6d72328f277b3e5' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"token": "1fb1756adb",
"cvv": "999",
"zip": "68521"
}'
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\"token\": \"1fb1756adb\", \"cvv\": \"999\", \"zip\": \"68521\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v1,customers,6e3d8d,methods,93aff8a9d49a403eb6d72328f277b3e5", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v1/customers/6e3d8d/methods/93aff8a9d49a403eb6d72328f277b3e5");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"token\": \"1fb1756adb\", \"cvv\": \"999\", \"zip\": \"68521\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/customers/6e3d8d/methods/93aff8a9d49a403eb6d72328f277b3e5")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = { token: '1fb1756adb', cvv: '999', zip: '68521' }.to_json
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"customers",
"6e3d8d",
"methods",
"93aff8a9d49a403eb6d72328f277b3e5"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify(
{
"token": "1fb1756adb",
"cvv": "999",
"zip": "68521"
}
));
req.end();
{
"success": true,
"method": {
"class": "method",
"id": "ec24265321574b8e94d4dd7dee1d73b5",
"method_type": "credit_card",
"last_4": "1111",
"card_type": "visa",
"card_exp_month": 8,
"card_exp_year": 2018,
"card_owner_name": "Ada Lovelace",
"csc_check": "0",
"created_at": "2017-10-30T13:17:56.403Z",
"updated_at": "2017-10-30T13:17:56.425Z",
"address": {
"address_1": null,
"address_2": null,
"city": null,
"state": null,
"country": null,
"zip": "68521",
"company": null
}
}
}
POST /customers/:customer_id/methods/:method_id
Updates a customer payment method using a token.
Parameters
Parameter | Details |
---|---|
customer_id | The unique identifier of the customer to add a method. |
method_id | The unique identifier of the payment method to delete. |
token | The unique identifier of the token to update the payment method. |
cvv | Card Verification Value (also called csc). This field is required if merchant cvv verification is enabled for credit card transactions. |
zip | Zip or postal code to be saved with the payment method. This field is required if merchant AVS Verification is enabled for credit card transactions. |
Error Codes
Error Code | Message |
---|---|
17001 | Could not find the specified customer. |
82002 | Could not find the specified method. |
23489 | Could not find specified token for merchant. |
82004 | Card verification failed. |
CPCVV1 | Card verification failed. Card Issuer does not support CVV, while the Merchant requires it. |
CPCVV2 | Card verification failed. Please double check your card verification code. |
AVSZIP404 | Merchant requires zip code for AVS verification. |
Charge a Customer's Payment Method
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/charge' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"customer_id": "6e3d86",
"amount": 2000,
"method_id": "c24265321574b8e94d4dd7dee1d73b5"
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/charge")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = {
customer_id: "4e49fb",
method_id: "c24265321574b8e94d4dd7dee1d73b5",
amount: 2001,
metadata: {
bar: "baz"
}
}.to_json
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/charge");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"customer_id\": \"4e49fb\",\"method_id\":\"c24265321574b8e94d4dd7dee1d73b5\",\"amount\": 2001,\"metadata\": {\"bar\": \"baz\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"charge"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify(
{
customer_id: '4e49fb',
method_id: "c24265321574b8e94d4dd7dee1d73b5",
amount: 2001,
metadata: {
bar: 'baz'
}
}
));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/charge)
payload = "{\"customer_id\": \"4e49fb\",\"method_id\": \"c24265321574b8e94d4dd7dee1d73b5\", \"amount\": 2001,\"metadata\": {\"bar\": \"baz\"}}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,charge", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "transaction",
"id": "14ae20e779b94378ac7d1be40cb4d61a",
"payment_method": "credit_card",
"created_at": "2017-11-21T16:14:59.701Z",
"merchant_id": "5bcadf893357_test",
"amount_authorized": 2000,
"amount_refunded": 0,
"amount_settled": 2000,
"amount_failed": 0,
"transaction_type": "sale",
"reference_number": "812079",
"description": null,
"card_type": "discover",
"card_number": "************1111",
"card_exp_month": "1",
"card_exp_year": "2020",
"authorized": true,
"settled": true,
"refunded": false,
"voided": false,
"system_trace": null,
"status": "SETTLED",
"customer_id": "62a987ed39",
"receipt": {},
"company": "ABC Corp",
"website": "http://www.example.com",
"card_owner_name": "Ada Lovelace",
"email_address": "test@example.com",
"email": "test@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"address_1": "123 Apple Street",
"address_2": "Apt 101",
"city": "Lincoln",
"state": "NE",
"zip": "68521",
"country": "USA",
"phone": "402-437-0127",
"fax": "402-437-0100",
"csc_check": "0",
"avs_address_check": "0",
"source": "web",
"successful": true,
"metadata": {},
"error_message": null,
"account_holder_name": "Ada Lovelace",
"recurring": false,
"processed_at": null,
"refunds": []
}
POST /charge
If you’ve created a customer record with at least one payment method, you can
then charge a specified customer payment method by providing a method_id
.
Parameters
Parameter | Details |
---|---|
customer_id | ID of saved customer. |
amount | Amount in cents. |
send_receipt | Boolean that will override your merchant and this customer’s settings for whether to send a receipt. |
receipt_template_id | ID for a receipt template that will override your merchant and this customer’s for which receipt template to use. |
description | text description for the transaction |
method_id | ID of the payment method you'd like to charge (if not present, will charge the default payment method of the customer). |
metadata | JSON object literal with key-value pairs; these will be displayed as "custom fields" in the dashboard and as metadata in the serialized charge. Any custom fields supplied here will be merged with whatever custom fields exist on the customer. |
Error Codes
Error Code | Message |
---|---|
34792 | Could not find payment token with id provided. |
99819 | Amount should be a positive number in cents. |
48291 | One or more parameters were missing. Please make sure you enter a correct customer_id and amount (in cents) and retry the transaction. |
59112 | Amount must be sent as a number of cents greater than zero. |
34798 | Please specify a valid customer_id for this charge. |
69005 | You need to specify an email_address with this transaction to send a receipt. |
69006 | The specified email address for the receipt is invalid. Please specify a valid email address. |
Account Updater
Credit card information is often subject to changes such as upgrades for customers, expiration dates, data breaches, and anti-fraud measures.
For a smooth payment process, it is essential to have the most recent customer data. Unfortunately, reaching out to each customer individually to update their information could be a daunting task, draining precious time and financial resources.
With that in mind, Nelnet Payment Services provides an account updater service that allows for updating customer data in batches of payment methods of any size.
Submit a list of payment methods for update
Submit a list of payment methods for update
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = '''{
"payment_methods": {
"0": {
"payment_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"card_exp_month": 1,
"card_exp_year": 2025
},
"1": {
"payment_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"card_exp_month": 3,
"card_exp_year": 2024
},
"2": {
"payment_id": "cccccccccccccccccccccccccccccccc",
"card_exp_month": 12,
"card_exp_year": 2030
}
}
}'''
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,tokens,update", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var payload = @"{
""payment_methods"": {
""0"": {
""payment_id"": ""aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"",
""card_exp_month"": 1,
""card_exp_year"": 2025
},
""1"": {
""payment_id"": ""bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"",
""card_exp_month"": 3,
""card_exp_year"": 2024
},
""2"": {
""payment_id"": ""cccccccccccccccccccccccccccccccc"",
""card_exp_month"": 12,
""card_exp_year"": 2030
}
}
}";
var client = new RestClient("https://api.paymentspring.com/api/v1/tokens/update");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", payload, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/tokens/update")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = {
payment_methods: {
"0": {
payment_id: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
card_exp_month: 1,
card_exp_year: 2025
},
"1": {
payment_id: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
card_exp_month: 3,
card_exp_year: 2024
},
"2": {
payment_id: "cccccccccccccccccccccccccccccccc",
card_exp_month: 12,
card_exp_year: 2030
}
}
}.to_json
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
method: "POST",
hostname: [
"api",
"paymentspring",
"com"
],
path: [
"api",
"v1",
"tokens",
"update"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify(
{
payment_methods: {
0: {
payment_id: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
card_exp_month: 1,
card_exp_year: 2025
},
1: {
payment_id: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
card_exp_month: 3,
card_exp_year: 2024
},
2: {
payment_id: "cccccccccccccccccccccccccccccccc",
card_exp_month: 12,
card_exp_year: 2030
}
}
}
));
req.end();
curl -X POST 'https://api.paymentspring.com/api/v1/tokens/update' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"payment_methods": {
"0": {
"payment_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"card_exp_month": 1,
"card_exp_year": 2025
},
"1": {
"payment_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"card_exp_month": 3,
"card_exp_year": 2024
},
"2": {
"payment_id": "cccccccccccccccccccccccccccccccc",
"card_exp_month": 12,
"card_exp_year": 2030
}
}
}'
Expected Response Data:
{
"id": "a0000000000000000000000000000001",
"class": "accountupdater",
"payment_methods": {
"accepted": {
"0": {
"payment_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"card_exp_month": 1,
"card_exp_year": 2025,
"result": {
"status": "Received"
}
},
"1": {
"payment_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"card_exp_month": 3,
"card_exp_year": 2024,
"result": {
"status": "Received"
}
},
"2": {
"payment_id": "cccccccccccccccccccccccccccccccc",
"card_exp_month": 12,
"card_exp_year": 2030,
"result": {
"status": "Received"
}
}
}
}
}
Response containing update errors:
{
"id": "e0000000000000000000000000000001",
"class": "accountupdater",
"payment_methods": {
"rejected": {
"0": {
"payment_id": 150000,
"card_exp_month": 8,
"card_exp_year": 2023,
"result": {
"status": "Fail",
"errors": [
{
"code": "122001",
"message": "Invalid payment ID."
}
]
}
},
"1": {
"payment_id": "8f2a570d4605498399b3752870c1df93",
"card_exp_month": 12,
"card_exp_year": 0,
"result": {
"status": "Fail",
"errors": [
{
"code": "122002",
"message": "Invalid card expiration month/year"
}
]
}
},
"2": {
"payment_id": "347ee36dd2b04fa0bac953963e5e70e6",
"card_exp_month": 13,
"card_exp_year": 2026,
"result": {
"status": "Fail",
"errors": [
{
"code": "122002",
"message": "Invalid card expiration month/year"
}
]
}
},
"3": {
"payment_id": "00000000000000000000000000000000",
"card_exp_month": 10,
"card_exp_year": 2030,
"result": {
"status": "Fail",
"errors": [
{
"code": "122003",
"message": "Unable to find payment method information. Please use a different payment ID."
}
]
}
}
}
}
}
POST /tokens/update
Submits a batch of payment methods for the account updater review process. Restricted to existing tokenized credit cards
Parameters
Parameter | Details |
---|---|
payment_methods | The main request object. It should contain any number of numerically indexed objects, each one representing an individual payment method. |
payment_id | The unique identifier of the payment method to update. |
card_exp_month | Expiration month of card as a number. January = 1, February = 2, etc. |
card_exp_year | Expiration year of card (example: 2018). |
Error Codes
Error Code | Message |
---|---|
122000 | Failed to process payment method updates. Please try again later. |
122001 | Invalid payment ID. |
122002 | Invalid card expiration month/year. |
122003 | Unable to find payment method information. Please use a different payment ID. |
122004 | The request body should contain a numerically keyed 'payment_methods' object. |
122005 | Unable to update this payment method. Please contact client services for assistance. |
Plans
Create a plan
CREATE A PLAN
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/plans' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"frequency": "daily",
"name": "gold",
"amount": 50000,
"callback_url": "http://api.myapi.com/plan_billed"
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/plans")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{ \"frequency\": \"weekly\", \"name\": \"gold\", \"amount\": 50000, \"day\": 4}"
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/plans");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{ \"frequency\": \"weekly\", \"name\": \"gold\", \"amount\": 50000, \"day\": 4}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"plans"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ frequency: 'weekly', name: 'gold', amount: 50000, day: 4 }));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/plans")
payload = "{ \"frequency\": \"weekly\", \"name\": \"gold\", \"amount\": 50000, \"day\": 4}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "undefined", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "plan",
"id": 1,
"name": "gold",
"merchant_id": "2a3478b8e320_test",
"frequency": "daily",
"day": "",
"amount": 50000,
"callback_url": "http://api.myapi.com/plan_billed",
"email_reports": null,
"receipt_template_id": ""
}
POST /plans
Create a plan for recurring billing.
Parameters
Parameter | Details |
---|---|
frequency | The frequency of the billing for the plan. Should be one of ‘daily’, ‘weekly’, ‘monthly’, ‘quarterly’, ‘yearly’, 'biannually'. |
name | The desired name for the new plan. |
amount | The number of cents for which to bill the plan every billing period. |
day | An integer or a hash describing when in the week, month or year the plan is billed. For daily plans, this is not required. For weekly plans, should be an integer between 1 and 7 (indicating Sunday through Saturday). For monthly plans, should be either an integer between 1 and 31, or a JSON-encoded hash with keys week (between 1 and 5, inclusive) and day (between 1 and 7, inclusive) to indicate a day of the week (e.g. {‘week’:2,’day’:5} to bill on the second Thursday of every month). For quarterly plans, should be a JSON-encoded hash with keys month (between 1 and 3, inclusive) and day (between 1 and 31, inclusive) to indicate a day of a month in the quarter (e.g. {‘month’:2,’day’:5} to bill on the fifth day of the second month every quarter). For yearly plans, should be either an integer between 1 and 366, or a JSON-encoded hash with keys month (between 1 and 12, inclusive) and day (between 1 and 31, inclusive) to indicate a day of the month (e.g. {‘month’:5,’day’:15} to bill on May 15 every year). For biannually (twice a year) plans, should be a JSON-encoded hash with keys month (between 1 and 6, inclusive) and day (between 1 and 31, inclusive) (e.g. {‘month’:1,’day’:15} to bill twice a year on January 15 and June 15). |
callback_url | A URL for the service to post to when a recurring billing is completed. |
email_reports | A boolean saying whether to email billing reports whenever this plan bills. Defaults to false. |
Error Codes
Error Code | Message | Deprecated |
---|---|---|
10000 | Amount must be an integer greater than 0. | |
10001 | Invalid frequency. | |
10002 | Weekly frequency: day must be an integer between 1 and 7. | |
10003 | Monthly frequency: day must be an integer or a hash. | |
10004 | Monthly frequency: day integer must be between 1 and 31. | |
10005 | Monthly frequency: day hash must have :week between 1 and 5, and :day between 1 and 7. | |
10006 | Yearly frequency: day must be an integer or hash. | |
10007 | Yearly frequency: day integer must be between 1 and 366. | |
10008 | Yearly frequency: day hash must have :month between 1 and 12, :day between 1 and 31. | |
10009 | Plan must have a name. | |
10012 | A plan with that name already exists. | |
10014 | You have registered 100 plans. Please delete one or more to make room for the new plan.= | |
10075 | Weekly frequency: day hash must have :day between 1 and 7 and :interval greater than 0 | |
10076 | Quarterly frequency: day Hash must have :month between 1 and 3, and :day between 1 and 31. | |
10077 | Biannually frequency: day Hash must have :month between 1 and 6, and :day between 1 and 31. | |
10015 | Quarterly frequency: day hash must have :month between 1 and 3, and :day between 1 and 31. | Deprecated |
10015 | Biannually frequency: day Hash must have :month between 1 and 6, and :day between 1 and 31. | Deprecated |
10016 | Quarterly frequency: day must be a hash. | Deprecated |
10016 | Biannually frequency: day must be a Hash. | Deprecated |
Get a Plan
GET A PLAN
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/plans/1
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/plans/plan_id1")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/plans/plan_id1");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"plans",
"plan_id1"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/plans")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "plan_id1", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "plan",
"id": 1,
"name": "gold",
"merchant_id": "5bcadf893357_test",
"frequency": "daily",
"day": "",
"amount": 50000,
"callback_url": "http://api.myapi.com/plan_billed",
"email_reports": null,
"receipt_template_id": ""
}
GET /plans/:id
Gets basic detail for a plan.
Parameters
Parameter | Details |
---|---|
id | ID of the plan you want to fetch. |
Error Codes
Error Code | Message |
---|---|
10010 | This plan ID is not available for your merchant account. |
Get All Plans
GET ALL PLANS
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/plans
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/plans")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/plans");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"plans"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/plans")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "undefined", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"list": [
{
"class": "plan",
"id": 2,
"name": "silver",
"merchant_id": "2a3478b8e320_test",
"frequency": "daily",
"day": "",
"amount": 5000,
"callback_url": null
},
{
"class": "plan",
"id": 4,
"name": "gold",
"merchant_id": "2a3478b8e320_test",
"frequency": "daily",
"day": "",
"amount": 50000,
"callback_url": null
},
{
"class": "plan",
"id": 5,
"name": "bronze",
"merchant_id": "2a3478b8e320_test",
"frequency": "monthly",
"day": 15,
"amount": 5000,
"callback_url": null
}
]
}
GET /plans
Gets basic details for all plans.
Parameters
Parameter | Details |
---|
Get Paginated Plans
GET PAGINATED PLANS
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/plans?page=1&items=25
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/plans?page=1&items=25")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/plans?page=1&items=25");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
async getPlans(page, items) {
const res = await fetch('api/v1/plans?page=' + page + '&items=' + items);
return res.json();
}
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/plans?page=1&items=25")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "undefined", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"data": [
{
"class": "plan",
"id": 2,
"name": "silver",
"merchant_id": "2a3478b8e320_test",
"frequency": "daily",
"day": "",
"amount": 5000,
"callback_url": null
},
{
"class": "plan",
"id": 4,
"name": "gold",
"merchant_id": "2a3478b8e320_test",
"frequency": "daily",
"day": "",
"amount": 50000,
"callback_url": null
},
{
"class": "plan",
"id": 5,
"name": "bronze",
"merchant_id": "2a3478b8e320_test",
"frequency": "monthly",
"day": 15,
"amount": 5000,
"callback_url": null
}
],
"meta":
{
"count": 26,
"page": 1,
"items": 25,
"pages": 2,
"last": 2,
"from": 1,
"to": 25,
"prev": null,
"next": 2,
"series": [
"1"
]
}
}
GET /plans
Gets basic details for all plans with pagination.
Parameters
Parameter | Details |
---|---|
page | The page of data you are looking for starting from index 1 |
items | The number of items you would like on each page |
Delete a Plan
DELETE A PLAN
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/plans/1
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/plans/plan_id1")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Delete.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/plans/plan_id1");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"plans",
"plan_id1"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/plans")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "plan_id1", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"success": true
}
DELETE /plans/:id
Delete a plan by ID.
Parameters
Parameter | Details |
---|---|
id | ID of the plan to delete. |
Error Codes
Error Code | Message |
---|---|
10010 | This plan id is not available for your merchant account. |
Subscribe a Customer
SUBSCRIBE A CUSTOMER
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/plans/436472/subscription/bff79e' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"ends_after": "12",
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/plans/873/subscription/bff79e")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"ends_after\": \"12\"}"
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/plans/873/subscription/bff79e");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"ends_after\":\"12\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"plans",
"873",
"subscription",
"bff79e"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ ends_after: '12' }));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/plans")
payload = "{\"ends_after\": \"12\"}"
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "873,subscription,bff79e", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "subscription",
"id": 8320,
"created_at": "2017-11-20T14:10:34-06:00",
"plan_id": 30825,
"merchant_id": "5bcadf893357_test",
"customer_id": "c73b8f",
"ends_after": 12,
"times_billed": 0,
"frequency": "daily",
"day": "",
"amount": 50000,
"next_billing": "2017-11-21T00:00:00-06:00",
"receipt_template_id": "",
"charge_bank_account": false,
"method_id": ""
}
SUBSCRIBE A CUSTOMER AND BILLING IMMEDIATELY
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/plans/436472/subscription/bff79e' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"ends_after": "12",
"bill_immediately": true
}'
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/plans/873/subscription/bff79e")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"ends_after\": \"12\", \"bill_immediately\": \"true\"}"
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/plans/873/subscription/bff79e");
var request = new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"ends_after\": \"12\", \"bill_immediately\": \"true\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"plans",
"873",
"subscription",
"bff79e"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ ends_after: '12', bill_immediately: 'true' }));
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/plans")
payload = "{\"ends_after\": \"12\",\"bill_immediately\":\"true\"}"
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "873,subscription,bff79e", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "subscription",
"id": 5,
"created_at": "2013-08-21T11:47:03-05:00",
"plan_id": 5,
"merchant_id": "2a3478b8e320_test",
"customer_id": "bff79e",
"ends_after": 12,
"times_billed": 1,
"frequency": "daily",
"day": "",
"amount": 2000,
"next_billing": "2014-03-13T00:00:00-05:00",
"transaction": {
"id": "bef97eb750",
"class": "transaction",
"created_at": "2014-03-12T18:45:17+00:00",
"status": "SETTLED",
"reference_number": "2275447",
"amount_refunded": 0,
"amount_settled": 2000,
"card_owner_name": "",
"email": "",
"card_number": "************1111",
"card_exp_month": "8",
"card_exp_year": "2016",
"card_type": "visa",
"description": "Recurring billing for silver",
"customer_id": "ab9a54",
"company": "",
"address_1": "",
"address_2": "",
"city": "",
"state": "",
"zip": "",
"country": "",
"phone": "",
"fax": "",
"website": "",
"new_record": false
}
}
POST /plans/:id/subscription/:customer_id
Subscribe a customer to a plan. A customer can be billed for their subscription by credit card or bank account.
Parameters
Parameter | Details |
---|---|
id | The ID of the plan to which to subscribe the customer. |
customer_id | The ID of the customer that is being subscribed. |
ends_after | An integer or a date representing how long the subscription lasts. If an integer, the subscription will end after that many billings. If a date (which must be formatted as a string ‘YYYY-mm-dd’), the subscription will run through that date inclusive. |
frequency | The frequency of the billing for the subscription. Will override the plan’s frequency. Should be one of ‘daily’, ‘weekly’, ‘monthly’, ‘quarterly’, ‘yearly’, 'biannually'. |
amount | The number of cents for which to bill the subscription every billing period. Will override the plan’s amount. |
day | An integer or a hash describing when in the week, month or year the subscription is billed. For daily plans, this is not required. For weekly plans, should be an integer between 1 and 7 (indicating Sunday through Saturday). For monthly plans, should be either an integer between 1 and 31, or a JSON-encoded hash with keys week (between 1 and 5, inclusive) and day (between 1 and 7, inclusive) to indicate a day of the week (e.g. {‘week’:2,’day’:5} to bill on the second Thursday of every month). For yearly plans, should be either an integer between 1 and 366, or a JSON-encoded hash with keys month (between 1 and 12, inclusive) and day (between 1 and 31, inclusive) to indicate a day of the month (e.g. {‘month’:5,’day’:15} to bill on May 15 every year). For quarterly plans, should be a JSON-encoded hash with keys month (between 1 and 3, inclusive) and day (between 1 and 31, inclusive) to indicate a day of a month in the quarter (e.g. {‘month’:2,’day’:5} to bill on the fifth day of the second month every quarter).For biannually (twice a year) plans, should be a JSON-encoded hash with keys month (between 1 and 6, inclusive) and day (between 1 and 31, inclusive) (e.g. {‘month’:1,’day’:15} to bill twice a year on January 15 and June 15). |
bill_immediately | If set to true, the subscription will make the first billing immediately. If this billing fails, the subscription will not be created. |
charge_bank_account | Boolean value that determines if this subscription should charge the customer’s bank account. If false or omitted, this subscription will instead charge the customer’s credit card. |
method_id | UUID of the customer's desired payment method. If none is provided, we use the default payment method. |
send_receipt | If set to true, the customer will receive a receipt with the charge each time the subscription is billed. |
Error Codes
Error Code | Message |
---|---|
10001 | Invalid frequency. |
10002 | Weekly frequency: day must be an integer between 1 and 7. |
10003 | Monthly frequency: day must be an integer or a hash. |
10004 | Monthly frequency: day integer must be between 1 and 31. |
10005 | Monthly frequency: day hash must have :week between 1 and 5, and :day between 1 and 7. |
10006 | Yearly frequency: day must be an integer or hash. |
10007 | Yearly frequency: day integer must be between 1 and 366. |
10008 | Yearly frequency: day hash must have :month between 1 and 12, :day between 1 and 31. |
10010 | This plan ID is not available for your merchant account. |
10200 | ends_after integer must be greater than 0 occurrences. |
10201 | ends_after must be an integer or a time. |
10204 | Customer is already subscribed to this plan. |
10075 | Weekly frequency: day hash must have :day between 1 and 7 and :interval greater than 0 |
10076 | Quarterly frequency: day Hash must have :month between 1 and 3, and :day between 1 and 31. |
10077 | Biannually frequency: day Hash must have :month between 1 and 6, and :day between 1 and 31. |
Unsubscribe a Customer
UNSUBSCRIBE A CUSTOMER
Sample Request:
curl -X DELETE 'https://api.paymentspring.com/api/v1/plans/1/subscription/bff97e' \
-u private-api-key:
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/plans/873/subscription/bff97e")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Delete.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/plans/873/subscription/bff97e");
var request = new RestRequest(Method.DELETE);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "DELETE",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"plans",
"873",
"subscription",
"bff97e"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/plans/")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("DELETE", "873,subscription,bff97e", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"success": true
}
DELETE /plans/:id/subscription/:customer_id
Unsubscribe a customer from a plan. No further billings will be processed.
Parameters
Parameter | Details |
---|---|
id | The ID of the plan to which to unsubscribe the customer. |
customer_id | The ID of the customer that is being unsubscribed. |
Error Codes
Error Code | Message |
---|---|
10010 | This plan id is not available for your merchant account. |
10011 | Could not locate subscription for that customer. |
Subscriptions
Get a Subscription
GET A SUBSCRIPTION
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/subscriptions/plan/b62d5f/customer/b62d5f
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/subscriptions/plan/b62d5f/customer/b62d5f")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/subscriptions/plan/b62d5f/customer/b62d5f");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"subscriptions",
"b62d5f",
"customer",
"b62d5f"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/subscriptions")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "plan,b62d5f,customer,b62d5f", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"class": "subscription",
"id": 17437,
"created_at": "2018-07-24T09:05:03-05:00",
"plan_id": 127456,
"merchant_id": "9ccaa2022007_test",
"customer_id": "b62d5f",
"ends_after": 12,
"times_billed": 0,
"frequency": "weekly",
"day": 4,
"amount": 50000,
"next_billing": "2018-07-25T00:00:00-05:00",
"receipt_template_id": "",
"charge_bank_account": false,
"method_id": "",
"metadata": null
}
GET /subscriptions/plan/:plan_id/customer/:customer_id
Gets details for the subscription for a specific customer and specific plan
Parameters
Parameter | Details |
---|---|
plan_id | The ID of the plan to get subscription details. |
customer_id | The ID of the customer to get subscription details. |
Get All Subscriptions
GET ALL SUBSCRIPTIONS
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/subscriptions
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/subscriptions/")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/subscriptions/");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"subscriptions"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/subscriptions")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"list": [
{
"class": "subscription",
"id": 17437,
"created_at": "2018-07-24T09:05:03-05:00",
"plan_id": 127456,
"merchant_id": "9ccaa2022007_test",
"customer_id": "b62d5f",
"ends_after": 12,
"times_billed": 0,
"frequency": "weekly",
"day": 4,
"amount": 50000,
"next_billing": "2018-07-25T00:00:00-05:00",
"receipt_template_id": "",
"charge_bank_account": false,
"method_id": "",
"metadata": null
}
]
}
GET /subscriptions
Gets details for all subscriptions.
Parameters
Parameter | Details |
---|
Get All Subscriptions For a Plan
GET ALL SUBSCRIPTIONS FOR A PLAN
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/subscriptions/plan/127456
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/subscriptions/plan/127456")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/subscriptions/plan/127456");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"subscriptions",
"127456"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/subscriptions")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "plan,127456", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"list": [
{
"class": "subscription",
"id": 17437,
"created_at": "2018-07-24T09:05:03-05:00",
"plan_id": 127456,
"merchant_id": "9ccaa2022007_test",
"customer_id": "b62d5f",
"ends_after": 12,
"times_billed": 0,
"frequency": "weekly",
"day": 4,
"amount": 50000,
"next_billing": "2018-07-25T00:00:00-05:00",
"receipt_template_id": "",
"charge_bank_account": false,
"method_id": "",
"metadata": null
}
]
}
GET /subscriptions/plan/:plan_id
Gets details for all subscriptions for a given plan.
Parameters
Parameter | Details |
---|---|
plan_id | The ID of the plan to get subscription details. |
page | (Optional) This parameter enables pagination. Passing "1" will retrieve the first page and information on the remaining pages. |
Get All Customer Subscriptions
GET ALL SUBSCRIPTIONS FOR A CUSTOMER
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/subscriptions/customer/b62d5f
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/subscriptions/customer/b62d5f")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var client = new RestClient("https://api.paymentspring.com/api/v1/subscriptions/customer/b62d5f");
var request = new RestRequest(Method.GET);
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"subscriptions",
"customer",
"customer_id"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPConnection("https://api.paymentspring.com/api/v1/subscriptions")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "customer,b62d5f", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"list": [
{
"class": "subscription",
"id": 17437,
"created_at": "2018-07-24T09:05:03-05:00",
"plan_id": 127456,
"merchant_id": "9ccaa2022007_test",
"customer_id": "b62d5f",
"ends_after": 12,
"times_billed": 0,
"frequency": "weekly",
"day": 4,
"amount": 50000,
"next_billing": "2018-07-25T00:00:00-05:00",
"receipt_template_id": "",
"charge_bank_account": false,
"method_id": "",
"metadata": null
}
]
}
GET /subscriptions/customer/:customer_id
Gets details for all subscriptions for a given customer.
Parameters
Parameter | Details |
---|---|
customer_id | The ID of the customer to get subscription details. |
Update a Subscription
Sample Request:
curl --location --request POST 'https://api.paymentspring.com/api/v1/subscriptions/947' \
--header 'Content-Type: application/json' \
-u private-api-key: \
--data-raw '{
method_id: 9c703e9ae95c41628c22dc956bae09c5
amount: 450.55
ends_after: 2022-05-27T05:00:00.000Z
day: 1
frequency: monthly
}'
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\"method_id\": \"9c703e9ae95c41628c22dc956bae09c5\",\"amount\": \"450.55\",\"ends_after\": \"2022-05-27T05:00:00.000Z\"\"day\": \"1\",\"frequency\": \"monthly\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v1,subscriptions,947", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v1/subscriptions/947");
var request new RestRequest(Method.POST);
client.Authenticator = new SimpleAuthenticator("username", "private-api-key", "password", "");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"method_id\": \"9c703e9ae95c41628c22dc956bae09c5\",\"amount\": \"450.55\",\"ends_after\": \"2022-05-27T05:00:00.000Z\"\"day\": \"1\",\"frequency\": \"monthly\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Context);
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/subscriptions/947")
http = Net::HTTP.new(url.host, url.port)
request["Content-Type"] = 'application/json'
request.basic_auth 'private-api-key', ''
request.body = {
method_id : '9c703e9ae95c41628c22dc956bae09c5',
amount : '450.55',
ends_after : '2022-05-27T05:00:00.000Z',
day : '1',
frequency : 'monthly',
}.to_json
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method" : "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"subscriptions",
"947"
],
headers: {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify(
{
"method_id": "9c703e9ae95c41628c22dc956bae09c5",
"amount": "450.55"
"ends_after": "2022-05-27T05:00:00.000Z"
"day": "1"
"frequency": "monthly"
}
));
req.end();
Expected Response Data:
{
"class": "subscription",
"id": 947,
"created_at": "2022-03-28T09:33:38-05:00",
"plan_id": 1169,
"plan_name": "4qi7v4fzejxjvopi62gtg",
"merchant_id": "53d779a6a880_test",
"customer_id": "e5632a",
"ends_after": 12,
"times_billed": 1,
"frequency": "monthly",
"day": 1,
"amount": 45055,
"next_billing": "2022-06-01T00:00:00-05:00",
"send_receipt": null,
"receipt_template_id": null,
"charge_bank_account": false,
"method_id": "9c703e9ae95c41628c22dc956bae09c5",
"metadata": {},
"status": "active"
}
POST /subscriptions/subscription_id
Updates the following fields on an existing subscription:
- ends_after
- frequency
- day
- amount
- next_billing
- method_id
There is a restriction in that you cannot update a subscription within 24hrs of its next_bills_at
time. This is because the next_bills_at
time will be recalculated following an update to the subscription.
Parameters
Parameter | Details |
---|---|
ends_after | An integer or a date representing how long the subscription lasts. If an integer, the subscription will end after that many billings. If a date (which must be formatted as a string ‘YYYY-mm-dd’), the subscription will run through that date inclusive. |
frequency | The frequency of the billing for the subscription. Will override the plan’s frequency. Should be one of ‘daily’, ‘weekly’, ‘monthly’, ‘quarterly’, ‘yearly’, 'biannually'. |
amount | The number of cents for which to bill the subscription every billing period. Will override the plan’s amount. |
day | An integer or a hash describing when in the week, month or year the subscription is billed. For daily plans, this is not required. For weekly plans, should be an integer between 1 and 7 (indicating Sunday through Saturday). For monthly plans, should be either an integer between 1 and 31, or a JSON-encoded hash with keys week (between 1 and 5, inclusive) and day (between 1 and 7, inclusive) to indicate a day of the week (e.g. {‘week’:2,’day’:5} to bill on the second Thursday of every month). For yearly plans, should be either an integer between 1 and 366, or a JSON-encoded hash with keys month (between 1 and 12, inclusive) and day (between 1 and 31, inclusive) to indicate a day of the month (e.g. {‘month’:5,’day’:15} to bill on May 15 every year). For quarterly plans, should be a JSON-encoded hash with keys month (between 1 and 3, inclusive) and day (between 1 and 31, inclusive) to indicate a day of a month in the quarter (e.g. {‘month’:2,’day’:5} to bill on the fifth day of the second month every quarter).For biannually (twice a year) plans, should be a JSON-encoded hash with keys month (between 1 and 6, inclusive) and day (between 1 and 31, inclusive) (e.g. {‘month’:1,’day’:15} to bill twice a year on January 15 and June 15). |
method_id | UUID of the customer's desired payment method. If none is provided, we use the default payment method. |
Error Code
Error Code | Message |
---|---|
10205 | A subscription for that customer and plan was not found. |
10207 | A subscription with that id was not found. |
11200 | A subscription cannot be updated after its ends_after date has passed. |
11201 | A subscription cannot be updated after it has been discarded. |
10001 | Invalid frequency. |
10002 | Weekly frequency: day must be an integer between 1 and 7. |
10003 | Monthly frequency: day must be an integer or a hash. |
10004 | Monthly frequency: day integer must be between 1 and 31. |
10005 | Monthly frequency: day hash must have :week between 1 and 5, and :day between 1 and 7. |
10006 | Yearly frequency: day must be an integer or hash. |
10007 | Yearly frequency: day integer must be between 1 and 366. |
10008 | Yearly frequency: day hash must have :month between 1 and 12, :day between 1 and 31. |
10010 | This plan ID is not available for your merchant account. |
10200 | ends_after integer must be greater than 0 occurrences. |
10201 | ends_after must be an integer or a time. |
10204 | Customer is already subscribed to this plan. |
10075 | Weekly frequency: day hash must have :day between 1 and 7 and :interval greater than 0 |
10076 | Quarterly frequency: day Hash must have :month between 1 and 3, and :day between 1 and 31. |
10077 | Biannually frequency: day Hash must have :month between 1 and 6, and :day between 1 and 31. |
Invoices
Create an Invoice
CREATE AN INVOICE
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,test")
payload = "{\"customer_first_name\":\"John\",\"customer_last_name\":\"Doe\",\"customer_email\":\"test@example.com\",\"customer_address_1\":\"123 Apple Street\",\"customer_address_2\":\"Apt 101\",\"customer_company\":\"ABC Corp\",\"customer_fax\":\"402-437-0100\",\"customer_phone\":\"402-437-0127\",\"customer_city\":\"Lincoln\",\"customer_state\":\"NE\",\"customer_zip\":\"68521\",\"invoice_date\":\"2017-02-04\",\"due_date\":\"2017-04-04\",\"custom_number\": false,\"deliver\": false,\"line_items\": [{\"0\": {\"description\":\"Rockets\",\"unit_price\":111,\"quantity\":7}}],\"tax\": 5788,\"shipping\":\"0\",\"notes\":\"Make sure to read the manual first!\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v1,invoices", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("http://api.paymentspring.com/api/v1/invoices");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.POST);
var json = "{\"customer_first_name\":\"John\",\"customer_last_name\":\"Doe\",\"customer_email\":\"test@example.com\",\"customer_address_1\":\"123 Apple Street\",\"customer_address_2\":\"Apt 101\",\"customer_company\":\"ABC Corp\",\"customer_fax\":\"402-437-0100\",\"customer_phone\":\"402-437-0127\",\"customer_city\":\"Lincoln\",\"customer_state\":\"NE\",\"customer_zip\":\"68521\",\"invoice_date\":\"2017-02-04\",\"due_date\":\"2017-04-04\",\"custom_number\": false,\"deliver\": false,\"line_items\": [{\"0\": \"description\":\"Rockets\",\"unit_price\":111,\"quantity\":7}}],\"tax\": 5788,\"shipping\":\"0\",\"notes\":\"Make sure to read the manual first!\"}";
request.AddParameter("text/json", json, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("http://api.paymentspring.com/api/v1/invoices")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request.basic_auth 'your-private-api-key', ''
request["Content-Type"] = 'application/json'
request.body = {
"customer_first_name" => "John",
"customer_last_name" => "Doe",
"customer_email" => "test@example.com",
"customer_address_1" => "123 Apple Street",
"customer_address_2" => "Apt 101",
"customer_company" => "ABC Corp",
"customer_fax" => "402-437-0100",
"customer_phone" => "402-437-0127",
"customer_city" => "Lincoln",
"customer_state" => "NE",
"customer_zip" => "68521",
"invoice_date" => "2017-02-04",
"due_date" => "2017-04-04",
"custom_number" => false,
"deliver" => false,
"line_items" => [
{
"0" => {
"description" => "Rockets",
"unit_price":111,
"quantity":7
}
}
],
"tax" => 5788,
"shipping" => "0",
"notes" => "Make sure to read the manual first!"
}.to_json
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"invoices"
],
"headers": {
"Content-Type": "application/json",
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ customer_first_name: 'John',
customer_last_name: 'Doe',
customer_email: 'test@example.com',
customer_address_1: '123 Apple Street',
customer_address_2: 'Apt 101',
customer_company: 'ABC Corp',
customer_fax: '402-437-0100',
customer_phone: '402-437-0127',
customer_city: 'Lincoln',
customer_state: 'NE',
customer_zip: '68521',
invoice_date: '2017-02-04',
due_date: '2017-04-04',
custom_number: false,
deliver: false,
line_items: [ { '0': { description: 'Rockets', unit_price: 111, quantity: 7 } } ],
tax: 5788,
shipping: '0',
notes: 'Make sure to read the manual first!' }));
req.end();
curl -H "Content-Type: application/json" -u private-api-key: -X POST -d '{
"customer_first_name":"Ada",
"customer_last_name": "Lovelace",
"customer_email": "ada@lovelace.com",
"customer_address_1":"123 Rocket Lane",
"customer_address_2":"Suite 300",
"customer_company":"Lovelace Calculators",
"customer_fax":"402.111.1111",
"customer_phone":"402.111.1111",
"customer_city":"Lincoln",
"customer_state":"NE",
"customer_zip":"68508",
"invoice_date": "2017-02-04",
"due_date": "2017-03-04",
"custom_number":"true",
"number":"ROCKET-1234",
"deliver": true,
"line_items": [
{
"0": {
"description":"Rockets",
"unit_price":111,
"quantity":7
}
}
],
"tax": 5788,
"shipping":"0",
"notes":"Make sure to read the manual first!"
}' https://api.paymentspring.com/api/v1/invoices
Expected Response Data:
{
"class": "invoice",
"id": "86a6041621",
"merchant_id": "4d5758b8a84c_test",
"merchant_first_name": "Maximus",
"merchant_last_name": "Decimus Meridius",
"merchant_company": "Champions",
"merchant_address_1": "123 A St",
"merchant_address_2": "",
"merchant_city": "Lincoln",
"merchant_state": "NE",
"merchant_zip": "68521",
"merchant_fax": null,
"merchant_phone": "123123123",
"merchant_website": "gladiator.com",
"merchant_email": "champs@rome.com",
"customer_id": null,
"customer_first_name": "John",
"customer_last_name": "Doe",
"customer_company": "ABC Corp",
"customer_address_1": "123 Apple Street",
"customer_address_2": "Apt 101",
"customer_city": "Lincoln",
"customer_state": "NE",
"customer_zip": "68521",
"customer_fax": "402-437-0100",
"customer_phone": "402-437-0127",
"customer_website": null,
"customer_email": "test@example.com",
"line_items": [
{
"class": "line_item",
"description": "Rockets",
"unit_price": 111,
"quantity": "7.0",
"total_price": 777
}
],
"invoice_date": "2017-02-04",
"due_date": "2017-04-04",
"subtotal": 777,
"tax": 5788,
"shipping": 0,
"total": 6565,
"delivered": false,
"paid_in_full": false,
"partial_pay_enabled": true,
"amount_paid": 0,
"number": null,
"notes": "Make sure to read the manual first!",
"credit_card_enabled": true,
"bank_account_enabled": true,
"new_record": false
}
POST /invoices
Create an invoice and submit it to a customer.
- Note - Before creating an invoice you must first set up your contact information so the recipient knows who is sending the invoice. At the very least, we'll need your company name and email address.
Parameters
Parameter | Details |
---|---|
customer_first_name | Customer first name. |
customer_last_name | Customer last name. |
customer_email | Customer email address. |
customer_address_1 | Customer address line 1. |
customer_address_2 | Customer address line 2. |
customer_city | Customer city. |
customer_state | Customer state or province. |
customer_zip | Customer zip or postal code. |
customer_company | Customer company name. |
customer_phone | Customer phone number. |
customer_fax | Customer fax number. |
invoice_date | String, formatted ‘YYYY-MM-DD’. Note: if this date is in the future, this is the date the invoice will be sent (assuming deliver: true). |
due_date | String, formated ‘YYYY-MM-DD’. |
custom_number | Boolean – true if you’re assigning a custom invoice number, false otherwise. Use this if you generate your own invoice numbers, otherwise Nelnet Payment Services will generate one for you. |
number | String – custom invoice number, if you so choose. Ignored unless custom_number: true. |
deliver | Boolean – If set to true the invoice will be emailed to the customer. |
partial_pay_enabled | Boolean - true if partial payments for the invoice are allowed. |
line_items | Array of objects (see note below this table for formatting). |
tax | Tax amount (in cents). This will be automatically added to the total of the invoice. |
shipping | Shipping & handling amount (in cents). This will be automatically added to the total of the invoice. |
credit_card_enabled | Boolean - true if you're allowing an invoice to be paid with a credit card. |
bank_account_enabled | Boolean - true if you're allowing an invoice to be paid with a bank account. |
notes | String – Any other notes you would like to add to the invoice. |
line_items should be formatted as follows:
{
"line_items": [
{ "0": { "description":"Parts", "unit_price":234, "quantity":7 } },
{ "1": { "description":"Fuel", "unit_price":888, "quantity":3 } }
]
}
Error Codes
Error Code | Message |
---|---|
92001 | An invoice requires at least one line item. |
92002 | Could not deliver invoice email. |
92004 | Could not save invoice. |
92100 | Please set your merchant contact details before sending invoices. |
92102 | Customer email required. |
92105 | Please enter a valid customer email. |
92103 | Invoice tax must be an integer number of cents. |
92104 | Invoice shipping must be an integer number of cents. |
92200 | Line items must have a description. |
92201 | Unit price must be an integer number of cents. |
92202 | Quantity must be a valid number. |
List All Invoices
LIST INVOICES
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,test")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("GET", "api,v1,invoices", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("http://api.paymentspring.com/api/v1/invoices");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("http://api.paymentspring.com/api/v1/invoices")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"invoices"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl -u private-api-key:
http://api.paymentspring.com/api/v1/invoices/
Expected Response Data:
{
"list":[
{
"class":"invoice",
"id":"925792f79a",
"merchant_id":"071b975dba6f_test",
"merchant_first_name":"Robert",
"merchant_last_name":"Goddard",
"merchant_company":"Rocket Parts",
"merchant_address_1":"123 Rocket Lane",
"merchant_address_2":"" ,
"merchant_city":"Lincoln",
"merchant_state":"NE",
"merchant_zip":"68502",
"merchant_fax":"",
"merchant_phone":"4028026578",
"merchant_website":null,
"merchant_email":"robert@goddard.com",
"customer_id":null,
"customer_first_name":"Ada",
"customer_last_name":"Lovelace",
"customer_company":null,
"customer_address_1":null,
"customer_address_2":null,
"customer_city":null,
"customer_state":"",
"customer_zip":null,
"customer_fax":null,
"customer_phone":null,
"customer_website":null,
"customer_email":"ada@lovelace.com",
"line_items":[
{
"class":"line_item",
"description":"rockets",
"unit_price":888,
"quantity":"7.0",
"total_price":6216
}
],
"invoice_date":"2017-01-31",
"due_date":"2017-03-02",
"subtotal":6216,
"tax":0,
"shipping":0,
"total":6216,
"delivered":true,
"paid_in_full":false,
"amount_paid":0,
"number":null,
"notes":null,
"new_record":false
}
],
"meta":{
"limit":25,
"offset":0,
"total_results":1
}
}
GET /invoices
Fetch a list of invoices.
Parameters
Parameter | Details |
---|---|
limit | Maximum number of invoices to return. |
offset | Event index to begin returning customers from, useful for pagination. |
Delete an Invoice
DELETE AN INVOICE
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,test")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("DELETE", "api,v1,invoices,d10c7d998e", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("http://api.paymentspring.com/api/v1/invoices/5bb3428b6c");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.DELETE);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("http://api.paymentspring.com/api/v1/invoices/5bb3428b6c")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Delete.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require("http");
var options = {
"method": "DELETE",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"invoices",
"5bb3428b6c"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl -u private-api-key: -X DELETE \
http://api.paymentspring.com/api/v1/invoices/5bb3428b6c
Expected Response Data:
{
"success": true
}
DELETE /invoices/:id
Delete an unpaid invoice.
Parameters
Parameter | Details |
---|---|
id | Invoice ID for deletion |
Error Codes
Error Code | Message |
---|---|
92007 | A paid invoice can not be deleted. |
92008 | Could not delete invoice. |
Mark Invoice as Paid
MARK AS PAID
Sample Request (Pay in full):
import http.client
conn = http.client.HTTPConnection("api,paymentspring,test")
payload = "{\"pay_in_full\": true}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v1,invoices,8033063b43,mark_as_paid", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("http://api.paymentspring.com/api/v1/invoices/8033063b43/mark_as_paid");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"pay_in_full\": true}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("http://api.paymentspring.com/api/v1/invoices/8033063b43/mark_as_paid")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request.basic_auth 'your-private-api-key', ''
request.body = "{\"pay_in_full\": true}"
response = http.request(request)
puts response.read_body
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"invoices",
"8033063b43",
"mark_as_paid"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ pay_in_full: true }));
req.end();
curl -X POST -u private-api-key:
http://api.paymentspring.com/api/v1/invoices/8033063b43/mark_as_paid \
-d '{
"pay_in_full": true
}'
Expected Response Data:
{
"class": "invoice",
"id": "8033063b43",
"merchant_id": "2a3478b8e320_test",
"merchant_first_name": "Merch",
"merchant_last_name": "Anter",
"merchant_company": "Merch Ants",
"merchant_address_1": "123 A St",
"merchant_address_2": "",
"merchant_city": "Lincoln",
"merchant_state": "NE",
"merchant_zip": "68521",
"merchant_fax": null,
"merchant_phone": "1231231233",
"merchant_website": "merchant.com",
"merchant_email": "merch@nt.com",
"customer_id": null,
"customer_first_name": "John",
"customer_last_name": "Doe",
"customer_company": "ABC Corp",
"customer_address_1": "123 Apple Street",
"customer_address_2": "Apt 101",
"customer_city": "Lincoln",
"customer_state": "NE",
"customer_zip": "68521",
"customer_fax": "402-437-0100",
"customer_phone": "402-437-0127",
"customer_website": null,
"customer_email": "test@example.com",
"line_items": [
{
"class": "line_item",
"description": "Rockets",
"unit_price": 111,
"quantity": "7.0",
"total_price": 777
}
],
"invoice_date": "2017-02-04",
"due_date": "2017-04-04",
"subtotal": 777,
"tax": 5788,
"shipping": 0,
"total": 6565,
"delivered": false,
"paid_in_full": true,
"partial_pay_enabled": true,
"amount_paid": 6565,
"number": null,
"notes": "Make sure to read the manual first!",
"credit_card_enabled": true,
"bank_account_enabled": true,
"new_record": false
}
Sample Request (Pay part of the invoice):
import http.client
conn = http.client.HTTPConnection("api,paymentspring,test")
payload = "{\"amount\": 100}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v1,invoices,a188205877,mark_as_paid", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("http://api.paymentspring.com/api/v1/invoices/a188205877/mark_as_paid");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"amount\": 100}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
require 'uri'
require 'net/http'
url = URI("http://api.paymentspring.com/api/v1/invoices/a188205877/mark_as_paid")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.basic_auth 'your-private-api-key', ''
request.body = "{\"amount\": 100}"
response = http.request(request)
puts response.read_body
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"invoices",
"a188205877",
"mark_as_paid"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ amount: 100 }));
req.end();
Expected Response Data:
{
"class": "invoice",
"id": "a188205877",
"merchant_id": "2a3478b8e320_test",
"merchant_first_name": "Merch",
"merchant_last_name": "Anter",
"merchant_company": "Merch Ants",
"merchant_address_1": "123 A St",
"merchant_address_2": "",
"merchant_city": "Lincoln",
"merchant_state": "NE",
"merchant_zip": "68521",
"merchant_fax": null,
"merchant_phone": "1231231233",
"merchant_website": "merchant.com",
"merchant_email": "merch@nt.com",
"customer_id": null,
"customer_first_name": "John",
"customer_last_name": "Doe",
"customer_company": "ABC Corp",
"customer_address_1": "123 Apple Street",
"customer_address_2": "Apt 101",
"customer_city": "Lincoln",
"customer_state": "NE",
"customer_zip": "68521",
"customer_fax": "402-437-0100",
"customer_phone": "402-437-0127",
"customer_website": null,
"customer_email": "test@example.com",
"line_items": [
{
"class": "line_item",
"description": "Rockets",
"unit_price": 111,
"quantity": "7.0",
"total_price": 777
}
],
"invoice_date": "2017-02-04",
"due_date": "2017-04-04",
"subtotal": 777,
"tax": 5788,
"shipping": 0,
"total": 6565,
"delivered": false,
"paid_in_full": false,
"partial_pay_enabled": true,
"amount_paid": 100,
"number": null,
"notes": "Make sure to read the manual first!",
"credit_card_enabled": true,
"bank_account_enabled": true,
"new_record": false
}
POST /invoices/:id/mark_as_paid
Mark an invoice as paid, either partially or in full. Use this if a customer pays the invoice outside of Nelnet Payment Services (e.g. by mailing a check, using cash, etc.).
Parameters
Parameter | Details |
---|---|
amount | The amount paid (in cents). |
pay_in_full | A boolean indicating that the invoice was payed in full. If true , the amount param is ignored. If false or not present, an amount must be provided. |
Error Codes
Error Code | Message |
---|---|
92003 | Invalid payment amount. |
92005 | Invoice already paid. |
92004 | Could not save invoice. |
Resend an Invoice
RESEND AN INVOICE
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,test")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v1,invoices,374c6a12bb,deliver", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("http://api.paymentspring.com/api/v1/invoices/374c6a12bb/deliver");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.POST);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("http://api.paymentspring.com/api/v1/invoices/374c6a12bb/deliver")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require("http");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"invoices",
"374c6a12bb",
"deliver"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl -u private-api-key:
https://api.paymentspring.com/api/v1/invoices/a57158d5e8/deliver
Expected Response Data:
{
"success":true
}
POST /invoices/:id/deliver
Resend an existing invoice by email.
Parameters
Parameter | Details |
---|---|
id | ID of invoice you want to re-send |
Error Codes
Error Code | Message |
---|---|
92002 | Could not deliver invoice email. |
Fetch an Invoice
RETRIEVE AN INVOICE
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,test")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("GET", "api,v1,invoices,d10c7d998e", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("http://api.paymentspring.com/api/v1/invoices/374c6a12bb");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
require 'uri'
require 'net/http'
url = URI("http://api.paymentspring.com/api/v1/invoices/374c6a12bb")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request.basic_auth 'your-private-api-key', ''
response = http.request(request)
puts response.read_body
var http = require("http");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"invoices",
"374c6a12bb"
],
"headers": {
'Authorization': 'Basic ' + new Buffer(yourPrivateApiKey + ':').toString('base64')
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
curl -u private-api-key:
https://api.paymentspring.com/api/v1/invoices/374c6a12bb
Expected Response Data:
{
"class": "invoice",
"id": "374c6a12bb",
"merchant_id": "2a3478b8e320_test",
"merchant_first_name": "Merch",
"merchant_last_name": "Anter",
"merchant_company": "Merch Ants",
"merchant_address_1": "123 A St",
"merchant_address_2": "",
"merchant_city": "Lincoln",
"merchant_state": "NE",
"merchant_zip": "68521",
"merchant_fax": null,
"merchant_phone": "1231231233",
"merchant_website": "merchant.com",
"merchant_email": "merch@nt.com",
"customer_id": null,
"customer_first_name": "John",
"customer_last_name": "Doe",
"customer_company": "ABC Corp",
"customer_address_1": "123 Apple Street",
"customer_address_2": "Apt 101",
"customer_city": "Lincoln",
"customer_state": "NE",
"customer_zip": "68521",
"customer_fax": "402-437-0100",
"customer_phone": "402-437-0127",
"customer_website": null,
"customer_email": "test@example.com",
"line_items": [
{
"class": "line_item",
"description": "Rockets",
"unit_price": 111,
"quantity": "7.0",
"total_price": 777
}
],
"invoice_date": "2017-02-04",
"due_date": "2017-04-04",
"subtotal": 777,
"tax": 5788,
"shipping": 0,
"total": 6565,
"delivered": true,
"paid_in_full": false,
"partial_pay_enabled": true,
"amount_paid": 0,
"number": null,
"notes": "Make sure to read the manual first!",
"credit_card_enabled": true,
"bank_account_enabled": true,
"new_record": false
}
GET /invoices/:id
Fetch a specific invoice.
Parameters
Parameter | Details |
---|---|
id | Invoice ID for fetching |
Error Codes
Error Code | Message |
---|---|
92000 | Could not find the specified invoice. |
Update an Invoice
UPDATE AN INVOICE
Sample Request:
import http.client
conn = http.client.HTTPConnection("api,paymentspring,test")
payload = "{\"line_items\": [{\"0\": { \"description\":\"Rockets\", \"unit_price