Introduction

This page contains internal Switch APIs. Before using, the user must first Self Register and then authenticate using the Get Token.

To help you get started with your integration, Cloud Payments provides a sample Postman collection that includes a template of all the Payments API endpoints. It also includes a sample environment file with the URL details.

Click the button below to download the collection and associated the environment file.

Companies

Create Company

Merchants or business organizations are created as companies in the system. Companies are common business entities used to manage other entities and to define relationships among them. The content of a business interaction is a set of actions that you can make for your entities in your hierarchy. These business entities must be created for your Tenant by registering a Company in the platform. To set up the primary entities for your infrastructure, Create Company must run the first time using the Box Owner credentials. This request is submitted with no parameters to generate the initial Entity ID (CompanyID) for the top-most parent object. The resulting Entity ID that gets generated in the response is used as a Parent ID, when the Create Company is executed again to create child entities within your business hierarchy. More info can be found on Companies page.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/createCompany
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	CREATE_COMPANY
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/x-www-form-urlencoded
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Create Company Request

{
"name":"The Testing Company",
"companyCode":"T400",
"country":"USA",
"timezoneFormatted":"America/Chicago",
"profileItems": [
"paymentProcessor":"CARD_CONNECT",
"merchantId":"800000000264",
{"key": "OWNER", "value": "John Doe"}
],
"profileItemsSecure": [
{"key": "pettycash_Combo_safe", "value": "123456"}
]
}

Request Parameters

Name	Required	Description	Value/Range
name	yes	Company Name	Alphanumeric
companyCode	yes	This will be the Company code that is assigned by corporate.	Alphanumeric
parentId	no - if this is the top most layer. yes - if a child entity.	The Parent Id of the Company created. Use Get Entity Hierarchy to retrieve the parent in the Tenant hierarchy. Note: This value is not needed if creating the top-most level.	Integer
country	no	Country where the company is located.	Returns 3 letter country code. Should comply with ISO 3166.
timezoneFormatted	yes	Joda-Time is the replacement for the Java date and time classes. http://www.joda.orgjoda-time/key_format.html.time zone_formatted is populated with the getTimeZones API, and is then used to populate the timezone and timezoneOffset columns on the back end, that are returned in the response.	Must comply with: http://joda-time.sourceforge.net/timezones.html
paymentProcessor	no	Payment processor that would process all the credit card transaction.	String Example: CARD_CONNECT
merchantId	no	Merchant Id received from the payment processor.	String
profileItems	no	Key-value pairs of data specific to a Tenant, about a Company.	Attributes type
profileItemsSecure	no	Key-value pairs of secure data specific to a Tenant, about a Company.	Attributes type

Create Company Response

{"createCompanyResponse":{
"contextResponse":{"tenantName":"CBD",
"statusCode":"SUCCESS",
"errors":null},
"companyId":"1413", //top level company created
"name":"The Testing Company",
"companyCode":"T400",
"country":"USA",
"merchantId":"800000000264",
"paymentProcessor":"CARD_CONNECT",
"timezoneFormatted":"America/Chicago",
"timezoneOffset":"-06:00",
"status":"ACTIVE",
"amlFlag":"false",
"profileItems":{"key":
"OWNER","value":"John Doe"},
"profileItemsSecure":{
"key":"pettycash_Combo_safe",
"value":"123456"} } }

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
companyID	Unique Company ID for each entity on the server. This value is auto-generated in this API	Integer
name	This will be the Company name you want to associate to the companyID.	Alphanumeric string.
companyCode	This will be the Company code that is assigned by corporate.	Alphanumeric string.
country	Physical location of the company.	Three letter country code. Must comply with ISO 3166.
paymentProcessor	no	Payment processor that would process all the credit card transaction.	String Example: CARD_CONNECT
merchantId	no	Merchant Id received from the payment processor.	String
timezone DEPRECATED	Company's timezone. Note: Although this field is deprecated, it is still in the WSDL for backwards compatibility, but is not validated. This value is returned in the response, and is derived from the Canonical ID that is passed from the timezone_formatted column.	Three letter country code. Must comply with ISO 3166.
timezoneOffset DEPRECATED	Time Zones around the world are expressed as positive or negative offsets from UTC. Timezones will offset from UTC without DST. Values range from -12.00 through +14.00. Note: Although this field is deprecated, it is still in the WSDL for backwards compatibility. It will not be validated. This value is returned in the response, and is derived from the Canonical ID that is passed from the timezone_formatted column.	Must comply with: http://joda-time.sourceforge.net/timezones.html
timezoneFormatted	Joda-Time is the replacement for the Java date and time classes. http://www.joda.org/joda-time/key_format.html. timezone_formatted is populated with the getTimeZones API, and is then used to populate the timezone and timezoneOffset columns on the back end, that are returned in the response.	Only formats according to ISO 8601 shall be accepted: http://joda-time.sourceforge.net/timezones.html
status	This is the current status of the company account. Default is in the ACTIVE state.	Alpha characters ACTIVE/SUSPENDED/CLOSED See Company page for more information.
amlFlag	Flag to determine if there was a AML hit. True indicates there was.	Boolean true/false
profile_items	Key-value pairs of data a Tenant wants to keep about a Company.	Attributes Key
profile_items_secure	Key-value pairs of data a Tenant wants to keep about a Company in encrypted form.	Attributes Key

Update Company API allows Company Users to update their Company's Information. To change the status of a Company see - Update Company Status API.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/createCompany
Response Formats	application/json text/plain; charset=utf-8
Entitlements	UPDATE_COMPANY
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Update Company Request

{
"id":"1413",
"name":"Freddies Fast Food",
"companyCode":"FR-103",
"country":"USA",
"merchantId":"800000000264",
"paymentProcessor":"CARD_CONNECT",
"timezoneFormatted":"EST",
"profileItems": [
{"key": "OWNER", "value": "John Doe"}
],
"profileItemsSecure": [
{"key": "safe_combo", "value": "12345"}
]
}

Request Parameters

Name	Required	Description	Value/Range
Id	yes	Unique Company ID company. This value is auto-generated in the Create Company API	Integer
name	yes	Company Name	Alphanumeric and special characters allowed.
companyCode	yes	This is a Company code assigned by corporate.	Alphanumeric
parentId	no	This is a Parent Id of the Company created.	Integer
country	no	Country where the company is located.	Alpha Returns 3 letter country code. Should comply with ISO 3166.
paymentProcessor	no	Payment processor that would process all the credit card transaction.	String Example: CARD_CONNECT
merchantId	no	Merchant Id received from the payment processor.	String
timezoneFormatted	yes	Joda-Time is the replacement for the Java date and time classes. http://www.joda.org/joda-time/key_format.html.time zone_formatted is populated with the getTimeZones API, and is then used to populate the timezone and timezoneOffset columns on the back end, that are returned	Must comply with: http://joda-time.sourceforge.net/timezones.html
profileItems	no	Key-value pairs of information specific to a Company.	string
profileItemsSecure	no	Key-value pairs of secure information specific to a Company.	string

Update Company Response


{"updateCompanyResponse":{"contextResponse":{"tenantName":"CBD",
"statusCode":"SUCCESS","errors":null},
"company":{"name":"Freddies Fast Food",
"companyCode":"FR-103",
"country":"USA",
 "merchantId":"800000000264",
"paymentProcessor":"CARD_CONNECT",
"timezone":"EST",
"timezoneOffset":"-05:00",
"profileItems":{"key":"OWNER",
"value":"John Doe"},
"profileItemsSecure":{"key":"safe_combo",
"value":"12345"},
"id":"1413","status":"ACTIVE"} } }

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
companyID	Unique Company ID for each entity on the server.	Integer
name	This is a Company name.	Alphanumeric
companyCode	Company code assigned by corporate.	Alphanumeric
country	Physical location of the company.	Alpha 3 letter country code. Must comply with ISO 3166.
paymentProcessor	no	Payment processor that would process all the credit card transaction.	String Example: CARD_CONNECT
merchantId	no	Merchant Id received from the payment processor.	String
timezone	Company's timezone. Auto-filled.	Must comply with: http://joda-time.sourceforge.net/timezones.html
timezoneOffset	Time Zones around the world are expressed as positive or negative offsets from UTC. Timezones will offset from UTC without DST. This value is returned in the response, and is derived from the Canoni cal ID that is passed from thetimezone_formatted column.	Must comply with: http://joda-time.sourceforge.net/timezones.html
status	This is the current status of the company account.	Alphanumeric ACTIVE / SUSPENDED / CLOSED See Company page for more information.
amlFlag	Flag to determine if there was an AML hit.	Boolean true/false
profile_items	Key-value pairs of additional information for a Company. Not Secure	String
profile_items_secure	Key-value pairs of private information for a Company. This information is encrypted	String

Get Company

Get Company information. The Company must already exist in the Switch to be accessible by a Company User. Information is retrieved using either a Company ID (generated when the Company was created) or company's corporate Company Code.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/getCompany
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GET_COMPANY
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Get Company Request

{
"companyId":"1413"
}

Request Parameters

Name	Required	Description	Value/Range
companyId	yes	Unique ID assigned to a Company when the Company was created.	Integer
companyCode	no	A corporate assigned company code.	Boolean True/False

Get Company Response

{"getCompanyResponse":{"contextResponse":{"tenantName":"CBD",
"statusCode":"SUCCESS",
"errors":null},
"name":"The Testing Company",
"companyCode":"T400",
"country":"USA",
"merchantId":"800000000264",
"paymentProcessor":"CARD_CONNECT",
"timezoneFormatted":"America/Chicago",
"status":"ACTIVE",
"companyId":"1413",
"profileItems":{"key":"OWNER",
"value":"John Doe"} } }

Response Parameters

Name	Description	Value/Range
contextResponse	Construction of the response	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
name	Company name that is stored on the platform for the Company ID	Alphanumeric
companyCode	Company code returned for Company ID	Alphanumeric
country	Country where the Company resides.	Alpha characters Must comply with ISO 3166Maximum: 3 characters.
paymentProcessor	no	Payment processor that would process all the credit card transaction.	String Example: CARD_CONNECT
merchantId	no	Merchant Id received from the payment processor.	String
timezoneFormatted	Timezone where the Company resides.
timezoneOffset	Time Zones around the world are expressed as positive or negative offsets from UTC.	Timezones will offset from UTC without DST Values range from -12.00 to +14.00 For a complete list of UTC values see: https://en.wikipedia.org/wiki/List_of_UTC_time_offsets
status	Current status of the Company's account.	Alpha characters ACTIVE/SUSPENDED/CLOSED
companyId	Unique ID that was assigned to the company when initially created.	Integer
profileItems	Optional data types entered as a key identifier for the associated value. Key values are defined for each tenant, and are used to look up value(s) in the table. Key names must always be consistent in their naming convention. Glob data types are permitted, and can be used for large items of any data format. E.g; Binary files. If any profile items exist, they are returned.	Key/Value

Get Entity Hierarchy

This operation retrieves all child Companies; starting one level down for any given parent Company. Output pagination with a default page number set to 50 pages. If a different page size is required, it can be set using the pageSize parameter in the request. The response always starts with the first page. If a different starting point is required it can be set using the pageNumber parameter.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/getEntityHierarchy
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GET_ENTITY_HIERARCHY
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Get Entity Hierarchy Request

{
"entityId":"1412",
"pageSize":2,
"pageNumber":0
}

Request Parameters

Name	Required	Description	Value/Range
entityId	yes/no Either entityId or companyCode is required.	Company ID. This value was auto-generated when the Company was created with the Create Company API.	Integer
companyCode	yes/no Either entityId or companyCode is required.	Company Code. This value was entered when the Company was created in the Create Company API.	Alphanumeric Special Characters: underscore "_"
pageSize	no	Number of Companies returned per page. If a value is not entered, up to 50 entries are displayed.	Integer
pageNumber	no	Page number. If not set, defaults to the first page (first page is 0).	Integer

Get Entity Hierarchy Response

{"getEntityHierarchyResponse":{
"contextResponse":{"tenantName":"CBD",
"statusCode":"SUCCESS",
"errors":null},
"entities":{"entityId":"1514",
"companyCode":"888",
"companyName":"second level company",
"merchantId":"800000000264",
"paymentProcessor":"CARD_CONNECT",
"status":"ACTIVE"},
"pageNumber":"0",
"totalElements":"1"} }

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
entityId	Company ID. This value was auto-generated when the Company was created in Create Company API.	Integer
companyCode	Company Code. This value was entered when the Company was created in the Create Company API.	Alphanumeric Special Characters:underscore "_"
companyName	Company Name.	Alphanumeric Special Characters: underscores "_" spaces " "
paymentProcessor	no	Payment processor that would process all the credit card transaction.	String Example: CARD_CONNECT
merchantId	no	Merchant Id received from the payment processor.	String
status	Company Status.	ACTIVE/SUSPENDED/CLOSED
pageNumber	Page number. If not set, this defaults to the first page (first page is 0).	Integer
totalElements	Total number of records found for this request.	Integer

Update Company Status

The Update Company Status API is designed to change a Company status. For a list of statuses and their meaning, see the Company page. NOT WORKING AT THIS TIME.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/updateCompanyStatus
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	UPDATE_COMPANY_STATUS
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Update Company Status Request

{
"companyId":"40611",
"companyName": "The Testing Company",
"companyStatus": "ACTIVE"
}

Request Parameters

Name	Required	Description	Value/Range
companyId	yes	Unique Company identifier generated when the company was initially created with the Create Company API.	Integer
companyName	no	Company name. This value does not need to be unique, and is for informational use only. Cannot be used in a search string.	Alphanumeric
companyStatus	yes	Status of a Company. Changes the current status of a company.	ACTIVE/SUSPENDED/CLOSED

Update Company Status Response

{
"updateCompanyStatusResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS"
  }
 }
}

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors /td>

Create Company Address

Enters address information of a Company. More than one address can be associated with a company. Creates one Company address entry with an associated ID for each execution. Each company address Id is unique.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/createCompanyAddress
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	CREATE_COMPANY_ADDRESS
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Create Company Address Request


{
"companyId":"1413",
"addressType":"Postal",
"address1":"10 willow street",
"country": "USA",
"city": "Austin",
"state": "Texas",
"postalCode": "58232",
"attributes": [
{"key": "postal_drop", "value": "back door"}
]
}

Request Parameters

Name	Required	Description	Value/Range
addressType	no	Address description. This can be defined as a Mailing Address, Billing Address, or Corporate Address. Free form text.	Alphanumeric Special character: spaces Maximum of 64
address1	no	The address for the company.	Alphanumeric Maximum of 255
country	no	The country in which the company resides. This country code is used to identify the companies' physical location.	Alpha Maximum: 3 characters Must comply with http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
city	no	The location of the company.	Alphanumeric Maximum of 100
state	no	The state in which the company resides.	Alpha Must comply with http://en.wikipedia.org/wiki/ISO_3166-2
postalCode	no	The postal code (zipcode) where the company physically resides. This is the postal code used by countries.	Alphanumeric Maximum: 9 characters Must comply with: http://www.geopostcodes.com/resources format depending on the country entered.
attributes	no	Attributes contain a key and a value to hold any additional information about the client. Some examples include municipality location, latitude and longitude coordinates, or any other information. More than one set of Key:Value parameters can be entered.	String. Key/Value

Create Company Address Response


{"createCompanyAddressResponse":{"contextResponse":{"tenantName":"CBD",
"statusCode":"SUCCESS",
"errors":null},
"companyAddressId":"3","companyAddress":{"companyId":"1413",
"addressType":"Postal",
"address1":"15 willow street",
"country":"USA",
"city":"Austin",
"state":"Texas",
"postalcode":"58232",
"attributes":{"key":"postal_drop",
"value":"back door"} },
"createdDate":"2016-05-18T13:46:46.685-05:00"} }

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
companyAddressId	Unique ID assigned to the address envelope. Each time a new address is added, a new company address Id is created.	Integer
companyId	Unique ID assigned to every company or entity.	Integer
addressType	Address description. This can be defined as a Mailing Address, Billing Address, Corporate Address. Free form text.	Alphanumeric Maximum: 64 characters.
address1	The address in which the company resides.	Alphanumeric Maximum : 255 characters
country	The country where the company is located.	Alphanumeric Maximum : 3 characters
city	The city where the company is located.	Alphanumeric Maximum : 100 characters
state	The state where the company is located.	Alphanumeric Maximum : 100 characters
postalcode	The postal code where the company is located.	Must comply with: http://www.geopostcodes.com/re sources format depending on the country entered.
attributes	Returns keys and their values stored on the server, that define any additional attributes for the company.	String. Key/ Value
createdDate	This is the date in which the account information was added to the database. This is different than the company was activation.	DateTime This must comply with ISO8601 Date and Time format Example: 2016-05-18T13:53:22.229-05:00

Get Company Addresses

This operation returns all the Company addresses listed for a Company ID. A Company may have multiple address entries associated with the company; each one retrievable using the unique Company Address ID of each entry.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/getCompanyAddresses
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GET_COMPANY_ADDRESS
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Get Company Address Request

{
"companyId":"1413"
}

Request Parameters

Name	Required	Description	Value/Range
companyId	yes	The companyID that was auto-generated when the company was initially created with the Create Company API. If this value is unknown, the Get Company API can be executed to retrieve the companyID.	Integer, Maximum of 64 characters.

Get Company Address Response


{"getCompanyAddressesResponse":{"contextResponse":{"tenantName":"CBD","statusCode":"SUCCESS",
  "errors":null},"companyAddresses":[
{"companyId":"1413","addressType":"HOME","address1":"122 foo street","country":"USA","city":"Austin","state":"Texas","postalcode":"58232",
  "attributes":{"key":"postal_drop_option1","value":"side door"},"id":"1"},
{"companyId":"1413","addressType":"House on the water","address1":"15 willow street","country":"USA","city":"Austin","state":"Texas","postalcode":"58232",
  "attributes":{"key":"postal_drop_option2","value":"side door"},"id":"2"},
{"companyId":"1413","addressType":"House on the water","address1":"25 willow street","country":"USA","city":"Austin","state":"Texas","postalcode":"58232",
  "attributes":{"key":"postal_drop_option3","value":"side door"},"id":"3"}]} }

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
companyId	The companyID that was auto-generated when the company was initially created with the Create Company API. If this value is unknown, the Get Company API can be executed to retrieve the companyID.	Integer
addressType	Address Type that was created when the address was first entered into the platform.	Alphanumeric, Maximum: 255 characters
address1	The street address where the company resides.	Alphanumeric, Maximum: 255 characters
country	The Country where the company resides.	Alpha, Maximum: 3 characters, Must comply with http://en.wikipedia.org/wiki/IS
city	The city where the company resides.	Alphanumeric, Maximum: 100 characters
state	The state where the company resides.	Alphanumeric, Maximum: 100 characters
postalcode	The postal code (zipcode) where the company physically resides. This is the postal code used by countries.	Alphanumeric, Maximum: 7 characters, Must comply with: http://www.geopostcodes.com/resources format depending on the country entered.
attributes	Returns keys and their values stored on the server that define any additional attributes that were added for the company. There may be more than one set of key value pairs listed.	Key/Value
id	Address ID, or unique ID attached to each address.	Integer

Delete Company Address

Removes address information from a Company. This API operates on one company address entry using the unique address ID that was created when the company address was initially entered in the system.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/deleteCompanyAddress
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	DELETE_COMPANY_ADDRESS
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Delete Company Address Request

{
"companyId":"1413",
"addressId":"7"
}

Request Parameter

Name	Required	Description	Value/Range
companyId	yes	Unique Company ID company. This value is auto-generated in the Create Company API	Integer
addressId	yes	Unique address ID for an address belonging to a company. This value is auto-generated with the Add Company API.	Integer

Delete Company Address Successful Response

{"deleteCompanyAddressResponse":{
"contextResponse":{"tenantName":"CBD",
"statusCode":"SUCCESS",
"errors":null},
"companyAddressId":"7",
"companyId":"1413"}
}

Delete Company Address Error Response Error if an invalid address ID is submitted Response HTTP 1/1 200 OK

{
"deleteCompanyAddressResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SERVICE",
"statusMessage": "No entity address found with id: 7653",
"errorArgs": null,
"errors": null
    },
"companyAddressId": "0",
"companyId": "0"
  }
}

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
companyAddressId	Unique address ID for an address generated for a company address	Integer
companyID	Unique Company ID. This value was auto-generated when the company was initially created.	Integer

Get Company Users

This operation retrieves all the Company Users of a given Company, using the company's Entity ID. The list is organized by the person ID in ascending order.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/getCompanyUsers
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GET_COMPANY_USERS
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Get Company Users Request

{
"entityId":"1413"
}

Request Parameters

Name	Required	Description	Value/Range
entityId	yes	Entity ID or Company ID. The ID that was auto-generated when the company was initially created in Create Company API. If this value is unknown, the Get Company API can be executed to retrieve it.	Integer

Get Company Users Response

