Company Blog Support
Martin Cogburn
posted

Contents

    Back to Top

    Payments API

    UPDATE:

    We have a new and improved API for ONTRAPORT users. You can find the documentation HERE. 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.

    Parameter Data Description
    Appid string (Required) You must first generate an App ID to use the API. Instructions to generate a key are in the "Authentication" section (above).
    Key string (Required) This is a unique key that you can generate for use in your App ID.
    reqType string (Required) Request type. See "Request Types" (below) for information detailing each request type.
    data string (Required only in "sale" requests) JSON data

    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.

    List Gateways

    Request: list_gateways

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

    Required Data: None

    List Invoices

    Request: list_invoices

    Return: (JSON) list of invoice templates in account

    Required Data: None

    FAQs

    Articles in this section

    Have more questions? Submit a request

    Comments

    Powered by Zendesk