For the examples below, we've added the equivalent calls using the new API (where available). While we don't have any plans to disable the old API, we do suggest switching over to this faster, more powerful version. Please note that with the new API, authentication is handled via the request headers (as opposed to being passed in the POST data). Please refer to the documentation page for more information.

All of our example code can be found on GitHub

Table of Contents

1. Sale - Charge a transaction
2. List Gateways - List gateways in account
3. List Invoices - List invoice templates in account

Frequently Asked Questions

Introduction

The Payments API accepts credit card data securely through https allowing you to run transactions and create subscriptions and payment plans on the fly. This makes it easy to use ONTRAPORT as your payment and customer management system without having to build or integrate a 3rd party shopping cart or other order management system. In order to use the Payments API, you must submit a standard HTTP (Hypertext Transfer Protocol) POST request to the ONTRAPORT Payments API server.

Authentication

To use the Payments API, you need to obtain an ONTRAPORT API App ID and API Key. These can be generated within your ONTRAPORT account by going to Admin > API Settings and Key Manager.

Note that if you have not done so already, you will need to submit a request for access to the API. Once access is granted, you can generate as many API App ID/API Key combinations as you want. For more information on how to generate a key or how to request access, please contact customer support.

Requests Overview

Currently we use REST Requests to handle requests to the web server. Typically XML data is posted via POST to the endpoint URI and a 'success', 'failure' or 'return data' will be returned depending on the type of call. REST supports a number of web server environments for development, and it's a pretty easy system to learn. Learn all about REST.

A typical request consists of two parts; a URL and post data.

The post URL is comprised of the API address (in this case, https://api.ontraport.com/payments.php) along with the following parameters.

A basic request should resemble the following:

Request URL:
https://api.ontraport.com/payments.php

POST data:
appid=abc12345&key=xyz54321&reqType=add&return_id=1&data=[data string]

In addition to the URL, the "sale" request requires some data be passed. The basic structure is as follows:

{
  "products":[
    {
      "quantity":"1",
      "price":"459.00",
      "type":"single",
      "id":"1"
    },
    {
      "id":"1",
      "quantity":"1",
      "type":"subscription",
      "unit":"week",
      "price":"35.00"
    },
    {
      "id":"1",
      "quantity":"1",
      "type":"payment_plan",
      "unit":"month",
      "price":"100.00",
      "payment_count":"4"
    }
  ],
  "contact_id":129278,
  "invoice_id":1,
  "gateway_id":1720,
  "card_details": {
    "card_number":"4111111111111111",
    "card_code":"123",
    "card_expire_month":5,
    "card_expire_year":2017,
    "contact_firstname":"Patrick",
    "contact_lastname":"Marleau",
    "contact_email":"PM12@test.com",
    "contact_address":"Test Address",
    "contact_city":"Santa Barbara",
    "contact_state":"CA",
    "contact_zip":"93105",
    "contact_country":"US"
    }
}

Returns

The Payments API will return id's to indicate the status of the charge attempt.

1 - Good
2 - Bad data
3 - Something wrong with the gateway account
4 - Problem with our api
5 - Problem with the remote gateway api
6 - Problem with gateway credentials
7 - Problem with the connection

Maximum Requests per Minute

Up to 180 requests per minute are allowed per ONTRAPORT account

Request Types

Sale

Request: sale

Action: Charges a transaction for the contact.

Return: (JSON) result code, oap transaction id, external transaction id, result message, contact id

Required Data: Billing information, contact ID, invoice ID, gateway ID, product(s) array

Optional Data: "card_detail" object containing billing information, "use_card_on_file" (boolean) set to "yes." One of these two must be sent in order to submit a payment. If "use_card_on_file" flag is set and contact has no credit card information on file, the transaction will fail.

Note: The "products" key is a multidimentional array of products. Each product being it's own array.

Subscriptions: To setup a subscription, set the "type" key on the product to "subscription". An addional key "unit" will need to be included with the value equal to when the subscription recurs ('day', 'week', 'month', 'quarter', 'year').

Payment Plans: To setup a payment plan, set the "type" key on the product to "payment_plan". Two additional keys "unit" and "payment_count" will need to be included with the values equal to when payments will be charged ('day', 'week', 'month', 'quarter', 'year') and the number of payments to be made respectively.

JSON NEW API

{
    "products": [
        {
            "quantity": "1",
            "price": "49.00",
            "type": "single",
            "id": "1"
        },
        {
            "id": "1",
            "quantity": "1",
            "type": "subscription",
            "unit": "week",
            "price": "35.00"
        },
        {
            "id": "1",
            "quantity": "1",
            "type": "payment_plan",
            "unit": "month",
            "price": "100.00",
            "payment_count": "4"
        }
    ],
    "contact_id": 49,
    "invoice_id": 1,
    "gateway_id": 1720,
    "card_details": {
        "card_number": "4111111111111111",
        "card_code": "123",
        "card_expire_month": 5,
        "card_expire_year": 2017,
        "contact_firstname": "Patrick",
        "contact_lastname": "Willis",
        "contact_email": "pw52@test.com",
        "contact_address": "123 Test St",
        "contact_city": "Santa Barbara",
        "contact_state": "CA",
        "contact_zip": "93105",
        "contact_country": "US"
    }
}

URL: http://api.ontraport.com/1/transaction/processManual

Method: POST

Data:
{
   "objectID":0,
   "contact_id":123456,
   "chargeNow":"chargeNow",
   "trans_date":1431551200,
   "invoice_template":1,
   "gateway_id":1,
   "offer":{
      "products":[
         {
            "quantity":1,
            "owner":1,
            "tax":false,
            "shipping":false,
            "id":40,
            "uid":0,
            "price":[
               {
                  "price":"49",
                  "payment_count":1,
                  "unit":"day"
               }
            ]
         }
      ]
   },
   "billing_address":{
      "address":"123 Test st",
      "address2":"Unit 123",
      "city":"Santa Barbara",
      "state":"CA",
      "zip":"93103",
      "country":"US"
   },
   "payer":{
      "ccnumber":4111111111111111,
      "expire_month":5,
      "expire_year":2017,
      "code":123
   },
   "hasTaxes":false,
   "hasShipping":false,
   "delay":0
}

Doc:
http://api.ontraport.com/doc/#!/transactions/processManual

List Gateways

Request: list_gateways

Return: (JSON) list of gateways in account with corresponding IDs

Required Data: None

XML NEW API

url: https://api.ontraport.com/payments.php

post args: "appid={APP_ID}&key={API_KEY}&reqType=list_gateways"

URL: http://api.ontraport.com/1/objects?ObjectID=70

Method: GET

Doc:
http://api.ontraport.com/doc/#!/objects/getObjects

List Invoices

Request: list_invoices

Return: (JSON) list of invoice templates in account

Required Data: None

XML NEW API

url: https://api.ontraport.com/payments.php

post args: "appid={APP_ID}&key={API_KEY}&reqType=list_invoices"

URL: http://api.ontraport.com/1/objects?ObjectID=46

Method: GET

Doc:
http://api.ontraport.com/doc/#!/objects/getObjects

FAQs