{
"getCompanyUsersResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
},
"companyUsers": [
{
"id": "1394954216",
"entity_id": "40606",
"entity_name": "test company 1",
"firstname": "test",
"lastname": "company 1",
"timezone": "America/Chicago",
"timezone_offset": "-06:00",
"status": "A",
"created_date": "2015-07-30T09:12:26.067-05:00"
},
{
"id": "1394954217",
"entity_id": "40606",
"entity_name": "test company 1",
"firstname": "test 2",
"lastname": "company 1",
"timezone": "America/Chicago",
"timezone_offset": "-06:00",
"status": "A",
"created_date": "2015-07-30T09:12:54.578-05:00"
},
{
"id": "1394954218",
"entity_id": "40606",
"entity_name": "test company 1",
"firstname": "test 3",
"lastname": "company 1",
"timezone": "America/Chicago",
"timezone_offset": "-06:00",
"status": "A",
"created_date": "2015-07-30T09:13:07.502-05:00"
           }
       ]
}
}

Response Parameters

name	Description	Value/Range
contextResponse	Contest Response	TenantName StatusCode - See status codes AdditionalStatusCode StatusMessage AdditionalStatusMessage ErrorArgs Errors
id	Person ID	Integer
entity_id	Unique ID generated for a company.	Integer
entity_name	Company Name.	Alphanumeric
firstname	First name of the Company User.	Alphanumeric
lastname	Last name of the Company User.	Alphanumeric
timezone	Person's timezone that was entered in the system.
timezone_offset	Time Zones around the world are expressed as positive or negative offsets from UTC.
status	This is the current status of the Company's account. One character is used for representing the following statuses: (A)CTIVE/ (S)USPENDED/(X) CLOSED	Alpha Character A/S/X
created_date	The date in which the Person information was added to the database.	Must comply with ISO8601 Date and Time format. Example: 2014-02-21 11:33:41.54408-05

Close Company

This operation closes a company and remove all users from the company. Closing a company changes the status flag from "ACTIVE" to "CLOSED" when completed and does not removed it from the database. This operation also has the option of closing all child companies and removing all their associated company users from the hierarchical tree.

Before the company is closed, a query is performed to verify all the companies' have a zero balance. If there is a balance, the company cannot be closed.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/closeCompany
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	CLOSE_COMPANY
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Close Company Request

{
"companyId":"40612",
"closeUsers":true,
"closeChildCompanies":true
}

Request Parameters

Name	Required	Description	Value/Range
companyId	yes	Unique Company ID company. This value is auto-generated in the Create Company API	Integer
closeUsers	yes no	Yes, to remove all Company users from the company.	Boolean True/False
closeChildCompanies	yes no	Yes, to close all child companies (entities) that are in the company's hierarchy.	Boolean True/False

Close Company Response

{
"closeCompanyResponse": {
"contextResponse": {
"tenantName": "CBD",
"statusCode": "SUCCESS",
"errors": null
},
"companyId": "40612"
 }
}

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
companyID	Unique Company ID. This value was auto-generated when the company was initially created.	Integer

Get Government ID

This operation retrieves Government ID information. When the request is processed, only the data that was entered at creation is returned.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/getGovernmentId
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GET_GOVERNMENT_ID
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Get Government ID Request

{
"governmentId":"2389"
}

Request Parameters

Parameter Name	Required	Description	Value/Range
governmentId	yes	Unique ID number that was generated when the ID information was entered into the system. Note: This is not the idNumber.	Integer

Get Government ID Respond


{
"getGovernmentIdResponse": {
"contextResponse": {
"tenantName": "CBD",
"statusCode": "SUCCESS",
"errors": null
},
"personId": "7013",
"idType": "SSN",
"idNumber": "22223C",
"issuePlace": "Austin",
"issueCountry": "FRA",
"issueDate": "2012-04-23",
"expirationDate": "2025-04-23"
       }
   }

Response Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
contextResponse	yes	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
personId	yes	This ID, is the person ID auto-generated when the person is created within the system.	Auto-generated ID returned from the server.
idType	yes	Type of ID issued from the Government.	MarticularConsular/Passport/AlienRegistration/VisaNumber/VoterID/DriversLicense/StateID/Other/TaxID/USMilitaryID/SSN/NationalID
idNumber	no	This is the official ID number from the Government ID.	Official ID returned from the server.
issuePlace	no	The city where the ID was issued.	Alpha characters
issueDate	no	This is the date in which the issue date information was added to the database.	This must comply with ISO8601 Date format Example: 2014-02-21
expirationDate	no	This is the date in which the ID expiration information was added to the database. This must comply with ISO8601 Date format	This must comply with ISO8601 Date format Example: 2014-02-21

Update Government ID

This operation changes information about an existing Government ID. * A Person can update their own Government ID.
* A Company User can update information for another Person. An example use case would be a Customer Service Person receiving a call from a person, and acting on behalf of that Person.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/updateGovernmentId
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	UPDATE_GOVERNMENT_ID
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Update Government ID Request

{
"governmentId" : 2389,
"personId": 78133,
"idType" : "SSN",
"idNumber" : "22223C",
"issuePlace" : "Austin",
"issueCountry" : "FRA",
"issueDate" : "2012-04-23",
"expirationDate" : "2025-10-23"
}

Request Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
governmentId	yes	Unique Identifier that was generated with Create Government ID and is used as a reference in the system.	Auto-generated integer.
personId	no	Person ID auto-generated when the person is created within system	Auto-generated number created.
idType	no	Type of Government ID	Marticular Consular/Passport/Alien Registration/Visa Number/Voter ID/Drivers License/State ID/Other, TaxID/US Military ID/SSN, National ID
idNumber	yes	This is the official Government ID number. Usually displayed on the physical form.	Alphanumeric String. Example: 22223C
issuePlace	no	The city where the ID was issued.	Alpha character string.
issueCountry	no	This defines the country that the ID was issued.	Must be a 3 character alpha code. This must comply with ISO 3166-1.
issueDate	no	This is the date/time in which the issue date information was added to the database.	Must comply with ISO_8601 Date and Time format (YYYY-MM-DD). Example: 2014-02-21
expirationDate	no	This is the date in which the ID expiration information was added to the database.	Must comply with ISO_8601 Date and Time format (YYYY-MM-DD). Example: 2022-02-21

Update Government ID Response

{"updateGovernmentIdResponse":{
"contextResponse":{
"tenantName":"CBD",
"statusCode":"SUCCESS",
"errors":null},
"personId":"7013","idType":"SSN",
"idNumber":"22223C","issuePlace":"Austin",
"issueCountry":"FRA",
"issueDate":"2012-04-23",
"expirationDate":"2025-10-23"} }

Response Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
contextResponse	yes	Response context.	tenantName statusCode See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
personId	no	Returns the ID that is attached for this person.	Auto-generated number created.
idType	yes	Government ID	Marticular Consular/Passport/Alien Registration/Visa Number/Voter ID/Drivers License/State ID/Other, TaxID/US Military ID/SSN, National ID
idNumber	no	This is the ID number on the physical Government ID.	Alphanumeric String. Example: 22223C
issuePlace	no	The city where the ID was issued.	Alpha character string.
issueCountry	no	This defines the country that the ID was issued. This will comply with ISO 3166	Must be a 3 character alpha code. This must comply with ISO 3166-1 standard.
issueDate	no	This is the date in which the issue date information was added to the database.	Example of the date format: 2014-02-21
expirationDate	no	This is the date in which the ID expiration information was added to the database.	Example of the date format: 2018-02-21

Notifications

You can use Notifications to send a Short Message Service (SMS) notification to SMS-enabled mobile phones and to an email. These APIs give Tenants a single way to orchestrate notification delivery across SMS and email services. A process to make sure that the right notifications go out. Notifications are designed not to just send notifications, it employs tenant specific configurations to determine when and how notifications should be sent. Configurations are from tenant preferences – In addition, it enables merchants to segment their users. For example, to send messages to all customers or just to those that belong to a certain Person Type. Notifications are sent in the language supported by the Program and in according to preferences configured for each Tenant.

Set Preferred Notifications- describes how to set notification preferences.
Notifications Opt-Out - to discontinue or not receive Notifications.

Event Types

Notifications are triggered when certain Events occur. Using the Events design, you can define the events the system raises when you change certain data with applications or run certain processes. Tenants can also define the event handlers that react to these specific event instances. Raising an event is the act of creating an event instance. When an application raises an event, the platform checks if the affected user is configured to receive a notification or has opt-out of notifications for the type of event raised. If the user is configured to receive notifications for that type, the platform checks the user's language and Notification Method (SMS/Email) settings to determine which version of the message to send and how it will be sent.

Notification Methods

Event Types

ACTIVATE_ACCOUNT_NOTIFICATION
- Person account creation event that needs to be activated.
ACTIVATE_PERSON_NOTIFICATION
BASIC_NOTIFICATION
CHANGE_PIN_PASSWORD_NOTIFICATION
CREATE_ACCOUNT_NOTIFICATION
- Represents a notification sent when a subscribers account is created.
TRANSFER_COMPLETED_NOTIFICATION
- Notification event implemented when a transfer has been TRANSFER_COMPLETED_NOTIFICATION
WELCOME_PERSON_NOTIFICATION

Notification Types

ACTIVATE_ACCOUNT
ACTIVATE_PERSON_CREDENTIAL
ADD_BALANCE_COMPLETED
AIRTIME_COMPLETED
AGENT_ASSISTED_PURCHASE_COMPLETED
BILLPAY_COMPLETED
CASH_IN_COMPLETED
COMPANY_SVA_WITHDRAWAL_COMPLETED
CREATE_ADDRESS
CREATE_EMAIL
CREATE_FIRST_EMAIL
CREATE_FIRST_PHONE
CREATE_PERSON
CREDIT_AN_ACCOUNT_COMPLETED
DEBIT_ACCOUNT_COMPLETED
DELETE_ADDRESS
DELETE_PHONE
DEPOSIT_TO_COMPANY_SVA_COMPLETED
DISTRIBUTE_STORE_VALUE_COMPLETED
EARN_ITEMS_EVENT
EARN_POINTS_EVENT
ENCASH_MT_CODE_AT_CORRESPONDENT_COMPLETED
ENCASH_MT_CODE_COMPLETED
LOAD_CARD_COMPLETED
LOAD_SVA_FROM_CREDIT_CARD_COMPLETED
MVAULT_BY_AGENT_COMPLETED
MVAULT_BY_CORRESPONDENT_COMPLETED
PERSON_TO_PERSON_TRANSFER_COMPLETED
POSITIVE_ADJUSTMENT_TRANSFER_COMPLETED
PURCHASE_COMPLETED
REDEEM_LOYALTY_REWARD_COMPLETED
REDEEM_OFFER_COMPLETED
REDEEM_REWARDS_EVENT
REFUND_SVA_TO_CREDIT_CARD_COMPLETED
REMITTANCE_COMPLETED
SENDMONEY2MTCODE_COMPLETED
SEND_MONEY_TO_MT_CODE_AT_CORRESPONDENT_COMPLETED
SEND_MONEY_TO_MTCODE_ATCORRESPONDENT_COMPLETED
SEND_MONEY_TO_MT_CODE_COMPLETED
SENDMONEY2MTCODE_COMPLETED
TEMPORARY_PASSWORD_RESET
TEMPORARY_PIN_RESET
TRANSFER_COMPLETED
TRANSFER_COMPLETED_NOTIFICATION
REMIT_FAILURE_EMAIL
REMIT_INPROGRESS_BANK (HOME SEND NOTIFICATIONS)
REMIT_INPROGRESS_CASH
REMIT_INPROGRESS_WALLET
REMIT_SUCCESS_BANK
REMIT_SUCCESS_CASH
REMIT_SUCCESS_WALLET
UPDATE_ADDRESS
UPDATE_EMAIL
UPDATE_PHONE
VERIFY_EMAIL
VERIFY_PHONE
WELCOME_PERSONACTIVATE_ACCOUNT

Notification Templates

The data available in the event is used to create the content of the notification. The different parameters in the event determine the correct notification template.

Notifications Opt Out

This operation removes an event type or all event types from a user's preferred notifications.

A Person can Opt-out of Notifications for themselves.
A Company User can Opt-out of Notifications on behalf of other Persons. An example use case would be a Customer Service Person receiving a call from a Subscriber.

"Notifications" are any messages sent via SMS, Email, or Push and support the following: - Trigger events; these events are defined by a notification type. - Bulk messaging; or "Push" notifications. - Language supported by the Program. - Are configurable according to the person's preferences, referencing the event type to receive notification messages, or not receive


Method	POST
Resource URL	{Switch_URL}/api/v1/services/notificationsOptOut
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	NOTIFICATIONS_OPT_OUT
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Notifications Opt-out

{
    "personId":"7358",
    "notifications": [
    {   "name": "TEMPORARY_PASSWORD_RESET", "active": false}
  ]
}

Request Parameters

Parameter Name	Required	Description	Value/Range
personId	no	Unique ID associated with a person.	Integer
notifications:name	yes	The notification type name..	Alpha Special characters "_" One or more of the following notification types can be selected: - "TEMPORARY_PASSWORD_RESET" - "TEMPORARY_PIN_RESET" - "WELCOME_PERSON" - "ACTIVATE_ACCOUNT" - "REDEEM_REWARDS_EVENT" - "EARN_POINTS_EVENT" - "ACTIVATE_PERSON_CREDENTIAL" - "EARN_ITEMS_EVENT" - "CREATE_FIRST_EMAIL" - "CREATE_EMAIL" - "CREATE_PHONE" - "CREATE_FIRST_PHONE" - "UPDATE_PHONE" - "DELETE_PHONE" - "CREATE_ADDRESS" - "UPDATE_ADDRESS" - "DELETE_ADDRESS" - "VERIFY_PHONE" - "VERIFY_EMAIL" - "SENDMONEY2MTCODE_COMPLETED" - "UPDATE_EMAIL" - "REMIT_SUCCESS_WALLET" - "REMIT_SUCCESS_BANK" - "REMIT_SUCCESS_CASH" - "REMIT_FAILURE_EMAIL" - "REMIT_INPROGRESS_WALLET" - "REMIT_INPROGRESS_BANK" - "REMIT_INPROGRESS_CASH"
notification:active	yes	Select false to opt out the notification, or not make active. Select true to re-enable, or make active.	Boolean True/False

Notifications Opt-Out Responses

{
   "notificationsOptOutResponse": {
      "contextResponse": {
       "tenantName": "CBD",
       "statusCode": "SUCCESS",
       "errors": null
    },
    "notifications": {
      "name": "TEMPORARY_PASSWORD_RESET",
      "active": "false"
}
    }
  }
}

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	- tenantName - statusCode - See status codes - additionalStatusCode - statusMessage - additionalStatusMessage - errorArgs - errors
notifications:name	If "active" is false, there are no notifications. If "active" is true, notifications are sent.	Boolean True/False

Set Preferred Notifications

Use this operation to configure a user to receive a notification for specific event types. - A Person can set their own preferred delivery method. By NOT passing a person's ID, the caller is requesting their own information.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/setPreferedNotifications
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	SET_PREFERED_NOTIFICATIONS
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Set Preferred Notifications Request

{
     "personId": 1394952276,
     "notificationType":"TEMPORARY_PASSWORD_RESET",
     "defaultNotification":"yes",
     "preferedNotifications": [
       {
           "priority":"1",
           "notificationMethod":"EMAIL"
       },
       {
            "priority":"2",
            "notificationMethod":"SMS"
       }
   ]
}

Request Parameters

Name	Required	Description	Value/Range
notifications:name	yes	The type of notification the person will receive. There is a type for each API that triggers a notification. Each type must be declared.	String One or more of the following notification types can be selected: - "TEMPORARY_PASSWORD_RESET" - "TEMPORARY_PIN_RESET" - "WELCOME_PERSON" - "ACTIVATE_ACCOUNT" - "REDEEM_REWARDS_EVENT" - "EARN_POINTS_EVENT" - "ACTIVATE_PERSON_CREDENTIAL" - "EARN_ITEMS_EVENT" - "CREATE_FIRST_EMAIL" - "CREATE_EMAIL" - "CREATE_PHONE" - "CREATE_FIRST_PHONE" - "UPDATE_PHONE" - "DELETE_PHONE" - "CREATE_ADDRESS" - "UPDATE_ADDRESS" - "DELETE_ADDRESS" - "VERIFY_PHONE" - "VERIFY_EMAIL" - "SENDMONEY2MTCODE_COMPLETED" - "UPDATE_EMAIL" - "REMIT_SUCCESS_WALLET" - "REMIT_SUCCESS_BANK" - "REMIT_SUCCESS_CASH" - "REMIT_FAILURE_EMAIL" - "REMIT_INPROGRESS_WALLET" - "REMIT_INPROGRESS_BANK" - "REMIT_INPROGRESS_CASH" Case Sensitive
personId	no yes - If a company User is action on behalf of another Person.	Person ID	Integer values only
defaultNotification	no	This will send the notification to the person's preferred delivery method.	- SMS - EMAIL - PUSH
priority	yes	Priority 1, Priority 2, etc. If Priority 1 is email and there is no email address, then selection 2 is chosen. In the example below, this is SMS).	Integer values only - 1 - 2 - 3
notificationMethod	yes	The available protocols used.	- SMS - EMAIL - PUSH

Set Preferred Notifications Response



{
    "setPreferedNotificationsResponse": {
      "contextResponse": {
           "tenantName": "CBD",
           "statusCode": "SUCCESS",
           "errors": null
      }
  }
}

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	- tenantName - statusCode - See status codes - additionalStatusCode - statusMessage - additionalStatusMessage - errorArgs - errors

Money Containers

Introduction

A Money Container is a wrapper that encapsulates the information of financial account components used for mobile accounts. Money containers are referenced for purchases, bills, and funds transfer. Money containers are also used to store loyalty points, earned coupons, and funds that are reserved for a program's SVA (Stored Value Account) that functions much like a gift card.

Once a money container is created, it is assigned a unique ID, which is stored on the server. Our APIs pass this money container ID to a third party connector. For information and a list of connectors see: Third Party Connectors.

Money Container Creation

Create Account

The Create Account API allows users to create Loyalty and Coupon accounts on a third party, and Stored Value Accounts (SVA) on the core Switch for storing the values of these accounts. When the Create Account API is executed, an account is created on a third party system. Once the core Switch receives an acknowledgement that the account was successfully created on the third party system, the addmoneyContainer API is executed to generate a new Money Container ID for a user. Coupons, Loyalty Points, and Stored Value Accounts (SVA) are product specific, and do not exist outside of the program. If the program ends for the user, these accounts no longer exist for the user.

image for create account

Add Money Container

The Add Money Container API is also used for creating a money container for a financial account that a user already owns such as a Credit, or Debit Card. Once the Money Container is loaded with funds after getting authorized. Bank Accounts can also have money containers attached, This includes merchant and personal accounts. These accounts are completely unaffected if a money container is removed, or added.

image for create account

Container Types and their Subtypes

LiftCommerce can process transactions for Container Types and Sub-Types listed in the table below. This table includes all the the required parameters names, attributes, and secure attributes to complete transactions for each container sub-type. Attributes listed in the "Mandatory Attributes" column are required for a success transaction. "Optional Attributes" are stored on the core server for later use. For example, you may want to store the address of a loyalty point customer for birthday mailings. Items that are stored in the "Secure Attributes" hstore are both hashed and encrypted, and is in compliance with current security standards. Attributes that are not stored in the Secure Attribute hstore are stored in the Attribute hstore as non-secure data. All non-secure data is stored as plain text.

Money Container Fees and Limits

Meta data is information we collect for fees. Every transaction has it's own fee schedule. To track the fee used and applied to transactions, a unique name is assigned, and stored as a Meta Type.

Container Types and Sub-Types needed for the AddMoneyContainer API

Container Types	Container Type Parameter Name	Container Sub-Type	Mandatory Attributes	Optional Attributes	Stored as Secure Attribute
Credit and Debit Cards	CC	VISA Mastercard American Express Discover	Account_Name EXPIRE_YEAR EXPIRE_MONTH CREDIT_CARD_CVV	-- HOLDER_FIRST_NAME HOLDER_LAST_NAME HOLDER_ADDRESS_LINE_1 HOLDER_ADDRESS_LINE_2 HOLDER_ADDRESS_CITY HOLDER_ADDRESS_STATE HOLDER_ADDRESS_POSTALCODE HOLDER_ADDRESS_COUNTRY ADDRESS_ALIAS	Yes No No No No No No No No No No No No
Bank Accounts	BANK_ACCOUNT	CHECKING SAVINGS	ROUTING_NUM ACCOUNT_NAME	ADDRESS_ALIAS	Yes Yes No
Stored Value Account	SVA	none	ACCOUNT_NAME		No

Money Container Restrictions

Money Containers can perform three Operations - Debit, Credit and a Balance Look-up. Each of these operations are configured for every money container type and its sub-type in the tenant configuration. The operations for each money container type are in the table below.
The default configuration for each operation is set to "TRUE", and cannot be overwritten within the configuration. To overwrite, the actual transaction code base must be modified.

