NAV
json

Introduction

 *******     *******   ****     **** ** **********
/**////**   **/////** /**/**   **/**/**/////**///
/**   /**  **     //**/**//** ** /**/**    /**
/*******  /**      /**/** //***  /**/**    /**
/**///**  /**      /**/**  //*   /**/**    /**
/**  //** //**     ** /**   /    /**/**    /**
/**   //** //*******  /**        /**/**    /**
//     //   ///////   //         // //     //

     **     *******  **
    ****   /**////**/**
   **//**  /**   /**/**
  **  //** /******* /**
 **********/**////  /**
/**//////**/**      /**
/**     /**/**      /**
//      // //       //

Welcome to the Romit API V1 documentation which is currently under active development.

The focus of this API is to give users the ability to grant merchant applications permission to their wallet through the familiarity of an OAuth 2 gateway.

This method empowers application developers to enroll and modify customer wallets while also giving users the tools and information necessary to make informed decisions regarding their online payment activity.

A picture can be worth a thousand words so please review a sample transaction flow diagram before integration.

Note: The API is for highly customized applications and developers seeking a simpler integration should consider our Merchant Tools

Making Requests

Successful Unauthenticated GET

  GET https://api.romit.io/example
  Content-type: application/json
  Authorization: Bearer e25da466-0420-4aa5-acef-1920b07545a6
  {
      "success": true,
      "error": null,
      "response":
          {
              "foo": "bar"
          }
  }

Successful Authenticated POST

  POST https://api.romit.io/example
  Content-type: application/json
  Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
  {
      "success": true,
      "error": null,
      "response":
          {
              "foo": "bar"
          }
  }

Requests must be made over SSL/TLS (HTTPS). All non-secure requests are ignored as no services listen on HTTP.

Authorization

All requests and response bodies are JSON encoded. A Content-type: application/json header is required for all requests.

All requests require either an OAuth access_token or an OAuth client_token. Both are passed via the Authorization HTTP header:

Authorization: Bearer {access_token} or {client_token}

Requests that require a client_token can request one here.

API Endpoint

Production: https://api.romit.io/v1

Sandbox: https://api.sandbox.romit.io/v1

Errors

Unsuccessful Response Example:

     {
         "success": false,
         "error":
            {
                "code": "err.invalid_arguments",
                "locale": "en-US",
                "message": "Invalid request"
            },
         "response": null
     }

When an API request results in an error, Romit typically responds with an HTTP status code outside of 2xx and a response body containing a JSON object containing an error Message, with success set to false and response being null.

General Errors

The following errors are common across all API endpoints.

Error Code Description
err.rate_limit_exceeded Money movement transactions are rate limited to 1 request every 5 seconds
err.access_denied The client or user does not have access to the requested resource.
err.invalid_arguments The request object is invalid
err.unexpected_error An unexpected internal error occurred
err.fatal_error An internal fatal error occurred

Error responses use HTTP status codes to indicate the type of error. The JSON response body will contain an error code and a description of the error.

OAuth

Romit’s API gives the ability to interact with a user’s Romit wallet and act on its behalf to send money, list transactions, and more. To do so, an application needs to seek authorization from the user.

Romit implements an OAuth 2.0 style flow to facilitate this. Similar to Facebook and Twitter’s authentication flow, the user is first presented with a permission dialog and the types of resources it is seeking to gain access to at which point they can either approve the permissions requested or reject them.

Unlike traditional OAuth, however, Romit seeks permission on behalf of the merchant application by either a text message or a phone call to the customer instead of redirecting the user to an OAuth web page. This is to ease the integration burden and better support existing checkout payment flows that already exist today.

If the user responds to the text message or phone call with an approval, a code is sent to your application from the provided redirect_uri, which will then be exchanged for an access_token and possibly a refresh_token if the merchant application requested one.

The access_token can then be used to make API calls which require user authentication like Transfer.

Token Lifecycle

Access Tokens are short lived: 1 hour.

Refresh Tokens are long lived: 60 days.

A refresh token can be used within 60 days to generate a new access_token and refresh_token pair. So long as the authorization is refreshed at least once every 60 days, your application can maintain authorization indefinitely without requiring the user to re-authorize so long as the user does not revoke your permission through their dashboard.

Requesting User Authorization

Request:

    POST /oauth
    Content-type: application/json
    Authorization: Bearer e25da466-0420-4aa5-acef-1920b07545a6
    {
        "client_id": "e8ec8917-1852-4ca1-96d1-af4bf6dc1407",
        "response_type": "code",
        "redirect_uri": "https://example.com/auth/romit",
        "scope": [
            "DEFAULT",
            "BANKING_READ",
            "BANKING_WRITE",
            "IDENTITY_READ",
            "IDENTITY_WRITE",
            "TRANSFER_READ",
            "TRANSFER_WRITE",
            "USER_READ",
            "USER_WRITE",
            "SUBSCRIPTION_READ",
            "SUBSCRIPTION_WRITE",
            "PLAN_READ",
            "PLAN_WRITE",
            "INVOICE_READ",
            "INVOICE_WRITE"
        ],
        "state": "my-secret-state-123456789",
        "phone": "+17755551212",
        "email": "chadd@example.com",
        "first": "Chadd",
        "last": "Sexington",
        "currency": "USD",
        "refresh": true,
        "call": false
    }

Response:

     {
        "success": true,
        "error": null,
        "response": {
        }
     }

To start the OAuth process, make a POST call with user information, the permissions your application seeks, how it will contact the customer, and if the application seeks a refresh token. It includes the permissions your application requires (scope), the application itself (client_id), where the user code will be sent after a successful authorization (redirect_uri), and the response you are seeking (response_type).

Request

POST https://api.romit.io/v1/oauth

Parameter Description
client_id The application key
response_type Must be set to code
redirect_uri URL where the callback payload will return the code that is redeemed for an access token.
scope Permissions the application is requesting. See below for a list of available scopes. Scopes are delimited by a pipe:
state A unique string passed in for this session that will be returned with the user code.
phone E164 phone number of the user
email The email address of the user
first Legal first name
last Legal last name
currency The currency type the customer will be transacting in.
refresh If set to true, will request a refresh token pair to be returned.
call If set to true, will make a telephone call to the user and seek application permission. If set to false, it will send a text message.

Callback Response

It will take time for the user to respond to the phone call or text message initiated by this request. As a result, this endpoint will respond immediately and when the user responds to the request, it will then POST to an endpoint you set in the redirect_uri with the following payload:

Callback Response:

     {
        "success": true,
        "error": null,
        "response": {
            "code":"ad3f0db2-62b6-4cf4-9027-14829d33cfd2",
            "state":"my-secret-state-123456789"
        }
     }
Parameter Description
code The authorization code that is redeemed for an access token.
state The unique string passed in the request for authorization call.

OAuth Scopes

Applications may request the following permission scopes when generating an access token:

Scope Name Description
DEFAULT Access to basic information
BANKING_READ Read access to Banking
BANKING_WRITE Write access to Banking
IDENTITY_READ Read access to Identity
IDENTITY_WRITE Write access to Identity
TRANSFER_READ Read access to Transfer
TRANSFER_WRITE Write access to Transfer
USER_READ Read access to User
USER_WRITE Write access to User
SUBSCRIPTION_READ Read access to Subscription
SUBSCRIPTION_WRITE Write access to Subscription
PLAN_READ Read access to Plan
PLAN_WRITE Write access to Plan
INVOICE_READ Read access to Invoice
INVOICE_WRITE Write access to Invoice

Finish User Authorization

Request:

    POST /oauth/token
    Content-type: application/json
    {
        "client_id": "e8ec8917-1852-4ca1-96d1-af4bf6dc1407",
        "client_secret": "3cb5ce96-3f35-40f0-b76f-2c33c95cb32d",
        "code": "ad3f0db2-62b6-4cf4-9027-14829d33cfd2",
        "grant_type": "authorization_code",
        "redirect_uri": "https://example.com/auth/romit"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":
            {
                "access_token": "68f144a2-35ea-44ed-8d2a-66000596b040",
                "access_token_expires": "2015-10-21T19:20:30+01:00",
                "refresh_token": "344bb945-9b1d-4959-a421-a1a21d26e94a",
                "refresh_token_expires": "2015-12-21T19:20:30+01:00",
                "token_type": "bearer",
                "scope": [
                    "DEFAULT",
                    "BANKING_READ",
                    "BANKING_WRITE",
                    "IDENTITY_READ",
                    "IDENTITY_WRITE",
                    "TRANSFER_READ",
                    "TRANSFER_WRITE",
                    "USER_READ",
                    "USER_WRITE",
                    "SUBSCRIPTION_READ",
                    "SUBSCRIPTION_WRITE",
                    "PLAN_READ",
                    "PLAN_WRITE",
                    "INVOICE_READ",
                    "INVOICE_WRITE"
                ]
            }
     }

Once the user responds to the text or phone message, a POST Authorization Callback is made to your application via the redirect_uri that was defined in the request. Exchange the included authorization code for an access_token and refresh_token pair.

Request

POST https://api.romit.io/v1/oauth/token

Parameter Description
client_id Application key
client_secret Application secret
code The authorization code that is included in the redirect URL
grant_type This must be set to authorization_code
redirect_uri The same redirect_uri specified in the initiation step

Response

Parameter Description
access_token The new access token with requested scopes
access_token_expires The date and time the access token will expire
refresh_token The new refresh token
refresh_token_expires The date and time the refresh token will expire
token_type Always bearer
scope A list of permission scopes granted

Refresh Authorization

Request:

    POST /oauth/token
    Content-type: application/json
    {
        "client_id": "e8ec8917-1852-4ca1-96d1-af4bf6dc1407",
        "client_secret": "3cb5ce96-3f35-40f0-b76f-2c33c95cb32d",
        "refresh_token": "344bb945-9b1d-4959-a421-a1a21d26e94a",
        "grant_type": "refresh_token"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":
            {
                "access_token": "aa2eff38-ec36-4232-b266-f0ea0ba71142",
                "access_token_expires": "2015-10-22T02:02:15+04:00",
                "refresh_token": "f8273a9c-1500-4b5b-9309-0bc31c9ce282",
                "refresh_token_expires": "2015-12-22T02:02:15+04:00",
                "token_type": "bearer",
                "scope": [
                    "DEFAULT",
                    "BANKING_READ",
                    "BANKING_WRITE",
                    "IDENTITY_READ",
                    "IDENTITY_WRITE",
                    "TRANSFER_READ",
                    "TRANSFER_WRITE",
                    "USER_READ",
                    "USER_WRITE",
                    "SUBSCRIPTION_READ",
                    "SUBSCRIPTION_WRITE",
                    "PLAN_READ",
                    "PLAN_WRITE",
                    "INVOICE_READ",
                    "INVOICE_WRITE"
                ]
            }
     }

Use a valid refresh_token to generate a new access_token and refresh_token pair.

Note: The refresh_token you receive will change every time you exchange either an authorization_code or refresh_token for a new token pair.

Request

POST https://api.romit.io/v1/oauth/token

Parameter Description
client_id The new access token with requested scopes
client_secret The date and time the access token will expire
refresh_token The new refresh token
grant_type Must be set to refresh_token

Response

Parameter Description
access_token The new access token with requested scopes
access_token_expires The date and time the access token will expire
refresh_token The new refresh token
refresh_token_expires The date and time the refresh token will expire
token_type Always bearer
scope A list of permission scopes granted

Client Access Token

Request:

    POST /oauth/token
    Content-type: application/json
    {
        "client_id": "e8ec8917-1852-4ca1-96d1-af4bf6dc1407",
        "client_secret": "3cb5ce96-3f35-40f0-b76f-2c33c95cb32d",
        "grant_type": "client_credentials"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":
            {
                "access_token": "e25da466-0420-4aa5-acef-1920b07545a6",
                "access_token_expires": "2015-10-23T02:02:15+04:00",
                "token_type": "bearer"
            }
     }

Some endpoints require a client access token, which is different from a user access token. Client access tokens don’t require any particular user’s authorization, since they grant your application access to resources which belong to the application itself, rather than an account. You’ll only need to provide your client credentials to receive a client access token.

Request

POST https://api.romit.io/v1/oauth/token

Parameter Description
client_id Application key
client_secret Application secret
grant_type This must be set to client_credentials

Response

Parameter Description
access_token The new access token (no scopes for client credentials)
access_token_expires The date and time the access token will expire
token_type Always bearer

Application

An Application represents the integration itself.

Get Application

Request:

    GET /
    Content-type: application/json
    Authorization: Bearer e25da466-0420-4aa5-acef-1920b07545a6

Response:

     {
        "success": true,
        "error": null,
        "response":
            {
                "id": "6766c5f3-b5d0-4ea0-9442-bbedd9aadbd6",
                "name": "My Application",
                "website": "http://example.com",
                "description": "The marketplace of examples.",
                "developerName": "",
                "developerWebsite": "",
                "ownerId": "8662275c-d001-4958-b200-04097721e14d",
                "users": 465,
                "tokens": 9001,
                "created": 1445350017000
            }
     }

Gets the Application.

Request

GET https://api.romit.io/v1/

Response

Parameter Description
id Type
name The application name
website The application website
description A description of the application
developerName The developer name
developerWebsite The developer’s website
ownerId The User ID of the application owner.
users The number of active users
tokens The number of issued access tokens.
created The date and time it was created

Banking

A Banking object represents the funding sources an individual or business may have stored on their account. These are typically used to pay for a Transfer.

List Banking

Request:

    GET /banking
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success": true,
        "error": null,
        "response":
            [
                {
                    "id": "19280d4f-fe94-4a79-b4f6-d0c853ee2f1f",
                    "label": "Chadd's Card",
                    "name": "Chadd Sexington",
                    "type": "CARD",
                    "status": "UNVERIFIED",
                    "active": true,
                    "created": 1445460807000
                },
                {
                    "id": "3ba28427-83b8-4471-9eb4-3cc081c9065c",
                    "label": "Chadd's Account",
                    "name": "Preferred Checking 0194",
                    "type": "ACCOUNT",
                    "status": "VERIFIED",
                    "active": true,
                    "created": 1445450102000
                }
            ]
     }

Retrieve a list of Banking.

Request

GET https://api.romit.io/v1/banking

Query String Parameter Description
limit (Optional) The amount of items to list (Max 100)
offset (Optional) The starting point of the list

Response

Parameter Description
id The unique ID of the banking device
label The device description
name The device name
type The type of banking device this is (WALLET, ACCOUNT, CARD)
status The status of the banking device (UNVERIFIED, VERIFIED)
active The state of the device
created The date and time it was created

Get Banking Card

Request:

    GET /banking/card/19280d4f-fe94-4a79-b4f6-d0c853ee2f1f
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success": true,
        "error": null,
        "response":
            {               
                "id": "19280d4f-fe94-4a79-b4f6-d0c853ee2f1f",
                "label": "Chadd's Card",
                "name": "Chadd Sexington",
                "number": "7842",
                "expiration": "09/17",
                "type": "VISA",
                "status": "UNVERIFIED",
                "active": true,
                "created": 1445460807000      
            }
     }

Retrieve a Banking card.

Response

GET https://api.romit.io/v1/banking/card/{id}

Parameter Description
id The unique ID of the banking device
label The device description
name The cardholder name
number Last four digits of the card number
expiration Expiration date of the card
type The type of card (VISA, MASTERCARD)
status The status of the card (UNVERIFIED, VERIFIED)
active The state of the device
created The date and time it was created

Create Banking Card

Request:

    POST /banking/card
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
    {      
        "label": "Chadd's Card",
        "name": "Chadd Sexington",
        "number": "4556899287487842",
        "month": 9,
        "year": 2017,
        "cvv": "947",
        "postal": "89101"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":
            {               
                "id": "19280d4f-fe94-4a79-b4f6-d0c853ee2f1f"
            }
     }

Create a Banking card. A maximum of 5 UNVERIFIED cards may be added at any one time.

Request

POST https://api.romit.io/v1/banking/card

Parameter Description
label The device description
name The cardholder name
number The complete card number
month The month number
year The year number
cvv The CVV number
postal The cardholder ZIP

Response

Parameter Description
id The unique ID of the banking device

Update Banking Card

Request:

    PUT /card/19280d4f-fe94-4a79-b4f6-d0c853ee2f1f
    Content-type: application/json
    Authorization: Bearer e25da466-0420-4aa5-acef-1920b07545a6
      {
          "label": "Chadd's Card",
          "month": null,
          "year": null,
          "cvv": null,
          "postal": null
      }

Response:

      {
         "success": true,
         "error": null,
         "response":
               {
               }
      }

Update a Banking card.

Request

PUT https://api.romit.io/v1/banking/card/{id}

Parameter Description
label The device description
month The month number
year The year number
cvv The cvv number (required when updating month and year or postal)
postal The cardholder ZIP

Response

Empty Response

Disable Banking Card

Request:

    POST /banking/card/19280d4f-fe94-4a79-b4f6-d0c853ee2f1f/disable
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success": true,
        "error": null,
        "response":
            {
            }
     }

Disable a Banking card.

Request

POST https://api.romit.io/v1/banking/card/{id}/disable

Get Banking Account

Request:

    GET /banking/account/3ba28427-83b8-4471-9eb4-3cc081c9065c
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success": true,
        "error": null,
        "response":
            {               
                "id": "3ba28427-83b8-4471-9eb4-3cc081c9065c",
                "label": "Chadd's Account",
                "name": "Preferred Checking 0194",
                "institution": "WELLS",
                "type": "DEPOSITORY",
                "status": "VERIFIED",
                "active": true,
                "created": 1445450102000        
            }
     }

Retrieve a Banking account.

Request

GET https://api.romit.io/v1/banking/account/{id}

Response

Parameter Description
id The unique ID of the bank account
label The device description
name The name of the bank account
institution The type of bank (AMEX, BOFA, CAPONE360, SCHWAB, CHASE, CITI, FIDELITY, PNC, SVB, US, USAA, WELLS, NFCU, TD, OTHER)
type The type of account (DEPOSITORY, CREDIT, LOAN, MORTGAGE, BROKERAGE, OTHER)
status The status of the account (UNVERIFIED, VERIFIED)
active The state of the device
created The date and time it was created

Request:

    POST /banking/account/link
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
    {               
        "username": "chads",
        "password": "123456",
        "institution": "usaa",
        "pin": "1234"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":
            {               
                "question": "You say tomato, I say...?",
                "devices": null,
                "institution": null,
                "selections": null,
                "message": null
            }
     }

Link your existing, third-party Banking accounts to Romit.

Request

POST https://api.romit.io/v1/banking/account/link

Parameter Description
username The user’s username registered with the institution
password The user’s password registered with the institution
institution The institution type, from the table below
pin The user’s PIN registered with the institution, only used in the case of USAA
Institution Name Institution Type
American Express amex
Bank of America bofa
Capital One 360 capone360
Charles Schwab schwab
Chase chase
Citi citi
Fidelity fidelity
Navy Federal Credit Union nfcu
PNC pnc
Silicon Valley Bank svb
SunTrust suntrust
TD Bank td
US Bank us
USAA usaa
Wells Fargo wells

Response

If the initial linking attempt requires Multi-Factor Authentication, the HTTP status code will be 201. When the response is 201, one of question, devices or selections will be populated. If a code was sent to a device by default, the message parameter will be populated.

If the initial linking attempt does not require Multi-Factor Authentication, the HTTP status code will be 200 and question, devices, selections and message will be empty.

Parameter Description
question A MFA question, in case the status is 201. Otherwise empty.
devices A list of MFA devices to send a code to, in case the status is 201. Otherwise empty.
selections A list of MFA multiple-choice questions, in case the status is 201. Otherwise empty.
message A message regarding a sent MFA code, in case the status is 201. Otherwise empty.

Request:

    POST /banking/account/link/step
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
    {               
        "answer": "fido"
    }

When calling /v1/banking/account/link, the response might be a HTTP status code of 201. This indicates that the institution requires Multi-Factor Authentication. Use this call to submit the additional factors of authentication.

Request

POST https://api.romit.io/v1/banking/account/link/step

Parameter Description
answer Response to MFA question
selections A comma-separated list of answers to selections
code The MFA code sent to either the specified or default device
sendMethodMask The mask of the device returned in the devices parameter that you’d like to send the MFA code to

Response

The response will either be 200 if the authentication was successful, an error status if it was unsuccessful, or another 201. In the case of another 201, you can reply again with this endpoint until you recieve a 200 status.

For a description of the response in the case of a 201 status, see Linking Bank Accounts.

Update Banking Account

Request:

    PUT /account/3ba28427-83b8-4471-9eb4-3cc081c9065c
    Content-type: application/json
    Authorization: Bearer e25da466-0420-4aa5-acef-1920b07545a6
      {
          "label": "Chadd's Account"
      }

Response:

      {
         "success": true,
         "error": null,
         "response":
               {
               }
      }

Update a Banking account.

Request

PUT https://api.romit.io/v1/banking/account/{id}

Parameter Description
label The device description

Response

Empty Response

Disable Banking Account

Request:

    POST /banking/account/3ba28427-83b8-4471-9eb4-3cc081c9065c/disable
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success": true,
        "error": null,
        "response":
            {
            }
     }

Disables a Banking account connected to the account.

Request

POST https://api.romit.io/v1/banking/account/{id}/disable

Parameter Description
id The ID of the account to disable

Identity

An Identity document provide verified information about the identity of the user.

List Identities

Request:

    GET /identity
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success": true,
        "error": null,
        "response":
            [
                {
                    "id": "141f6ec2-855d-4ffa-ac6d-85ee030aa8d0",
                    "type": "INFO",
                    "created": 1445463455000
                },
                {
                    "id": "7102b78c-81a5-43b2-9d94-566c9c88bd40",
                    "type": "DOCUMENT",
                    "created": 1445473004000
                },
                {
                    "id": "61250195-fc72-4b3c-8a84-1857f470aedb",
                    "type": "SOCIAL",
                    "created": 1445644634000
                }
            ]
     }

Retrieve a list of Identity.

Request

GET https://api.romit.io/v1/identity

Query String Parameter Description
limit (Optional) The amount of items to list (Max 100)
offset (Optional) The starting point of the list

Response

Parameter Description
id The unique ID of the identity
type The type of identity (INFO, DOCUMENT, SOCIAL)
created The date and time it was created

Get Identity Info

Request:

    GET /identity/info/141f6ec2-855d-4ffa-ac6d-85ee030aa8d0
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {  
        "success": true,
        "error": null,
        "response": {
           "id": "141f6ec2-855d-4ffa-ac6d-85ee030aa8d0",
           "first": "Chadd",
           "last": "Sexington",
           "addressOne":"712 Red Bark Lane",
           "addressTwo": null,
           "city": "Henderson",
           "state": "NV",
           "postal": "89011",
           "country": "US",
           "dob": "1955-05-12",
           "gender": "MALE",
           "type": "DRIVERS_LICENSE",
           "created": 1446087178000
        }
     }

Get an Identity info for the authenticated user.

Request

GET https://api.romit.io/v1/identity/info/{id}

Response

Parameter Description
id Unique ID of the identity information
first The first name
last The last name
addressOne First line address on document
addressTwo Second line address on document
city City on document
state State on document
postal Zip on document
country Two letter country code on document
dob The date of birth (yyyy-MM-dd)
gender Gender on document (MALE, FEMALE)
type Document type (DRIVERS_LICENSE, GENERIC_ID, PASSPORT, VISA)
created The date and time it was created

Create Identity Info

Request:

    POST /identity/info
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
    {
       "first": "Chadd",
       "last": "Sexington",
       "addressOne": "712 Red Bark Lane",
       "addressTwo": null,
       "city": "Henderson",
       "state": "NV",
       "postal": "89011",
       "country": "US",
       "dob": "1955-05-12",
       "gender": "MALE",
       "type": "DRIVERS_LICENSE"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":            
            {
                "id": "141f6ec2-855d-4ffa-ac6d-85ee030aa8d0"
            }            
     }

Create an Identity info for the authenticated user.

Request

POST https://api.romit.io/v1/identity/info

Parameter Description
first The first name
last The last name
addressOne First line address on document
addressTwo Second line address on document
city City on document
state State on document
postal Zip on document
country Two letter country code on document
dob The date of birth (yyyy-MM-dd)
gender Gender on document (MALE, FEMALE)
type Document type (DRIVERS_LICENSE, GENERIC_ID, PASSPORT, VISA)

Response

Parameter Description
id Unique ID of the identity document

Get Identity Document

Request:

    GET /identity/document/7102b78c-81a5-43b2-9d94-566c9c88bd40
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {  
        "success":true,
        "error":null,
        "response":{  
           "id": "7102b78c-81a5-43b2-9d94-566c9c88bd40",
           "url": {
                "value": "https://example.com/temporary_url",
                "expires": 1445723566000
           },
           "type": "DRIVERS_LICENSE",           
           "created": 1445637226000           
        }
     }

Get an Identity document for the authenticated user.

Request

GET https://api.romit.io/v1/identity/document/{id}

Response

Parameter Description
id Unique ID of the identity information
url A temporarily generated URL that can be used to serve the base64 document
type The type of the document
created The date and time it was created

Create Identity Document

Request:

    POST /identity/document
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
    {
        "file": "TWFuIGlzIG...",
        "type": "DRIVERS_LICENSE"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":            
            {
                "id": "7102b78c-81a5-43b2-9d94-566c9c88bd40"
            }            
     }

Create an Identity document for the authenticated user.

Request

POST https://api.romit.io/v1/identity/document

Parameter Description
file Base64 image string of an image or PDF document
type Document type (DRIVERS_LICENSE, GENERIC_ID, PASSPORT, VISA, FACE_PICTURE_WITH_ID, BUSINESS_ARTICLES, BUSINESS_BANK_STATEMENT, BUSINESS_LICENSE, BUSINESS_VOIDED_CHECK, BUSINESS_PROCESSING_STATEMENT, BUSINESS_MARKETING_MATERIALS, BUSINESS_W9, BUSINESS_SIGNOR_ID)

Response

Parameter Description
id Unique ID of the identity document

Get Identity Social Network

Request:

    GET /identity/social/61250195-fc72-4b3c-8a84-1857f470aedb
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {  
        "success":true,
        "error":null,
        "response":{  
           "id": "61250195-fc72-4b3c-8a84-1857f470aedb",
           "userId": "51970...",
           "type": "FACEBOOK",           
           "created": 1445644634000           
        }
     }

Get an Identity social network for the authenticated user.

Request

GET https://api.romit.io/v1/identity/social/{id}

Response

Parameter Description
id Unique ID of the identity information
userId Unique ID of the user’s social network account
type The type of the social network
created The date and time it was created

Create Identity Social Network

Request:

    POST /identity/social
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
    {
       "token": "CAACEdE...",
       "type": "FACEBOOK"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":            
            {
                "id": "61250195-fc72-4b3c-8a84-1857f470aedb"
            }            
     }

Create an Identity social network for the authenticated user.

Request

POST https://api.romit.io/v1/identity/social

Parameter Description
token An access token to the user’s social network account
type The type of social network (FACEBOOK, LINKEDIN)

Response

Parameter Description
id Unique ID of the identity

Get Identity Business

Request:

    GET /identity/business/b281e2f0-b3ca-4393-8993-dc886662fb05
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {  
        "success": true,
        "error": null,
        "response": {
            "id": "b281e2f0-b3ca-4393-8993-dc886662fb05",
            "ein": "12-1234567",
            "name": "SpringShield",
            "addressOne": "712 Red Bark Lane",
            "addressTwo": null,
            "city": "Henderson",
            "state": "NV",
            "postal": "89011",
            "country": "US",
            "phone": "+17025551212",
            "website": "http://example.com",
            "description": "Private security agency",
            "created": 1446087178000
        }
     }

Get an Identity business for the authenticated user.

Request

GET https://api.romit.io/v1/identity/business/{id}

Response

Parameter Description
id Unique ID of the identity business
ein The tax ID number of the business
name The name of the business
addressOne First line address
addressTwo Second line address
city City
state State
postal Zip
country Two letter country code on document
phone The phone number of the business
website The website of the business
description A description of the business
created The date and time it was created

Create Identity Business

Request:

    POST /identity/business
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
    {
       "ein": "12-1234567",
       "name": "SpringShield",
       "addressOne": "712 Red Bark Lane",
       "addressTwo": null,
       "city": "Henderson",
       "state": "NV",
       "postal": "89011",
       "country": "US",
       "phone": "+17025551212",
       "website": "http://example.com",
       "description": "Private security agency"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":            
            {
                "id": "b281e2f0-b3ca-4393-8993-dc886662fb05"
            }            
     }

Create an Identity info for the authenticated user.

Request

POST https://api.romit.io/v1/identity/business

Parameter Description
ein The tax ID number of the business
name The name of the business
addressOne First line address
addressTwo Second line address
city City
state State
postal Zip
country Two letter country code on document
phone The phone number of the business
website The website of the business
description A description of the business

Response

Parameter Description
id Unique ID of the identity document

Transfer

A Transfer represents money moving from one user to another.

List Transfers

Request:

    GET /transfer
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success": true,
        "error": null,
        "response":
            [
                {
                    "id": "296db7c3-ef0b-4720-a338-ca52d4e562d4",
                    "from": "6a5699bf-f659-406d-97e7-e30517fa8d83",
                    "to": "2d4f9b08-c171-4cc9-83de-1411d0794b6d",
                    "by": "ABC Payments, Inc.",
                    "fromAmount": {
                        "currency": "USD",
                        "value": "100.00"
                    },
                    "toAmount": {
                        "currency": "USD",
                        "value": "98.00"
                    },
                    "bankingId": "7b71256b-4638-4a9e-b605-711775fb0a55",
                    "subscriptionId": null,
                    "memo": "INV-123456789",
                    "type": "PAYMENT",
                    "status": "EXECUTED",
                    "refund": null,
                    "created": 1445462910000
                },
                {
                    "id": "a8518b88-c0ca-4783-b80a-3f1cf89c52c4",
                    "from": "6a5699bf-f659-406d-97e7-e30517fa8d83",
                    "to": "70c3e7aa-4d13-4972-af24-a8175a554691",
                    "by": "ABC Payments, Inc.",
                    "fromAmount": {
                        "currency": "USD",
                        "value": "102.00"
                    },
                    "toAmount": {
                        "currency": "USD",
                        "value": "100.00"
                    },
                    "bankingId": "19280d4f-fe94-4a79-b4f6-d0c853ee2f1f",
                    "subscriptionId": null,
                    "memo": "Have some money bill.",
                    "type": "REMITTANCE",
                    "status": "EXECUTED",
                    "refund": null,
                    "created": 1445462910000,
                    "invoiceId":"f5261285-3712-4b8d-8d73-89c86a979f32"
                }
            ]
     }

Retrieve a list of Transfer.

Request

GET https://api.romit.io/v1/transfer

Query String Parameter Description
limit (Optional) The amount of items to list (Max 100)
offset (Optional) The starting point of the list

Response

Parameter Description
id The unique ID of the transfer
from The user ID who sent the transaction
to The user ID who received the transaction
by The name that will be appear on the billing statement
fromAmount The value/currency pair the sender paid
toAmount The value/currency pair the receiver received
bankingId The banking ID that was charged (if applicable)
subscriptionId The Subscription that executed the transfer (if applicable)
memo The memo attached to the transaction
type The type of transaction (PAYMENT, REMITTANCE)
status The status of the transaction (CREATED, EXECUTED, CANCELLED, ERROR, AUTHED, VOIDED, REFUNDED)
refund This will be null unless the transaction was refunded or attempted to have been refunded.
invoiceId If this transaction pays towards an invoice, this is the invoice’s identifier (if applicable)
created The date and time it was created

Get Transfer

Request:

    GET /transfer/296db7c3-ef0b-4720-a338-ca52d4e562d4
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success": true,
        "error": null,
        "response":            
            {
                "id": "296db7c3-ef0b-4720-a338-ca52d4e562d4",
                "from": "079c9ba5-0968-4730-8088-7f2e606287c7",
                "to": "6a5699bf-f659-406d-97e7-e30517fa8d83",
                "by": "ABC Payments, Inc.",
                "fromAmount": {
                    "currency": "USD",
                    "value": "100.00"
                },
                "toAmount": {
                    "currency": "USD",
                    "value": "98.00"
                },
                "bankingId": "7b71256b-4638-4a9e-b605-711775fb0a55",
                "subscriptionId": null,
                "memo": "INV-123456789",
                "type": "PAYMENT",
                "status": "REFUNDED",
                "refund":{
                    "refundAmount":{
                        "currency":"USD",
                        "value":"100.00"
                    },
                    "reimburseAmount":{
                        "currency":"USD",
                        "value":"0.76"
                    },
                    "memo":"Customer not satisfied",
                    "status":"EXECUTED",
                    "created":1452283103000
                },
                "created": 1445462910000,
                "invoiceId":"f5261285-3712-4b8d-8d73-89c86a979f32"
            }            
     }

Get a Transfer.

Request

GET https://api.romit.io/v1/transfer/{id}

Response

Parameter Description
id The unique ID of the transfer
from The user ID who sent the transaction
to The user ID who received the transaction
by The name that will be appear on the billing statement
fromAmount The value/currency pair the sender paid
toAmount The value/currency pair the receiver received
bankingId The banking ID that was charged (if applicable)
subscriptionId The Subscription that executed the transfer (if applicable)
invoiceId The Invoice that was paid toward the transfer (if applicable)
memo The memo attached to the transaction
type The type of transaction (PAYMENT, REMITTANCE)
status The status of the transaction (CREATED, EXECUTED, CANCELLED, ERROR, AUTHED, VOIDED, REFUNDED)
refund This will be null unless the transaction was refunded or attempted to have been refunded.
invoiceId If this transaction pays towards an invoice, this is the invoice’s identifier (if applicable)
created The date and time it was created

Create Transfer

Request:

    POST /transfer
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
    {               
        "amount": {
            "currency": "USD",
            "value": "100.00"
        },
        "userId": "70c3e7aa-4d13-4972-af24-a8175a554691",
        "bankingId": "19280d4f-fe94-4a79-b4f6-d0c853ee2f1f",
        "memo": "Have some money bill.",
        "mode": "AUTH_AND_CAPTURE"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":            
            {
                "id": "296db7c3-ef0b-4720-a338-ca52d4e562d4"
            }            
     }

Create a Transfer.

Request

POST https://api.romit.io/v1/transfer

Parameter Description
amount The value/currency pair to transfer
phone/userId (Optional) Destination of the transfer (if omitted, assumes destination is the application owner)
bankingId (Optional) The banking device to be charged (if omitted, assumes primary wallet)
invoiceId (Optional) The invoice to be paid
memo (Optional) The information to be included in this transaction
mode (Optional) This can be either ‘AUTH’ or ‘AUTH_AND_CAPTURE’. ‘AUTH’ will only authorize a transfer (will require a later Capture or Void. ‘AUTH_AND_CAPTURE’ will do a complete transfer. (default: AUTH_AND_CAPTURE)

Response

Parameter Description
id The unique ID of the transfer

Capture Transfer

Request:

    POST /transfer/296db7c3-ef0b-4720-a338-ca52d4e562d4/capture
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
    {
        "amount": {
            "currency": "USD",
            "value": "100.00"
        }
    }

Response:

     {
        "success": true,
        "error": null,
        "response":
            {
            }
     }

Create a Transfer to the business associated with the application owner.

Request

POST https://api.romit.io/v1/transfer/{id}/capture

Parameter Description
amount (Optional) The value/currency pair amount to capture from the authorization

Response

Empty Response

Refund Transfer

Request:

    POST /transfer/296db7c3-ef0b-4720-a338-ca52d4e562d4/refund
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
    {
        "amount": {
            "currency": "USD",
            "value": "100.00"
        },
        "memo": "Customer wasn't satisfied"
    }

Response:

     {
        "success": true,
        "error": null,
        "response":
            {
            }
     }

Create a refund for a Transfer. Refunds can only be made to transfers that were from a customer to a business.

Request

POST https://api.romit.io/v1/transfer/{id}/refund

Parameter Description
amount (Optional) The value/currency pair amount to refund (can be less or equal to transfer amount)
memo (Optional) The information to be added for refunds

Response

Empty Response

Void Transfer

Request:

    POST /transfer/296db7c3-ef0b-4720-a338-ca52d4e562d4/void
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success": true,
        "error": null,
        "response":
            {
            }
     }

Prior to capturing an authorization Transfer, it is possible to void the authorization and no charge will be made to the customer. Note that it may still show as a temporary hold of funds on the customer’s account for multiple business days.

Request

POST https://api.romit.io/v1/transfer/{id}/void

Response

Empty Response

User

A User represents an individual or business.

User level indicate the tier the user currently sits in. Users can transact with other users who are in their level or lower. As an example, a user in level 2 can transact with another user that is in level 2 and level 0, but may not transact with a user in level 3.

A user can be upgraded to a higher level by submitting more Identity objects. Users may be upgraded to higher level at any time and should be checked before initiating a Transfer. Statuses indicate where they currently stand in the level they have been placed in. If a user were in a DENIED status in level 2, they would not be able to transact with any users until they are in APPROVED.

Get Public User

Request:

    GET /user/b4a8ecae-9a27-4742-a79a-bd456e1e351f
    Content-type: application/json
    Authorization: Bearer e25da466-0420-4aa5-acef-1920b07545a6

Response:

     {
        "success": true,
        "error": null,
        "response":            
            {
                "level": 0,
                "type": "INDIVIDUAL",
                "businessName": null
            }            
     }

Get a public User.

Request

GET https://api.romit.io/v1/user/{id}

Query String Parameter Description
userId/phoneE164 The E164 phone or id of the user

Response

Parameter Description
type Type of user (INDIVIDUAL, BUSINESS)
level Integer representing what users this one can transact with
businessName String of the business name if the user is of type ‘BUSINESS’

Get User

Request:

    GET /user
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success": true,
        "error": null,
        "response":            
            {
                "id": "079c9ba5-0968-4730-8088-7f2e606287c7",
                "phone": "+17755551212",
                "email": "chunkylover53@aol.com",
                "first": "Chadd",
                "last": "Sexington",
                "type": "INDIVIDUAL",
                "status": "APPROVED",
                "level": 2,
                "created": 1445062910000
            }            
     }

Get the authenticated User.

Request

GET https://api.romit.io/v1/user

Response

Parameter Description
id Unique ID of the user
phone E164 phone of the user
email Email of the user
first Legal first name
last Legal last name
type Type of user (INDIVIDUAL, BUSINESS)
status Identity status of current level (NOT_SUBMITTED, SUBMITTED, APPROVED, DENIED)
level Integer representing what users this one can transact with
created The date and time the user was created.

Subscription

A Subscription is a recurring Transfer billed on a schedule from a biller’s Plan.

List Subscription

List of Subscription.

Request:

    GET /subscription
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

      {
         "success": true,
         "error": null,
         "response":
             [
               {
                 "id": "44387a2d-15ce-4d18-9fd6-97b96912031e",
                 "bankingId": "19280d4f-fe94-4a79-b4f6-d0c853ee2f1f",
                 "planId": "e04c7110-c604-4d3d-90bc-33c37625edcb",
                 "status": "CANCELLED",
                 "created": 1445099210000
               },
               {
                 "id": "9703d7be-6a19-4a1c-9f82-136edb12f102",
                 "bankingId": "19280d4f-fe94-4a79-b4f6-d0c853ee2f1f",
                 "planId": "4ebcba6a-1582-4a90-ab45-6256fd95c499",
                 "status": "ACTIVE",
                 "created": 1445073740000
               }
             ]
      }

Request

GET https://api.romit.io/v1/subscription

Query String Parameter Description
limit (Optional) The amount of items to list (Max 100)
offset (Optional) The starting point of the list

Response

Parameter Description
id Unique ID of the subscription
bankingId The Banking device that will be charged
planId The Plan ID that governs the Transfer schedule
status The status (ACTIVE, CANCELLED, ERROR)
created The date and time the subscription was created.

Get Subscription

Request:

    GET /subscription/44387a2d-15ce-4d18-9fd6-97b96912031e
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

      {
         "success": true,
         "error": null,
         "response":
               {
                 "id": "44387a2d-15ce-4d18-9fd6-97b96912031e",
                 "bankingId": "19280d4f-fe94-4a79-b4f6-d0c853ee2f1f",
                 "planId": "e04c7110-c604-4d3d-90bc-33c37625edcb",
                 "status": "CANCELLED",
                 "created": 1445099210000
               }
      }

Get a Subscription.

Request

GET https://api.romit.io/v1/subscription/{id}

Response

Parameter Description
id Unique ID of the subscription
bankingId The Banking device that will be charged
planId The Plan ID that governs the Transfer schedule
status The status (ACTIVE, CANCELLED, ERROR)
created The date and time the subscription was created.

Create Subscription

Request:

    POST /subscription
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
      {
          "bankingId": "19280d4f-fe94-4a79-b4f6-d0c853ee2f1f",
          "planId": "e04c7110-c604-4d3d-90bc-33c37625edcb"
      }

Response:

      {
         "success": true,
         "error": null,
         "response":
               {
                 "id": "44387a2d-15ce-4d18-9fd6-97b96912031e"
               }
      }

Create a Subscription.

Request

POST https://api.romit.io/v1/subscription

Parameter Description
bankingId The Banking ID that will be charged
planId The Plan ID that governs the schedule of the Subscription

Response

Parameter Description
id Unique ID of the subscription

Update Subscription

Request:

    PUT /subscription/44387a2d-15ce-4d18-9fd6-97b96912031e
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
      {
          "bankingId": "19280d4f-fe94-4a79-b4f6-d0c853ee2f1f",
          "planId": "e04c7110-c604-4d3d-90bc-33c37625edcb"
      }

Response:

      {
         "success": true,
         "error": null,
         "response":
               {
               }
      }

Update a Subscription.

Request

PUT https://api.romit.io/v1/subscription/{id}

Parameter Description
bankingId The Banking device that will be charged
planId The Plan that governs the schedule of the Subscription

Response

Empty Response

Cancel Subscription

Request:

    POST /subscription/44387a2d-15ce-4d18-9fd6-97b96912031e/cancel
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

      {
         "success": true,
         "error": null,
         "response":
               {
               }
      }

Cancel a Subscription.

Request

POST https://api.romit.io/v1/subscription/{id}/cancel

Response

Empty Response

Plan

A Plan is a schedule that is applied to a billed Subscription.

List Plan

Request:

    GET /plan
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

      {
         "success": true,
         "error": null,
         "response":
               [
                  {
                    "id": "e04c7110-c604-4d3d-90bc-33c37625edcb",
                    "name": "Silver Plan",
                    "amount": {
                      "currency": "USD",
                      "value": "9.99"
                    },
                    "interval": {
                      "span": "MONTH",
                      "count": 1,
                      "trial": {
                        "span": "DAY",
                        "count": 7
                      }
                    },
                    "memo": "",
                    "callback": "",
                    "active": true,
                    "created": 1445088190000
                  },
                  {
                      "id": "2f18ff84-7627-41a0-b5c7-328d7446124b",
                      "name": "Gold Plan",
                      "amount": {
                        "currency": "USD",
                        "value": "19.99"
                      },
                      "interval": {
                        "span": "MONTH",
                        "count": 1,
                        "trial": null
                      },
                      "memo": "",
                      "callback": "",
                      "active": false,
                      "created": 1445088190000
                  }
               ]

      }

Retrieve a list of Plan.

Request

POST https://api.romit.io/v1/plan

Query String Parameter Description
limit (Optional) The amount of items to list (Max 100)
offset (Optional) The starting point of the list

Response

Parameter Description
id Unique ID of the plan
name The name of the plan
amount The value/currency pair the sender paid
interval The scheduled Interval
memo The message to be attached to the Transfer when executed
callback The callback URL that calls a Plan Update
active The state of the plan
created The date and time the plan was created

Get Public Plan

Request:

    GET /plan/e04c7110-c604-4d3d-90bc-33c37625edcb
    Content-type: application/json
    Authorization: Bearer e25da466-0420-4aa5-acef-1920b07545a6

Response:

    {
       "error":null,
       "response":{
          "id":"e04c7110-c604-4d3d-90bc-33c37625edcb",
          "name":"Silver Plan",
          "amount":{
             "currency":"USD",
             "value":"9.99"
          },
          "interval":{
             "span":"MONTH",
             "count":1,
             "trial":{
                "span":"DAY",
                "count":7
             }
          }
       },
       "success":true
    }

Gets a public Plan.

Request

POST https://api.romit.io/v1/plan/{id}

Response

Parameter Description
id Unique ID of the plan
name The name of the plan
amount The value/currency pair the sender paid
interval The scheduled Interval

Get Plan

Request:

    GET /plan/e04c7110-c604-4d3d-90bc-33c37625edcb
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

      {
         "success": true,
         "error": null,
         "response":
              {
                "id": "e04c7110-c604-4d3d-90bc-33c37625edcb",
                "name": "Silver Plan",
                "amount": {
                  "currency": "USD",
                  "value": "9.99"
                },
                "interval": {
                  "span": "MONTH",
                  "count": 1,
                  "trial": {
                    "span": "DAY",
                    "count": 7
                  }
                },
                "memo": "",
                "callback": "",
                "active": true,
                "created": 1445088190000
              }
     }

Get Plan.

Request

POST https://api.romit.io/v1/plan/{id}

Response

Parameter Description
id Unique ID of the plan
name The name of the plan
amount The value/currency pair the sender paid
interval The scheduled Interval
memo The message to be attached to the Transfer when executed
callback The callback URL that calls a Plan Update when changed
active The active status of the plan
created The date and time the plan was created

Create Plan

Request:

    POST /plan
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
      {
          "name": "Silver Plan",
          "amount": {
            "currency": "USD",
            "value": "9.99"
          },
          "interval": {
            "span": "MONTH",
            "count": 1,
            "trial": {
              "span": "DAY",
              "count": 7
            }
          },
          "memo": "",
          "callback": null
      }

Response:

      {
         "success": true,
         "error": null,
         "response":
               {
                 "id": "e04c7110-c604-4d3d-90bc-33c37625edcb"
               }
      }

Create a Plan.

Request

POST https://api.romit.io/v1/plan

Parameter Description
name The name of the plan
amount The value/currency pair the sender paid
interval The scheduled Interval
memo The message to be attached to the Transfer when executed
callback The callback URL that calls a Plan Update when changed

Response

Parameter Description
id Unique ID of the plan

Update Plan

Request:

    PUT /plan/e04c7110-c604-4d3d-90bc-33c37625edcb
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
      {
          "name": "Silver Plan",
          "memo": "",
          "callback": null
      }

Response:

      {
         "success": true,
         "error": null,
         "response":
               {
               }
      }

Update a Plan.

Request

PUT https://api.romit.io/v1/plan/{id}

Parameter Description
name The name of the plan
memo The message to be attached to the Transfer when executed
callback The callback URL that calls a Plan Update when changed

Response

Empty Response

Disable Plan

Request:

    POST /plan/2f18ff84-7627-41a0-b5c7-328d7446124b/disable
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

      {
         "success": true,
         "error": null,
         "response":
               {
               }
      }

Disable a Plan.

Request

POST https://api.romit.io/v1/plan/{id}/disable

Response

Empty Response

Invoice

An Invoice is a statement of an amount due and provides a convenient way to request payment.

List Invoice

Request:

    GET /invoice
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

     {
        "success":true,
        "error":null,
        "response":[
           {
              "id":"eaddfad9-d62c-4df8-9c00-99ff95e886d1",
              "description":"This describes an invoice",
              "amount":{
                 "currency":"USD",
                 "value":"2.00"
              },
              "amountDue":{
                 "currency":"USD",
                 "value":"2.00"
              },
              "invoiceDate":"2016-08-08",
              "dueDate":"2016-08-08",
              "reference":"some-arbitrary-reference",
              "note":"This is something the recipient will see",
              "memo":"This is an internal memo field",
              "terms":"Bunch of legalese that no one reads",
              "status":"UNPAID",
              "created":1445088190000
           },
           {
              "id":"f5261285-3712-4b8d-8d73-89c86a979f32",
              "description":null,
              "amount":{
                 "currency":"USD",
                 "value":"3.00"
              },
              "amountDue":{
                 "currency":"USD",
                 "value":"0.00"
              },
              "invoiceDate":"2016-08-08",
              "dueDate":null,
              "reference":null,
              "note":"This is something the recipient will see",
              "memo":null,
              "terms":"Bunch of legalese that no one reads",
              "status":"CANCELLED",
              "created":1445088190000
           }
        ]
     }

Lists invoices that the authenticated user has created.

Request

GET https://api.romit.io/v1/invoice

Query String Parameter Description
limit (Optional) The amount of items to list (Max 100)
offset (Optional) The starting point of the list

Response

Parameter Description
id The invoice’s unique identifier
description A description of the invoice that the customer will see
amount The invoice value/currency pair
amountDue The remaining amount of the invoice, less any partial payments made
invoiceDate The invoice date
dueDate The date the invoice is due
reference An arbitrary, internal identifier that the user won’t see. This could be, e.g. a PO#.
memo An internal memo that the merchant can see, but the user cannot
terms Terms and Conditions of the invoice
status The invoice status (UNPAID, PARTIAL_PAID, PAID, PAST_DUE, CANCELLED)
created The date and time it was created

Get Public Invoice

Request:

    GET /invoice/e04c7110-c604-4d3d-90bc-33c37625edcb
    Content-type: application/json
    Authorization: Bearer e25da466-0420-4aa5-acef-1920b07545a6

Response:

      {
         "success":true,
         "error":null,
         "response":{
            "id":"eaddfad9-d62c-4df8-9c00-99ff95e886d1",
            "description":"This describes an invoice",
            "amount":{
               "currency":"USD",
               "value":"2.00"
            },
            "amountDue":{
               "currency":"USD",
               "value":"2.00"
            },
            "invoiceDate":"2016-08-08",
            "dueDate":"2016-08-08",
            "note":"This is something the recipient will see",
            "terms":"Bunch of legalese that no one reads",
            "status":"UNPAID"
         }
      }

Gets a public Invoice.

Request

GET https://api.romit.io/v1/invoice/{id}

Response

Parameter Description
id The invoice’s unique identifier
description A description of the invoice that the customer will see
amount The invoice value/currency pair
amountDue The remaining amount of the invoice, less any partial payments made
invoiceDate The invoice date
dueDate The date the invoice is due
note This is a note to the recipient, separate from the description
terms Terms and Conditions of the invoice
status The invoice status (UNPAID, PARTIAL_PAID, PAID, PAST_DUE, CANCELLED)

Get Invoice

Request:

    GET /invoice/e04c7110-c604-4d3d-90bc-33c37625edcb
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

      {
         "success":true,
         "error":null,
         "response":{
            "id":"f5261285-3712-4b8d-8d73-89c86a979f32",
            "description":null,
            "amount":{
               "currency":"USD",
               "value":"3.00"
            },
            "amountDue":{
               "currency":"USD",
               "value":"2.00"
            },
            "invoiceDate":"2016-08-08",
            "dueDate":null,
            "reference":"an-arbitrary-reference",
            "note":null,
            "memo":"This is a memo",
            "terms":null,
            "status":"CANCELLED",
            "created":1445088190000
         }
      }

Gets an Invoice.

Request

GET https://api.romit.io/v1/invoice/{id}

Response

Parameter Description
id The invoice’s unique identifier
description A description of the invoice that the customer will see
amount The invoice value/currency pair
amountDue The remaining amount of the invoice, less any partial payments made
invoiceDate The invoice date
dueDate The date the invoice is due
reference An arbitrary, internal identifier that the user won’t see. This could be, e.g. a PO#.
note This is a note to the recipient, separate from the description
memo An internal memo that the merchant can see, but the user cannot
terms Terms and Conditions of the invoice
transfers The Transfer list paid toward the invoice
status The invoice status (UNPAID, PARTIAL_PAID, PAID, PAST_DUE, CANCELLED)
created The date and time it was created

Create Invoice

Request:

    POST /invoice
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
        {
           "description":"This describes an invoice",
           "amount":{
              "currency":"USD",
              "value":"2.00"
           },
           "invoiceDate":"2016-08-04",
           "dueDate":"2016-12-25",
           "reference":"some-arbitrary-reference",
           "note":"This is something the recipient will see",
           "memo":"This is an internal memo field",
           "terms":"Bunch of legalese that no one reads"
        }

Response:

      {
         "success":true,
         "error":null,
         "response":{
            "id":"c533b177-f940-4dff-8590-2f8f2a27d553"
         }
      }

Creates an Invoice.

Request

POST https://api.romit.io/v1/invoice

Parameter Description
description A description of the invoice that the customer will see
amount The invoice value/currency pair
invoiceDate The invoice date
dueDate The date the invoice is due
reference An arbitrary, internal identifier that the user won’t see. This could be, e.g. a PO#.
note This is a note to the recipient, separate from the description
memo An internal memo that the merchant can see, but the user cannot
terms Terms and Conditions of the invoice

Response

Parameter Description
id The invoice’s unique identifier

Update Invoice

Request:

    PUT /invoice/f5261285-3712-4b8d-8d73-89c86a979f32
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040
        {
           "memo":"This is an updated memo",
           "reference":"an-updated-arbitrary-reference"
        }

Response:

      {
         "success":true,
         "error":null,
         "response":{

         }
      }

Updates an Invoice.

Request

PUT https://api.romit.io/v1/invoice/{id}

Parameter Description
reference An arbitrary, internal identifier that the user won’t see. This could be, e.g. a PO#.
memo An internal memo that the merchant can see, but the user cannot

Response

Cancel Invoice

Request:

    POST /invoice/a0974619-1b29-41ad-85fa-078bb03da6e3/cancel
    Content-type: application/json
    Authorization: Bearer 68f144a2-35ea-44ed-8d2a-66000596b040

Response:

      {
         "success":true,
         "error":null,
         "response":{

         }
      }

Cancels an Invoice.

Request

POST https://api.romit.io/v1/invoice/{id}/cancel

Response

Models

Authorization Callback

After a user affirmatively responds to the Request for Authorization, this object is POSTed to the redirect_uri of the request.

Parameter Description
code A code that can be exchanged for an access token
state A unique string included from the request for user authorization

Refund

These are refund transaction details that are listed on a transaction under the “refund” field.

Parameter Description
refundAmount The value/currency pair of the amount that was refunded
reimburseAmount The value/currency pair for the amount that needs to be reimbursed from the business to the processor for the cost of the original processed payment.
memo The memo that was attached to the refund
status The status of the refund (MANUAL, CREATED, EXECUTED, ERROR)
created The date of the refund

Interval

Parameter Description
span The timespan of the scheduled interval (DAY, WEEK, MONTH, YEAR)
count The number of charges to be placed in a given span
trial (Optional) A trial Interval period before the transaction is billed.

Plan Update

When a subscription gets either added to, updated, or disabled from a plan, the provided callback URL is called notifying the application of this change.

Parameter Description
planId A Plan id
subscriptionId A Subscription id
status The status of the subscription’s relationship to the plan (CREATED, UPDATED, DISABLED)
created The date the callback was fired

Sandbox Environment

The sandbox environment gives users the ability to use the Romit platform without using real money. In order to achieve this, differences exist between the sandbox and production that should be noted:

Merchant Tools

By copying and pasting the client-side code generated under the Payments section in settings, merchants and individuals can begin receiving payments and remittances directly from their website. In order to enable the checkout button, a user must:

1) Change their account type to business under the settings page.

2) Set a preferred operator location in the dropdown menu under the settings page.

3) Get Verified by providing your personal and business information in addition to your ACH information if you want digital settlement payments.

The preferred operator location will be who you receive money from when customers pay you through your integrated button. An operator may be either a digital location who will send you money through the provided wiring information in the Get Verified section or it could even be a physical tablet or kiosk where you can pick up money in cash in-person.

Checkout Button

Initialization

You can optionally specify a logo to show on the form. After including the payments script, in the initialization call, an optional fourth parameter can be a URL pointing to your logo.

An optional fifth parameter allows you to specify user details that we’ll use to populate the relevant fields, simplifying signup for your users. Valid idTypes are DRIVERS_LICENSE, CEDULA, VISA, PASSPORT and OTHER. Valid sexes are MALE and FEMALE.

Parameters

The button is configurable through HTML data tags that will set transaction specific information prior to a user clicking on the button.

<html>
    <head>
    </head>
    <body>
    <button
        data-payment="romit"
        data-memo="test-"
        data-price="1.00"
        data-currency-type="USD"></button>
    <script src="https://checkout.sandbox.romit.io/payments.min.js" id="romit-payments-script"></script>
    <script>
            Romit.initialize("CHECKOUT_ID",
                             function(paymentId) {
                             console.log("success: " + paymentId);
                             }, function() {
                             console.log("failure");
                            });
    </script>
    </body>    
</html>
Parameter Description
data-price The decimal amount of money to charge the customer. It must be at least 0.50.
data-currency-type The currency type the customer will be transacting in.
data-memo Arbitrary data that can be attached to the transaction that will become available in the sourceMessage callback. Typically, your globally unique generated invoice ID would be included so that the payment can be correlated from the callback upon a successful user transaction.
data-signup-first Populates the ‘Legal First Name’ field of the sign up form.
data-signup-last Populates the ‘Legal Last Name’ field of the sign up form.
data-signup-phone Populates the ‘Phone Number’ field of the sign up form. Format the number to E.164 format.
data-signup-email Populates the ‘Email’ field of the sign up form.
data-style Optional. Can be “none” or “default”.

Payment Page

You can also provide a link to a payment page, hosted on romit.io, populated with passed-in parameters. When the user successfully completes the payment, we’ll redirect them to the payment success callback URL specified on the Settings page, under the Payments tab, Callback setup section.

Parameters

The link is configurable through its querystring and will set transaction specific information prior to a user clicking on the link.

<a href="https://checkout.romit.io/payment-page?vendor_id=ab56b252-5470-43d6-91f8-8bcac6ee7a4d&amp;price=99.99&amp;currency_type=USD&amp;memo=a53803f9-9307-463b-83bd-89305473388f">Pay with Romit</a>
Parameter Description
vendor_id Your business account’s user ID
price The decimal amount of money to charge the customer. It must be at least 0.50.
currency_type Optional. Defaults to USD. The currency type the customer will be transacting in.
memo Optional. Arbitrary data that can be attached to the transaction that will become available in the sourceMessage callback. Typically, your globally unique generated invoice ID would be included so that the payment can be correlated from the callback upon a successful user transaction.
first_name Optional. Populates the ‘Legal First Name’ field of the sign up form.
last_name Optional. Populates the ‘Legal Last Name’ field of the sign up form.
phone Optional. Populates the ‘Phone Number’ field of the sign up form. Format the number to E.164 format.
email Optional. Populates the ‘Email’ field of the sign up form.
marketplace_id Optional.
referrer_id Optional.
logo_url Optional. The URL of a logo you’d like to use on the payment page.
user Optional. A user object. See the checkout button initialization. This object must be URL-encoded, e.g. %7B%22email%22%3A%22elliot%40cubeway.com%22%2C%22name%22%3A%7B%22first%22%3A%22Elliot%22%2C%22last%22%3A%22Henry%22%7D%2C%22phone%22%3A%222025550159%22%2C%22dob%22%3A%221981-11-25%22%2C%22address%22%3A%7B%22streetNumber%22%3A%2225%22%2C%22route%22%3A%22Taylor%20Street%22%2C%22city%22%3A%22San%20Francisco%22%2C%22state%22%3A%22CA%22%2C%22postalCode%22%3A%2294102%22%2C%22country%22%3A%22United%20States%22%7D%2C%22idType%22%3A%22drivers_license%22%2C%22sex%22%3A%22male%22%7D

Payment Frame

You can also provide an iframe loading a payment page, hosted on romit.io, populated with passed-in parameters. When the user successfully completes the payment, we’ll redirect them to the payment success callback URL specified on the Settings page, under the Payments tab, Callback setup section.

Parameters

The iframe is configurable through its querystring and will set transaction specific information prior to a user clicking on the link.

<iframe src="https://checkout.romit.io/payment-frame?vendor_id=ab56b252-5470-43d6-91f8-8bcac6ee7a4d&amp;price=99.99&amp;currency_type=USD&amp;memo=a53803f9-9307-463b-83bd-89305473388f"></iframe>
Parameter Description
vendor_id Your business account’s user ID
price The decimal amount of money to charge the customer. It must be at least 0.50.
currency_type Optional. Defaults to USD. The currency type the customer will be transacting in.
memo Optional. Arbitrary data that can be attached to the transaction that will become available in the sourceMessage callback. Typically, your globally unique generated invoice ID would be included so that the payment can be correlated from the callback upon a successful user transaction.
first_name Optional. Populates the ‘Legal First Name’ field of the sign up form.
last_name Optional. Populates the ‘Legal Last Name’ field of the sign up form.
phone Optional. Populates the ‘Phone Number’ field of the sign up form. Format the number to E.164 format.
email Optional. Populates the ‘Email’ field of the sign up form.
marketplace_id Optional.
referrer_id Optional.
logo_url Optional. The URL of a logo you’d like to use on the payment page.
user Optional. A user object. See the checkout button initialization. This object must be URL-encoded, e.g. %7B%22email%22%3A%22elliot%40cubeway.com%22%2C%22name%22%3A%7B%22first%22%3A%22Elliot%22%2C%22last%22%3A%22Henry%22%7D%2C%22phone%22%3A%222025550159%22%2C%22dob%22%3A%221981-11-25%22%2C%22address%22%3A%7B%22streetNumber%22%3A%2225%22%2C%22route%22%3A%22Taylor%20Street%22%2C%22city%22%3A%22San%20Francisco%22%2C%22state%22%3A%22CA%22%2C%22postalCode%22%3A%2294102%22%2C%22country%22%3A%22United%20States%22%7D%2C%22idType%22%3A%22drivers_license%22%2C%22sex%22%3A%22male%22%7D

Callback

The Send Money callback gives recipients of a send money transaction (either a payment or a remittance) the ability to be notified to changes from these types of transactions. Checkout button transactions are Send Money transactions and are therefore included.

Callback URL

The Callback URL is set under the main Settings of a user account under the Payment Button tab. Only accounts that are of type business can see this tab which can be set in the general settings tab. All URLs must be HTTPS and they cannot be local.

Response:

     {
        "paymentId": "1e66b44b-04d7-4aab-854b-2adec2ac3bcf",
        "sourceBankUserId": "f333d4c3-f1ab-48ce-8454-8532cd4e2842",
        "sourceAmount": 1.0,
        "sourceCurrencyType": "USD",
        "sourceMessage": "a53803f9-9307-463b-83bd-89305473388f",
        "destinationAmount": 0.93,
        "destinationCurrencyType": "USD",
        "statusType": "EXECUTED",
        "createDate": 1436314058000,
        "executeDate": 1436314750000
     }

Callback Parameters

This is the response object that will be sent in a POST to the provided callback URL.

Parameter Description
paymentId The unique payment ID that is generated when a request is created.
sourceBankUserId The unique ID of the user who originated the transaction.
sourceAmount The amount of money spent by the source customer.
sourceCurrencyType The currency type of the source customer.
sourceMessage The optional memo attached to the transaction.
destinationAmount The amount of money received by the destination user.
destinationCurrencyType The currency type of the destination user.
statusType The current status of the transaction. Includes: CREATED, CLAIMED, EXECUTED, CANCELLED, ERROR.
createDate The timestamp of when the payment was created.
executeDate The timestamp of when the payment was executed.

Retry

The callback server expects a 2xx response from the endpoint it is POSTing to. If it does not receive a valid status code, it will attempt several requests until it does. It employs exponential back-off and will attempt delivery for the next 2 days, giving the integrator sufficient time to resolve any unexpected downtime.

Security

The callback endpoint URL you provide should only trust information coming from Romit. To ensure this, transactions should be digitally checked at the application layer and requests should be filtered by IP at the network layer.

Application Filtering

When the callback URL is set in the user settings page, Romit will digitally sign the transaction payload with a generated private key that becomes available in your settings page. Using HMAC SHA256, the signature generated form the payload will be placed in the request header every time a transaction occurs. For your convenience, we have provided a sample application that demonstrates a third party application securely consuming these requests.

Network Filtering

Applications should only listen to requests from our IP address: 54.68.57.30 Consult the Sandbox Environment documents for requests originating from the sandbox.

Styling

By default, you get a handsomely-styled button. You can achieve this by either leaving out the data-style parameter, or setting its value to “default”. To customize the button, set the data-style parameter to “none”. You are now free to set the text of the button and its styling. Each button has the ‘romit-payment-button’ class appended.