NAV
  • Getting Started With Our API

    • Getting Started With Our API

    This guide is a quick introduction to our API and to some preferred workflows; call it “The Nelnet Payment Services Way”, if you like. The goal here is for you, the integrator, to feel confident that you are going about things the right way and that you are unlikely to be eaten by bears while following our advice. Ready? Let’s begin.

    The first distinction we should make is the difference between one-time and repeat actions. We use token to refer to ephemeral card-data (which disappears after use or after 15 minutes, whichever comes first), and we use customer to refer to permanently stored card-data. Other payment gateways and services may use different terms.

    Per our tokenization script’s instructions, you’ll want to create a token client-side (i.e. with Javascript, in the browser) instead of ever letting card-data touch your servers. This ensures data integrity, in that if your server is ever compromised, there is no way for a malicious actor to get access to card data. It requires some Javascript on your end to actually submit the charge once you have the token, but regardless, this is the route you’ll want to take.

    How do I know if I even need an API integration?

    Depending on how much you’re willing to do by hand, you may never need a true API integration. Using our merchant dashboard, you can securely create customers, store payment methods, and charge cards all from the comfort of your web browser. But if you have more specific needs or workflows, if you want to automate some of these tasks, or if you want to have a payment presence in your own website that fits neatly into your complex workflows (checking out on an eCommerce site, or signing up for a SaaS product), you’ll probably need an API integration. That said, if your payments and integration needs are simple, it may be worth checking out our checkout button and form integrations, as those provide a quick integration, albeit with less potential for customizability.

    The Gateway team makes use of a lot of different tools when building our API (and when working with other APIs), including Postman, which is a free API integration tool (it can even help you write your code!).

    We also recommend working against our sandbox first (sandbox accounts are free and take just a few seconds to set up), as you’ll be able to try things out without risk of accidentally charging anyone’s card.

    Some Things to Know Before You Start

    Nelnet Payment Services offers two accounts to all merchants; Sandbox accounts, and Live accounts. On the dashboard, you can switch between them with the push of a button. Live accounts are the real deal — you submit a payment, and it gets sent to the processor (and to the card authorities, and to the banks, and so on). Sandbox accounts do not submit live transactions, but otherwise do everything else you might need to do. Use a sandbox account for testing (both on the dashboard and through the API), as everything you do there will be self-contained. This way your live account only has real data, and is not cluttered with any sort of test data.

    You also have public and private keys.

    Your public key is only for making tokens, which stand in for card information. You can include your public key in client-side javascript, as if it is compromised, all that anyone can do is create tokens, which would then, in this case, sit idle for 24 hours and then be deleted.

    Your private key is for all other API interactions: running charges, creating invoices, refunding payments, and creating customers (to name a few). If your private key is compromised, your entire account is at risk, so make sure to keep it secure.

    Your test API keys create test data within the sandbox. Your live API keys create live data.

    When building your API integration, start with test keys and work with the sandbox. Once you’re ready to go live, swap out your test keys for live keys (you can still use your test keys in local development, or on your staging environment, or anywhere else you want to test features without running the risk of accidentally running real charges).

    API Integration #1: Submitting a one-time charge

    Suppose you have an online donation form, and you want to accomplish the following:

    Here are roughly the steps you’ll take:

    1. The customer fills out your donation form and clicks “Submit”
    2. Our tokenization script, coupled with your public key, submits their card information and creates a token.
    3. Upon token creation, your defined callback submits that token to your server
    4. Your server, using your private key, submits the token and an amount to our charge endpoint, making sure to indicate that you want a receipt to be sent along with it.
    5. Upon a successful charge, you store the transaction ID and any other relevant information on your server

    You can also use our Checkout Form/Button widgets, which do most of this work for you. But you’ll still need to provide some javascript to communicate the final transaction information to your server.

    API Integration #2: Creating a customer with a stored payment method

    You have a business with a roster of existing customers, and you charge them for services rendered (perhaps you groom their dogs, or perhaps you maintain their solar farms!). When a customer signs up with you, they save their payment information so you can bill them automatically.

    Here are roughly the steps you would take:

    1. Per above, a customer fills out their relevant information on a form and clicks “Submit”.
    2. Our tokenization script, coupled with your public key, submits their card information and creates a token.
    3. Upon token creation, your defined callback submits that token to your server, along with any other information you might need to store.
    4. You create a customer, but instead of providing cardholder information (or bank account information), you provide your token. Our service uses that token to create the customer with securely encrypted payment information
    5. You store the customer ID (which we send back at the time of creation), as well as any other information you might need to store (excluding the customer’s payment information) on your server.
    6. Away you go!

    You can store biographical information about a customer (name, address, etc.) on our system, but you aren’t required to at all. All customers are assigned a unique ID. If you prefer to only use Nelnet Payment Services to store payment information, and to otherwise store all other information on your server, you certainly can do that. It’ll just mean you will not be able to search by customer name, and instead will have to pull the customer ID from your system. Our suggestion is that you store biographical information on the Nelnet Payment Services server as well to make it easier to find the information you need later.

    API Integrations #3 – ???: Some Other Possibilities

    Let’s say you are organizing a walk-a-thon. You could pass around a sign-up sheet (paper, even!) to collect email addresses of donors, then send them each an invoice with a single line item, with a price of whatever they agreed to donate per mile and a quantity of the number of miles you walked (or jogged. You could jog). You would have to track the agreed-upon price and the number of miles on your own (we do not yet have a walk-a-thon tool).

    Or you could build an online sign-up page, have them enter their payment information, create a custom receipt template that tells them exactly how far you walked, and charge them straightaway, making sure to send that receipt (make sure you have permission for this first!).

    Have any feedback on this page? Let us know!