Money Container Type	Money Container Subtype	Available Options
CC	VISA MASTERCARD DISCOVER AMERICANEXPRESS	"Debit Operations" "Balance Lookup Operations"
BANK_ACCOUNT		"Debit Operations" "Credit Operations"
SVA	none	"Debit Operations" "Credit Operations" "Balance Lookup Operations"

If a Transaction attempts to perform an operation that is defined as restricted, the following errors are returned. 1. Error status code VALIDATION
2. Additional status code MC_OPERATION_NOT_ALLOWED
3. Additional status message: Operation type {type name} is not allowed for the money container of the type {money containertype and subtype}.

Transaction Steps

Each of the Operations are further divided into Transaction Steps, which are grouped under each operation.

Operations	Transaction Steps
Debit Operations	HOLD COMMIT DEBIT REDEEM PURCHASE BANK_TRANSFER

Deletion of Money containers

Money Containers cannot be completely removed from the system. For auditing purposes; we must keep account information for all money containers should any suspicious activity occur. At this time we keep the last 4-digits of the account number as a reference.
When the Remove Money Container operation is processed on the platform, the money container is marked as deleted and the account ID which is stored is removed.

1. When a Remove Money Container transaction is processed on the platform:
2. The Money Container is marked as deleted.

Money Container Status

There are two statuses for Money Containers:
1. ACTIVE
2. DELETED
To track the possible statuses of a Money Container, see the phoenix.switch_moneycontainer table

API	State	Description
removeMoneyContainer	DELETED ( Soft)	Account has been de-activated, and can no longer be referenced. It is not removed from the system.
addMoneyContainer	ACTIVE	An existing financial account is assigned to a new Money Container ID.
createAccount	ACTIVE	New Account is created with a new Money Container ID.
getMoneyContainer	Returns money containers that are in the "ACTIVE" state.	Returns all existing Money Containers.

Add Money Container

This operation adds a Money Container for use when completing transactions. This API validates the fund source and stores the container's information for later use. A Money Container references an object on the core server that holds personal account information for a user that may include the source of of the funds or any other third party information.

To ensure credit card details are secure, customers must add their credit card information by using the provided attributes, and once a user authenticates into the system, any financial transactions they perform are encrypted, making the payment process safe and secure. Credit Card details can be separated into three distinct type of attributes:

attributesSecureRetrievable, attributes, and attributesSecure. The two attributes that must be used if card details are needed in a response are attributesSecureRetrievable and attributes. A description of all three attributes are described below: - Fields sent within the attributesSecureRetrievable field are stored encrypted in the system and are returned decrypted. - Fields sent within the attributes field are stored as clear text in the system and are returned in clear text. - Fields sent within the attributesSecure field are stored encrypted in the system and are NOT returned in the response.

The Add Money Container API is executed in one of two ways:

From a Channel - A new money container is requested for an existing financial account, such as a Credit Card, Debit Card, or a Bank Account. For example; when a consumer has an already existing credit card account and requires a money container to pull and hold account information.
Executed from the backend - When the CreateAccount API creates a new account on a third-party system, and the core receives confirmation of account creation, the Add Money Container API is automatically executed and the Money Container ID returned in the response.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/addMoneyContainer
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
tenantName	{tenant_name}

Add Money Container Request


{
  "accountNumber": "4111111111111111",
  "attributes": [

            {
      "key": "ACCOUNT_NAME",
      "value": "My Credit Card"
    },
    {
      "key": "MERCHANT_ID",
      "value": "800000000264"
    }


  ],
  "attributesSecure": [
    {
      "key": "CREDIT_CARD_CVV",
      "value": "123"
    }
  ],
  "attributesSecureRetrievable": [
    {
      "key": "EXPIRE_YEAR",
      "value": "22"
    },
        {
      "key": "EXPIRE_MONTH",
      "value": "11"
    },
    {
      "key": "CARD_HOLDER_FIRST_NAME",
      "value": "Ashwin"
    },
    {
      "key": "CARD_HOLDER_LAST_NAME",
      "value": "Tandel"
    }
  ],
  "containerSubType": "VISA",
  "containerType": "CC",
  "contextRequest": {
    "tenantName": "{ {tenant_name} }",
    "token": "{ {subs_token} }"
  },
  "currency": "840",
  "default": false,
  "description": "Add during demo"
}

Request Parameters

Parameter Name	Required	Data Type	Description	Example
ContextResponse	yes	Object Array	The response object

Add Money Container Response

{
  "addMoneyContainerResponse": {
    "contextResponse": {
      "tenantName": "CBD",
      "statusCode": "SUCCESS",
      "errors": null
    },
    "id": "6121"
  }
}

## Create Account

### Overview

