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.
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. |
91703 | We are unable to verify your account, please re-enter your information or try a different account. If not successful, please verify your account with your financial institution. |
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\":111, \"quantity\":7},\"1\": { \"description\":\"Lasers\", \"unit_price\":25, \"quantity\":4}} ],\"tax\": 6100,\"shipping\":\"0\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Authorization' : 'Basic %s' % encoded_auth }
conn.request("POST", "api,v1,invoices,374c6a12bb", payload, 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.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"line_items\": [{\"0\": { \"description\":\"Rockets\", \"unit_price\":111, \"quantity\":7},\"1\": { \"description\":\"Lasers\", \"unit_price\":25, \"quantity\":4}} ],\"tax\": 6100,\"shipping\":\"0\"}", 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/374c6a12bb")
http = Net::HTTP.new(url.host, url.port)
request.basic_auth 'your-private-api-key', ''
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\"line_items\": [{\"0\": { \"description\":\"Rockets\", \"unit_price\":111, \"quantity\":7},\"1\": { \"description\":\"Lasers\", \"unit_price\":25, \"quantity\":4}} ],\"tax\": 6100,\"shipping\":\"0\"}"
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"
],
"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({ line_items:
[ { '0': { description: 'Rockets', unit_price: 111, quantity: 7 },
'1': { description: 'Lasers', unit_price: 25, quantity: 4 } } ],
tax: 6100,
shipping: '0' }));
req.end();
curl -u private-api-key: \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"line_items": [
{
"0": {
"description":"Rockets",
"unit_price":111,
"quantity":7
},
"1": {
"description":"Lasers",
"unit_price":25,
"quantity":4
}
}
],
"tax": 6100,
"shipping":"0"
}' \
http://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
},
{
"class": "line_item",
"description": "Lasers",
"unit_price": 25,
"quantity": "4.0",
"total_price": 100
}
],
"invoice_date": "2017-02-04",
"due_date": "2017-04-04",
"subtotal": 877,
"tax": 6100,
"shipping": 0,
"total": 6977,
"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
}
POST /invoices/:id
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 } }
]
}
Update an existing unpaid invoice.
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. |
line_items | Array of objects (see note below this table for formatting). Note: If this field is empty, any existing line items will be preserved. If you supply any line items in this field, they will overwrite any existing line items. Therefore, if you are attempting to add new line items to existing line items, you will need to supply both existing and new in this field. |
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. |
notes | String – Any other notes you would like to add to the invoice. |
Error Codes
Error Code | Message |
---|---|
92006 | A paid invoice can not be updated. |
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. |
Widgets
Create Widget
Sample Request:
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/checkout_forms")
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 = "{\"config\": {\"amount\": 3000,\"enabled_methods\": [\"credit_card\", \"bank_account\"], \"distribution\": {\"enabled\": true, \"values\": [\"General Fund\", \"Special Fund\"]}, \"recurring\": {\"enabled\": true, \"prompt\": \"Make a monthly payment?\"}, \"address\": true}, \"form_type\": \"form\", \"name\": \"General Donation Widget\"}"
response = http.request(request)
puts response.read_body
curl -u private-api-key:
https://api.paymentspring.com/api/v1/checkout_forms \
-d '{
"config": {
"amount": 3000,
"enabled_methods": ["credit_card", "bank_account"],
"distribution": {
"enabled": true,
"values": ["General Fund", "Special Fund"]
},
"recurring": {
"enabled": true,
"prompt": "Make a monthly payment?"
},
"address": true
},
"form_type": "form",
"name": "General Donation Widget"
}'
var client = new RestClient("https://api.paymentspring.com/api/v1/checkout_forms");
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", "{\"config\": {\"amount\": 3000, \"enabled_methods\": [\"credit_card\", \"bank_account\"], \"distribution\": {\"enabled\": true, \"values\": [\"General Fund\", \"Special Fund\"]}, \"recurring\": {\"enabled\": true, \"prompt\": \"Make a monthly payment?\"}, \"address\": true}, \"form_type\": \"form\", \"name\": \"General Donation Widget\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\"config\": {\"amount\": 3000, \"enabled_methods\": [\"credit_card\", \"bank_account\"], \"distribution\": {\"enabled\": true, \"values\": [\"General Fund\", \"Special Fund\"]}, \"recurring\": {\"enabled\": true, \"prompt\": \"Make a monthly payment?\"}, \"address\": true}, \"form_type\": \"form\", \"name\": \"General Donation Widget\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type' : 'application/json',
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,checkout_forms", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"checkout_forms"
],
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({
"config": {
"amount": 3000,
"enabled_methods": [
"credit_card",
"bank_account"
],
"distribution": {
"enabled": true,
"values": [
"General Fund",
"Special Fund"
]
},
"recurring": {
"enabled": true,
"prompt": "Make a monthly payment?"
},
"address": true
},
"form_type": "form",
"name": "General Donation Widget"
}));
req.end();
Expected Response Data:
{
"class": "checkout",
"id": "393555a25f4b13d9a06d",
"config": {
"amount": 3000,
"enabled_methods": [
"credit_card",
"bank_account"
],
"distribution": {
"enabled": true,
"values": [
"General Fund",
"Special Fund"
]
},
"recurring": {
"enabled": true,
"prompt": "Make a monthly payment?"
},
"address": true
},
"form_type": "form",
"name": "General Donation Widget",
"created_at": "2018-06-18T20:50:07.538Z",
"subscription_id": 289
}
POST /checkout_forms
Creates a widget.
Parameters
Parameter | Details |
---|---|
form_type | The type of form you are creating. This can be either button or form . |
name | A descriptive name to help you manage your widgets. |
config | JSON representing the widgets configuration. See below for more details on building your widget's config. |
Error Codes
Error Code | Message |
---|---|
80010 | The checkout form was not created. |
80012 | An authenticated merchant is needed to create to a form. |
80023 | A form config attribute is required to create a widget. |
80013 | The checkout form enabled distribution field must be set to true or false. |
80014 | The checkout form values distribution field must be an array of fund names. |
80015 | The checkout form distribution must include the enabled and values attributes. |
80016 | The checkout form fee must include the credit_card and ach attributes. |
80018 | The checkout form credit card fee must be an integer representing the fee in cents. |
80019 | The checkout form ach fee must be an integer representing the fee in cents. |
80020 | The checkout form enabled methods must be an array including the payment methods you wish to allow: credit_card or bank_account . |
80021 | The checkout form amount must be a positive integer representing the form amount in cents. |
80023 | A form config attribute is required to create a checkout form. |
80024 | A form must have a form type of either button or form . |
80029 | The percentage fee for credit card must be a percentage represented between 0 and 1. |
80028 | The percentage fee for ach must be a percentage represented between 0 and 1. |
80026 | The fee type must be either percentage or flat . |
80027 | Fee values must be a hash consisting of credit_card and ach keys. |
80025 | This merchant is not allowed to utilize the cover fee feature. |
80030 | Recurring enabled field must be true or false. |
80031 | Recurring prompt must not be blank. |
80032 | The meta fields attribute must be an array. |
80033 | A meta field type must be text , dropdown , or hidden . |
80034 | A meta field name must be provided. |
80035 | A meta field's options attribute must be an array of one or more strings when configured as a dropdown. |
80036 | The schedule payment enabled field must be true or false. |
80037 | A hidden meta field must have name and value attributes. |
Widget Config
A widgets config attribute determines what options and abilities your widget utilizes. Below are all the attributes you may include with your config.
To further explore how these configurations work, head over to dashboard.paymentspring.com and create a widget. Once created, you can view your widget's settings to see how we set up the widget's config for you.
enabled_methods: An array of strings identifying which payment methods may be accepted by the widget. This attribute is required and must include at least one payment method type: credit_card
and/or bank_account
.
{ enabled_methods: ['credit_card', 'bank_account'] }
default_method: If the widget has more than one enabled payment method, the default_method
configuration option allows you to select which one is displayed to the user first.
{ default_method: 'credit_card' }
amount: If included, the amount (represented in cents as an integer) makes the widget have a static payment amount. If an amount is not provided, the user will be able to provide an amount for the payment.
{ amount: 2000 }
recurring: Lets users make recurring payments. You must specify this attribute as enabled (see example).
The prompt
attribute is optional. This allows you to customize the label for the recurring selection displayed to the user.
The frequencies
attribute is optional. If omitted, the recurring frequency will be monthly. Frequencies must be an array with one or more frequency options: weekly
, monthly
, and quarterly
. If more than
one are provided, the user will be able to select their frequency at the time of making a payment on the widget.
The default_frequency
attribute is optional. If omitted the widget will default to having no recurring option selected when rendered. The default_frequency
must be a string matching one of the frequencies
provided.
The subscription_name
attribute is optional. When a widget with recurring enabled is created, we create the backing subscription for you. If subscription_name
is omitted, we will name the subscription using the
widget's name or the widgets form_id.
{ recurring: { enabled: true, prompt: 'Make this a monthly payment?', frequencies: ['monthly', 'quarterly'], default_frequency: 'monthly', subscription_name: 'test widget subscription' } }
recurring only: These widgets only allow users to make recurring payments. This attribute is a subset of the above recurring configuration. The frequency
attribute can be weekly
, monthly
, or quarterly
.
{ recurring: { enabled: true, recurring_only: { enabled: true, frequency: 'weekly' } } }
recurring billing day: Recurring widgets can be configured to bill on a specific day. Say we want our monthly recurring widget to bill on the 15th of every month. You can utilize the day
attribute.
{ recurring: { enabled: true, frequencies: ['monthly'], day: 15 } }
The day attribute may only be used when a single frequency is specified.
Depending on the frequency, the day attribute must be an integer or a hash describing when in the week, month, or quarter the subscription is billed. For weekly widgets, day should be an integer between 1 and 7 (indicating Sunday through Saturday). For monthly widgets, day should be either an integer between 1 and 31. For quarterly widgets, day should be a JSON-encoded hash with keys month (between 1 and 3 representing the 1st, 2nd, or 3rd month of the quarter) and day (between 1 and 31, inclusive). An example quarterly day configuration is shown below. This would bill on the 2nd month of the quarter (February, May, August, and November) on the 15th day of the month.
{ recurring: { enabled: true, frequencies: ['quarterly'], day: { month: 2, day: 15 } } }
recurring number of billings: Unless specified, recurring widgets bill until the customer is unsubscribed. You can configure how many times the widget's subscription should be billed by including the ends_after
attribute. The value for ends_after
should be an integer representing how many times the subscription should bill. In the example below, the monthly widget will bill for 6 months.
{ recurring: { enabled: true, frequencies: ['monthly'], ends_after: 6 } }
button_text: Change the text that appears on the widget's buttons. This affects both the button to open the widget as well as the button to submit the payment.
{ button_text: 'Submit Payment' }
address: Require users to submit their address along with their payment. If enabled, address fields are required.
{ address: true }
distribution: Allow users to select from a list of funds to distribute their payment/donation between.
{ distribution: { enabled: true, values: ['General Fund', 'Special Purpose Fund'] } }
meta fields: You can specify any number of text, drop down, and hidden fields to allow you to collect more information from your users.
{ meta_fields: [ { type: 'text', name: 'In Honor Of' }, { type: 'dropdown', name: 'T-Shirt Size', options: ['S', 'M', 'L', 'XL'] }, { type: 'hidden', name: 'campaign_id', value: 'ac2bd1' } ] }
additional donation: Give users the option to add an additional donation to help cover costs and make the most of their donation. This can be done by a percentage of the donation or a flat amount. Please note that only organizations designated as charitable or social service organizations may utilize this configuration feature.
flat amount: (example below: $2.75 for credit cards and $1.25 for ach)
{ fee: { type: 'flat', values: { credit_card: 275, ach: 125 } } }
percentage amount: (example below: 3% for credit cards and 1% for ach)
{ fee: { type: 'percentage', values: { credit_card: 0.03, ach: 0.01 } } }
receipts: By default, widgets send receipts utilizing your merchant's default receipt. This configuration option allows you to turn receipt sending off so you can handle receipting your own way.
{ receipts: { enabled: false } }
Retrieve Widget
Sample Request:
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/checkout_forms/393555a25f4b13d9a06d")
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
curl -u private-api-key:
https://api.paymentspring.com/api/v1/checkout_forms/393555a25f4b13d9a06d
var client = new RestClient("https://api.paymentspring.com/api/v1/checkout_forms/393555a25f4b13d9a06d");
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);
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = { 'Content-Type': "application/json" }
conn.request("GET", "api,v1,checkout_forms,393555a25f4b13d9a06d", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"checkout_forms",
"393555a25f4b13d9a06d"
],
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:
{
"class": "checkout",
"id": "393555a25f4b13d9a06d",
"config": {
"amount": 3000,
"address": true,
"recurring": {
"prompt": "Make a monthly payment?",
"enabled": true
},
"distribution": {
"values": [
"General Fund",
"Special Fund"
],
"enabled": true
},
"enabled_methods": [
"credit_card",
"bank_account"
]
},
"form_type": "form",
"name": "General Donation Widgetss",
"created_at": "2018-06-18T20:50:07.538Z",
"subscription_id": 289
}
GET /checkout_forms/:id
Retrieves a widget.
Error Codes
Error Code | Message |
---|---|
80011 | The widget is not available. |
List Widgets
Sample Request:
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/checkout_forms")
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
curl -u private-api-key:
https://api.paymentspring.com/api/v1/checkout_forms/
var client = new RestClient("https://api.paymentspring.com/api/v1/checkout_forms");
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);
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,checkout_forms", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"checkout_forms"
],
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:
{
"list": [
{
"class": "checkout",
"id": "393555a25f4b13d9a06d",
"config": {
"amount": 3000,
"address": true,
"recurring": {
"prompt": "Make a monthly payment?",
"enabled": true
},
"distribution": {
"values": [
"General Fund",
"Special Fund"
],
"enabled": true
},
"enabled_methods": [
"credit_card",
"bank_account"
]
},
"form_type": "form",
"name": "General Donation Widgetss",
"created_at": "2018-06-18T20:50:07.538Z",
"subscription_id": 289
}
]
}
GET /checkout_forms
Retrieves a list of widgets
Update Widget
Sample Request:
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/checkout_forms/393555a25f4b13d9a06d")
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 = "{\"config\": {\"enabled_methods\": [\"credit_card\"],\"amount\": 2500}, \"form_type\": \"button\"}"
response = http.request(request)
puts response.read_body
curl -u private-api-key: -X PUT
https://api.paymentspring.com/api/v1/checkout_forms/393555a25f4b13d9a06d \
-d '{
"config": {
"enabled_methods": ["credit_card"],
"amount": 2500
},
"form_type": "button"
}'
var client = new RestClient("https://api.paymentspring.com/api/v1/checkout_forms/393555a25f4b13d9a06d");
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", "{\"config\": {\"enabled_methods\": [\"credit_card\"],\"amount\": 2500},\"form_type\": \"button\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': 'application/json',
'Authorization': 'Basic %s' % encoded_auth
}
payload = "{\"config\": {\"enabled_methods\": [\"credit_card\"],\"amount\": 2500}, \"form_type\": \"button\"}"
conn.request("POST", "api,v1,checkout_forms,393555a25f4b13d9a06d", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"checkout_forms",
"393555a25f4b13d9a06d"
],
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({
"config": {
"enabled_methods": [
"credit_card"
],
"amount": 2500
},
"form_type": "button"
}));
req.end();
Expected Response Data:
{
"class": "checkout",
"id": "393555a25f4b13d9a06d",
"config": {
"enabled_methods": [
"credit_card"
],
"amount": 2500
},
"form_type": "form",
"name": null,
"created_at": "2018-06-18T20:50:07.538Z",
"subscription_id": 289
}
POST /checkout_forms/:id
Updates a widget.
Parameters
Parameter | Details |
---|---|
form_type | The type of form you are creating. This can be either button or form . |
name | A descriptive name to help you manage your widgets. |
config | A JSON string representing the widgets configuration. See below for more details on building your widget's config. |
Error Codes
Error Code | Message |
---|---|
80013 | The checkout form enabled distribution field must be set to true or false. |
80014 | The checkout form values distribution field must be an array of fund names. |
80015 | The checkout form distribution must include the enabled and values attributes. |
80016 | The checkout form fee must include the credit_card and ach attributes. |
80018 | The checkout form credit card fee must be an integer representing the fee in cents. |
80019 | The checkout form ach fee must be an integer representing the fee in cents. |
80020 | The checkout form enabled methods must be an array including the payment methods you wish to allow: credit_card or bank_account . |
80021 | The checkout form amount must be a positive integer representing the form amount in cents. |
80023 | A form config attribute is required to create a checkout form. |
80024 | A form must have a form type of either button or form . |
80029 | The percentage fee for credit card must be a percentage represented between 0 and 1. |
80028 | The percentage fee for ach must be a percentage represented between 0 and 1. |
80026 | The fee type must be either percentage or flat . |
80027 | Fee values must be a hash consiting of credit_card and ach keys. |
80025 | This merchant is not allowed to utilize the cover fee feature. |
80030 | Recurring enabled field must be true or false. |
80031 | Recurring prompt must not be blank. |
80032 | The meta fields attribute must be an array. |
80033 | A meta field type must be text , dropdown , or hidden . |
80034 | A meta field name must be provided. |
80035 | A meta field's options attribute must be an array of one or more strings when configured as a dropdown. |
80036 | The schedule payment enabled field must be true or false. |
80037 | A hidden meta field must have name and value attributes. |
Delete Widget
Sample Request:
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/checkout_forms/393555a25f4b13d9a06d")
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
curl -u private-api-key: -X DELETE
https://api.paymentspring.com/api/v1/checkout_forms/393555a25f4b13d9a06d
var client = new RestClient("https://api.paymentspring.com/api/v1/checkout_forms/393555a25f4b13d9a06d");
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);
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,checkout_forms,393555a25f4b13d9a06d", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var http = require("https");
var options = {
"method": "DELETE",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"checkout_forms",
"393555a25f4b13d9a06d"
],
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 /checkout_forms/:id
Deletes a widget.
Site Integration
Example Widget Codes Snippet
<script src="https://checkout.paymentspring.com/js/paymentspring.js" formId="393555a25f4b13d9a06d" ></script>
Integrating a widget into your site is as easy as pasting one line of code where you would like the widget button or form to appear.
For those that want more control, see below for more things you can do to configure your widget directly on your site.
Javascript Callback
Javascript Callback
<sciprt>
function myAwesomeCallback(response) {
console.log(response.data.amount_settled);
}
</script>
Need to know about your widget's transactions? We've got your callback.
You can specify a javascript callback to fire upon a transaction being successfully submitted through your widget.
Start by creating a javascript function that takes, as an argument, the response object from the call the widget makes to execute the transaction. This javascript callback function should be defined in your site's global scope.
As with any exposed function, webhook endpoint, or other publicly accessible point of entry you should be careful to verify the data provided before taking some action with it. For example, with this callback you could take the transaction response and send a request to your own server to save a record of the payment for your application. Rather than directly save the response from the callback, you should make a follow up request from your sever to Nelnet Payment Services with the transaction_id to verify that the transaction is indeed a valid Nelnet Payment Services transaction.
Programmatically Open Widget
Hide Open Widget Button
<script src="https://checkout.paymentspring.com/js/paymentspring.js" formId="393555a25f4b13d9a06d" hideButton></script>
You can control when a user sees your widget by programmatically triggering the opening of the widget modal. We expose a javascript function called psDisplayWidget(form_id)
that accepts the formId
of the widget you want to open.
To turn off the widget button simply add the attribute hideButton
to your widget's script tag. The button will no longer be displayed on the page and you control when your users are displayed the widget.
Client-side Configuration
Client-side Configuration
<script formId="393555a25f4b13d9a06d" src="https://checkout.paymentspring.com/js/paymentspring.js" widgetData="customizeWidget"></script>
<script>
function customizeWidget() {
return {
config: {
amount: userDefinedAmount()
}
}
}
</script>
To add even more customizability and expressivity you can override your widgets amount right form your sites html and javascript. To do this, start by defining a function in your page's global scope that will return an object defining the new configured amount.
Next we must tell our widget that this new function exists. In our script tag we can add an attribute widgetData
and set it equal to the name of the function, in our example: customizeWidget
.
For example, lets say you want to update the widget amount based on some user selection so you have a function called userDefinedAmount()
. Remember, we represent currency as an integer in cents. We use this user defined data to provide the value for our amount configuration. See code example.
The widgetData
function needs to be defined before the widget's script tag is loaded. In our example above, we want the amount to be dependent on a user's selection. To do this we need to dynamically inject the widget's script tag into the page after the user's selection has been made so the widget can initialize itself with our new amount.
Client-side Metadata
Client-side Metadata
<script>
function customizeWidget() {
return {
config: {
amount: 2500
},
metadata: {
accountID: '123abc'
}
}
}
</script>
We can extend the configuration function from above to also provide custom metadata with the widget's transaction. To do this, we add the metadata
property to the object returned from our function. To further our example above, lets say we want transactions generated from our widget to include an account id with it's transaction. We add accountId
and its value as to the metadata property of our widgetData
function.
Once the user clicks submit, the widget checks this function to see if any metadata is present and includes it along with the transaction.
Webhooks
Overview
You can use webhooks to power real-time notifications of events within the Nelnet Payment Services Gateway.
Webhooks have two primary components: rules and strategies.
Rules determine when you receive notifications. For example, I can create a rule that notifies me of every failed transaction, or every successful recurring transaction over $10.00, or any time a receipt is sent (this is a very small sampling of what's possible). Rules match against an event resource, an even type, and one or more constraints.
Strategies determine who gets notified and how they get notified when a rule matches. You can send notifications via email, SMS, or post request (to any server with a publicly accessible endpoint and behind an SSL certificate).
A given rule can have several strategies associated with it. Conversely, a given strategy can be used by several rules.
Event Resources and Types
Here is the list of all currently available event resources and types:
Event Resource | Event Type | Details |
---|---|---|
batch | settled | fires any time a ACH or mobile batch settles |
invoice | paid | fires any time an invoice is paid |
plan | paid | fires whenever a batch of subscriptions for a given plan gets processed. Does not include the transactions themselves. |
receipt | sent | fires any time an SMS or Email receipt is sent |
scheduled_payment | created | fires when a one-time payment is scheduled for the future |
scheduled_payment | billed | fires when a scheduled payment bills |
scheduled_payment | canceled | fires when a scheduled payment is canceled |
subscription | created | fires any time a customer is enrolled in a subscription |
subscription | destroyed | fires any time a customer is removed from a subscription |
transaction | created | fires any time a transaction is successfully created |
transaction | failed | fires any time a credit card transaction is rejected by the processor, an ACH charge is immediately rejected by the processor, or an ACH transaction is marked as "returned" |
transaction | refunded | fires any time a transaction gets refunded |
transaction | status_change | fires any time an ACH transaction's status changes (from "submitted" to "remitted", or from "submitted" or "remitted" to "failed") |
method | account_update_received | fires any time a payment method has been updated* |
method | account_update_disabled_method | fires any time a payment method has been disabled* |
method | account_update_unavailable | fires any time a payment method update was unavailable* |
- Account Updater features will require additional configuration. Please contact Client Services for more information at NPS-ClientServices@nelnet.net.
Constraints
Constraints are the secret sauce of webhooks; they let you cleanly filter through events so that your notifications are granular and specific. They do this through a DSL which allows the construction of queries through supplied JSON constructs. Constraints can compare against constant values, pull values from the event payload itself, be composed using comparison and logical operators, and can make historical queries.
Constant Values
The simplest constraint is the constant:
{
"operator": "constant",
"value": true
}
If you created a rule and this was the only constraint you put on the rule, the
rule would be fired every time the relevant event_type
occurred. The "value" can
be a boolean, integer, or string.
Payload Lookups
Payload lookup constraints allow you to use values from the body of the event that is occurring:
{
"operator": "payload_value",
"key": "amount"
}
This constraint would return the "amount" field for the event. For example, if
this constraint were placed on an "transaction" "created" event, it would return
the amount of the transaction. The currently supported payload value lookups for
a given event_resource
are listed in the "Payload Values" section of this
document.
If you want to use this field, you must ultimately resolve it into a boolean. This will usually happen by comparing it, using a comparison operator, to a constant.
Nested Payload Lookups
Nested payload lookup constraints allow you to pull nested values, such as from metadata:
{
"operator": "nested_payload_value",
"key": "metadata ->> donor_id"
}
The example above will look for the value of donor_id
as a top-level key
within metadata
on a Transaction. You can further nest as deep as you like so
long as you are searching within a key/value store.
If the existing lower-level key does not exist, no value will be extracted.
Currently, the metadata
key of Transactions is the only one available for
nested lookups.
Comparison Operators
Comparison operators allow you to check values against each other:
{
"operator": "Comparison.greater_than",
"left_constraint": {
"operator": "payload_value",
"key": "amount"
},
"right_constraint": {
"operator": "constant",
"value": 100
}
}
If you placed this constraint on a transaction created
rule, it would
evaluate to "true" whenever the amount of the transaction was greater than 100
(cents).
Currently supported comparison operators are:
Comparison.equal
Comparison.not_equal
Comparison.greater_than
Comparison.less_than
The left_constraint
and right_constraint
values can be any type of
constraint: constants, payload lookups, other comparisons, logical operators, or
historic queries.
Logical Operators
Logical operators allow you to perform logical operations across multiple constraints:
{
"operator": "Logical.and",
"constraints": [
{
"operator": "Comparison.greater_than",
"left_constraint": {
"operator": "payload_value",
"key": "amount"
},
"right_constraint": {
"operator": "constant",
"value": 100
}
},
{
"operator": "Comparison.equal",
"left_constraint": {
"operator": "payload_value",
"key": "status"
},
"right_constraint": {
"operator": "constant",
"value": "FAILED"
}
}
]
}
If you placed this constraint on a transaction - created
rule, it would
evaluate to "true" whenever the amount of the transaction was greater than 100
and the status was "FAILED".
Currently supported logical operators are:
Logical.and
Logical.or
Similar to comparison constraints, the "constraints" you supply to a logical
operator can be any type of constraint: constants, payload lookups, comparisons,
other nested logical operators, or historic queries. You can supply any number
of these constraints in the "constraints" array of a logical operator.
Ultimately each of those must resolve to true
or false
.
Historical Queries
Historical constraints allow you to query events as they occur over time in Nelnet Payment Services:
{
"operator": "Query::PaymentSpring.recent_transaction_failures",
"merchant_id_constraint": {
"operator": "payload_value",
"value": "merchant_id"
},
"lookup_count_constraint": {
"operator": "constant",
"value": 6
}
}
Historic query constraints are fairly case specific, but in general they will
require constraints to be supplied as domain specific key values and those will
be provided to a given query. The example above takes two constraints as
arguments: merchant_id_constraint
and lookup_count_constraint
. The
constraint as a whole will give you back the number of failed transactions out
of the last x transactions created by y, where x is whatever value
lookup_count_constraint
returns and y is whatever value
merchant_id_constraint
returns.
The currently supported historic queries and their expected parameters are:
PaymentSpring.recent_transaction_failures
Parameters
Parameter | Details |
---|---|
merchant_id_constraint |
The merchant_id which the historic transactions were created under. You will want this to be your own merchant id. |
lookup_count_constraint |
The number of transactions you want to look back through. If you are looking for 4 failures of the last 10 transactions, you will want this to be "10". |
Payload Values
The possible payload values that a rule can query on are limited by the
event resource the rule is listening for. The following tables detail the
currently supported event resources and the payload_value
keys which they
receive.
Batch |
---|
amount |
end_date |
merchant_id |
start_date |
success |
type |
uuid |
Invoice |
---|
amount_paid |
customer_address_1 |
customer_address_2 |
customer_city |
customer_company |
customer_email |
customer_fax |
customer_first_name |
customer_id |
customer_last_name |
customer_phone |
customer_state |
customer_website |
customer_zip |
delivered |
due_date |
invoice_date |
line_items |
merchant_address_1 |
merchant_address_2 |
merchant_city |
merchant_company |
merchant_email |
merchant_fax |
merchant_first_name |
merchant_id |
merchant_last_name |
merchant_phone |
merchant_state |
merchant_website |
merchant_zip |
notes |
number |
paid_in_full |
shipping |
subtotal |
tax |
total |
Plan |
---|
amount |
customer_id |
plan_id |
plan_name |
success |
Receipt |
---|
email_address |
id |
name |
phone_number |
receipt_text |
receipt_type |
subject |
transaction_id |
Subscription |
---|
amount |
charge_bank_account |
customer_id |
day |
ends_after |
frequency |
merchant_id |
method_id |
plan_id |
receipt_template_id |
Transaction |
---|
account_holder_name |
account_number |
account_type |
address_1 |
address_2 |
amount_authorized |
amount_failed |
amount_refunded |
amount_settled |
authorized |
avs_address_check |
card_exp_month |
card_exp_year |
card_number |
card_owner_name |
card_type |
city |
class |
company |
country |
created_at |
csc_check |
customer_id |
description |
email_address |
error_message |
fax |
first_name |
id |
last_name |
merchant_id |
payment_method |
phone |
receipt |
recurring |
reference_number |
refunded |
routing_number |
settled |
source |
state |
status |
successful |
system_trace |
transaction_type |
voided |
website |
zip |
Scheduled Payment |
---|
id |
status |
created_at |
updated_at |
transaction_id |
amount |
bill_on |
description |
charge_bank_account |
card_owner_name |
bank_account_holder_first_name |
bank_account_holder_last_name |
company |
website |
phone_number |
fax_number |
address_1 |
address_2 |
city |
state |
zip |
send_receipt |
receipt_template_id |
email_address |
metadata |
amount |
send_receipt |
Method |
---|
customer_id |
method_id |
billable |
last_four |
previous_last_four |
card_exp_month |
card_exp_year |
previous_card_exp_month |
previous_card_exp_year |
Create a Rule
CREATE A RULE
Sample Request:
curl -X POST 'https://api.paymentspring.com/api/v1/webhooks/rules' \
-H 'Content-Type: application/json' \
-u private-api-key: \
-d '{
"event_resource": "invoice",
"event_type": "paid",
"constraints": {
"operator": "Constant",
"value": true
}
}'
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/rules");
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", "{"event_resource\": \"invoice\",\"event_type\": \"paid\","constraints\": { "operator\": \"Constant\",\"value\": true}}", 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",
"webhooks",
"rules"
],
"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({ event_resource: 'invoice',
event_type: 'paid',
constraints: { operator: 'Constant', value: true } }));
req.end();
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/rules")
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 = {
event_resource: "invoice",
event_type: "paid",
constraints: {
operator: "Constant",
value: true
}
}.to_json
response = http.request(request)
puts response.read_body
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{"event_resource\":\"invoice\",\"event_type\":\"paid\",\"constraints\":{"operator\":"Constant\",\"value\":true}}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,webhooks,rules", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Expected Response Data:
{
"type": "rule",
"id": "c4c77d0a03644d7e91266f05b894bd3c",
"created_at": "2018-06-20T20:47:36.414Z",
"updated_at": "2018-06-20T20:47:36.414Z",
"event_resource": "invoice",
"event_type": "paid",
"constraints": {
"value": "true",
"operator": "Constant"
},
"description": "invoice - paid"
}
POST /webhooks/rules
Creates a webhook rule.
Parameters
Parameter | Details |
---|---|
event_resource | The resource type of the event. See our list of event resources and types for a list of event_resources . |
event_type | The type of event the rule is listening for. |
constraints | The constraint body. See our webhooks documentation for more details on creating constraints. |
Error Codes
Error Code | Message |
---|---|
100004 | Event resource is required. |
100005 | Event type is required. |
400001 | Operator must be supplied in constraint data. |
400002 | Operator could not be found, please see documentation for list of operators. |
400003 | That event type is not currently supported, please see documentation for list of event types. |
List Rules
Sample Request:
curl -u private-api-key: https://api.paymentspring.com/api/v1/webhooks/rules
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/rules")
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
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,webhooks,rules", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
// NodeJS - requests using your private API key should never be made client-side
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"rules"
],
"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();
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/rules");
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);
Expected Response Data
{
"list": [
{
"type": "rule",
"id": "2e10c9493f694ede8a563178a0525a6d",
"created_at": "2018-02-02T15:55:12.207Z",
"updated_at": "2018-02-02T15:55:12.207Z",
"event_resource": "transaction",
"event_type": "created",
"constraints": {
"value": "true",
"operator": "constant"
},
"description": "transaction - created"
}
]
}
GET /webhooks/rules
Fetch all notification rules
Parameters
None
Error Codes
None
Fetch a Rule
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/webhooks/rules/709c358eeac541bba104fb3b5475d4bf
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/rules/c4c77d0a03644d7e91266f05b894bd3c");
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);
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"rules",
"c4c77d0a03644d7e91266f05b894bd3c"
],
"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("api,paymentspring,com")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "api,v1,webhooks,rules,c4c77d0a03644d7e91266f05b894bd3c", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/rules/c4c77d0a03644d7e91266f05b894bd3c")
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
Expected Response Data:
{
"type": "rule",
"id": "c4c77d0a03644d7e91266f05b894bd3c",
"created_at": "2017-10-10T19:44:05.024Z",
"updated_at": "2017-10-10T19:44:05.024Z",
"event_resource": "invoice",
"event_type": "paid",
"description": "invoice - paid",
"constraints": {
"operator": "constant",
"value": true
}
}
GET /webhooks/rules/:id
Fetch a rule.
Parameters
Error Codes
Error Code | Message |
---|---|
100001 | Rule not found. |
Update a Rule
Sample Request:
curl -u private-api-key: -X put \
-H 'Content-Type: application/json' -d \
{
"event_resource": "transaction",
"event_type": "created",
"constraints": {
"operator": "Comparison.equal",
"left_constraint": {
"key": "source",
"operator": "payload_value"
},
"right_constraint": {
"value": "mobile",
"operator": "constant"
}
}
} https://api.paymentspring.com/api/v1/webhooks/rules/709c358eeac541bba104fb3b5475d4bf
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/rules/709c358eeac541bba104fb3b5475d4bf");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"event_resource\":\"transaction\",\"event_type\":\"created\",\"constraints\":{\"operator\":\"Comparison.equal\",\"left_constraint\":{\"key\":\"source\",\"operator\":\"payload_value\"},\"right_constraint\":{\"value\":\"mobile\",\"operator\":\"constant\"}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("https");
var options = {
"method": "PUT",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"rules",
"709c358eeac541bba104fb3b5475d4bf"
],
"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({
event_resource: 'transaction',
event_type: 'created',
constraints: {
operator: 'Comparison.equal',
left_constraint: {
key: 'source',
operator: 'payload_value'
},
right_constraint: {
value: 'mobile',
operator: 'constant'
}
}
}));
req.end();
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\"event_resource\":\"transaction\",\"event_type\":\"created\",\"constraints\":{\"operator\":\"Comparison.equal\",\"left_constraint\":{\"key\":\"source\",\"operator\":\"payload_value\"},\"right_constraint\":{\"value\":\"mobile\",\"operator\":\"constant\"}}}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("PUT", "api,v1,webhooks,rules,709c358eeac541bba104fb3b5475d4bf", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/rules/709c358eeac541bba104fb3b5475d4bf")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Put.new(url)
request.basic_auth 'your-private-api-key', ''
request["Content-Type"] = 'application/json'
request.body = {
event_resource: "transaction",
event_type: "created",
constraints: {
operator: "Comparison.equal",
left_constraint: {
key: "source",
operator: "payload_value"
},
right_constraint: {
value: "mobile",
operator:"constant"
}
}
}.to_json
response = http.request(request)
puts response.read_body
Expected Response Data:
{
"type": "rule",
"id": "709c358eeac541bba104fb3b5475d4bf",
"created_at": "2017-10-10T19:44:05.024Z",
"updated_at": "2017-10-10T19:55:57.878Z",
"steward_id": "9fbfc14fc08944d1b8b3928f016c2caa",
"event_resource": "invoice",
"event_type": "paid",
"constraints": {
"operator": "Comparison.equal",
"left_constraint": {
"operator": "payload_value",
"key": "amount"
},
"right_constraint": {
"operator": "constant",
"value": 100
}
},
"description": "invoice - paid"
}
PUT /webhooks/rules/:id
Update an existing rule.
Parameters
Parameter | Details |
---|---|
event_resource | The resource type of the event. See our webhooks documentation for a list of event_resource values. |
event_type | The type of event the rule is listening for. See the full list here |
constraints | The constraint body. See our webhooks documentation for more details on creating constraints. |
description | An optional name or description for this rule |
Error Codes
Error Code | Message |
---|---|
100000 | Rule ID is required. |
100001 | Rule not found. |
100004 | Event resource is required. |
100005 | Event type is required. |
400001 | Operator must be supplied in constraint data. |
400002 | Operator could not be found, please see documentation for list of operators. |
400003 | That event type is not currently supported, please see documentation for list of event types. |
Delete a Rule
Sample Request:
curl -u private-api-key: -X DELETE
https://api.paymentspring.com/api/v1/webhooks/rules/0c61e1a287524430be7b52c392bd81e4
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/rules/c4c77d0a03644d7e91266f05b894bd3c");
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);
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,webhooks,rules,c4c77d0a03644d7e91266f05b894bd3c", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var http = require("https");
var options = {
"method": "DELETE",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"rules",
"c4c77d0a03644d7e91266f05b894bd3c"
],
"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();
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/rules/c4c77d0a03644d7e91266f05b894bd3c")
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
Expected Response Data:
{
"success": true
}
DELETE /webhooks/rules/:id
Delete a rule
Parameters
Parameter | Details |
---|---|
id | ID of the rule to delete. |
Error Codes
Error Code | Message |
---|---|
100000 | Rule ID is required. |
100001 | Rule not found. |
Create a Strategy
Sample Request:
curl -u private-api-key: -X post -H 'Content-Type: application/json' -d \
{ "target":"1234567890", "mode": "sms" } \
https://api.paymentspring.com/api/v1/webhooks/strategies
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\"mode\": \"email\",\"target\": \"test_email@example.com\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,webhooks,strategies", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/strategies");
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", "{\"mode\":\"email\",\"target\": \"test_email@example.com\"}", 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",
"webhooks",
"strategies"
],
"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({ mode: 'email', target: 'test_email@example.com' }));
req.end();
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/strategies")
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 = {mode: "email", target: "test_email@example.com"}.to_json
response = http.request(request)
puts response.read_body
Expected Response Data:
{
"type": "strategy",
"id": "1bf9008d03b04ce6ae2e2a06ee23b6d2",
"created_at": "2017-10-10T20:09:31.128Z",
"updated_at": "2017-10-10T20:09:31.128Z",
"mode": "sms",
"target": "+11234567890"
"description": "phone - 11234567890"
}
POST /webhooks/strategies
Creates a webhook strategy.
Parameters
Parameter | Details |
---|---|
mode | The mode that this strategy will use. Currently supported values: sms , email , or post_request . |
target | The destination of the notification. Example values would be: 17296368777 , hello@world.com , or https://webhooks.com for sms , email , and post_request respectively. If post_request , the URL must start with https:// (and have an SSL certificate active and available) |
description | Optional description, e.g. Director's Email or Test URL |
Error Codes
Error Code | Message |
---|---|
200000 | Target is required. |
200001 | Mode is required. |
200002 | Invalid phone number. Please provide a phone number including area code. |
200003 | Invalid email address. |
200004 | Invalid URL. |
200005 | Invalid mode. Please provide ‘sms’, ’email’, or ‘post_request’ |
List Strategies
Sample Request:
curl -u private-api-key: https://api.paymentspring.com/api/v1/webhooks/strategies
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/strategies")
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
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,webhooks,strategies", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
// NodeJS - requests using your private API key should never be made client-side
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"strategies"
],
"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();
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/strategies");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Expected Response Data
{
"list": [
{
"type": "strategy",
"id": "0e02c27088e14851983e11709d9cb57c",
"created_at": "2017-12-27T22:09:19.492Z",
"updated_at": "2017-12-27T22:09:19.492Z",
"mode": "post_request",
"target": "https://my-api.com/endpoint",
"description": "my awesome endpoint"
}
]
}
GET /webhooks/strategies
Fetch all notification strategies
Parameters
None
Error Codes
None
Fetch a Strategy
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/webhooks/strategies/709c358eeac541bba104fb3b5475d4bf
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/strategies/709c358eeac541bba104fb3b5475d4bf");
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);
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"strategies",
"709c358eeac541bba104fb3b5475d4bf"
],
"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("api,paymentspring,com")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "api,v1,webhooks,strategies,709c358eeac541bba104fb3b5475d4bf", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/strategies/709c358eeac541bba104fb3b5475d4bf")
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
Expected Response Data:
{
"type": "strategy",
"id": "709c358eeac541bba104fb3b5475d4bf",
"created_at": "2017-10-10T20:09:31.128Z",
"updated_at": "2017-10-10T20:09:31.128Z",
"mode": "sms",
"target": "+11234567890"
"description": "Grace's Phone"
}
GET /webhooks/strategies/:id
Fetch a specific strategy.
Parameters
Parameter | Details |
---|
Error Codes
Error Code | Message |
---|---|
200007 | Strategy not found. |
Update a Strategy
Sample Request:
curl -u private-api-key: -X put \
-H 'Content-Type: application/json' -d \
{
"target":"accountant@email.com",
"mode": "email",
"description":"Accounting Firm Email"
} https://api.paymentspring.com/api/v1/webhooks/strategies/8609b2db675e443a8b19e521e31db417
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/strategies/8609b2db675e443a8b19e521e31db417");
client.Authenticator = new SimpleAuthenticator("username", "your-private-api-key", "password", "");
var request = new RestRequest(Method.PUT);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("undefined", "{\"mode\": \"email\",\"target\": \"accountant@email.com\",\"description\": \"Accounting Firm Email\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require("https");
var options = {
"method": "PUT",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"strategies",
"8609b2db675e443a8b19e521e31db417"
],
"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({ mode: 'email',
target: 'accountant@email.com',
description: 'Accounting Firm Email' }));
req.end();
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\"mode\": \"email\",\"target\": \"accountant@email.com\",\"description\": \"Accounting Firm Email\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("PUT", "api,v1,webhooks,strategies,8609b2db675e443a8b19e521e31db417", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/strategies/8609b2db675e443a8b19e521e31db417")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Put.new(url)
request.basic_auth 'your-private-api-key', ''
request["Content-Type"] = 'application/json'
request.body = "{\"mode\": \"email\",\"target\": \"accountant@email.com\",\"description\": \"Accounting Firm Email\"}"
response = http.request(request)
puts response.read_body
Expected Response Data:
{
"type": "strategy",
"id": "8609b2db675e443a8b19e521e31db417",
"created_at": "2017-10-10T20:09:31.128Z",
"updated_at": "2017-10-10T20:09:31.128Z",
"mode": "email",
"target": "accountant@email.com",
"description": "Accounting Firm Email"
}
PUT /webhooks/strategies/:id
Update an existing strategy.
Parameters
Parameter | Details |
---|---|
mode | The mode that this strategy will use. Currently supported values are sms , email , or post_request . |
target | The target of the strategy. Example values would be: 7296368777 , hello@world.com , or www.webhooks.com for sms , email , and post_request respectively. |
description | an optional name or description for this strategy |
Error Codes
Error Code | Message |
---|---|
200000 | Target is required. |
200001 | Mode is required. |
200002 | Invalid phone number. Please provide a phone number including area code. |
200003 | Invalid email address. |
200004 | Invalid URL. |
200005 | Invalid mode. Please provide sms , email , or post_request |
Delete a Strategy
Sample Request:
curl -u private-api-key: -X DELETE
https://api.paymentspring.com/api/v1/webhooks/strategies/0c61e1a287524430be7b52c392bd81e4
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/strategies/c4c77d0a03644d7e91266f05b894bd3c");
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);
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,webhooks,strategies,c4c77d0a03644d7e91266f05b894bd3c", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var http = require("https");
var options = {
"method": "DELETE",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"strategies",
"c4c77d0a03644d7e91266f05b894bd3c"
],
"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();
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/strategies/c4c77d0a03644d7e91266f05b894bd3c")
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
Expected Response Data:
{
"success": true
}
DELETE /webhooks/strategies/:id
Delete a strategy
Parameters
Parameter | Details |
---|---|
id | ID of the strategy to delete. |
Error Codes
Error Code | Message |
---|---|
200006 | Strategy ID is required. |
200007 | Strategy not found. |
Add a Strategy to a Rule
Sample Request:
curl -u private-api-key: -X post \
-d {"strategy_id": "1bf9008d03b04ce6ae2e2a06ee23b6d2"} \
https://api.paymentspring.com/api/v1/webhooks/rules/b1461667fb3947f494f3cf2f1d6e5e90/strategies
// This request uses your private key, and should only be made server-side.
// Your private key should never be sent in javascript served to a user.
var http = require("https");
var options = {
"method": "POST",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"rules",
"c4c77d0a03644d7e91266f05b894bd3c",
"strategies"
],
"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({ strategy_id: '8609b2db675e443a8b19e521e31db417' }));
req.end();
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/rules/c4c77d0a03644d7e91266f05b894bd3c/strategies");
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", "{"strategy_id\":\"8609b2db675e443a8b19e521e31db417\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
import http.client
conn = http.client.HTTPConnection("api,paymentspring,com")
payload = "{\"strategy_id\":\"8609b2db675e443a8b19e521e31db417\"}"
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("POST", "api,v1,webhooks,rules,c4c77d0a03644d7e91266f05b894bd3c,strategies", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1//webhooks/rules/c4c77d0a03644d7e91266f05b894bd3c/strategies")
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 = {strategy_id:"8609b2db675e443a8b19e521e31db417"}.to_json
response = http.request(request)
puts response.read_body
Expected Response Data:
{
"success": true
}
POST /webhooks/rules/:rule_id/strategies
Creates a relation between a rule and a strategy. Having a relation between a rule and a strategy will cause the strategy to execute when all of a rule’s constraints are met.
Parameters
Parameter | Details |
---|---|
strategy_id | The id of the strategy to link the rule to. |
Error Codes
Error Code | Message |
---|---|
300000 | Strategy ID is required. |
300001 | Rule ID is required. |
300002 | Strategy ID is invalid. |
300005 | Rule ID is invalid. |
List Rules For a Strategy
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/webhooks/strategies/709c358eeac541bba104fb3b5475d4bf/rules
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/strategies/709c358eeac541bba104fb3b5475d4bf/rules")
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
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,webhooks,strategies,709c358eeac541bba104fb3b5475d4bf,rules", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
// NodeJS - requests using your private API key should never be made client-side
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"strategies",
"709c358eeac541bba104fb3b5475d4bf",
"rules"
],
"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();
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/strategies/709c358eeac541bba104fb3b5475d4bf/rules");
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);
Expected Response Data
{
"list": [
{
"type": "rule",
"id": "2e10c9493f694ede8a563178a0525a6d",
"created_at": "2018-02-02T15:55:12.207Z",
"updated_at": "2018-02-02T15:55:12.207Z",
"event_resource": "transaction",
"event_type": "created",
"constraints": {
"value": "true",
"operator": "constant"
},
"description": "transaction - created"
}
]
}
GET /webhooks/strategies/:strategy_id/rules
Fetch all notification rules that make use of a given strategy
Parameters
None
Error Codes
None
List Strategies for a Rule
Sample Request:
curl -u private-api-key:
https://api.paymentspring.com/api/v1/webhooks/rules/709c358eeac541bba104fb3b5475d4bf/strategies
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/rules/c4c77d0a03644d7e91266f05b894bd3c/strategies");
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);
var http = require("https");
var options = {
"method": "GET",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"rules",
"c4c77d0a03644d7e91266f05b894bd3c",
"strategies"
],
"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("api,paymentspring,com")
encoded_auth = b64encode(b"private-api-key:").decode("ascii")
headers = {
'Content-Type': "application/json",
'Authorization' : 'Basic %s' % encoded_auth
}
conn.request("GET", "api,v1,webhooks,rules,c4c77d0a03644d7e91266f05b894bd3c,strategies", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/rules/c4c77d0a03644d7e91266f05b894bd3c/strategies")
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
Expected Response Data
{
"list": [
{
"type": "strategy",
"id": "0e02c27088e14851983e11709d9cb57c",
"created_at": "2017-12-27T22:09:19.492Z",
"updated_at": "2017-12-27T22:09:19.492Z",
"mode": "post_request",
"target": "https://my-api.com/endpoint",
"description": "my awesome endpoint"
}
]
}
GET /webhooks/rules/:rule_id/strategies
Fetch all notification strategies tied to a given rule.
Parameters
None
Error Codes
None
Delete a Rule-Strategy Relation
Sample Request:
curl -u private-api-key: -X DELETE
https://api.paymentspring.com/api/v1/webhooks/rules/b1461667fb3947f494f3cf2f1d6e5e90/strategies/1bf9008d03b04ce6ae2e2a06ee23b6d2
var client = new RestClient("https://api.paymentspring.com/api/v1/webhooks/rules/c4c77d0a03644d7e91266f05b894bd3c/strategies/1bf9008d03b04ce6ae2e2a06ee23b6d2");
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);
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,webhooks,rules,c4c77d0a03644d7e91266f05b894bd3c,strategies,1bf9008d03b04ce6ae2e2a06ee23b6d2", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
var http = require("https");
var options = {
"method": "DELETE",
"hostname": [
"api",
"paymentspring",
"com"
],
"path": [
"api",
"v1",
"webhooks",
"rules",
"c4c77d0a03644d7e91266f05b894bd3c",
"strategies",
"1bf9008d03b04ce6ae2e2a06ee23b6d2"
],
"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();
require 'uri'
require 'net/http'
url = URI("https://api.paymentspring.com/api/v1/webhooks/rules/c4c77d0a03644d7e91266f05b894bd3c/strategies/1bf9008d03b04ce6ae2e2a06ee23b6d2")
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
Expected Response Data:
{
"success": true
}
DELETE /webhooks/rules/:rule_id/strategies/:strategy_id
Delete a relation between a rule and a strategy. This means that when the rule matches an event, that notification strategy will no longer be used.
Parameters
Parameter | Details |
---|---|
rule_id | the UUID of the rule in question (passed in through the URL) |
strategy_id | the UUID of the strategy in question (passed in through the URL) |
Error Codes
Error Code | Message |
---|---|
100001 | Rule not found. |
200007 | Strategy not found. |
300003 | Relation not found. |
Custom Fields
Custom fields (also referred to as metadata
) give you an opportunity to insert
your own attributes into a record.
You can add custom fields onto:
- transactions
- customers
- billing subscriptions
- billing plans
- payment widgets
These fields generally have a key of metadata
and a value of a JSON object
literal, e.g. { "internal_donor_id": "abc123" }
.
These fields are also merged. For example, when charging a customer, any custom fields provided when running the charge will be merged with (and potentially override, in the event of conflict) custom fields on the customer record.
When enrolling a customer in a plan, the subscription record will, by default, inherit any custom fields on the plan record. Those fields will be passed in with each billing, and will merge with any custom fields on the customer record (the customer fields will override the fields on the billing in the event of conflict).
Customers created through a payment widget will inherit the custom fields from that widget, as will be the case with recurring billings created through a payment widget.
You might use custom fields to:
- categorize a transaction (e.g. "donation" or "membership dues")
- include extra information about the payer (e.g. t-shirt size)
- tie a transaction to a fundraising campaign
- tie a
Customer
record in Nelnet Payment Services to a customer record in your own CRM (such as Salesforce, Constant Contact, or Raiser's Edge). - provide supplemental transaction information (identifying a transaction as payment for a work order or invoice in your own system).
You can also search for transactions by custom fields on the transaction search page. A search
query of "type": "donation"
(note the quotation marks) will find all
transactions you've categorized as donations. A search query of
"salesforce_id": "12345abc"
will find all transactions tied to that Salesforce
record. You could also search for "salesforce_id"
to find all transactions
with a salesforce_id
attribute, regardless of which ID is present.
Finally, you can use the nested_payload_value
operator within webhooks to
selectively send notifications when certain metadata values are present. For
example, if your metadata were something to the effect of { "type":
"tuition_payment", "level": "elementary" }
, you could set up two separate
webhooks rules (one for a type of tuition_payment
, one for a level of
elementary
) and send a notification both to the person in charge of tuition
and the person who handles enrollment for an elementary school. This gives you
some of the benefits of an API integration without needing to write your own API
integration (and in the event you do have an API integration, your payments
intelligence gets all the more powerful).
Logged Events
Retrieve All Logged Events
RETRIEVE ALL LOGGED EVENTS
Sample Request:
curl -X GET 'https://api.paymentspring.com/api/v1/logs' \
-u private-api-key: \
-d '{
"limit": 3,
"offset": 0
}'
Expected Response Data:
{
"list": [
{
"id": "51e58c3b44b36fe3b600006d",
"class": "logged_event",
"date": "2013-07-16T18:08:59Z",
"subject_class": "token",
"subject_id": null,
"subject": {},
"action": "/tokens",
"method": "POST",
"request": {
"card_number": "XXXX-XXXX-XXXX-XXXX",
"card_exp_month": "1",
"card_exp_year": "2020"
},
"response": {
"id": "1a7afecc9c",
"class": "token",
"card_type": "visa",
"card_owner_name": null,
"last_4": "1111",
"card_exp_month": 1,
"card_exp_year": 2020
},
"status": null
},
{
"id": "51e58c3b44b36fe3b600006d",
"class": "logged_event",
"date": "2013-07-16T18:08:59Z",
"subject_class": "token",
"subject_id": null,
"subject": {},
"action": "/tokens",
"method": "POST",
"request": {
"card_number": "XXXX-XXXX-XXXX-XXXX",
"card_exp_month": "1",
"card_exp_year": "2020"
},
"response": {
"id": "1a7afecc9c",
"class": "token",
"card_type": "visa",
"card_owner_name": null,
"last_4": "1111",
"card_exp_month": 1,
"card_exp_year": 2020
},
"status": null
},
{
"id": "51e58c3b44b36fe3b600006d",
"class": "logged_event",
"date": "2013-07-16T18:08:59Z",
"subject_class": "token",
"subject_id": null,
"subject": {},
"action": "/tokens",
"method": "POST",
"request": {
"card_number": "XXXX-XXXX-XXXX-XXXX",
"card_exp_month": "1",
"card_exp_year": "2020"
},
"response": {
"id": "1a7afecc9c",
"class": "token",
"card_type": "visa",
"card_owner_name": null,
"last_4": "1111",
"card_exp_month": 1,
"card_exp_year": 2020
},
"status": null
}
],
"meta": {
"limit": 3,
"offset": 0,
"total_results": 9000
}
}
GET /logs
Gets a log of the most recent events.
Parameters
Parameter | Details |
---|---|
limit | Maximum number of events to return. |
offset | Event index to begin returning events 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. |
Retrieve All Customer Logged Events
RETRIEVE ALL CUSTOMER LOGGED EVENTS
Sample Request:
curl -X GET 'https://api.paymentspring.com/api/v1/customers/log' \
-u private-api-key: \
-d '{
"limit": 3,
"offset": 0
}'
Expected Response Data:
{
"list": [
{
"id": "51e58c3b44b36fe3b600006d",
"class": "logged_event",
"date": "2013-07-16T18:08:59Z",
"subject_class": "customer",
"subject_id": "fe37ce",
"subject": {},
"action": "/customers/fe37ce",
"method": "POST",
"request": {
"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",
"card_number": "XXXX-XXXX-XXXX-XXXX",
"card_exp_month": "5",
"card_exp_year": "2022",
"country": "USA"
},
"response": {
"id": "fe37ce",
"created_at": "2013-07-16T20:27:57+00:00",
"updated_at": "2013-07-16T20:27:59+00:00",
"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": null,
"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
},
"status": null
},
{
"id": "51e58c3b44b36fe3b600006d",
"class": "logged_event",
"date": "2013-07-16T18:08:59Z",
"subject_class": "customer",
"subject_id": "fe37ce",
"subject": {},
"action": "/customers/fe37ce",
"method": "POST",
"request": {
"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",
"card_number": "XXXX-XXXX-XXXX-XXXX",
"card_exp_month": "5",
"card_exp_year": "2022",
"country": "USA"
},
"response": {
"id": "fe37ce",
"created_at": "2013-07-16T20:27:57+00:00",
"updated_at": "2013-07-16T20:27:59+00:00",
"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": null,
"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
},
"status": null
},
{
"id": "51e58c3b44b36fe3b600006d",
"class": "logged_event",
"date": "2013-07-16T18:08:59Z",
"subject_class": "customer",
"subject_id": "fe37ce",
"subject": {},
"action": "/customers/fe37ce",
"method": "POST",
"request": {
"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",
"card_number": "XXXX-XXXX-XXXX-XXXX",
"card_exp_month": "5",
"card_exp_year": "2022",
"country": "USA"
},
"response": {
"id": "fe37ce",
"created_at": "2013-07-16T20:27:57+00:00",
"updated_at": "2013-07-16T20:27:59+00:00",
"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": null,
"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
},
"status": null
}
],
"meta": {
"limit": 3,
"offset": 0,
"total_results": 9000
}
}
GET /customers/log
Gets a log of the most recent events involving customers.
Parameters
Parameter | Details |
---|---|
limit | Maximum number of events to return. |
offset | Event index to begin returning events 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. |
Retrieve All Transaction Logged Events
RETRIEVE ALL TRANSACTION LOGGED EVENTS
Sample Request:
curl -X GET 'https://api.paymentspring.com/api/v1/transactions/log' \
-u private-api-key: \
-d '{
"limit": 3,
"offset": 0
}'
Expected Response Data:
{
"list": [
{
"id": "5eb03466418aab0020000008",
"class": "logged_event",
"date": "2020-05-04T15:27:33.635Z",
"subject_class": "transaction",
"subject_id": "6826e97491ce46d9817c4a33b782444d",
"subject": {},
"action": "/api/v1/charge",
"method": "POST",
"request": {
"customer_id": "e510f5",
"amount": 2001
},
"response": {
"class": "transaction",
"id": "6826e97491ce46d9817c4a33b782444d",
"payment_method": "credit_card",
"created_at": "2020-05-04T15:27:33.840Z",
"merchant_id": "3a3478b8e329_test",
"amount_authorized": 2001,
"amount_refunded": 0,
"amount_settled": 2001,
"amount_failed": 0,
"transaction_type": "sale",
"reference_number": "518e16da-c51c-4788-83f2-ebc77b0e3700",
"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": "e510f5",
"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": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"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": "John Doe",
"recurring": false,
"processed_at": null,
"refunds": []
},
"status": null
{
"id": "5eb02d34418aab0020000006",
"class": "logged_event",
"date": "2020-05-04T14:56:51.781Z",
"subject_class": "transaction",
"subject_id": "9dc6689889634493b0c3940a81dc8a15",
"subject": {},
"action": "/api/v1/charge/9dc6689889634493b0c3940a81dc8a15/cancel",
"method": "POST",
"request": {
"amount": 2006
},
"response": {
"class": "transaction",
"payment_method": "credit_card",
"id": "9dcXXXX-XXXX-XXXX-XXXXb0c3940a81dc8a15",
"description": null,
"merchant_id": "3a3478b8e329_test",
"created_at": "2020-05-04T14:54:01.490Z",
"amount_settled": 2006,
"amount_refunded": 2006,
"amount_failed": 0,
"account_holder_name": "Ada Lovelace",
"status": "REFUNDED",
"customer_id": null,
"receipt": {},
"company": null,
"website": null,
"card_owner_name": "Ada Lovelace",
"email_address": null,
"email": null,
"address_1": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"country": "USA",
"phone": null,
"fax": null,
"source": "web",
"recurring": false,
"successful": true,
"metadata": null,
"error_message": null,
"amount_authorized": 2006,
"transaction_type": "sale",
"reference_number": "f0268f04-c99e-40ff-a67a-6b39453beb23",
"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,
"first_name": null,
"last_name": null,
"csc_check": "0",
"avs_address_check": "0",
"processed_at": null,
"refunds": [
{
"amount": 2006,
"status": "settled",
"error_message": {},
"created_at": "2020-05-04T14:56:51.973Z"
}
]
},
"status": null
},
{
"id": "5ea1d97e53e54d002e000007",
"class": "logged_event",
"date": "2020-04-23T18:07:56.920Z",
"subject_class": "transaction",
"subject_id": "b98cacddeab14cf6bca5010786012fd9",
"subject": {},
"action": "/api/v1/charge",
"method": "POST",
"request": {
"customer_id": "437312",
"amount": 414
},
"response": {
"class": "transaction",
"id": "b98cacddeab14cf6bca5010786012fd9",
"payment_method": "credit_card",
"created_at": "2020-04-23T18:07:57.380Z",
"merchant_id": "3a3478b8e329_test",
"amount_authorized": 414,
"amount_refunded": 0,
"amount_settled": 414,
"amount_failed": 0,
"transaction_type": "sale",
"reference_number": "9535145",
"description": null,
"card_type": "visa",
"card_number": "************1111",
"card_exp_month": "12",
"card_exp_year": "2021",
"authorized": true,
"settled": true,
"refunded": false,
"voided": false,
"system_trace": null,
"status": "SETTLED",
"customer_id": "437312",
"receipt": {},
"company": null,
"website": null,
"card_owner_name": "31789479-d28e-4915-81af-9a12d43c720b",
"email_address": null,
"email": null,
"first_name": "cfaa70b3fa1f285b1f8a",
"last_name": "cXXXX-XXXX-XXXX-XXXXccf0a",
"address_1": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"country": "USA",
"phone": null,
"fax": null,
"csc_check": "0",
"avs_address_check": null,
"source": "web",
"successful": true,
"metadata": {},
"error_message": null,
"account_holder_name": "31789479-d28e-4915-81af-9a12d43c720b",
"recurring": false,
"refunds": []
},
"status": null
}
],
"meta": {
"limit": 3,
"offset": 0,
"total_results": 9000
}
}
GET /transactions/log
Gets a log of the most recent events.
Parameters
Parameter | Details |
---|---|
limit | Maximum number of events to return. |
offset | Event index to begin returning events 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. |
Retrieve a Customer's Logged Events
RETRIEVE A CUSTOMER’S LOGGED EVENTS
Sample Request:
curl -X GET 'https://api.paymentspring.com/api/v1/customers/6e3d8d/log' \
-u private-api-key: \
-d '{
"limit": 3,
"offset": 0
}'
Expected Response Data:
{
"list": [
{
"id": "51e58c3b44b36fe3b600006d",
"class": "logged_event",
"date": "2013-07-16T18:08:59Z",
"subject_class": "customer",
"subject_id": "",
"subject": {},
"action": "/customers/",
"method": "POST",
"request": {
"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",
"card_number": "XXXX-XXXX-XXXX-XXXX",
"card_exp_month": "5",
"card_exp_year": "2022",
"country": "USA"
},
"response": {
"id": "",
"created_at": "2013-07-16T20:27:57+00:00",
"updated_at": "2013-07-16T20:27:59+00:00",
"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": null,
"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
},
"status": null
}
],
"meta": {
"limit": 3,
"offset": 0,
"total_results": 1
}
}
GET /customers/:id/log
Gets a log of the most recent events involving a specific customer.
Parameters
Parameter | Details |
---|---|
limit | Maximum number of events to return. |
offset | Event index to begin returning events from, useful for pagination. |
id | ID of the customer to retrieve events from. |
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. |
Retrieve a Transactions Logged Events
RETRIEVE A TRANSACTION’S LOGGED EVENTS
Sample Request:
curl -X GET
'https://api.paymentspring.com/api/v1/transactions/e5fb751593864854a76195f60c361d7c/log' \
-u private-api-key: \
-d '{
"limit": 3,
"offset": 0
}'
Expected Response Data:
{
"list": [
{
"id": "5eb03466418aab0020000008",
"class": "logged_event",
"date": "2020-05-04T15:27:33.635Z",
"subject_class": "transaction",
"subject_id": "6826e97491ce46d9817c4a33b782444d",
"subject": {},
"action": "/api/v1/charge",
"method": "POST",
"request": {
"customer_id": "e510f5",
"amount": 2001
},
"response": {
"class": "transaction",
"id": "6826e97491ce46d9817c4a33b782444d",
"payment_method": "credit_card",
"created_at": "2020-05-04T15:27:33.840Z",
"merchant_id": "3a3478b8e329_test",
"amount_authorized": 2001,
"amount_refunded": 0,
"amount_settled": 2001,
"amount_failed": 0,
"transaction_type": "sale",
"reference_number": "518e16da-c51c-4788-83f2-ebc77b0e3700",
"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": "e510f5",
"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": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"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": "John Doe",
"recurring": false,
"processed_at": null,
"refunds": []
},
"status": null
}
],
"meta": {
"limit": 3,
"offset": 0,
"total_results": 1
}
}
GET /transactions/:id/log
Gets a log of the most recent events involving a specific transaction.
Parameters
Parameter | Details |
---|---|
limit | Maximum number of events to return. |
offset | Event index to begin returning events from, useful for pagination. |
id | ID of the transaction to get events associated with. |
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. |