This application creates a financial account on the third party system. A third party system may be either a coupon or a loyalty program provider.
When an account is initially requested, a new account is created in the third party. After the account is successfully created on the third party, a new Money Container is created in the Switch with a unique ID. This unique ID is used as the reference when accessing the money container.
[See *Money Containers*](http://www.google.com) for a full list of container types, sub-types, input parameters, attributes, and secure attributes for all money containers.

### Use Cases
- Company Users can create accounts for a company SVA, a Loyalty program, or an Offers program.
- Company Users can create accounts on behalf of a Subscriber.
- Company Users cannot create personal Money Containers, or use Money Containers for personal use.
- Subscribers can create accounts for their own SVAs, Offers and Loyalty programs.


<aside class="notice">
** Note:**
* The money container flag is set to `false` by default when it's initially created. <br> In order for a money container to be accessible, the value must be set to `true`.
</aside>

|                            |                                       |
| :---        |    :---     |
| Method                     | POST                                       |
| Resource URL               | {Switch_URL}/api/v1/services/createAccount                       |
| Request Headers            | application/json text/plain                |
| Response Formats           | application/json text/plain; charset=utf-8 |
| Entitlements               | CREATE_ACCOUNT                                 |
| Required Authentication    | Yes                                        |


### Header Parameters

| Key | Value |
|--------------|-----------------------------|
| Content-Type | application/json           |
| api-key      | {api-key} |
| Authorization| Bearer {access_token}      |
| tenantName   | {tenantName}




> Create Account Request
> A subscriber creates a personal SVA.

```json
{
  "personId":"1394952276",
  "containerType":"SVA",
  "isDefault":true,
  "currency":"840",
  "attributesSecure": [
     {"key": "send_no_email", "value": "true"},
     {"key": "first_name", "value": "Jane"},
     {"key": "last_name", "value": "Doe"},
     {"key": "ACCOUNT_NAME", "value": " Fancy Burgers Loyalty Program"}
  ]
}

Create Account Request A Company User creates a company SVA, only for company use.

{
  "entityId":"307",
  "containerType":"SVA",
  "isDefault":true,
  "currency":"840",
  "attributesSecure": [
     {"key": "send_no_email", "value": "true"},
     {"key": "first_name_of_program_manager", "value": "Joe"},
     {"key": "last_name_of_program_manager", "value": "Manager"},
     {"key": "ACCOUNT_NAME", "value": "Store's SVA for their Loyalty Program"}
  ]
}

Request Parameters

Name	Required	Description	Value
personId	no	A generated ID used to identify the use.	Auto-generated and sequenced incrementally.
entityId	no	The value must be entered if the user is a company related user. Subscribers are not associated with any company do not require this value.	Auto-generated and sequenced incrementally.
containerType	yes	This value is the parent of the container subTypes	See Money Containers for additional information.
containersubtype	no	Sub container type	See Money Containers for additional information
isDefault	yes	Designate if this money container will be used as the default money container.	Boolean true or false
attributes	yes	Key value pairs required by the third party.	Array of objects

Attributes

key	Value
send_no_email	true or false
first_name	string
last_name	string

Response Parameters

Name	Required	Description	Value
contextResponse	yes	Response returned	tenantName statusCode errors
id	yes	Money Container ID.	Integer

Create Account Response when a subscriber creates a personal SVA.

{"createAccountResponse": {
 "contextResponse": {
   "tenantName": "CBD",
   "statusCode": "SUCCESS",
   "errors": null
 },
 "id": "5890"
}
}

Create Account Response for a Company User who creates a company SVA.

{
 "createAccountResponse": {
   "contextResponse": {
     "tenantName": "CBD",
     "statusCode": "SUCCESS",
     "errors": null
   },
   "id": "6141"
 }
}

Error Responses Condition: If any of the parameters are invalid. HTTP Status Code: 4XX BAD REQUEST Example:

{
   "currency": [
       "Please provide a valid currency code.",
   ]
}

Get Money Container

This JSON operation retrieves a listing of all existing Money Containers that belong to a Person or a Company. This API will only return Money Containers in the "ACTIVE" state and not Money Containers that are marked as "DELETED".

A Subscriber can retrieve a list of their own personal Money Containers, but are unable to retrieve other Subscriber's money containers.
Only Company Users can retrieve a list of Money Containers that exist for another Person. An example use case would be a Customer Service Representative receiving a call from a Subscriber, and acting on behalf that Subscriber.
Company Users can retrieve a list of Money Containers that exist for their Company.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/getMoneyContainers
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GET_MONEY_CONTAINERS
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Get Money Container Request

{

  "contextRequest": { },
  "personId":"d34a9cb7-2a57-4b05-98fe-95c0e6665af9"

}

Request Parameters

Name	Required	Description	Value/Range
personId	yes	ID of the Person in the platform. This was generated with the `Create Person` or `Setup Account` APIs. This value can be obtained using the Get Person API.	This value is generated on the server for each Person.
entityID	no - if calling on a Person yes - if called	Id of the Company in the Platform. Is generated in Create Company API. Required only if retrieving Money Containers for a Company.	This value is generated on the server for each Company.

Get Money Container Response

{
    "contextResponse": {
        "tenantName": "CLOUDPAY",
        "statusCode": "SUCCESS",
        "errors": {}
    },
    "moneyContainers": [
        {
            "mozidoId": 4670,
            "containerId": 4670,
            "type": "CC",
            "subType": "MASTERCARD",
            "last4AccountDigits": "5454",
            "description": "Test card",
            "attributes": [
                {
                    "key": "EXPIRE_YEAR",
                    "value": "20"
                },
                {
                    "key": "ACCOUNT_NAME",
                    "value": "My Credit Card"
                },
                {
                    "key": "Credit Card Number",
                    "value": "5454545454541234"
                },
                {
                    "key": "EXPIRE_MONTH",
                    "value": "10"
                },
                {
                    "key": "MERCHANT_ID",
                    "value": "800000000264"
                }
            ]
        },
        {
            "mozidoId": 4671,
            "containerId": 4671,
            "type": "CC",
            "subType": "VISA",
            "last4AccountDigits": "1111",
            "description": "Test card",
            "attributes": [
                {
                    "key": "EXPIRE_YEAR",
                    "value": "20"
                },
                {
                    "key": "ACCOUNT_NAME",
                    "value": "My Credit Card"
                },
                {
                    "key": "Credit Card Number",
                    "value": "4111111111111234"
                },
                {
                    "key": "EXPIRE_MONTH",
                    "value": "10"
                },
                {
                    "key": "MERCHANT_ID",
                    "value": "800000000264"
                }
            ]
        },
        {
            "mozidoId": 4672,
            "containerId": 4672,
            "type": "SVA",
            "last4AccountDigits": "3035",
            "attributes": [
                {
                    "key": "ACCOUNT_NAME",
                    "value": "Test account_IPP_user"
                },
                {
                    "key": "send_no_email",
                    "value": "true"
                }
            ]
        },
        {
            "mozidoId": 4674,
            "containerId": 4674,
            "type": "CC",
            "subType": "VISA",
            "last4AccountDigits": "8700",
            "description": "Test card",
            "attributes": [
                {
                    "key": "EXPIRE_YEAR",
                    "value": "20"
                },
                {
                    "key": "ACCOUNT_NAME",
                    "value": "My Credit Card"
                },
                {
                    "key": "EXPIRE_MONTH",
                    "value": "10"
                },
                {
                    "key": "MERCHANT_ID",
                    "value": "800000000264"
                }
            ]
        },
        {
            "mozidoId": 4675,
            "containerId": 4675,
            "type": "CC",
            "subType": "VISA",
            "last4AccountDigits": "8700",
            "description": "Test card",
            "attributes": [
                {
                    "key": "EXPIRE_YEAR",
                    "value": "20"
                },
                {
                    "key": "ACCOUNT_NAME",
                    "value": "My Credit Card"
                },
                {
                    "key": "EXPIRE_MONTH",
                    "value": "10"
                },
                {
                    "key": "MERCHANT_ID",
                    "value": "800000000264"
                }
            ]
        }
    ]
}

Response Parameters

Name	Description	Value/Range
contextResponse	Response context	ContextResponse type
containerType	Money Container Type. See Money Containers for a list of valid money containers.	See Money Containers for valid types.
subType	Money Container SubType. See Money Containers for a list of valid money containers.	See Money Containers for valid sub-types.
last4AccountDigits	The last four digits of the account number associated with the money container. E.g. Last 4-digits of the credit card number.	4 digits
default	Indicates if the Money Container is setup as the default option for all payments.	true or false
attributes	Key–> Value pairs representing tenant specific information that is passed with the money container	See Attributes Table

Attributes Table

Key	Description
ACCOUNT_NAME	Name on the Card
EXPIRE_YEAR	Two digits representing the year the card expires.
EXPIRE_MONTH	Two digits representing the month the card expires.
EXTERNAL_ID	ID or card number of the external account.

Update Money Containers

This JSON operation adds or changes a Money Container's default status or any of the attributes associated with their money container.
A Person can update their own Money Containers for all their accounts.
A Company User can update Money Containers for another Person. An example use case would be a Customer Service Representative receiving a call from a Subscriber, and acting on behalf that Subscriber.
A Company User updates Money Containers for a Company

NOTE:
If no Person ID is passed, the current user's money container is updated.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/updateMoneyContainer
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	UPDATE_MONEY_CONTAINER
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Update Money Container Request

{
"id":"243659",
"personId":"1394952276",
"isDefault":false,
"description":"This was updated",
"attributes": [
{"key": "ACCOUNT_NAME", "value": "Updated account name"}
],
"attributesSecure": [
{"key": "CREDIT_CARD_CVV", "value": "123"}
]}

Request Parameters

Name	Required	Style	Description	Value/Range
contextRequest	yes		Calling context	ContextRequest type. Token parameter is required.
id	no - if called for self yes - if called for another user yes, to remove all Company users from the company.	TEMPLATE	The is the Money Container ID. If this value is unknown, you may retrieve a list of money containers using the Get Money Container API	Auto-generated integer assigned tothe money container when it was initially created
personId	no - if called for self yes - if called for another user yes, to remove all Company users from the company.	TEMPLATE	ID of the Person in the platform. This was generated with the Create Person or Setup Account APIs. This value can be obtained using the Get Person API.	This value is generated on the server for each Person.
entityId	no - if called for self yes - if called for another user yes, to remove all Company users from the company.	TEMPLATE	ID of the Company in the Platform. This was generated in Create Company API. This value can be obtained using the Get Company API. Required only if retrieving Money Containers for a Company.	This value is generated on the server for each Company.
isDefault	no	TEMPLATE	You must indicate if this money container will be used as a default money container. If not set,the server will set this value to "false". If the value is set to "true" but there is a Money Container that a)belongs to this user b) has same type and subtype c) is marked as default than new Money Container will be marked as default and old one will be set as non default.	true or false
description		TEMPLATE	Description of the change	Alphanumeric
attributes		TEMPLATE	Key–> Values pairs representing tenant specific information that is passed with the money container. A fixed key representing the name of attribute, followed by a value. See Money Containers for information on Attributes.	Key = ACCOUNT_NAME value = Alphanumeric String
attributesSecure		TEMPLATE	Secured Attributes are stored encrypted in the database. See Money Containers for information on Secured Attributes. Secure Attributes on a money container allow the user/application to load values that should be repeated to the host, but stored encrypted and not returned to the device later.	Key = CREDIT_CARD_CVV value =

Update Money Container Response

{
"updateMoneyContainerResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
},
"id": "243659",
"personId": "1394952276",
"containerType": "SVA",
"description": "This was updated",
"default": "false",
"attributes": [
{"key": "ACCOUNT_NAME",
"value": "Updated account name"},
{"key": "EXTERNAL_ID",
"value": "8353660754122439"},
{"key": "EXPIRE_YEAR",
"value": "15"},
{"key": "EXPIRE_MONTH",
"value": "12"}
],"attributesSecure": [
{"key": "first_name_of_program_manager"},
{"key": "last_name_of_program_manager"},
{"key": "send_no_email"}
] } }

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	ContextResponse type
id	Unique ID for each Money Container. All info under this parameter belong to this Money Container.	Auto-generated integer assigned to the money container when it was initi ally created
personId	Id of the Person in the platform. Is generated in Create Person or Setup Account APIs. Can be obtained in Get Person API.	This value is generated on the server for each Person.
containerType	Money Container Type. See Money Containers for a list of valid money containers.	LOYALTY SVA COUPON BANK_ACCOUNT CC
description	Description of the change	Alphanumeric
default	You must indicate if this money container will be used as a default money container. If not set, the server will set this value to "false". If the value is set to "true" but there is a Money Container that belongs to this user has same type and subtype is marked as default than new Money Container will be marked as default and old one will be set as non default.	true or false
attributes	Key –> Values pairs representing tenant specific information that is passed with the money container. A fixed key representing the name of attribute, followed by a value. See Money Containers for information on Attributes.	Key/value pair
attributesSecure	Secured Attributes are stored encrypted in the database. See Money Containers for information on Secured Attributes. Secure Attributes on a money container allow the user/application to load values that should be repeated to the host, but stored encrypted and not returned to the device later.	Key/value pair

Remove Money Container

This JSON operation removes the functionality of a Money Container. Money Containers are not removed completely from the system. For auditing purposes; we must keep the last 4 digits of the account number for all money containers should any suspicious activity occur.
A Person removes a Money Container on their own account.
A Company User removes a Money Container for another Person. An example use case would be a Customer Service Representative receiving a call from a Subscriber, and acting on behalf that Subscriber.
A Company User can remove Money Containers for a Company.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/removeMoneyContainer
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	REMOVE_MONEY_CONTAINER
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Remove Money Container Request

{
"personId":"1394952276",
"containerId":"243694"
}

Request Parameters

Name	Required	Style	Description	Value/Range
contextRequest	yes		Calling context	ContextRequest type. Token parameter is required.
personId	yes	ID of the Person in the platform. This was generated with the Create Person or Setup Account APIs. This value can be obtained using the Get Person API.	This value is generated on the server for each Person.
containerId	yes	ID that was assigned to the money container. To get a list of money containers that display all the Money Container IDs, see Get Money API.	Integer value. See Money Containers for more information.

Remove Money Container Response

{
"removeMoneyContainerResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
     }
  }
}

Response Parameters

Name	Description	Value/Range

| contextResponse | | |

Get Account Balance

This operation pulls in an existing balance of a Money Container using the Money Container ID. For Company Users; their role and their organizational hierarchy level determines the type of access. - A Person with a Subscriber role can get money container balance for themselves. - A Company User retrieving money a container balance for another Person. For example, a Customer Service Representative receiving a call from a Subscriber, and acting on behalf of that Subscriber. - A Company User retrieving a money container balance for a Company.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/getAccountBalance
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GET_ACCOUNT_BALANCE
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Optional Parameters:
If the parameter is optional and you do not want to pass it - do not pass null. Just do not send the parameter itself.

Get Account Balance Request

 {
 "personId":"1394952276",
 "moneyContainerId":"243659"
 }

Request Parameters

Name	Required	Description	Value/Range
personId	no - if called on self yes - if called for another user	ID of the Person in the platform. Is generated in Create Person or Setup Account APIs. Can be obtained in Get Person API.	This value is generated on the server for each Person.
moneyContainerId	yes	This is a auto-generated Money Container ID, created when a Person. creates their money container using either the createAccount or addMoneyContainer API. If this value is unknown, the gettmoneyContainers API is used to retrieve money container IDs.	Integer value. See Money Containers for more information.

Get Account Balance Response

{
 "getAccountBalanceResponse": {
   "contextResponse": {
     "tenantName": "channel_sdk",
     "statusCode": "SUCCESS",
     "errors": null
   },
   "moneyContainerId": "243659",
   "balance": "0",
   "availableBalance": "0",
   "holdBalance": "0",
   "currency": "840"
 }
}

Response Parameters

Name	Description	Value/Range
contextResponse	Tenant Name, status code and errors
moneyContainerId	Unique Company ID. This value was auto-generated when the company was initially created.	Integer value only
balance	The total balance of an account, that is referenced by the money container ID. This value is represented as an integer value. The balance is equal to available balance + the hold balance. In lowest denomination of the currency.	Integer value only For example, 2700 represents $27.00
avalableBalance	The total balance of an account less any funds placed on hold. This value is represented as an integer value. In lowest denomination of the currency.	Integer value only For example, 2500 represents $25.00
holdBalance	The total balance of an account less any funds placed on hold. This value is represented as an integer value.
currency	This is a numeric code that is in compliance with ISO 4217	Integer value only For example; 200 represents $2.00

Transactions

Self Register

This API is used by client programs and interfaces to allow consumers to sign-up or self-register on their own. Once registration is complete, consumers are registered on back-end sub systems that include Switch, MCP, Sticky Street and the required Authentication and Authorization systems. Consumers are able to access all services exposed by the internal systems.


Method	POST
Resource URL	/selfregister
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements
Required Authentication	No

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Self Registration Request

{
  "firstName": "string",
  "lastName": "string",
  "username": "string",
  "password": "string",
  "timeZoneFormatted": "string",
  "userContact": "string",
  "contactType": "string",
  "role": [
    "string"
  ],
  "pin": "string",
  "details": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "preferredLanguage": "string"
}

Request Parameters

Parameter Name	Required	Description	Value/Range
firstName	yes	First Name of the registered user	String
lastName	yes	Last Name of the registered user	String
username	yes	User name of the registered user	String
password	yes	Password	String
timeZoneFormatted	yes	Timezone of the consumer. Values for this could be populate using getTimeZones API. Only formats according to ISO 8601 shall be accepted: http://joda-time.sourceforge.net/timezones.html Example: America/Chicago	String
userContact	yes	Value of either Email or Mobile as per contactType selected.	String
contactType	yes	contact means - Either email or phone	String
role	yes	Role name	String
pin	yes		String
details	yes		String

Self Registration Response

{
  "contextResponse": {
    "statusCode": "string",
    "errors": [
      {
        "errorCode": "string",
        "errorMessage": "string"
      }
    ]
  },
  "uuid": "string",
  "firstName": "string",
  "lastName": "string",
  "username": "string",
  "timeZoneFormatted": "string",
  "userContact": "string",
  "contactType": "string",
  "role": [
    "string"
  ],
  "details": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Response Parameters

Parameter Name	Required	Description	Value/Range
contextResponse	Yes	Status code and Errors	String
uuid	Yes	Unique Identifier	String
firstName	Yes	First name of the regisgtered user	String
lastName	Yes	Last Name of the registered user	String
username	Yes	User name of the registered user	String
timeZoneFormatted	Yes	Timezone of the consumer. Values for this could be populate using getTimeZones API. Only formats according to ISO 8601 shall be accepted: http://joda-time.sourceforge.net/timezones.html Example: America/Chicago	String
userContact	Yes	Value of either Email or Mobile as per contactType selected.	String
contactType	Yes	contact means - Either email or phone	String
role	Yes	Role name	String
details	Yes	Key values pairs describing the details.	String

Create Terminal Session

A session with the terminal must be created before processing a payment with a credit card. This new session token last 10 minutes, but it is recommended to end the session immediately after a payment has completed processing. To end a session, the Destroy Terminal Session is called.


Method	POST
Resource URL	{POS_URL}/v1/getSessionKey
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}

Create Terminal Session Request


    {
      "merchantId": "100000000101",
      "hsn": "123456789012345",
      "serviceType": 0
    }

Request Parameters

Parameter Name	Required	Data Type	Description	Example
merchantId	yes	Integer	Identifier of the company	100000000101
hsn	yes	Integer	Identifier of the card terminal	123456789012345
serviceType	yes	Integer	Unique identifier of the service to use	0

Create Terminal Session Response

{
    "statusCode": "OK",
    "code": 200,
    "msg": "Success",
    "sessionKey": "93e6bbdb6a314754818f81f5c40f89fd"
}

Response Parameters

Parameter Name	Required	Data Type	Description	Example
statusCode	Yes	String
code		Yes	String	HTTP Status Code
msg	Yes	String	Message indicating success or failure
sessionKey	Yes	String	Session Key

Add Frequent Recipient

This operation adds a frequent recipient to the list of frequent recipients for a person, A frequent recipient is either a person or a company who regularly receives funds from a transaction, such as a utility company or a credit card company.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/addFrequentRecipient
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Add Frequent Recipient Request

{
"personId":"1394952276",
"recipientType":"PayCPG",
"name":"John Doe",
"nickname": "Fred",
"extendedAttributes": [
{"key": "Country", "value": "Argentina"},
{"key": "City", "value": "City Bell"},
{"key": "ZipCode", "value": "1896"}
]
}

Request Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
personId	yes	ID of the Person in the platform.This is required if accessing another Person's record.	Integer value auto-generated for each person added to the system in Create Person API.
recipientType	yes	The transaction type associated with the recipient.	Alpha Transaction Types: PayCPG/Airtime/BillPay/P2P
recipientSubType	no	The transaction sub-type associated with the recipient.	Based on the recipientType.
name	yes	The name of the frequent recipient.	Alphanumeric and special characters: Minimum: 1 character Maximum: 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
nickname	yes	The nickname of the frequent recipient.	Alphanumeric and special characters: Minimum: 1 character Maximum: 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
extendedAttributes	no	Key/Value pairs specific to this recipient. Can be one or more.	Key: String Value: string.

Add Frequent Recipient Response

{
"addFrequentRecipientResponse": {
"contextResponse": {
"tenantName": "M360",
"statusCode": "SUCCESS",
"errors": null
},
"frequentRecipient": {
"recipientType": "PayCPG",
"name": "John Doe",
"nickname": "Testy",
"extendedAttributes": [
{
"key": "Country",
"value": "Argentina"
},
{
"key": "ZipCode",
"value": "1896"
},
{
"key": "City",
"value": "City Bell"
}
],
"recipientID": "204"
}
}
}

Response Parameters

Parameter Name	Required	Description	Value/Range
contextResponse	yes	Response context.	tenantName statusCode - See status codes additionalStatusCode sStatusMessage additionalStatusMessage ErrorArgs Errors
recipientType	yes	The transaction type most associated with the recipient. Unique Company ID. This value was auto-generated when the company was initially created.	Alphanumeric “PayCPG” “Airtime” “BillPay” “P2P”
name	yes	The name of the frequent recipient.	Alphanumeric and special characters: Minimum: 1 character Maximum: 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
nickname	yes	The nickname of the frequent recipient.	Alphanumeric and special characters: Minimum: 1 character Maximum: 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
extendedAttributes:	no	Key/Value pairs specific to this recipient. Can be one or many.	Key: string Value: String
recipientID	yes	Recipient ID.	Integer

Get Frequent Recipient

This operation retrieves a Frequent Recipient from the Frequent Recipients List. Use this operation to view the details of a Frequent Recipient. A frequent recipient is an entity to whom a Company User regularly sends transactions, such as a utility company or a credit card company.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/getFrequentRecipient
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GET_FREQUENT_RECIPIENT
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Get Frequent Recipient Request

{
"personId": 1394952276,
"recipientId": 192
}

Request Parameters

Parameter Name	Required	Description	Value/Range
contextRequest	yes	Calling context.	ContextRequest type. A token is required.
personId	no – if accessing the Frequent Recipient List of your own account. yes – if accessing the Frequent Recipient List of another Person's account.	ID of the Person in the platform.	Integer value auto-generated for each person added to the system in Create Person API.
recipientId	yes	ID of the Recipient in the platform.	Integer value auto-generated for each person added to the system in Add Frequent Recipient API.
offset	yes	Offset amount for Pagination. For example, if there are 136 total records, and you enter 130 for your offset, the total number of records returned is five.	Integer value required Min value = zero
max	yes	This is used for Pagination, which controls the number of records in the response. If no value is passed, it defaults to zero.	Integer value required Min value = zero

Get Frequent Recipient Response

{
"getFrequentRecipientResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
},
"frequentRecipient": {
"recipientType": "PayCPG",
"name": "Mike",
"nickname": "Mike",
"extendedAttributes": {
"key": "State",
"value": "Tx"
},
"recipientID": "192"
   }
  }
}

Response Parameters

Name	Required	Definition and Business Requirements	Value/Range
contextResponse	yes	Response context.	ContextResponse type.
recipientType	yes	The transaction type most associated with the recipient.	“PayCPG”, “Airtime”, “BillPay”, “P2P”
recipientSubType	yes	The transaction sub-type most associated with the recipient.	Based on the recipientType
name	yes	The name of the frequent recipient.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
nickname	yes	The nickname of the frequent recipient.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
extendedAttributes: Key	yes	Any attribute specific to this recipient. Can be one or many.	Returned if entered if added to recipient when created.
extendedAttributes: Value	yes	A value for this attribute specific to this recipient.	Returned if entered if added to recipient when created.

Get Frequent Recipients

This JSON operation retrieves all the recipients from a recipient's list stored in the Core Switch. Recipients are added when the person uses the Add Frequent Recipients API.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/getFrequentRecipients
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GET_FREQUENT_RECIPIENTS
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Get Frequent Recipients Request


{
"personId":1394952276,
"offset":0,
"max":100
}

Request Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
contextRequest	yes	Calling context.	Should be of ContextRequest type. A token is required.
personId	no	ID of the Person in the platform.This is required if accessing another Person's record.	Integer value auto generated for each person added to the system in Create Person APIs.
offset	yes	Offset amount for Pagination. For example, if there are 136 total records, and you enter 130 for your offset, the total number of records returned is five.	Integer value required Min value = zero
max	yes	This is used for Pagination, which controls the number of records in the response. If no value is passed, it defaults to zero.	Integer value required Min value = zero

Get Frequent Recipients Response

{
"getFrequentRecipientsResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
},
"offset": "0",
"max": "100",
"totalElements": "3",
"frequentRecipients": [
{
"recipientType": "PayCPG",
"name": "Test Testerson",
"nickname": "Testy",
"extendedAttributes": [
{
"key": "Country",
"value": "Argentina"
},
{
"key": "ZipCode",
"value": "1896"
},
{
  "key": "City",
"value": "City Bell"
}
],
"recipientID": "196"
},

{
"recipientType": "PayCPG",
"name": "Test Testerson",
"nickname": "Testy",
"extendedAttributes": [
{
"key": "Country",
"value": "Argentina"
},
{
"key": "ZipCode",
"value": "1896"
},
{
"key": "City",
"value": "City Bell"
}
],
"recipientID": "203"
},
{
"recipientType": "PayCPG",
"name": "Test Testerson",
"nickname": "Testy",
"extendedAttributes": [
{
"key": "Country",
"value": "Argentina"
},
{
"key": "ZipCode",
"value": "1896"
},
{
"key": "City",
"value": "City Bell"
}
],
"recipientID": "193"
}
]
}
}

Response Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
contextResponse	yes	Response context.	Should be of ContextResponse type.
recipientType	yes	The transaction type most associated with the recipient.	“PayCPG”, “Airtime”, “BillPay”, “P2P”
recipientSubType	yes	The transaction sub-type most associated with the recipient.	Based on the recipientType
name	yes	The name of the frequent recipient.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
nickname	yes	The nickname of the frequent recipient.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
extended Attribute: Key	yes	Any attribute specific to this recipient. Can be one or many.	Returned if entered if added to recipient when created.
extended Attribute: Value	yes	A value for this attribute specific to this recipient.	Returned if entered if added to recipient when created.

Lookup Frequent Recipients

This operation retrieves the details of a Person in the Frequent Recipients List. This allows the user to re-enter information that might have changed for a recipient used repeatedly in transactions.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/lookupFrequentRecipients
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Lookup Frequent Recipients request Using a person ID

{
"personId": 1394952276,
"recipientType":"PayCPG",
"name":"Mike",
"nickname": "Mike",
"offset": 0,
"max": 10,
"filter":[
{
"key":"State",
"value":"Tx"
}]
}

Request Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
personId	no	ID of the Person in the platform.This is required if accessing another Person's record.	Integer value auto-generated for each person added to the system in Create Person.
recipientType	no	The transaction type most associated with the recipient.	“PayCPG”, “Airtime”, “BillPay”, “P2P”
recipientSubType	no	The transaction sub-type most associated with the recipient.	Based on the recipientType.
name	no	The recipient's name.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
nickname	no	The recipient's nickname.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
offset	no	Page number of the returned results.	Integer
max	no	Maximum number of returned records per page.	Integer
filter	no	Added filter to narrow the result of the search.	Key value pair.

Lookup Frequent Recipients Response

{
"lookupFrequentRecipientsResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
},
"frequentRecipients": {
"recipientType": "PayCPG",
"name": "Mike",
"nickname": "Mike",
"extendedAttributes": {
"key": "State",
"value": "Tx"
}
},
"totalCount": "1"
}
}

Response Parameters

Name	Required	Description	Value/Range
contextResponse	yes	Response context.	Should be of ContextResponse type.
recipientType	yes	The transaction type most associated with the recipient.	“PayCPG”, “Airtime”, “BillPay”, “P2P”
name	yes	The name of the frequent recipient.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
nickname	yes	The nickname of the frequent recipient.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
extendedAttributes: key	no	Any attribute specific to this recipient. Can be one or many.
extendedAttributes: value	no	A value for this attribute specific to this recipient.
totalCount	yes	The number of recipient records retrieved.

Delete Frequent Recipient

This JSON operation removes recipients from a user's Frequent Recipients list, if no long required. Using the PersonID and RecipientID, a Company User can delete a person's information from the list.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/deleteFrequentRecipient
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Delete Frequent Recipient Request

{
"personId": 1394952276,
"recipientId": 204
}

Request Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
contextRequest	yes	Calling context.	ContextRequest type. A token is required.
personId	yes	ID of the Person in the platform.	Integer value auto-generated for each person added to the system in Create Person or Setup Account APIs.
recipientIds	yes	The recipientID of the Person in the platform.	Integer value auto-generated for each recipient added to the system in Add Frequent Recipient API.

Delete Frequent Recipient Response

{
"deleteFrequentRecipientResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
}
}
}

Response Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
contextResponse	yes	Response context.	Should be of ContextResponse type.

Update Frequent Recipient

This operation changes the details of a current frequent recipient in the list of frequent recipients. A frequent recipient is either a person or a company who regularly receives funds from a transaction, such as a utility company or a credit card company.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/updateFrequentRecipient
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Update Frequent Recipient Request Request Using a person Id

{
"personId": 1394952276,
"recipientId": 192
"name": "Mike",
"extendedAttributes": [
{
"key": "State",
"value": "TX"
}
]
}

Request Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
contextRequest	yes	Calling context.	Should be of ContextRequest type. A token is required.
personId	yes	ID of the Person in the platform.This is required if accessing another Person's record.	Integer value auto-generated for each person added to the system in Create Person API.
recipientId	yes	Unique ID the recipient in the Frequent Recipient list.	Assigned by the system when the recipient was added to the Frequent Recipient List.
name	no	The name of the frequent recipient.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
nickname	no	The nickname of the frequent recipient.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
recipientType	yes	The transaction type most associated with the recipient.	Alphanumeric PayCPG/Airtime/BillPay/P2P
recipientSubType	no	The transaction sub-type most associated with the recipient.	Based on the recipientType
extendedAttribute: Key	no	Any attribute specific to this recipient. Can be one or many.(address, city, amount, etc.)	Optional
extendedAttribute: Value	no	A value for this attribute specific to this recipient.	Optional

Update Frequent Recipient Response


{
  Not Available
}

Response Parameters

Name	Required	Definition and Business Requirements	Value/Range
contextResponse	yes	Response context.	Should be of ContextResponse type.
recipientType	yes	The transaction type most associated with the recipient.	“PayCPG”, “Airtime”, “BillPay”, “P2P”
recipientSubType	no	The transaction sub-type most associated with the recipient.	Based on the recipientType
name	yes	The name of the frequent recipient.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
nickname	yes	The nickname of the frequent recipient.	Minimum of 1 alpha-numeric or special character is required. Maximum length is 127 characters. Special characters permitted: `$!@#-='(*)/+=_-)^%$#@!?>": Special characters not permitted: <&
recipientType	yes	The transaction type most associated with the recipient.	“PayCPG”, “Airtime”, “BillPay”, “P2P”
recipientSubType	no	The transaction sub-type most associated with the recipient.	Based on the recipientType.
extendedAttributes: value	no	A value for this attribute specific to this recipient.	Returns the data set in the request.

Prepare - CORE Options

All the options available under the CORE category, for the prepareTrx API.


Method	POST
Resource URL	/prepare
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Prepare Transaction Request for Core


{
    "personId": "1394950588",
    "details": {
        "name": "CORE"

    }
}

Request Parameters

Parameter Name	Required	Description	Value/Range
personId	yes	Unique ID attached to a person.	Integer
name	yes	Level under Root. Core options are all financial transactions outside of Financial Services, Loyalty and Offers.	Boolean True/False

Prepare Core Options Response


{"prepareTrxResponse":{"contextResponse":{"tenantName":"CBD",
"statusCode":"SUCCESS",
"errors":null},
"option":{"nextMethod":"prepareTrx",
"name":"CORE",
"subOptions":[{
"nextMethod":"prepareTrx",
"name":"SENDMONEY2MTCODE","availableField":{"key":"PIN","isMandatory":"true"} },
{"nextMethod":"prepareTrx","name":"LOAD_SVA_FROM_MT_CODE",
"availableField":{"key":"MT_CODE","type":"STRING","isMandatory":"true"} },

{"nextMethod":"executeTrx",
"name":"MVAULT_BY_CORRESPONDENT","availableField":[{
"key":"CREDENTIAL","type":"STRING","isMandatory":"true"},
{"key":"CREDENTIAL_TYPE","type":"STRING","isMandatory":"true"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"},
{"key":"BANK_ID","type":"STRING","isMandatory":"true"},
{"key":"BANK_BRANCH_ID","type":"STRING","isMandatory":"true"},
{"key":"INVOICE_REFERENCE","type":"STRING","isMandatory":"false"}]},

{"nextMethod":"executeTrx",
"name":"AGENT_ASSISTED_PURCHASE","availableField":[{
"key":"FROM_ACCOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"NUMBER","isMandatory":"true"},
{"key":"THIRDPARTY_TRANSACTION_ID","type":"NUMBER","isMandatory":"true"},
{"key":"COMPANY_CODE","type":"STRING","isMandatory":"true"}]},

{"nextMethod":"executeTrx",
"name":"TRANSFER","availableField":[{
"key":"FROM_ACCOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"},
{"key":"THIRD_PARTY","type":"STRING","isMandatory":"false"}]},

{"nextMethod":"executeTrx",
"name":"DEBIT","availableField":[{
"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"true"},{
"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},{
"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"}]},

{"nextMethod":"executeTrx",
"name":"ENTITY_TO_ENTITY_TRANSFER","availableField":[{
"key":"FROM_ACCOUNT","type":"NUMBER","isMandatory":"false"},
{"key":"FROM_COMPANY_CODE","type":"STRING","isMandatory":"false"},
{"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"false"},
{"key":"TO_COMPANY_CODE","type":"STRING","isMandatory":"false"},{
"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"},{
"key":"NOTES","type":"STRING","isMandatory":"false"}]},

// Ready for execution. Only parameters with isMandatory=true are required.

{"nextMethod":"executeTrx","name":"CASH_IN_SVA_AGENT","availableField": [{
"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"false"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"},
{"key":"CREDENTIAL","type":"STRING","isMandatory":"false"},
{"key":"CREDENTIAL_TYPE","type":"STRING","isMandatory":"false"},
{"key":"COMPANY_CODE","type":"STRING","isMandatory":"false"}]},

{"nextMethod":"executeTrx",
"name":"CREDIT","availableField":[
{"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"}]},

{"nextMethod":"executeTrx",
"name":"PAYMENT_TO_GA","availableField":[
{"key":"OTP","type":"STRING","isMandatory":"true"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"false"},
{"key":"CREDENTIAL","type":"STRING","isMandatory":"false"},
{"key":"CREDENTIAL_TYPE","type":"STRING","isMandatory":"false"},
{"key":"PERSON_ID","type":"NUMBER","isMandatory":"false"},
{"key":"COMPANY_CODE","type":"STRING","isMandatory":"false"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"false"}]},

{"nextMethod":"executeTrx",
"name":"CASH_OUT_SVA_AGENT","availableField":[{
"key":"CREDENTIAL","type":"STRING","isMandatory":"true"},
{"key":"CREDENTIAL_TYPE","type":"STRING","isMandatory":"true"},{
"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"NUMBER","isMandatory":"true"}]},

{"nextMethod":"executeTrx","name":"DEPOSIT_TO_SVA","availableField":
[{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"},
{"key":"SOURCE_ACCOUNT_ID","type":"NUMBER","isMandatory":"true"},
{"key":"SOURCE_TRANSACTION_ID","type":"NUMBER","isMandatory":"true"},
{"key":"SOURCE_TRANSACTION_DATETIME","type":"STRING","isMandatory":"true"},
{"key":"CREDENTIAL","type":"STRING","isMandatory":"true"},
{"key":"CREDENTIAL_TYPE","type":"STRING","isMandatory":"true"}]},

{"nextMethod":"executeTrx",
"name":"SVA_WITHDRAW_AGENT","availableField":[
{"key":"FROM_ACCOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"}]},

{"nextMethod":"executeTrx",
"name":"PERSON_TO_PERSON_TRANSFER",
"availableField":[{"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"false"},
{"key":"CREDENTIAL","type":"STRING","isMandatory":"false"},
{"key":"CREDENTIAL_TYPE","type":"STRING","isMandatory":"false"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"},
{"key":"FROM_ACCOUNT","type":"NUMBER","isMandatory":"false"},
{"key":"PIN","isMandatory":"true"}]},

{"nextMethod":"executeTrx","name":"SEND_MONEY_TO_MTCODE_ATCORRESPONDENT",
"availableField":[
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"BANK_ID","type":"STRING","isMandatory":"true"},
{"key":"BANK_BRANCH_ID","type":"STRING","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"},
{"key":"NOTIFICATION_METHOD_TYPE","type":"STRING","isMandatory":"true"},
{"key":"NOTIFICATION_METHOD_CREDENTIAL","type":"STRING","isMandatory":"true"},
{"key":"RECIPIENT_FIRST_NAME","type":"STRING","isMandatory":"true"},
{"key":"RECIPIENT_LAS
T_NAME","type":"STRING","isMandatory":"true"},
{"key":"RECIPIENT_MOBILE_PHONE","type":"STRING","isMandatory":"true"}]},

{"nextMethod":"executeTrx","name":"PAY_FROM_ACCOUNT",
"availableField":[{"key":"FROM_ACCOUNT",
"type":"STRING","isMandatory":"true"},
{"key":"AMOUNT", "type":"NUMBER","isMandatory":"true"}]},

{"nextMethod":"executeTrx","name":"CASH_IN_CORRESPONDENT","availableField":[
{"key":"CREDENTIAL","type":"STRING","isMandatory":"true"},
{"key":"CREDENTIAL_TYPE","type":"STRING","isMandatory":"true"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"},
{"key":"BANK_ID","type":"STRING","isMandatory":"true"},
{"key":"BANK_BRANCH_ID","type":"STRING","isMandatory":"true"}]},

{"nextMethod":"executeTrx","name":"DISTRIBUTE_STORE_VALUE","availableField":[
{"key":"FROM_ACCOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"}]},

{"nextMethod":"executeTrx","name":"PURCHASE","availableField":[
{"key":"FROM_ACCOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"COMPANY_CODE","type":"NUMBER","isMandatory":"true"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"}]},

{"nextMethod":"executeTrx","name":"MVAULT_BY_SVA_AGENT","availableField":[
{"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"false"},
{"key":"CREDENTIAL","type":"STRING","isMandatory":"false"},
{"key":"CREDENTIAL_TYPE","type":"STRING","isMandatory":"false"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"NUMBER","isMandatory":"true"},
{"key":"INVOICE_REFERENCE","type":"STRING","isMandatory":"false"}]},

{"nextMethod":"prepareTrx","name":"PURCHASE_PRODUCT","availableField":
[{"key":"PAYER_PRIMARY_ID","type":"STRING","isMandatory":"true"},
{"key":"PAYER_PRIMARY_ID_TYPE","type":"STRING","isMandatory":"true"}],"subOptions":

[{"nextMethod":"prepareTrx","name":"POSA","availableField":[
{"key":"PAYER_PRIMARY_ID","type":"STRING","isMandatory":"true"},
{"key":"PAYER_PRIMARY_ID_TYPE","type":"STRING","isMandatory":"true"}],
"supportedCriterion":[
{"key":"SELLER_ID","type":"STRING"},
{"key":"PAGING","type":"PAGING"}],"subOptions":

[{"nextMethod":"executeTrx","name":"TMOBILE","availableField":[
{"key":"AIRTIME_MINUTES","type":"STRING","isMandatory":"true"},
{"key":"PIN","type":"STRING","isMandatory":"true"},
{"key":"PAYER_PRIMARY_ID","type":"STRING","isMandatory":"true"},
{"key":"PAYER_PRIMARY_ID_TYPE","type":"STRING","isMandatory":"true"}],
"feeInfo":[{"description":"Mozido Purchase Airtime Fee",
"fee":{"ammount":"1000.0","currency":"USD"},
"feeId":"PURCHASE_AIRTIME_FEE","name":"Operator Fee"},
{"description":"TMobile Purchase Airtime Fee",
"fee":{"amount":"100.0","currency":"USD"},
"feeId":"3RD_PARTY_AIRTIME_FEE","name":"3rd-party Airtime Fee"}]},

{"nextMethod":"executeTrx","name":"VIRGIN_MOBILE","availableField":[
{"key":"PAYER_PRIMARY_ID","type":"STRING","isMandatory":"true"},
{"key":"PAYER_PRIMARY_ID_TYPE","type":"STRING","isMandatory":"true"}]}]},

{"nextMethod":"prepareTrx","name":"LIME",
  "availableField":[{"key":"PRINCIPAL_AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"PRINCIPAL_CURRENCY","type":"STRING","isMandatory":"true"},
{"key":"PAYER_PRIMARY_ID","type":"STRING","isMandatory":"true"},{"key":"PAYER_
PRIMARY_ID_TYPE","type":"STRING","isMandatory":"true"}]}]},

{"nextMethod":"executeTrx","name":"POSITIVE_ADJUSTMENT_TRANSFER",
"availableField":[{"key":"FROM_ACCOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"true"},{"key":"AMOUNT",
"type":"NUMBER","isMandatory":"true"},{"key":"CURRENCY_CODE","type":"STRING",
"isMandatory":"true"},{"key":"THIRD_PARTY","type":"STRING","isMandatory":"false"},
{"key":"REASON","type":"STRING","isMandatory":"true"}]},

{"nextMethod":"executeTrx","name":"LOAD_CARD","availableField":[
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"FIRST_NAME","type":"STRING",
"isMandatory":"true"},{"key":"LAST_NAME","type":"STRING","isMandatory":"true"},
{"key":"CARD_TYPE","type":"STRING","isMandatory":"false"},{"key":"CARD_NUMBER",
"type":"STRING","isMandatory":"false"},{"key":"EXP_DATE",
"type":"STRING","isMandatory":"false"},
{"key":"AUTH_CODE","type":"STRING","isMandatory":"false"},
{"key":"TERMINAL_ID","type":"NUMBER","isMandatory":"false"},{"key":"MIDDLE_NAME",
"type":"STRING","isMandatory":"false"},{"key":"PHONE_NUMBER","type":"NUMBER",
"isMandatory":"false"},{"key":"ZIP_CODE","type":"STRING","isMandatory":"false"}]},

{"nextMethod":"executeTrx","name":"AGENT_ASSISTED_PURCHASE_NO_ACCOUNT",
"availableField":[{"key":"CONTAINER_TYPE","type":"STRING","isMandatory":"true"},
{"key":"CONTAINER_SUBTYPE","type":"STRING","isMandatory":"true"},
{"key":"ACCOUNT_NUMBER","type":"NUMBER","isMandatory":"true"},
{"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
{"key":"CURRENCY_CODE","type":"NUMBER","isMandatory":"true"},
{"key":"THIRDPARTY_TRANSACTION_ID","type":"NUMBER","isMandatory":"true"},
{"key":"COMPANY_CODE","type":"STRING","isMandatory":"true"},
{"key":"HOLDER_FIRST_NAME","type":"STRING","isMandatory":"true"},
{"key":"HOLDER_LAST_NAME","type":"STRING","isMandatory":"true"},
{"key":"HOLDER_ADDRESS_LINE1","type":"STRING","isMandatory":"false"},
{"key":"HOLDER_ADDRESS_CITY","type":"STRING","isMandatory":"false"},
{"key":"HOLDER_ADDRESS_STATE","type":"STRING","isMandatory":"false"},
{"key":"HOLDER_ADDRESS_POSTALCODE","type":"STRING","isMandatory":"false"},
{"key":"EXPIRE_YEAR","type":"NUMBER","isMandatory":"false"},{"key":"EXPIRE_MONTH",
"type":"NUMBER","isMandatory":"false"},{"key":"CREDIT_CARD_CVV",
"type":"NUMBER","isMandatory":"false"}]},

{"nextMethod":"executeTrx","name":"LOAD_SVA_FROM_CREDIT_CARD","availableField":[
{"key":"FROM_ACCOUNT","type":"NUMBER","isMandatory":"true"},{"key":"TO_ACCOUNT",
"type":"NUMBER","isMandatory":"true"},{"key":"AMOUNT","type":"NUMBER",
"isMandatory":"true"},{"key":"CURRENCY_CODE","type":"STRING","isMandatory":"true"},
{"key":"THIRD_PARTY","type":"STRING","isMandatory":"false"}]},

  {"nextMethod":"prepareTrx","name":"ENCASH_MT_CODE",
  "availableField":{"key":"MT_CODE","type":"STRING","isMandatory":"true"} },

  {"nextMethod":"executeTrx","name":"REFUND_TRANSFER","availableField":[
  {"key":"FROM_ACCOUNT","type":"NUMBER","isMandatory":"true"},
  {"key":"TO_ACCOUNT","type":"NUMBER","isMandatory":"true"},
  {"key":"AMOUNT","type":"NUMBER","isMandatory":"true"},
  {"key":"ORIGINAL_UTID","type":"STRING","isMandatory":"false"},
  {"key":"TRANSACTION_ID","type":"STRING","isMandatory":"false"}]},

  {"nextMethod":"prepareTrx","name":"ENCASH_MT_CODE_AT_CORRESPONDENT",
  "availableField":[{"key":"BANK_ID","type":"STRING","isMandatory":"true"},
  {"key":"BANK_BRANCH_ID","type":"STRING","isMandatory":"true"},
  {"key":"MT_CODE","type":" STRING","isMandatory":"true"} ] }] } } }

Response Parameters

Name	Description	Value/Range
contextResponse	Context response.
nextMethod	Method or transaction used to call the option.	prepareTrx
name	Main option. Child of Root.	CORE
availableField	key/value
option:subOptions	List of Transactions that are referred to as Sub-Options.	sub-option name

List of Sub-Options available. The prepare lists all the parameters needed for the execute command.

If nextmethod is equal to prepareTrx, Prepare is run again with the sub-option name to display the available parameters. In the example below, the prepare transaction must use the sub-option name - "SENDMONEY2MTCODE" to determine the additional fields.

If nextmethod is equal to executeTrx, then no additional parameters are required. In the example below - MVAULT_BY_CORRESPONDENT displays all the available keys, and the data type required for the value. Available keys may not be require. If the isMandatory is set to true the parameter option is required. If set to false, the parameter is optional.

Execute Transaction - Debit

Performs a transaction to debit the balance of a Money Container account.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/execute
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	EXECUTE_TRX, PREPARE_TRX, DEBIT
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Execute Debit Transaction Request

Request Using a Person Id

{
  "contextRequest": {

  },
  "details": {
    "name": "CORE",
    "details":{
      "name": "DEBIT",
      "field":[{
        "key":"TO_ACCOUNT",
        "value":"5991"
      },
      {
        "key":"AMOUNT",
        "value":"2500"
      },
      {
        "key":"CURRENCY_CODE",
        "value":"840"
      }

      ]
    }
  }
}

Request Parameters for DEBIT

Parameter Name	Required	Data Type	Description	Example

Execute Debit Transaction Response


    {
      tbd
    }

Response Parameters for DEBIT

Parameter Name	Required	Data Type	Description	Example

Execute Transaction - Credit

Performs a transaction to credit the balance of a Money Container account.


Method	POST
Resource URL	/execute
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	EXECUTE_TRX, PREPARE_TRX, CREDIT
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Execute a Credit Transaction Request

Request Using a Person Id

  {
  "personId": "1394950588",
  "details": {
  "name": "CORE",
  "details": {
  "name": "CREDIT",
  "field": [{
  "key": "TO_ACCOUNT",
  "value": "244760"
  }, {
  "key": "AMOUNT",
  "value": "1000"
  }, {
  "key": "CURRENCY_CODE",
  "value": "840"
        }]
     }
    }
  }
}

Request Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
personId	no	The person ID	Integer
name	yes	Transaction Parent.	Alpha CORE Case Sensitive
name	yes	Transaction Option.	Alpha CREDIT Case Sensitive.
TO_ACCOUNT Deprecated. Credential and Credential Type must be used.	yes	Money container ID of the target SVA.If a Money Container does not exist use Add Money Container or Create Account APIs.	Integer
AMOUNT	yes	The amount of the deposit. The value is represented as an integer and must be in the lowest denomination of the country's' currency. Representing money as a double or float while performing additions, and subtractions on inexact numbers, loses precision. Whole integers are used for money, where perfect accuracy for multiples of base 10 is required.	Integer E.g. To request $40.00, enter "4000".
CURRENCY_CODE	no	The currency code of the AMOUNT. Currency code must match for both the source and recipient money containers.	Any valid currency code. See IS O 3166-1 for a valid list.

See the Switch API Reference Guide for additional details, requirements, and usage examples for this API.

Execute a Credit Transaction Response

{"executeTrxResponse":{"contextResponse":{
"tenantName":"CBD",
"statusCode":"SUCCESS"},
"confirmationInfo":{"confirmationDate":"2016-06-14T16:05:09.724-05:00",
"confirmationId":"CONFIRMATION_ID"},
"transactionInfo":{
"timeStamp":"1465938309724",
"transactionId":"43613"} } }

Response Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
contextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode StatusMessage AdditionalStatusMessage ErrorArgs Errors
confirmationDate	yes	Confirmation Date.	dateTime Example: "2016-06-14T16:05:09.724-05:00"
confirmationId	yes	Confirmation number from a third party. For now just a place holder used.
timeStamp	yes	Time represented in Epoch Time.	dateTime Example: "1415041821303"
transactionId	yes	Transaction ID.	Integer

Execute - Deposit

A Company User who has access to corporate financial accounts is able to deposits funds to a Company's Stored Value Account (SVA). This operation is the reverse of Company SVA Withdrawal.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/executeTrx
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	EXECUTE, PREPARE, DEPOSIT_TO_SVA
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Execute Transaction ( Deposit) Request


{
"PersonId": "16872", //Admin's Person ID
"details": {
"name": "CORE",
"details": {
"name": "DEPOSIT_TO_SVA",
"field": [{
"key": "TO_ACCOUNT",
"value": "11963" // Money Container ID
},
{
"key": "AMOUNT",
"value": "10000"
},
{
"key": "SOURCE_ACCOUNT_ID",
"value": "3169175108543657"
},
{
"key": "SOURCE_TRANSACTION_ID",
"value": "00987654321"
},
{
"key": "SOURCE_TRANSACTION_DATETIME",
"value": "2014-11-03T13:10:21"
},
{
"key": "CREDENTIAL", //Jack's credential
"value": "jacktheadmin"
},
{
"key": "CREDENTIAL_TYPE",
"value": "USER"
},
{
"key": "CURRENCY_CODE",
"value": "840"
}]
}
}
{"key":"IdCompanies"
}"value":true
}

Request Parameters

Field Name	Required	Definition and Business Requirements	Value/Range
personId	no	The person ID.	Integer
name	yes	Transaction Parent.	Alpha CORE Case Sensitive
name	yes	Transaction Option.	Alpha Special Characters: underscores "_" "DEPOSIT_TO_SVA" Case Sensitive.
TO_ACCOUNT Deprecated. Credential and Credential Type must be used.	no	SVA Money container ID of the source. If a Money Container does not exist use Add Money Container or Create Account APIs.	Integer.
AMOUNT	yes	The amount of the deposit. The value is represented as an integer and must be in the lowest denomination of the country's' currency. Representing money as a double or float while performing additions, and subtractions on inexact numbers, loses precision. Whole integers are used for money, where perfect accuracy for multiples of base 10 powers is required.	Integer E.g. To request $40.00, enter 4000".
CURRENCY_CODE	yes	The currency code of the AMOUNT. Currency code must match for both the source and recipient money containers.	Any valid currency code. See ISO 3166-1 for a valid list.
SOURCE_ACCOUNT_ID	yes	Source Account Number Id.	Format of the Account ID is from the bank.
SOURCE_TRANSACTION_ID	yes	Source Transaction ID. Transaction Id from the bank's HOLD request.	Format of the transaction ID is from the bank.
SOURCE_TRANSACTION_DATETIME	yes	Date and Time of the Source Transaction. Timestamp of the hold transaction.	Should comply with ISO8 601 Date and Time format.
CREDENTIAL_TYPE	yes	Agent's credential type. Although an active session token is required, credential information is passed as an additional security requirement.	For full list of credentials types please see Person Credentials page. These fields are case sensitive and must be consistent throughout your development process. It is recommended that you use Uppercase only.
CREDENTIAL	yes	Agent's credential.	If credentialType is "EMAIL", an example could be john.doe@gmail.com, Must be a valid email address. If credentialType is "USER" an example could be john.doe, or johndoe84, Must be alpha-numeric, and allow for special characters. If credentialType is "PHONE", an example can be 512-455-6789. Note: The activation code is sent using the activate PersonCredential API. Code is sent to the email address or phone number used as the credential.

Replenish a company's SVA account. Must be done by an authorized company user.

Execute Transaction (Deposit) Response


{"executeTrxResponse":{"contextResponse":{"tenantName":"CBD",
"statusCode":"SUCCESS"},"confirmationInfo":
{"confirmationDate":"2017-01-05T13:53:06.346-06:00",
"confirmationId":"CONFIRMATION_ID"},
"transactionInfo":{"timeStamp":"1483645986346","transactionId":"70155"} } }

Errors Use Case - Sysadmin who is not authorized attempts to deposit funds into a SVA.


{"executeTrxResponse":{"contextResponse":{"tenantName":"CBD",
"statusCode":"SECURITY",
"additionalStatusCode":"REQUIRED_ENTITLEMENT_NOT_GRANTED",
"statusMessage":"The Entitlement EXECUTE_TRX is required for executing this operation.",
"additionalStatusMessage":"The Entitlement EXECUTE_TRX is required for executing this
operation.",
"errorArgs":null,"errors":null} } }

Sending an invalid credential
"key": "CREDENTIAL",
"value": "Jack_the_admin"


{"executeTrxResponse":{"contextResponse":{"tenantName":"CBD",
"statusCode":"DATABASE",
"statusMessage":"Authentication Error: Credential not found",
"errorArgs":null,"errors":null} } }

Sending an invalid credential type
"key": "CREDENTIAL_TYPE",
"value": "USERxx"

{"executeTrxResponse":{"contextResponse":{"tenantName":"CBD","statusCode":"DATABASE",
"statusMessage":"Authentication Error: Credential not found",
"errorArgs":null,"errors":null} } }

Sending an invalid money container
"key": "TO_ACCOUNT",
"value": "119636".


{"executeTrxResponse":{"contextResponse":{"tenantName":"CBD",
"statusCode":"TRANSACTION",
"statusMessage":"MoneyContainer not found"},
"confirmationInfo":{"confirmationDate":"2017-01-05T14:09:41.798-06:00",
"confirmationId":"CONFIRMATION_ID"},
"transactionInfo":{"timeStamp":"1483646981798","transactionId":"70158"} } }

Sending an invalid currency code
"key": "CURRENCY_CODE",
"value": "740"


{"executeTrxResponse":{"contextResponse":{"tenantName":"CBD","statusCode":"TRANSACTION",
"additionalStatusCode":"NON_MATCHING_CURRENCY_CODE",
"statusMessage":"Error Processing Transaction",
"additionalStatusMessage":"Invalid Currency Code"},
"confirmationInfo":{"confirmationDate":"2017-01-05T14:12:56.376-06:00",
"confirmationId":"CONFIRMATION_ID"},
"transactionInfo":{"timeStamp":"1483647176376",
"transactionId":"70159"} } }

Response Parameters

Name	Required	Definition and Business Requirements	Value/Range
contextResponse	yes	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
confirmationDate	yes	Confirmation Date	dateTime Example: "2016-06-14T16:05:09.724-05:00"
confirmationId	yes
timeStamp	yes	Time represented in Epoch Time.	dateTime Example: "1415041821303"
transactionId	yes	transactionId	Integer

Execute - Send to MTC Code

This JSON operation lets a Subscriber or a Company User transfer money from their Stored Value Account (SVA) Money Container to a company holding account. These funds are accessible by a Money Transfer Code (MTC) that gets generated when the funds are placed into the company holding account. Funds are removed using either the Encash MT Code (at an Agent location ) or Encash MT Code at a Correspondent.

This Transaction can also be used if a Subscriber or an Agent gives cash to Agent. Money is given to an Agent, who debits (removes) the amount from a company's account, and sends a MTC to a recipient. From the platform perspective, the amount will be transferred from a Person's SVA to a holding account where the holding account acts like a temporary Money Container. If any fees are required, they are defined in the Tenant configuration.

External Person Identifiers (OTHERS) Additional Fields are required to identify an external Sender and Recipient. These fields are configured in the Tenant. See MTC rules for more information.

What's Next Following the receipt of the MTC via email or SMS, the Encash MT Code transaction is used to retrieve the cash.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/executeTrx
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Execute Transaction (Send money to MTC) Request


{
"details": {
"name": "CORE",
"details": {
"name": "SENDMONEY2MTCODE",
"details": {
"name": "SELF",
"field": [ {
"key": "AMOUNT",
"value": "1"
}, {
"key": "CURRENCY_CODE",
"value": "840"
}, {
"key": "PASS",
"value": "password"
}, {
"key": "SENDER_FIRST_NAME",
"value": "John"
}, {
"key": "SENDER_LAST_NAME",
"value": "Jackson"
}, {
"key": "RECIPIENT_FIRST_NAME",
"value": "TEST"
}, {
"key": "RECIPIENT_LAST_NAME",
"value": "ONE"
}, {
"key": "TOTAL_FEE_AMOUNT",
"value": "1"
}, {
"key": "FEE_SIGN",
"value": "Jackson"
}, {
"key": "SECRET_WORD",
"value": "ssecret"
}, {
"key": "NOTIFICATION_METHOD_TYPE",
"value": "EMAIL"
}, {
"key": "NOTIFICATION_METHOD_CREDENTIAL",
"value": "mp.test1@yopmail.com"
}, {
"key": "COUNTY",
"value": "ORANGE"
}, {
"key": "NAME",
"value": "Austin"
}]
}
}
}
}

Request Parameters

Parameter Name	Required	Description	Value/Range
details:name	yes	CORE
details:details:name	yes	Transaction Option under the CORE set of transactions.	SENDMONEY2MTCODE
details:details:details:name	yes	Money can be sent to self or another person.	SELF/OTHERS
details:details:details:field	yes	key value pairs that are required, or defined as isMandatory	See Details

Details

Key	Value	isMandatory
AMOUNT	The AMOUNT from the SVA account to be transferred to a MT code. This value is represented as an integer and must be in the lowest denomination of the currency. Representing money as a double or float while performing additions, and subtractions on in exact numbers, loses precision. Whole integers are used for money, where perfect accuracy for multiples of base 10 powers is required. Integer E.g. To request $40.00, enter "4000".	yes
CURRENCY_CODE	Integer Any valid currency code. See ISO 3166-1 for a valid list.	yes
MONEY_CONTAINER_ID	Integer Existing Money Container ID number.	no
SECRET_WORD	Any string of characters used to redeem the person's MTC. Similar to a password.	no
NOTIFICATION_METHOD_TYPE	Only required if sending to another person - "OTHERS". This is the notification type for the recipient. SMS/EMAIL	yes
NOTIFICATION_METHOD_CREDENTIAL	Only required if sending to another person - "OTHERS". Email address or phone number.	yes
additional attributes	Additional Fields required to identify the Sender and the Recipient are configured per Tenant. If a transaction is submitted without the configured attributes, an error message is displayed with the missing fields.	yes

Execute Transaction (Send money to MTC) Response

 {
"confirmationInfo": {
"confirmationDate": "2015-09-16T14:14:40.981-05:00",
"confirmationId": "CONFIRMATION_ID"
},
"transactionInfo": {
"timeStamp": "1442430880982",
"transactionId": "1451042"
} }

Error if money container does not contain sufficient funds.

{
"executeTrxResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "TRANSACTION",
"additionalStatusCode": "INSUFFICIENT_BALANCE",
"statusMessage": "Error Processing Transaction",
"additionalStatusMessage": "1"
},
"confirmationInfo": {
"confirmationDate": "2015-09-16T14:14:40.981-05:00",
"confirmationId": "CONFIRMATION_ID"
},
"transactionInfo": {
"timeStamp": "1442430880982",
"transactionId": "1451042"
}
}
}

Response Parameters

Name	Description	Value/Range
contextResponse	Response context.	ContextResponse type
confirmationInfo:confirmationDate		Example: "2015-09-16T14:14:40.981-05:00"
confirmationInfo:confirmationId		Unique ID generated at the time of confirmation
transactionInfo:timeStamp	Epoch time-stamp representing the transaction time.	Integer
transactionInfo:transactionId	Unique transaction ID.	Integer

Generate OTP

Generate OTP generates a payment code and sends the code via customer's preferred notification method. This one time code is typically used for authorizing a payment. A caller can be either a subscriber or a company user.
A payment code is generated by the system and sent to the customer via SMS. This code is either presented to an agent for payment authorization or the customer themselves are able to perform the transaction.

A person identified by either a PersonId or a credential/credentialType receives the generated OTP via send SMS.
If no PersonId or credential/credentialType is passed, a payment code for the person initiating the transaction (determined by the token) receives the OTP.
If the Money Container Id passed in the FROM_ACCOUNT parameter is invalid, the call will use the default money container tied to the caller.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/generateOtp
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GENERATE_OTP
Notifications	GENERATE_OTP
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Generate OTP Request

{
"personId": 10,
"fromAccount": 1,
"maxAmount": 4000,
"expireAfterSeconds": 2500,
"maxNoOfTimes": 4,
"companyCodes": [
"companyCode"
],
"channelType": "MOBILE",
"currencyCode": 840,
"comment": "this is a comment"
}

Request Parameters

Parameter Name	Required	Description	Value/Range
personId	no	Person ID of the customer.	Integer
credential	yes, if credentialType is passed.	Customer's credential.	String
credentialType	yes, if credential is passed.	Credential Type.	See the MoTEAF API Reference "Person Credentials APIs" for a list of valid credential types.
fromAccount	no - if a credential is passed	Money container ID of the Customer.	Integer
maxAmount	yes	Max amount is authorized using the payment code.	Integer Lowest denomination of the currency code. For example, if the currency is US dollars, the value is in pennies (1000 for 10 dollars).
expireAfterSeconds	no	Time until the code is rendered invalid. Value is displayed in seconds.	Integer representing seconds For example, 3600 for 1 hour.
maxNoOfTimes	no	Maximum number of times the code can be used to authorize payments.	Integer
companyCodes	yes	Merchant/Store/Company identifiers where the code can be used for payment.	String
channelType	no	The channel type used in the requestvto generate a payment code.	Alpha MOBILE/WEB_APP
currencyCode	yes	Currency Code of the maxAmount value.	Integer Any valid currency code. See ISO-3166-1 for a valid list.
comment	no	Additional information about the Customer authorization.	String

Generate OTP Response

{
"generateOtpResponse": {
"contextResponse": {
"tenantName": "Generic QSR",
"statusCode": "SUCCESS",
"additionalStatusMessage": "OTP Code generated for personId: 10"
}
}
}

Errors

Response with a validation Error

{
"generateOtpResponse": {
"contextResponse": {
"tenantName": "Generic QSR",
"statusCode": "VALIDATION",
"additionalStatusCode": "FIELD_INVALID_VALUE",
"statusMessage": "Field error in object
'com.mozido.api.core.generatepaymentcode.GenerateOtpRequest' on field 'currencyCode':
rejected value [25]",
"additionalStatusMessage": "Field currencyCode value [25] is invalid",
"errorArgs": "currencyCode,25",
"errors": null
}
}
}

Response Parameters

Parameter Name	Description	Value/Range
contextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors

Execute Transaction - Encash MT Code

This operation lets a Subscriber or a Company User to cash-out from a Money Transfer. A recipient visits an agent location, with the MT code that was generated from the Send Money to MT Code API. After verifying the recipient's identity, and MT Code, this transaction is executed by a Company User Agent, who physically hands cash to the recipient.
From the platform perspective, the amount is transferred from a SVA account Money Container holding account to a recipient.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/executeTrx
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	EXECUTE_ENCASH_MT_CODE
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Request Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
ContextRequest	yes	Calling context.	ContextRequest type.
name	yes		CORE
name	yes		ENCASH_MT_CODE
field	yes	see Attributes

Attributes

Field Name	Required	Definition and Business Requirements	Value/Range
MT_CODE	yes	The code that is used to retrieve the cash from an agent location.	Returned in the response from to MT Code API
AMOUNT	no	The amount that was placed in the hold account from the sender.	Value is a integer and must be in the lowest denomination of the currency. E.g. To request $40.00, enter "4000".
CURRENCY_CODE	no	The currency code type in which the AMOUNT is send.	Any valid currency code. See ISO 3166-1 for a valid list.

Execute Transaction Request Using Person ID

{
"amount":"1",
"currencyCode":"840",
"mtCode":"OeYC61pQ"
}

Execute Transaction Successful Response

{
"executeTrxResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS"
},
"confirmationInfo": {
"confirmationDate": "2015-09-09T07:37:35.721-05:00",
"confirmationId": "CONFIRMATION_ID"
},
"transactionInfo": {
"timeStamp": "1441802255721",
"transactionId": "1455837"
        }
     }
  }

Execute Transaction Response (Errors) ```json

{ "executeTrxResponse": { "contextResponse": { "statusCode": "SECURITY", "statusMessage": "Active token not found", "errorArgs": null, "errors": null } } } ```

{
"statusCode": "400",
"message": "validation error",
"attributes": {
"currencyCode": "should be a numeric value."
}
}

{
"executeTrxResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "TRANSACTION",
"statusMessage": "The MT Code does not exist.",
"errorArgs": null,
"errors": null
    }
  }
}

Response Parameters

Name	Required	Description	Value/Range
contextResponse	yes	Response context.	Should be of ContextResponse type.
companyID	no	A unique company ID. This is auto-generated, and will be used as the ParentID for any child companies.	Auto-generated on the server.
parentId	no	In the Tenant hierarchy this will be the ParentId of the Company created. This value is not needed if creating the top-most level.	Auto-generated on the server for children.
name	yes	Company Name.	Returns user entered name.
companyCode	yes	Company code that is supplied by a corporate office.	Returns user entered code.
country	no	This further refines default country. This will comply with ISO 3166	Returns 3 letter country code. Should comply with ISO 3166.
timezone	no	Company timezone. This value is returned in the response, and is derived from the Canonical ID that is passed from the timezone_formatted column.	Must comply with ISO_8601.
timezoneOffset	no	Time Zones around the world are expressed as positive or negative offsets from UTC. Timezones will offset from UTC without DST. This value is returned in the response, and is derived from the *Canonical ID* that is passed from the timezone_formatted column.
timezoneFormatted-	no	This value is returned in the response, and is derived from the Canonical ID that is passed from the timezone_formatted column, which is populated from the getTimeZones API.	Must comply with: http://joda-time.sourceforge.net/timezones.html
status	no	This is the current status of the company account. Default is in the ACTIVE state.	For full info see Company page.
amlFlag	no	Flag to determine if there was a AML hit.	true/false
profile_items	no	Key-value pairs of data of any sort that a Tenant wants to keep about a Company.	Attributes\Type
profile_items_Secure	no	Key-value pairs of data of any sort that a Tenant wants to keep about a Company in encrypted form.	Attributes\Type

Load SVA from Credit Card

This Transaction is designed to allow a Subscriber to add funds to their Stored Value Account using their credit card. From the platform perspective, it is a transfer between two money containers that belong to a Subscriber. Use the prepareTrx option tree to determine if there is a fee or other attributes for this transaction. All additional attributes are determined by the tenant configuration.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/executeTrx
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	LOAD_SVA_FROM_CREDIT_CARD
Required Authentication	No

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Execute Load SVA from Credit Card Transaction Request

{

    "details": {
        "name": "CORE",
        "details": {
            "name": "LOAD_SVA_FROM_CREDIT_CARD",
            "field": [ {
                "key": "AMOUNT",
                "value": "100"
            }, {
                "key": "CURRENCY_CODE",
                "value": "784"
            },{
                "key": "FROM_ACCOUNT",
                "value": "78444"
            },{
                "key": "TO_ACCOUNT",
                "value": "78455"
            },
            {
                "key": "TRANSACTION_TIME",
                "value": "83023434098"
            }
            ]
        }
    }
}

Request Parameters

Parameter Name	Required	Data Type	Description
name	Yes	string	Top level Core
details	Yes	string	Load SVA from Credit Card Object

Load SVA from Credit Card Object

Parameter Name	Required	Data Type	Description
name	Yes	string	Name of transaction
field	Yes	string	Description of key value pairs for LOAD_SVA_FROM_CREDIT_CARD

Fields

Parameter Name	Required	Data Type	Description
FROM_ACCOUNT	Yes	Credit Card money container ID for the source of funds. If a Money Container does not exist for your credit card, see Add Money Container. If a Money Container does not exist for your credit card, see Add Money Container.	Integer
TO_ACCOUNT	Yes	Money container ID of the target SVA account. If a Money Container does not exist for your SVA, see createAccount. If a Money Container was created, but the number isn't known, you can use the Get Money Container API to retrieve this number.	Integer
PIN	No	Requirement is configurable for each tenant	Pin requirements, set by the tenant must conform to PIN Configuration and Policy.
FEE	No	Requirement is configurable for each tenant.	Integer
AMOUNT	Yes	The AMOUNT from the credit card to be transferred. This amount will be charged to the card holder. This value is represented as an integer and must be in the lowest denomination of the currency. Representing money as a double or float while performing additions, and subtractions on inexact numbers, loses precision. Whole integers are Integer used for money, where perfect accuracy for multiples of base 10 powers is required.	E.g. To request $40.00, enter "4000".
CURRENCY_CODE	Yes	The currency in which the AMOUNT is send. For example the U.S is 840.	Integer Max characters: 3 Any valid currency code. See ISO 3166-1 for a valid list.

Execute Load SVA From Credit Card Transaction Response


 {
  "contextResponse": {
    "tenantName": "JANUS",
    "statusCode": "SUCCESS"
  },
  "confirmationInfo": {
    "confirmationDate": "2019-09-04T19:28:44.724Z",
    "confirmationId": "12564"
  },
  "transactionInfo": {
    "timeStamp": "1567625324724",
    "transactionId": "12564"
  }
}

Response Parameters

Parameter Name	Required	Description
contextResponse	Yes	Key value pairs describing the context response.
confirmationInfo	Yes	Key value pairs describing the confirmation info.
transactionInfo	Yes	Key value pairs describing the transaction info.

Context Response Fields


Key	Value
tenantName	tenant name
statusCode	SUCCESS or FAILURE

Confirmation Info Fields


Key	Value
confirmationDate	"2019-09-04T19:28:44.724Z"
confirmationId	Integer

Transaction Info Fields


Key	Value
timeStamp	epoch number for time.
transactionId	Integer

Execute - P2P

This Transaction is designed to allow a Subscriber to purchase something from a Company.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/executeTrx
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	EXECUTE_TRX, PREPARE_TRX, PERSON_TO_PERSON_TRANSFER
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Execute P2P Transaction Request

{

    "details": {
        "name": "CORE",
        "details": {
            "name": "PERSON_TO_PERSON_TRANSFER",
            "field": [ {
                "key": "AMOUNT",
                "value": "100"
            }, {
                "key": "CURRENCY_CODE",
                "value": "784"
            },{
                "key": "FROM_ACCOUNT",
                "value": "78444"
            },{
                "key": "TO_ACCOUNT",
                "value": "78455"
            },
            {
                "key": "TRANSACTION_TIME",
                "value": "83023434098"
            }
            ]
        }
    }
}

Request Parameters for P2P

Parameter Name	Required	Data Type	Description	Example
name	Yes	string	Top level Core	"CORE"
details	Yes	string	Person to Person Transfer Object	Object Array

Person to Person Transfer Object

Parameter Name	Required	Data Type	Description	Example
name	Yes	string	Name of transaction	"PERSON_TO_PERSON_TRANSFER"
field	Yes	string	Description of key value pairs for Person to Person Transfer	key value pairs

Fields


Key	Value
AMOUNT	Integer
CURRENCY_CODE	Integer
FROM_ACCOUNT	Sting
TO_ACCOUNT	String
TRANSACTION_TIME	String

Execute P2P Transaction Response


 {
  "contextResponse": {
    "tenantName": "JANUS",
    "statusCode": "SUCCESS"
  },
  "confirmationInfo": {
    "confirmationDate": "2019-09-04T19:28:44.724Z",
    "confirmationId": "12564"
  },
  "transactionInfo": {
    "timeStamp": "1567625324724",
    "transactionId": "12564"
  }
}

Response Parameters for P2P

Parameter Name	Required	Description
contextResponse	Yes	Key value pairs describing the context response
confirmationInfo	Yes	Key value pairs describing the confirmation info
transactionInfo	Yes	Key value pairs describing the transaction i

Context Response Fields


Key	Value
tenantName	tenant name
statusCode	SUCCESS or FAILURE

Confirmation Info Fields


Key	Value
confirmationDate	"2019-09-04T19:28:44.724Z"
confirmationId	Integer

Transaction Info Fields


Key	Value
timeStamp	epoch number for time.
transactionId	Integer

Execute P2P Transaction Response


 {
  "contextResponse": {
    "tenantName": "JANUS",
    "statusCode": "SUCCESS"
  },
  "confirmationInfo": {
    "confirmationDate": "2019-09-04T19:28:44.724Z",
    "confirmationId": "12564"
  },
  "transactionInfo": {
    "timeStamp": "1567625324724",
    "transactionId": "12564"
  }
}

Response Parameters for P2P

Parameter Name	Required	Description
contextResponse	Yes	Key value pairs describing the context response
confirmationInfo	Yes	Key value pairs describing the confirmation info
transactionInfo	Yes	Key value pairs describing the transaction i

Context Response Fields


Key	Value
tenantName	tenant name
statusCode	SUCCESS or FAILURE

Confirmation Info Fields


Key	Value
confirmationDate	"2019-09-04T19:28:44.724Z"
confirmationId	Integer

Transaction Info Fields


Key	Value
timeStamp	epoch number for time.
transactionId	Integer

Execute - Purchase

This Transaction is designed to allow a Subscriber to purchase something from a Company. From the platform perspective it is a transfer from Subscriber's Money Container to Company's Money Container. For a successful execution.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/executeTrx
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	EXECUTE_TRX, PREPARE_TRX, PURCHASE
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Execute Purchase Transaction Request

{

"details": { "name": "CORE", "details": { "name": "PURCHASE", "field": [ { "key": "COMPANY_CODE", "value": "SL1C002" }, { "key": "FROM_ACCOUNT", "value": "78444" }, { "key": "AMOUNT", "value": "100" }, { "key": "CURRENCY_CODE", "value": "784" }

] } } }

Request Parameters for Purchase

Parameter Name	Required	Data Type	Description	Example
name	Yes	string	Top level Core	"CORE"
details	Yes	string	Purchase Object	Object Array

Purchase Object

Parameter Name	Required	Data Type	Description	Example
name	Yes	string	Name of transaction	"PURCHASE"
field	Yes	string	Description of key value pairs for Purchase	key value pairs

Fields

Execute Purchase Transaction Response


 {
  "contextResponse": {
    "tenantName": "JANUS",
    "statusCode": "SUCCESS"
  },
  "confirmationInfo": {
    "confirmationDate": "2019-09-04T19:28:44.724Z",
    "confirmationId": "12564"
  },
  "transactionInfo": {
    "timeStamp": "1567625324724",
    "transactionId": "12564"
  }
}

Response Parameters for Purchase

Parameter Name	Required	Description
contextResponse	Yes	Key value pairs describing the context response
confirmationInfo	Yes	Key value pairs describing the confirmation info
transactionInfo	Yes	Key value pairs describing the transaction i

Context Response Fields


Key	Value
tenantName	tenant name
statusCode	SUCCESS or FAILURE

Confirmation Info Fields


Key	Value
confirmationDate	"2019-09-04T19:28:44.724Z"
confirmationId	Integer

Transaction Info Fields


Key	Value
timeStamp	epoch number for time.
transactionId	Integer

Execute Transaction - SVA withdraw agent

A Company User who has access to corporate financial accounts can withdraw funds from a Company's Stored Value Account (SVA) money container and process a credit to the recipient's bank account money container. Both SVAs must belong to the same entity.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/executeTrx
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	EXECUTE_TRX, PREPARE_TRX, SVA_WITHDRAW_AGENT
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Execute - SVA Withdraw Agent Request


{
"details": {
"name": "CORE",
"details": {
"name": "SVA_WITHDRAW_AGENT",
"field": [
{
"key": "FROM_ACCOUNT",
"value": "6132"
},{
"key": "TO_ACCOUNT", //Bank's Money Container.
"value": "6133"
},
{
"key": "AMOUNT",
"value": "300"
},
{
"key": "CREDENTIAL",
"value": "jdoe"
},
{
"key": "CREDENTIAL_TYPE",
"value": "user"
},
{
"key": "CURRENCY_CODE",
"value": "840"
}]
}
}
}

Request Parameters

Parameter Name	Required	Definition and Business Requirements	Value/Range
name	yes	CORE	Alpha
name	yes	SVA_WITHDRAW_AGENT	Alpha Special Characters: underscore"_"
AMOUNT	yes	The amount to be transferred FROM the SVA TO the bank account.This amount will be debited from the sender's SVA account, and credited to the Bank Account of the financial Institution. Value is represented as an integer and must be in the lowest denomination of the currency. Representing money as a double or float while performing additions, and subtractions on inexact numbers, loses precision. Whole integers are used for money, where perfect accuracy for multiples of base 10 powers is required.	Integer E.g. To request $40.00, enter "4000".
CURRENCY_CODE	yes	The currency code of the AMOUNT. Currency code must match for both the source and recipient money containers.	Any valid currency code. See ISO 3166-1 for a valid list.
FROM_ACCOUNT	yes	SVA Money container ID of the source. If a Money Container does not exist use Add Money Container or Create Account APIs.	Integer Existing money container ID number.
TO_ACCOUNT	yes	Bank Account's Money Container ID of the recipient of funds.	Integer Existing money container ID number.

Execute - SVA Withdraw Agent Response


{"executeTrxResponse":{
"contextResponse":{"tenantName":"CBD",
"statusCode":"SUCCESS"},
"confirmationInfo":{
"confirmationDate":"2016-06-15T14:27:55.872-05:00",
"confirmationId":"CONFIRMATION_ID"},
"transactionInfo":{
"timeStamp":"1466018875872",
"transactionId":"43805"} } }

Response Parameters

Parameter Name	Required	Description	Value/Range
contextResponse	yes	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
confirmationDate	yes	Confirmation Date.	dateTime Example: "2016-06-14T16:05:09.724-05:00"
confirmationId	yes
timeStamp	yes	Time represented in Epoch Time.	dateTime Example: "1415041821303"
transactionId	yes	Transaction ID	Integer

Cancel Transaction

This JSON operation cancels any previous transactions that have been executed. By providing a Transaction ID, the transaction history can be accessed and all steps reversed.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/cancelTrx
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	CANCEL_TRX
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Cancel Transaction Request

{
"transactionId": "1427399",
"reason": "Client returned item"
}

Request Parameters

Name	Required	Definition and Business Requirements	Value/Range
transactionId	yes	This is the ID of the transaction selected for cancellation. The Get Transaction Details can be used to retrieve a transaction ID if unknown.	Integer Unique auto-generated ID representing each transaction.
reason	yes	Reason for canceling the transaction.	Alpha-numeric string.

Cancel Transaction Respond

{"cancelTrxResponse":{"contextResponse":{
"tenantName":"CBD",
"statusCode":"SUCCESS"},
"confirmationInfo":{"confirmationDate":"2016-06-14T16:05:09.724-05:00",
"confirmationId":"CONFIRMATION_ID"},
"transactionInfo":{
"timeStamp":"1465938309724",
"transactionId":"43613"} } }

Response Parameters

Name	Definition and Business Requirements	Value/Range
contextResponse	Response context.	tenantName StatusCode - See status codes additionalStatusCode StatusMessage additionalStatusMessage errorArgs Errors
confirmationDate:confirmationDate	confirmation date of the transaction cancellation.	dateTime Example: 2014-05-12T09:54:11.499-05:00
confirmationId:confirmationId	Placeholder for a third party confirmation.	String Returned from the server.
transactionInfo:timeStamp	Timestamp of the last status change in Epoch time.	Integer.
transactionInfo:transactionId	ID of the transaction canceled.	Auto-generated integer.

Refund Transaction

This JSON operation refunds a transaction amount. * If an AMOUNT is not passed, the full transaction amount is refunded. * If the AMOUNT is equal or less than the original transaction amount, the specified amount is refunded. * If the AMOUNT is greater than the original transaction, the transaction will fail.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/refundTrx
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	REFUND_TRX
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Refund Transaction Request Request Using a person Id



{
"transactionId" : "1449603",
"amount" : "10",
"reason" : "test reason"
}

Request Parameters

Name	Required	Definition and Business Requirement	Value/Range
transactionId	yes	Identifier of the transaction to be refunded.	Returned when the transaction was confirmed.
amount	no	The AMOUNT to be refunded to SVA . Value is represented as an integer and must be in the lowest denomination of the currency, for example, 20 US dollars would be 2000.	Integer E.g. To request $40.00, enter "4000".
reason	no	The reason for the refund.	String Any valid reason for the refund.

Refund Transaction Response


{
"refundTrxResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SERVICE",
"statusMessage": "Transaction is not complete and can not be refunded"
},
"confirmationInfo": null,
"transactionInfo": null
}
}

Execute - CVT

Make a purchase using a Card Virtual Terminal Transaction (CVT)


Method	POST
Resource URL	{Switch_URL}/api/v1/executeTrx
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	EXECUTE_TRX, PREPARE_TRX
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/x-www-form-urlencoded
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Execute CVT Request

{
  "contextRequest": {

  },
  "details": {
    "name": "NONACCOUNT",
    "details":{
      "name": "CVT",
      "field":[{
        "key":"A_MERCHANT_ID",   (optional for IPP)
        "value":"800000000264"
      }
      ,
      {
        "key":"RSP_AC_CARD_HOLDER_FULL_NAME",
        "value":"Ashwin Tandel098"
      },
      {
        "key":"SP_accountNumberClear",
        "value":"4111111111111111"
      },
      {"key":"AMOUNT",
        "value":"2222"
      },
      {"key":"CURRENCY_CODE",
        "value":"840"
      },
    {
        "key":"RSP_AC_CARD_TYPE",
        "value":"VISA"
      },
      {
       "key":"RSP_AC_EXPIRE_MONTH",
        "value":"12"
      },
      {
        "key":"RSP_AC_EXPIRE_YEAR",
        "value":"19"
      },
      {
        "key":"RSP_AC_CARD_HOLDER_ADDRESS_LINE1",
        "value":"South Mopac"
      },
      {
        "key":"RSP_AC_CARD_HOLDER_ADDRESS_LINE2",
        "value":"Six Street"
      },
      {
        "key":"RSP_AC_CARD_HOLDER_ADDRESS_CITY",
        "value":"Austin"
      },
      {
        "key":"RSP_AC_CARD_HOLDER_ADDRESS_STATE",
        "value":"TX"
      },
      {
        "key":"RSP_AC_CARD_HOLDER_ADDRESS_COUNTRY",
        "value":"US"
      },
      {
        "key":"RSP_AC_CARD_HOLDER_ADDRESS_POSTALCODE",
        "value":"73301"
      },
      {
        "key":"RSP_AC_CARD_HOLDER_EMAIL",
        "value":"aaa@aa.com"
      },
      {
        "key":"RSP_AC_CARD_HOLDER_PHONE",
        "value":"2018897765"
      },
      {
        "key":"RSP_AC_CARD_HOLDER_ADDRESS_FAX",
        "value":"2018897764"
      }
      ,
      {
        "key":"STORE_CUSTOMER_PROFILE",
        "value":"YES"
      }]
    }
  }
}

Execute CVT Response

{
    "contextResponse": {
        "tenantName": "CLOUDPAY",
        "statusCode": "SUCCESS"
    },
    "confirmationInfo": {
        "confirmationDate": "2019-08-19T19:26:04.572Z",
        "confirmationId": "12412"
    },
    "transactionInfo": {
        "timeStamp": "0",
        "transactionId": "12412",
        "details": [
            {
                "key": "AUTH_CODE",
                "value": "PPS326"
            },
            {
                "key": "A_MERCHANT_ID",
                "value": "800000000264"
            },
            {
                "key": "BATCH_ID",
                "value": "250"
            },
            {
                "key": "CURRENCY_CODE",
                "value": "840"
            },
            {
                "key": "MESSAGE",
                "value": "Approval"
            },
            {
                "key": "ACCOUNT",
                "value": "41XXXXXXXXXX1111"
            },
            {
                "key": "AMOUNT",
                "value": "2222"
            },
            {
                "key": "TRANSACTION_TYPE_NAME",
                "value": "CVT"
            },
            {
                "key": "CARD_PROC",
                "value": "FNOR"
            },
            {
                "key": "SP_accountNumberClear",
                "value": "4111111111111111"
            },
            {
                "key": "COMMCARD",
                "value": " C "
            },
            {
                "key": "AVS_RESPONSE",
                "value": "Z"
            },
            {
                "key": "BIN_TYPE"
            },
            {
                "key": "ACCT_ID",
                "value": "1"
            },
            {
                "key": "DEFAULT_ACCT",
                "value": "Y"
            },
            {
                "key": "STORE_CUSTOMER_PROFILE",
                "value": "YES"
            },
            {
                "key": "RETREF",
             "value": "231782155564"
            },
            {
                "key": "ENTRY_MODE",
                "value": "ECommerce"
            },
            {
                "key": "CODE_RESPONSE",
                "value": "00"
            },
            {
                "key": "STAT_RESPONSE",
                "value": "A"
            },
            {
                "key": "MERCHANT_ID",
                "value": "800000000264"
            }
        ]
    }
}

Response Parameters

Name	Required	Definition and Business Requirement	Value/Range
ContextResponse	yes	Response context.	Status Codes and Messages.
ConfirmationDate	yes	Confirmation date of the transaction cancellation.	Returns the date and time in dateTime format. Example: 2014-05-12T09:54:11.499-05:00
ConfirmationID	yes	Description for the transaction ID.	Returned from the server.
TimeStamp	yes	Timestamp of the last status change in Epoch time. Unix Time is represented by a 32 bit integer.	Integer
TransactionId	yes	ID of the transaction canceled.	Auto-generated integer.

Get Transaction Details

This operation retrieves the details for a particular transaction.


Method	POST
Resource URL	{Switch_URL}/api/v1/services/getTrxDetails
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	GET_TX_DETAILS
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Get Transaction Details Request

{
"trxId": "1446611"
}

Request Parameters

Name	Required	Description	Value/Range
trxId	yes	A unique value identifying a transaction. If this value is unknown, use the confirmationCode Transaction History Lookup API.	Integer Auto-generated when a transaction is entered in the system.

Get Transaction Details Response

{
"getTrxDetailsResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
},
"transactionDetails": {
"tenant_name": "channel_sdk",
"status": "COMPLETED",
"confirmationId": "1446611",
"transaction_create_time": "2015-07-21T10:50:42.603-05:00",
"description": "CREDIT transaction to account 244728",
"transactionType": "RECOVERY",
"transactionTypeName": "CREDIT",
"caller_id": "1394931243",
"transactionAmount": "10000",
"currency": "840",
"total_fee_amount": "0",
"fee_currency": "840",
"recipient_amount": "10000",
"recipient_moneycontainer_id": "244728",
"attributes": [
{
"name": "SKIP_FEE_CALCULATION",
"value": "TRUE"
},
{
"name": "REVERSED_PAYLOAD",
"value": "1446610"
},
{
"name": "TO_ACCOUNT",
"value": "244728"
},
{
"name": "CURRENCY_CODE",
"value": "840"
},
{
"name": "OPTION_NAME",
"value": "CREDIT_RECOVERY"
}
],
"recipient_moneycontainer_subtype": "DISCOVER"
},
"transactionParticipants": [
{
"participant_type": "SUBSCRIBER",
"participant_transaction_role": "RECEIVER",
"first_name": "TEST",
"last_name": "ONE",
"person_id": "1394950588"
},
{
"participant_type": "BOX_OWNER",
"participant_transaction_role": "CALLER",
"first_name": "channel_sdk_box_owner",
"last_name": "channel_sdk_box_owner_lastname",
"person_id": "1394931243",
"attributes": {
"name": "default_city",
"value": "Austin"
}
}
]
}
}

{
"getTrxDetailsResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
},
"transactionDetails": {
"tenant_name": "channel_sdk",
"status": "COMPLETED",
"confirmationId": "1446364",
"transaction_create_time": "2015-07-21T10:05:05.531-05:00",
"description": "CREDIT transaction to account 244760",
"transactionTypeName": "CREDIT",
"caller_id": "1394931243",
"transactionAmount": "100000",
"currency": "840",
"total_fee_amount": "0",
"fee_currency": "840",
"recipient_amount": "100000",
"recipient_moneycontainer_id": "244760",
"attributes": [
{
"name": "attributes_EXTERNAL_ID",
"value": "7079154014261491"
},
{
"name": "accountHashingStrategy",
"value": "BCrypt0"
},
{
"name": "ACCOUNT_ID",
"value": "244760"
},
{
"name": "isDefault",
"value": "false"
},
{
"name": "accountNumberLast4",
"value": "1491"
},
{
"name": "attributes_ACCOUNT_NAME",
"value": "test account name"
},
{
"name": "TO_ACCOUNT",
"value": "244760"
},
{
"name": "CURRENCY_CODE",
"value": "840"
},
{
"name": "OPTION_NAME",
"value": "CREDIT"
},
{
"name": "SUB_TYPE",
"value": "null"
},
{
"name": "TYPE",
"value": "SVA"
}
]
},
"transactionParticipants": [
{
"participant_type": "SUBSCRIBER",
"participant_transaction_role": "RECEIVER",
"initial_balance": "0",
"currency": "840",
"new_balance": "100000",
"first_name": "TEST",
"last_name": "ONE",
"person_id": "1394950588",
"amount": "100000",
"amount_sign": "C",
"moneycontainer_id": "244760",
"money_container_type": "SVA",
"money_container_num": "1491"
},
{
"participant_type": "BOX_OWNER",
"participant_transaction_role": "CALLER",
"first_name": "channel_sdk_box_owner",
"last_name": "channel_sdk_box_owner_lastname",
"person_id": "1394931243",
"attributes": {
"name":"default_city",
"value": "Austin",
}
}
]
}
}

Response Parameters

Parameter Name	Definition and Business Requirements	Value/Range
contextResponse	Response context.
tenant_name	Tenant name as it appears in the system.	String Returns up to a 255 alpha-numeric character string.
status	Status of the transaction. S - Successful, F - Failed, R - Reversed, C - Cancelled, Z - Reverse Failed.	1 Alpha-character string S/F/R/C/Z
confirmationId	This is the confirmation code in the transaction history.	Integer Unique value returned from the server representing the confirmation ID of the transaction.
transaction_create_time	This information is collected at the time of the transaction. The date and time in which the person made their transaction.	Response must comply with ISO8601 Date and Time date/time format Example: 2014-06-09T09:34:06.590-05:00
transactionType	Integer value representing the transaction type.	Integer
transactionTypeName	Transaction name as it is represented in the system.	String Returns one of the following AIRTIME/PURCHASE Case sensitive.
caller_id	This Person ID of the caller. This value was auto generated when the caller was created on the system.	Integer Unique returned from the server representing the ID of the Person.
transactionAmount	Total transaction amount. Value is represented as an integer and must be in the lowest denomination of the currency. Representing money as a double or float while performing additions, and subtractions on inexact numbers, loses precision. Whole integers are used for money, where perfect accuracy for multiples of base 10 powers is required.	Integer For example, If the amount is $15.00, it is represented as "1500".
currency	The ISO-4217 code list is used in banking globally. This is a set of 3-digit codes, that represent the names of countries and dependent areas.	3 - digits. See http://en.wikipedia.org/wiki/ISO_4217#Active_codes
total_fee_amount	Value representing the fee amount. Value is represented as an integer and must be in the lowest denomination of the currency.	Integer For example, If the fee amount is 50 cents, it is represented as "50".
fee_currency	Code to represent the currency code the fee. The ISO-4217 code list is used in banking globally. This is a set of 3-digit codes, developed and maintained by the United Nations Statistics Division to represent the names of countries and dependent areas.	Integer 3 - characters. See http://en.wikipedia.org/wiki/ISO_4217#Active_codes
sender_fee_amount	A one time fee charged to the sender. Value is represented as an integer and must be in the lowest denomination of the currency.	Integer For Example, if a fee is in the amount of 50 cents, it is represented as "50".
intermediate_fee_amount	Amount of the fee for the intermediate transfer. Value is represented as an integer and must be in the lowest denomination of the currency.	Integer For Example, if a fee is in the amount of 50 cents, it is represented as "50".
recipient_amount	Amount sent to the recipient. Value is represented as an integer and must be in the lowest denomination of the currency.	Integer For example, If the amount is $15.00, it is represented as "1500".
agent_entity_id	Each agent is a Company User who is associated with a Company.	Integer Unique value returned from the server representing the ID of the Company
agent_entity_name	Entity or Company name that is associated with the Entity ID above.	Returns up to a 255 alpha-numeric string
sender_name	Name of the sender.	Returns up to a 255 alpha-numeric string
sender_moneycontainer_id	The sender's Money Container ID.	Integer Unique value returned from the server representing the ID of the Money Container.
recipient_moneycontainer_id	The recipient's Money Container ID.	Integer Unique value returned from the server representing the ID of the Money Container.
failure_reason	A reason as to why there was a failure in the business transaction.	Sting Returns up to a 255 alpha-numeric character string.
reversal_reason	A reason as to why a transaction was cancelled. A reversal involves completely resetting the original business transaction.	String Returns up to a 255 alpha-numeric character string.
reversal_note	Additional notes as to why there was a reversal in the business transaction.	String Returns up to a 255 alpha-numeric string.
reversal_date	The reversal’s posting date.	dateTime
linked_transaction_id	This is a link to any additional transactions that may have been executed as a result of this transaction. For example, a Purchase transaction, generates another transaction to notify a loyalty program. Both are independent transactions, but the Loyalty program notification transaction will have a link from the Purchase transaction.	String Returns a link if two transactions are related.
channel	Channel calling switch.	Returns the channel type.
attributes	These attributes are determined by the Tenant, and refers to the name of the key value sets. The same key request must be used throughout your program.	Must be of Attributes type.
participant_type	Participant's Person Type. See Person Type for more information.	String SUBSCRIBER/COMPANY_USER/BOX_OWNER/EXTERNAL/ENTITY Case sensitive.
participant_transaction_role	The Role of the participant in regards to the transaction. E.g. Sender role vs Receiver Role.	String SENDER/RECEIVER/INTERMEDIARY/CALLER Case sensitive.
initial_balance	Initial balance of the participant's money container. Value is represented as an integer and must be in the lowest denomination of the currency.	Integer For Example, if a fee is in the amount of $250.00, it is represented as "25000".
currency	The ISO-4217 code list is used in banking globally. This is a set of 3-digit codes, representing the names of countries and dependent areas.	3 - digits. See http://en.wikipedia.org/wiki/ISO_4217#Active_codes
new_balance	Balance after the transaction has completed. Value is represented as an integer and must be in the lowest denomination of the currency.	Returned from the request. This should be a Integer value. For Example, if a fee is in the amount of $225.00, it is represented as "22500".
funds_type	Funds type for this participant in this transaction.	String AMOUNT/FEE/AIRTIME/RESIDUAL/CASH/COMMISSION/DEPOSIT/WITHDRAWL
participant_account_number	Bank account number.	Returned from the request.
non_switch_first_name	First name of the non-switch person participating in transaction.	Returns up to a 255 alpha-numeric string
non_switch_maternal_name	Maternal name of the non-switch person participating in transaction.	Returns up to a 255 alpha-numeric string
non_switch_last_name	Last name of the non-switch person participating in transaction.	Returns up to a 255 alpha-numeric string.
non_switch_middle_name	Middle name of the non-switch person participating in transaction.	Returns up to a 255 alpha-numeric string
non_switch_phone_number	Phone number of the of the non-switch person participating in transaction.	Returns the phone number that was entered in the database for the Participant.
non_switch_email	Email address of the non-switch person participating in transaction.	Returns up to a 255 alpha-numeric string
first_name	First name of the Person participating in transaction.	Returns up to a 255 alpha-numeric string
last_name	Last name of the Person participating in transaction.	Returns up to a 255 alpha-numeric string.
maternal_name	Maternal name of the Person participating in transaction.	Returns up to a 255 alpha-numeric string.
middle_name	Middle name of the Person participating in a transaction.	Returns up to a 255 alpha-numeric string
entity_name	This is the company name that the Person or Company is associated with.	Returns up to a 255 alpha-numeric string
entity_id	This is the Company ID that the Person or Company is associated with. This value was auto-generated when the Company was created on the system.	Unique Integer returned from the server representing the ID of the Entity.
person_id	This Person_id of the participant, that was auto-generated when the Person was created on the system.	Unique Integer value returned from the server representing the ID of the Person.
amount	Amount sent by the Participant.	Integer For example; If $1.00 is send by the sender, it is recorded and returned in the response as "100"
amount_sign	An amount sign determines if a fee was collected from a transaction, and is used to indicate if the amount was added to the transaction amount. This is either a Debit or Credit to this participant.	Alpha 1- character string D/C
amount_currency	The ISO-4217 code list is used in banking globally. This is a set of 3-digit codes.	3 - digits. See http://en.wikipedia.org/wiki/ISO_4217#Active_codes
fee_amount	A fee charged for the transaction. This amount is usually equal to a percentage of the payment transaction amount.	Integer
fee_sign	A fee_sign determines if a fee was collected from a transaction, and is used to indicate if the fee was added to the transaction amount. This is either a Debit or Credit to this participant.	Alpha 1-character string D/C
fee_currency	The ISO-4217 code list is used in the banking industry, and is used globally. This is a set of 3-digit codes, developed and maintained by the United Nations Statistics Division to represent the names of countries and dependent areas.	3 - digits. See http://en.wikipedia.org/wiki/ISO_4217#Active_codes
moneycontainer_id	Money Container ID of the Participant's money container.	Unique Integer value returned from the server representing the ID of the Money Container.
money_container_type	The type of money container used.	See Money Containers for a list of valid types.
money_container_num	Last four digits of the participant's money container account number.	4-digits.
create_time	Creation date of the participant's posting.	Must be in the dateTime format.
external_type	External participants type.	MONEY_GRAM
external_info	Any external information entered into the system.	Returns up to a 255 alpha-numeric string
nfc	NFC is used mostly for financial transactions.that allows data to be exchanged between devices that are a few inches apart.	Returns up to a 255 alpha-numeric string.
aml_flag	AML status of participant.	Cleared/NotCleared/WorkInProgress
attributes	These attributes are determined by the tenant, and refers to the name of the key value sets. The same key request must be used throughout your program.	Must be of Attributes type.

Pay With Card

Manage credit card payments through a terminal.


Method	POST
Resource URL	{POS_URL}/v1/payWithCard
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
sessionKey	{sessionKey}
tenantName	{tenant_name}

Pay with Card Request

    {
      "merchantId": "100000000101",
      "hsn": "123456789012345",
      "serviceType": 0,
      "amount": "707",
      "includeSignature": false,
      "includePIN": false,
      "beep": false,
      "paymentType": "0",
      "currencyType": "USD",
      "attributes": {}
    }

The data submitted is composed of the following fields:

Request Parameters

Parameter Name	Required	Data Type	Description	Example
merchantId	yes	Integer	Identifier of the company	100000000101
hsn	yes	Integer	Identifier of the card terminal	123456789012345
serviceType	yes	Integer	Unique identifier of the service to use	0
amount	yes	currency	Amount expressed in cents.	Example = $10 = 1000
paymentType	yes	Integer	Payment type to use.	For Credit Card = 0, Crypto Currency = 1, Debit Card = 2
currencyType	yes	USD	Currency code to use.
includeSignature	no	Boolean	Indicates if the payment required signature.
includePIN	no	Boolean	Indicates if the payment required pin.
beep	no	Boolean	Indicates if the terminal should sound.
attributes	no	String	Custom information { "promoCode": "NY20019", "discount": "25" }

Pay With Card Response

    {
        "statusCode": "OK",
        "code": 200,
        "msg": "Success",
        "merchantId": "800000000264",
        "hsn": "17244PP83363874",
        "serviceType": "CARD_CONNECT",
        "reference": "12409",
        "name": "TEST CARD/EMV BIN-2",
        "amount": 1923,
        "creationDate": "2019-08-19T18:01:18.374+0000",
        "account": "22XXXXXXXXXX0856",
        "message": "Approval",
        "batchId": "250",
        "authCode": "PPS418",
        "entryMode": "EMV Contact",
        "emvData": {
            "TVR": "0000008000",
            "ARC": "00",
            "PIN": "None",
            "Signature": "true",
            "Mode": "Issuer",
            "TSI": "E800",
            "AID": "A0000000041010",
            "IAD": "0014A08003220000A49000000000000000FF",
            "Entry method": "Chip Read",
            "Application Label": "MASTERCARD"
        }
    }

    IPP-> {
        "statusCode": "OK",
        "code": 200,
        "msg": "Success",
        "merchantId": "api_1GHGYCziIz0LCVMuEbEq1cnUZxk",
        "hsn": "bhsp4fherttvo9bnbr1g",
        "serviceType": "IPP",
        "reference": "12355",
        "amount": 841,
        "creationDate": "2019-08-16T01:06:48.141+0000",
        "message": "APPROVAL VTLMC1",
        "authCode": "VTLMC1",
        "entryMode": "emv",
        "emvData": {
            "EMV_AID": "A0000000041010",
            "EMV_TSI": "E800",
            "EMV_TVR": "0800088800",
            "EMV_APP_NAME": "MASTERCARD"
        },
        "transactionType": "sale",
        "amountAuthorized": "841",
        "paymentType": "card",
        "paymentMethod": "terminal",
        "transactionSource": "api",
        "emailReceipt": "false"
    }

Response Parameters

Parameter Name	Required	Data Type	Description	Example
statusCode	yes	Boolean	Status Code	OK

Transaction History Lookup

This operation lets a Person access the entire transaction history of either a single Person or a Company, results can be filtered as desired. This operation can operate on the following use cases: - Company User requesting transactions for an entity - No filtering is used; the response contains all transactions for the company. - Company User filtering transactions by a date - The token is used to identify the person, who in this case is a Company User. - Company User filtering transactions by PersonID - A Company User requesting the entire transaction history for another person using the person's ID. - Subscriber requesting a transaction history on themselves. The token is used to identify the Subscriber. The pagination feature is used to control the output. - Transaction History Returns Debit details - This will return the Debit details if the Tenant is configured. - Transaction History Returns Fee details (amount and sign) - This will return the Fee details (amount and sign) if the Tenant is configured.

Transaction Recovery
In the event that the switch fails during a transaction, any transaction payload that was not completed is rolled back to the previous step and a message is sent stating that the rollback is due to a system restart.
A tenant can be configured to remove recovery transactions from the results of the transactionHistoryLookup call. and will not be displayed in the response. Recovery transactions WILL NOT be removed from the database table. For more information see: Financial Transaction APIs.


Method	POST
Resource URL	{Switch_URL}/api/v1/transactionhistoryLookup
Request Headers	application/json text/plain
Response Formats	application/json text/plain; charset=utf-8
Entitlements	TRANSACTION_HISTORY_LOOKUP
Required Authentication	Yes

Header Parameters

Key	Value
Content-Type	application/json
api-key	{api-key}
Authorization	Bearer {access_token}
tenantName	{tenantName}

Transaction History Lookup Request Request Using a Person ID Transaction history request for a Person, using the Person ID.

{
"personId": "1394931243",
"offset":"0",
"max":"3",
"orderByDate":"ASC"
}

Transaction history request for an Entity, using the Entity ID. Request using the entity ID


{
"entityId": "17954",
"offset":"0",
"max":"3",
"orderByDate":"ASC"
}

Transaction history Request filtering with selected traits.


{
"entityId": "17954",
"traits": [
{
"key": "TRANSACTION_DATE",
"value": "2015-01-19"
},
{
"key": "STATUS",
"value": "COMPLETED"
}
],
"offset":"0",
"max":"3",
"orderByDate":"ASC"
}

Request Parameters

Name	Required	Description	Value/Range
personId	no	If unknown, see getPerson.	Integer
entityId	no	If requesting transactions for a company, this field should contain the Company's ID. Company's ID that was auto generated when the company was initially created.	Integer
offset	no	Offset amount for Pagination. For example, if there are 136 total records, and you enter 130 for your offset, the total number of records returned is six. Records - 131,132,133,134,135, and 136 are displayed.	Integer Min value = 0
max	no	This is used for Pagination, which controls the number of records in the response. If no value is passed, it defaults to zero.	Integer Min value = 0
orderByDate	no	Returns the transactions in a list. If no value is entered, the default is ascending. -Ascending: From the earliest to the latest date is ascending. -Descending: From the latest to the earliest date is descending.	String ASC/DSC Case Sensitive.
traits:key	no	Key-value pairs used as possible options in a search. *see Key/Value Table below

Traits: Key and Value

Key	Value
AMOUNT	This value is represented as an integer and must be in the lowest denomination of the country's currency. Representing money as a double or while float performing additions, and subtractions on exact numbers lose precision. Whole integers are used for money, where perfect accuracy for multiples of base ten powers is required. E.g.: "1535" represents $15.35 if the currency is for the U.S.
STATUS	NOT_STARTED/IN_PROGRESS/COMPLETED/FAILED/ERROR/ABORTED/CANCELED
TRANSACTION_TYPE_NAME	REDEEM_REWARD/ADD_BALANCE/AIRTIME/REMITTANCE/LOYALTY/OFFERS/CASH_IN_CORRESPONDENT/PURCHASE/LOAD_CARD/CASH_IN_SVA_AGENT/ SVA_WITHDRAW_AGENT/DEBIT/DEPOSIT_TO_SVA/DISTRIBUTE_STORE_VALUE/SENDMONEY2MTCODE/SEND_MONEY_TO_MTCODE_ATCORRESPONDENT/ENCASH_MT_CODE/ENCASH_MT_CODE_AT_CORRESPONDENT/LOAD_SVA_FROM_CREDIT_CARD/MVAULT_BY_SVA_AGENT/MVAULT_BY_CORRESPONDENT/REDEEM_OFFER/POSITIVE_ADJUSTMENT_TRANSFER/PURCHASE/TRANSFER/BILL_PAY
PARTICIPANT_PERSON_ROLE	Entries are Tenant specific. SENDER/RECEIVER/CALLER/CASHIER
PARTICIPANT_TYPE	ENTITY/BOX_OWNER/COMPANY_USER/SUBSCRIBER/ENTITY
TRANSACTION_DATE	Required: Must comply with ISO8601 using the yyyy-mm-dd format Example: 2014-05-30
TTRANSACTION_START_DATETIME Required: Request must have the transaction start date in the dateTime format.	Required: Request must have the transaction start date in the dateTime format. Must comply with ISO8601 with combined time in UTC Example: 2014-04-23T23:27:52.840-05:00
TRANSACTION_END_DATETIME	Required: Request must have the transaction end date in the dateTime format. This must comply with ISO8601 with combined time in UTC Example: 2014-04-23T23:27:52.840-05:00

Response Parameters

Name	Description	Value/Range
ContextResponse	Response context.	tenantName statusCode - See status codes additionalStatusCode statusMessage additionalStatusMessage errorArgs errors
id	ID of the Transaction.	Integer Auto-generated when a transaction was entered in the system.
participants:id	Participant's ID.	Integer
participants:name	Participant's full name or Company Name if the participant is a Company.	String Returns an alphanumeric string. First and Last Name are concatenated together. If only the First Name is used, only the First Name is returned in the response.
participants:participantType	Participant's Type. If a participant is a Person, their Person Type is either a Box Owner, a Company User, or a Subscriber. If the participant is a Company, the type is Entity.	String EXTERNAL/BOX_OWNER/COMPANY_USER/SUBSCRIBER/ENTITY Case Sensitive.
participants:participantRole	Participant's Role. Sender - the person who requested the transaction if their money container is used. For example SendMoney@Agent, is a money transfer from money container to money container of a SENDER and RECEIVER. Caller - One who executes the API. For example -SendMoney@Correspondent is a Credit-based transaction, and only has the RECEIVER and CALLER as participants. Receiver - The recipient. For example, EncashMTCode transaction has a receiver as a participant.	String RECEIVER/SENDER/CALLER/INTERMEDIARY Case Sensitive.
confirmationCode	Confirmation Code.	String
transactionDateTime	This is the date and time of the actual transaction.	Must be in the dateTime format, and comply with ISO8601 with combined time in UTC. Example: 2014-02-21 11:33:41.54408-05
transactionTypeName	Type of transaction performed. To be entered as it appears in the transaction.	String REDEEM_REWARD ADD_BALANCE/AIRTIME/REMITTANCE/LOYALTY/OFFERS/CASH_IN_CORRESPONDENT/PURCHASE/LOAD_CARD/CASH_IN_SVA_AGENT/SVA_WITHDRAW_AGENT/DEBIT/DEPOSIT_TO_SVA/DISTRIBUTE_STORE_VALUE/SENDMONEY2MTCODE/SEND_MONEY_TO_MTCODE_AT_CORRESPONDENT/ENCASH_MT_CODE/ENCASH_MT_CODE_AT_CORRESPONDENT/LOAD_SVA_FROM_CREDIT_CARD/MVAULT_BY_SVA_AGENT/MVAULT_BY_CORRESPONDENT/REDEEM_OFFER/POSITIVE_ADJUSTMENT_TRANSFER/PURCHASE/TRANSFER/BILL_PAY/CALCULATE_FEE/NAREMITTANCERECEIVE Case sensitive.
transactionAmount	The amount requested for the transaction will be shown in the lowest currency for that country.	Integer For example, 1535 represents $15.35.
transactionStatus	Status of the transaction.	String NOT_STARTED/IN_PROGRESS/COMPLETED/FAILED/ERROR/ABORTED/CANCELED Uppercase. Case Sensitive.
transactions:recipientMoneyContainerSubtype	Represents the sub-type of the money container.	See Money Containers for more information.
totalCount	Total number of records that exist for the request. The number of records is not the total reflected in the response, but represents the total amount that exist in the database.	Integer Returned from the system.

Successful Response

{
"transactionHistoryLookupResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
},
"transactions": [
{
"id": "1427290",
"participants": [
{
"id": "1394950588",
"name": "TEST ONE",
"participantType": "SUBSCRIBER",
"participantRole": "RECEIVER"
},
{
"id": "1394931243",
"name": "channel_sdk_box_owner channel_sdk_box_owner_lastname",
"participantType": "BOX_OWNER",
"participantRole": "CALLER"
}
],
"confirmationCode": "1446364",
"transactionDateTime": "2015-07-21T10:05:05.531-05:00",
"transactionTypeName": "CREDIT",
"transactionAmount": "100000",
"transactionStatus": "COMPLETED"
},
{
"id": "1427399",
"participants": [
{
"id": "1394950588",
"name": "TEST ONE",
"participantType": "SUBSCRIBER",
"participantRole": "RECEIVER"
},
{
"id": "1394931243",
"name": "channel_sdk_box_owner channel_sdk_box_owner_lastname",
"participantType": "BOX_OWNER",
"participantRole": "CALLER"
}
],
"confirmationCode": "1446473",
"transactionDateTime": "2015-07-21T10:29:29.208-05:00",
"transactionTypeName": "CREDIT",
"transactionAmount": "10000",
"transactionStatus": "COMPLETED"
},
{
"id": "1427535",
"participants": [
{
"id": "1394950588",
"name": "TEST ONE",
"participantType": "SUBSCRIBER",
"participantRole": "RECEIVER"
},
{
"id": "1394931243",
"name": "channel_sdk_box_owner channel_sdk_box_owner_lastname",
"participantType": "BOX_OWNER",
"participantRole": "CALLER"
}
],
"confirmationCode": "1446609",
"transactionDateTime": "2015-07-21T10:50:08.268-05:00",
"transactionTypeName": "CREDIT",
"transactionAmount": "10000",
"transactionStatus": "COMPLETED"
},
{
"id": "1427536",
"participants": [
{
"id": "1394950588",
"name": "TEST ONE",
"participantType": "SUBSCRIBER",
"participantRole": "RECEIVER"
},
{
"id": "1394931243",
"name": "channel_sdk_box_owner channel_sdk_box_owner_lastname",
"participantType": "BOX_OWNER",
"participantRole": "CALLER"
}
],
"confirmationCode": "1446611",
"transactionDateTime": "2015-07-21T10:50:42.603-05:00",
"transactionTypeName": "CREDIT",
"transactionType": "RECOVERY",
"transactionAmount": "10000",
"transactionStatus": "COMPLETED",
"recipientMoneyContainerSubtype": "DISCOVER"
}
],
"totalCount": "26"
}
}

Successful Response using Entity ID

{
"transactionHistoryLookupResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
},
"transactions": [
{
"id": "585897",
"participants": [
{
"id": "1394783493",
"name": "Merchant ROU",
"participantType": "COMPANY_USER",
"participantRole": "CALLER"
},
{
"id": "1394783495",
"name": "Subscriber Active",
"participantType": "SUBSCRIBER",
"participantRole": "RECEIVER"
}
],
"confirmationCode": "604422",
"transactionDateTime": "2014-12-11T17:48:38.858-06:00",
"transactionTypeName": "CASH_IN_CORRESPONDENT",
"transactionAmount": "1000",
"transactionStatus": "COMPLETED"
},
{
"id": "585898",
"participants": [
{
"id": "1394783493",
"name": "Merchant ROU",
"participantType": "COMPANY_USER",
"participantRole": "CALLER"
},
{
"id": "17954",
"name": "Regional Office Utah",
"participantType": "ENTITY",
"participantRole": "SENDER"
},
{
"id": "1394783495",
"name": "Subscriber Active",
"participantType": "SUBSCRIBER",
"participantRole": "RECEIVER"
}
],
"confirmationCode": "604423",
"transactionDateTime": "2014-12-11T17:48:44.281-06:00",
"transactionTypeName": "CASH_IN_SVA_AGENT",
"transactionAmount": "1000",
"transactionStatus": "FAILED"
},
{
"id": "585899",
"participants": [
{
"id": "1394783493",
"name": "Merchant ROU",
"participantType": "COMPANY_USER",
"participantRole": "CALLER"
},
{
"id": "17954",
"name": "Regional Office Utah",
"participantType": "ENTITY",
"participantRole": "SENDER"
},
{
"id": "1394783495",
"name": "Subscriber Active",
"participantType": "SUBSCRIBER",
"participantRole": "RECEIVER"
}
],
"confirmationCode": "604424",
"transactionDateTime": "2014-12-11T17:48:44.515-06:00",
"transactionTypeName": "CASH_IN_SVA_AGENT",
"transactionAmount": "1000",
"transactionStatus": "COMPLETED"
},
{
"id": "589644",
"participants": [
{
"id": "1394783493",
"name": "Merchant ROU",
"participantType": "COMPANY_USER",
"participantRole": "CALLER"
},
{
"id": "1394783495",
"name": "Subscriber Active",
"participantType": "SUBSCRIBER",
"participantRole": "RECEIVER"
}
],
"confirmationCode": "608169",
"transactionDateTime": "2014-12-12T09:19:22.648-06:00",
"transactionTypeName": "CASH_IN_CORRESPONDENT",
"transactionAmount": "1000",
"transactionStatus": "COMPLETED"
}
],
"totalCount": "152"
}
}

Successful Response filtering with selected traits

{
"transactionHistoryLookupResponse": {
"contextResponse": {
"tenantName": "channel_sdk",
"statusCode": "SUCCESS",
"errors": null
},
"transactions": [
{
"id": "757238",
"participants": [
{
"id": "1394783493",
"name": "Merchant ROU",
"participantType": "COMPANY_USER",
"participantRole": "CALLER"
},
{
"id": "1394783495",
"name": "Subscriber Active",
"participantType": "SUBSCRIBER",
"participantRole": "RECEIVER"
}
],
"confirmationCode": "775862",
"transactionDateTime": "2015-01-19T11:56:12.765-06:00",
"transactionTypeName": "CASH_IN_CORRESPONDENT",
"transactionAmount": "1000",
"transactionStatus": "COMPLETED"
},
{
"id": "757239",
"participants": [
{
"id": "1394783493",
"name": "Merchant ROU",
"participantType": "COMPANY_USER",
"participantRole": "CALLER"
},
{
"id": "17954",
"name": "Regional Office Utah",
"participantType": "ENTITY",
"participantRole": "SENDER"
},
{
"id": "1394783495",
"name": "Subscriber Active",
"participantType": "SUBSCRIBER",
"participantRole": "RECEIVER"
}
],
"confirmationCode": "775863",
"transactionDateTime": "2015-01-19T11:56:14.120-06:00",
"transactionTypeName": "CASH_IN_SVA_AGENT",
"transactionAmount": "1000",
"transactionStatus": "COMPLETED"
},
{
"id": "757240",
"participants": [
{
"id": "1394783493",
"name": "Merchant ROU",
"participantType": "COMPANY_USER",
"participantRole": "CALLER"
},
{
"id": "17954",
"name": "Regional Office Utah",
"participantType": "ENTITY",
"participantRole": "RECEIVER"
}
],
"confirmationCode": "775864",
"transactionDateTime": "2015-01-19T11:56:15.774-06:00",
"transactionTypeName": "CREDIT",
"transactionAmount": "1000000",
"transactionStatus": "COMPLETED"
},
{
"id": "757244",
"participants": [
{
"id": "1394783103",
"name": "supertenant_sample_box_owner supertenant_sample_box_owner_lastname",
"participantType": "BOX_OWNER",
"participantRole": "CALLER"
},
{
"id": "17954",
"name": "Regional Office Utah",
"participantType": "ENTITY",
"participantRole": "RECEIVER"
}
],
"confirmationCode": "775868",
"transactionDateTime": "2015-01-19T11:56:18.177-06:00",
"transactionTypeName": "DEPOSIT_TO_SVA",
"transactionAmount": "100",
"transactionStatus": "COMPLETED"
}
],
"totalCount": "10"
}
}

Errors

This error section is stored in a separate file in includes/_errors.md. Slate allows you to optionally separate out your docs into many files...just save them to the includes folder and add them to the top of your index.md's frontmatter. Files are included in the order listed.

The API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The resource requested is hidden for administrators only.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The resource requested has been removed from our servers.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.