Difference between revisions of "JSON API Documentation"

From Cloud9 Payment Processing Gateway Documentation
Jump to: navigation, search
(Available Commands and Operands)
(JSON Schema)
 
(80 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{Template:C9Header|JSON API Documentation}}
 
{{Template:C9Header|JSON API Documentation}}
=Step One=
+
 
Please, review the '''[[Payment_Processing_Developer_Guide|Developer Guide]]''' to determine the best integration approach, before diving into the API Documentation below.
+
<br>
 +
'''ALL API is COPYRIGHT by 911 Software, INC 2019'''
 +
<br>
 +
=API DOCUMENTATION=
 +
==Executable Sandbox==
 +
* '''[http://apidocs.c9pg.com  C9PG JSON API Documentation, Sandbox, Demo and Test Suite (Swagger)]'''
 +
<br> Note: the API Sandbox contains a fair number of samples, but for complete API please refer to '''[http://cloud9paymentgateway.com/docs/API/JSON/  C9PG JSON API Documentation PDF]'''
 +
 
 +
===JSON Schema===
 +
[[image:swagger_schema.jpg|none|thumb|750px|You can click on Schema to reveal the JSON schema for the operation.|link=http://apidocs.c9pg.com]]<br>
 +
 
 +
===Executable API===
 +
[[image:swagger.jpg|none|thumb|750px|You can click on any API, such as SALE, then "Try It Out" and "Execute" to run the transaction against a test server.|link=http://apidocs.c9pg.com]]<br>
 +
 
 +
==PDF Documentation==
 +
* '''[http://cloud9paymentgateway.com/docs/API/JSON/  C9PG JSON API Documentation PDF]'''
 +
 
 +
See below for a good intro to the API with some examples.
 +
 
 +
= C9PG Portal Access =
 +
Please [http://cloud9paymentgateway.com/contact/ contact us to get access to the portal for the above Sandbox]
 +
 
 +
=Sample Working JSON=
 +
While we supply a complete sandbox [http://apidocs.c9pg.com here], where you can test various API,<br>
 +
you can also try out the examples below, using any free testing tool, such as [https://www.getpostman.com/ Postman]
 +
[[image:postman1.jpg|none|thumb|750px|POSTMAN Cloud9 JSON Sample Screenshot|link=https://www.getpostman.com/]]<br>
 +
 
 +
==Request==
 +
POST to URL: <code>https://testlink.c9pg.com:11911/restApi</code>
 +
===Sale===
 +
<code>
 +
{
 +
  "GMID": "1110222484",
 +
  "GTID": "GT1120095178",
 +
  "GMPW": "GMPW3010300378",
 +
  "TransType": "Sale",
 +
  "Medium": "Credit",
 +
  "AccountNum": "4788250000028291",
 +
  "ExpDate": "1222",
 +
  "MainAmt": "1001",
 +
  "TipAmt": "212",
 +
  "IncTaxAmt": "153",
 +
  "EntryMode": "Manual",
 +
  "NeedSwipeCard": "N"
 +
}
 +
</code>
 +
 
 +
or another example of request:
 +
 
 +
===Card Authentication (Verify)===
 +
<code>
 +
{
 +
 
 +
  "GMID": "1110222484",
 +
  "GTID": "GT1120095178",
 +
  "GMPW": "GMPW3010300378",
 +
  "TransType": "Verify",
 +
  "Medium": "Credit",
 +
  "AccountNum": "4788250000028291",
 +
  "ExpDate": "1222",
 +
  "MainAmt": "0",
 +
  "EntryMode": "Manual",
 +
  "CardPresent": "N"
 +
}
 +
</code>
 +
 
 +
==Response==
 +
You will receive an appropriate response in JSON format. Here is an example
 +
 
 +
<code>
 +
{
 +
    "AVSResultCode": "0",
 +
    "AccountNum": "478825******8291",
 +
    "AuthAmt": "1213",
 +
    "AuthCode": "TAS701",
 +
    "AuthDate": "20191010",
 +
    "AuthTime": "050209",
 +
    "Brand": "Visa",
 +
    "ErrorCode": "000",
 +
    "ErrorText": "APPROVAL TAS701 ",
 +
    "ExpDate": "1222",
 +
    "GMID": "1110222484",
 +
    "GMPW": "GMPW3010300378",
 +
    "GTID": "GT1120095178",
 +
    "GTRC": "194baa7ad35b4daea69879c94a3a9898",
 +
    "MainAmt": "1001",
 +
    "Medium": "Credit",
 +
    "MerchantAddr": "265 S Federal Hwy",
 +
    "MerchantCity": "Deerfield Beach",
 +
    "MerchantName": "TSYS Test",
 +
    "MerchantPhoneNum": "5613929606",
 +
    "MerchantState": "FL",
 +
    "MerchantZip": "33441",
 +
    "NewRecordCreated": "Y",
 +
    "ProcessorID": "40203",
 +
    "ResponseCode": "00",
 +
    "ResponseText": "APPROVAL TAS701 ",
 +
    "ResultCode": "000",
 +
    "ResultText": "APPROVAL TAS701 ",
 +
    "SESSIONID": "Web{a6270e3e-d488-4243-a46f-d8740d3e725d}_1570698127640",
 +
    "Status": "success",
 +
    "TipAmt": "212",
 +
    "TransType": "Sale",
 +
    "TransactionIdentifier": "000000000234399"
 +
}
 +
</code>
 +
 
 +
=Test Cards and Amounts=
 +
'''Aside from the example above, only specific account numbers, AVS, CVV and amounts will result in approvals'''<br>
 +
Please, see [[TSYS_Test_Account|TSYS Test Account]]
  
 
=Elements=
 
=Elements=
Line 9: Line 118:
  
 
=Connection Types=
 
=Connection Types=
;PDC Connection:Connects to the local device driver - '''wss://localhost:5556/'''
+
{{Template:ConnectionTypes}}
;PWC Connection:Connects directly to the Cloud9 server - '''https://testlink.c9pg.com:5558/hj'''
 
 
 
=Basic Transaction=
 
  
{  // REQUEST
+
=Core Key Names / Commands=
  "GMID":"10XXXXXX50",  // Gateway Merchant ID
 
  "GTID":"GTXXXXXXX53", // Gateway Terminal ID
 
  "GMPW":"XXX",        // Gateway Password
 
  "TransType":"Auth",  // Transaction Type
 
  "Medium":"Credit",    // Transaction Medium (Credit=Credit Card)
 
  "MainAmt":"123",      // Amount
 
  "IncTaxAmt":"56",    // Tax Amount
 
  "SourceTraceNum":"123456"  // Trace Number
 
}
 
 
{  // RESPONSE
 
  "Status": "success",  // Response Status
 
  "ResponseCode": "00", // Response Code
 
  "AuthCode": "12345A"  // Authorization Approval Code
 
}
 
 
 
=Core Commands/Key Names=
 
==Core Commands==
 
 
{| class="wikitable"
 
{| class="wikitable"
 
!scope="col"|Value
 
!scope="col"|Value
Line 46: Line 134:
 
|Gateway Account Password
 
|Gateway Account Password
 
|-
 
|-
|TransType
+
|[[#TransType - Transaction Type Command|TransType]]
 
|Transaction Type
 
|Transaction Type
 
|-
 
|-
|Medium
+
|[[#Medium - Processing Medium Command|Medium]]
 
|Transaction Medium (e.g. Credit Card/Debit Card/etc)
 
|Transaction Medium (e.g. Credit Card/Debit Card/etc)
 
|-
 
|-
Line 56: Line 144:
 
|-
 
|-
 
|IncTaxAmt
 
|IncTaxAmt
|Tax Amount
+
|Tax Amount - Required for Corporate Cards to avoid downgrades
 
|-
 
|-
 
|SourceTraceNum
 
|SourceTraceNum
 
|Merchant Transaction Trace Number
 
|Merchant Transaction Trace Number
|-
 
|IncTaxAmt
 
|Tax Amount
 
 
|-
 
|-
 
|InvoiceNum
 
|InvoiceNum
Line 93: Line 178:
 
|CardPresent
 
|CardPresent
 
|Sets the Card Present Indicator (optional)
 
|Sets the Card Present Indicator (optional)
 +
|-
 +
|EntryMode (optional)
 +
|Entry Mode
 
|}
 
|}
  
 
+
=Core Values=
  
 
==TransType - Transaction Type Command==
 
==TransType - Transaction Type Command==
Line 113: Line 201:
 
|Modify
 
|Modify
 
|Modifies a transaction, also finalizing it and getting it ready to be batched/settled
 
|Modifies a transaction, also finalizing it and getting it ready to be batched/settled
 +
|-
 +
|Finalize
 +
|Finalizes Authorization and turns then into Sale, getting it ready to be batched/settled
 +
 
|-
 
|-
 
|Void
 
|Void
Line 157: Line 249:
 
|}
 
|}
  
=Live Sample Companions=
+
==Boolean Values==
&rarr; '''NOTE:''' It is '''highly recommended''' that you use the live '''[[Cloud9 API|PDC API Sample]]''' or '''[[HTML Web API|WEB API Sample]]''',<br>which have real time source code windows to help you understand the API.
+
{| class="wikitable"
<br>
+
!scope="col"|Value
 
+
!scope="col"|Explanation
=Using API Documentation=
+
|-
*'''There are two main files of interest:'''<br>
+
|Y
;PgcClient.h:contains functions
+
|True or Yes
;PgcKey.h:contains parameter definitions for the key pairs
+
|-
 
+
|N
'''You can use the File List and File Member functions like so, to get more detail on what is available.<br>You can also use Search to find a function'''
+
|False or No
<br>[[File:doxygen1.jpg|none|frame]]
+
|}
<br>[[File:doxygen1a.jpg|none|frame]]
 
<br>'''This is how you can browse the parameter definitions'''
 
<br>[[File:doxygen3.jpg|none|frame]]
 
  
=Cloud9 Payment Gateway Documentation=
 
&rarr; ''' Please, see [http://cloud9paymentgateway.com/docs/API  Payment Gateway Documentation Portal]
 
  
 
{{Template:C9Footer|Integration}}
 
{{Template:C9Footer|Integration}}

Latest revision as of 21:44, 19 February 2020




Cloud9 Payment Gateway Documentation. This site can also be reached at http://docs.cloud9paymentgateway.com


ALL API is COPYRIGHT by 911 Software, INC 2019

API DOCUMENTATION

Executable Sandbox


Note: the API Sandbox contains a fair number of samples, but for complete API please refer to C9PG JSON API Documentation PDF

JSON Schema

You can click on Schema to reveal the JSON schema for the operation.

Executable API

You can click on any API, such as SALE, then "Try It Out" and "Execute" to run the transaction against a test server.

PDF Documentation

See below for a good intro to the API with some examples.

C9PG Portal Access

Please contact us to get access to the portal for the above Sandbox

Sample Working JSON

While we supply a complete sandbox here, where you can test various API,
you can also try out the examples below, using any free testing tool, such as Postman

POSTMAN Cloud9 JSON Sample Screenshot

Request

POST to URL: https://testlink.c9pg.com:11911/restApi

Sale

{

 "GMID": "1110222484",
 "GTID": "GT1120095178",
 "GMPW": "GMPW3010300378",
 "TransType": "Sale",
 "Medium": "Credit",
 "AccountNum": "4788250000028291",
 "ExpDate": "1222",
 "MainAmt": "1001",
 "TipAmt": "212",
 "IncTaxAmt": "153",
 "EntryMode": "Manual",
 "NeedSwipeCard": "N"

}

or another example of request:

Card Authentication (Verify)

{

 "GMID": "1110222484",
 "GTID": "GT1120095178",
 "GMPW": "GMPW3010300378",
 "TransType": "Verify",
 "Medium": "Credit",
 "AccountNum": "4788250000028291",
 "ExpDate": "1222",
 "MainAmt": "0",
 "EntryMode": "Manual",
 "CardPresent": "N"

}

Response

You will receive an appropriate response in JSON format. Here is an example

{

   "AVSResultCode": "0",
   "AccountNum": "478825******8291",
   "AuthAmt": "1213",
   "AuthCode": "TAS701",
   "AuthDate": "20191010",
   "AuthTime": "050209",
   "Brand": "Visa",
   "ErrorCode": "000",
   "ErrorText": "APPROVAL TAS701 ",
   "ExpDate": "1222",
   "GMID": "1110222484",
   "GMPW": "GMPW3010300378",
   "GTID": "GT1120095178",
   "GTRC": "194baa7ad35b4daea69879c94a3a9898",
   "MainAmt": "1001",
   "Medium": "Credit",
   "MerchantAddr": "265 S Federal Hwy",
   "MerchantCity": "Deerfield Beach",
   "MerchantName": "TSYS Test",
   "MerchantPhoneNum": "5613929606",
   "MerchantState": "FL",
   "MerchantZip": "33441",
   "NewRecordCreated": "Y",
   "ProcessorID": "40203",
   "ResponseCode": "00",
   "ResponseText": "APPROVAL TAS701 ",
   "ResultCode": "000",
   "ResultText": "APPROVAL TAS701 ",
   "SESSIONID": "Web{a6270e3e-d488-4243-a46f-d8740d3e725d}_1570698127640",
   "Status": "success",
   "TipAmt": "212",
   "TransType": "Sale",
   "TransactionIdentifier": "000000000234399"

}

Test Cards and Amounts

Aside from the example above, only specific account numbers, AVS, CVV and amounts will result in approvals
Please, see TSYS Test Account

Elements

The library has two basic elements:

Connection
Client can either connect directly to
a)Cloud9 Server Payment Web Controller (PWC) - this is a good option is local hardware payment terminals are not used
b)Local Payment Device Controller (PDC), which controls the payment terminal.
Name/Value Pair

Connection Types

  1. Payment Device Controller (PDC) Connection:Connects to the local device driver - wss://localhost:5556/
    Advantage: Offline Store & Forward Capability
    Disadvantage: Needs local software install
    Main Cloud9 Payment Processing Gateway Integration Diagram
  2. Web Based Payment Device Controller (PWC):Connects directly to the Cloud9 server - https://testlink.c9pg.com:5558/hj
    Advantage: No local software required, unlimited cross platform capability
    Disadvantage: No Offline Store & Forward Capability

    Cloud9 PWC Direct Integration Diagram

Core Key Names / Commands

Value Explanation
GMID Gateway Merchant ID
GTID Gateway Terminal ID
GMPW Gateway Account Password
TransType Transaction Type
Medium Transaction Medium (e.g. Credit Card/Debit Card/etc)
MainAmt Main Transaction Amount
IncTaxAmt Tax Amount - Required for Corporate Cards to avoid downgrades
SourceTraceNum Merchant Transaction Trace Number
InvoiceNum Invoice Number
OrderNum Order Number
VoucherNum Voucher Number
AdditionalInfo Additional Transaction Info
AccountNum Account Number (optional - only needed if PDC is not used to control the payment terminal)
ExpDate Expiration Date (optional - only needed if PDC is not used to control the payment terminal)
Track1 Track1 of Card (optional - only needed if PDC is not used to control the payment terminal)
Track2 Track2 of Card (optional - only needed if PDC is not used to control the payment terminal)
PinData Pin Data for Debit (optional - only needed if PDC is not used to control the payment terminal)
CardPresent Sets the Card Present Indicator (optional)
EntryMode (optional) Entry Mode

Core Values

TransType - Transaction Type Command

Value Explanation
Auth Authorization. Authorization is a non-finalized transaction that is used in a tip environment. Add tip to finalize. Only finalized transactions are batched/settled
Sale Sale. Sale is a finalized transaction that will be included in the next batch/settlement
AddTip Adds Tip to an Auth, finalizing it and getting it ready to be batched/settled
Modify Modifies a transaction, also finalizing it and getting it ready to be batched/settled
Finalize Finalizes Authorization and turns then into Sale, getting it ready to be batched/settled
Void Voids a transaction
Refund Refunds a transaction
Inquiry Debit, Credit or Gift Card Card Balance Inquiry
Activate Activate a Gift Card
AddValue Add Value to a Gift Card
Deactivate Deactivate a Gift Card

Medium - Processing Medium Command

Value Explanation
Credit Credit Card
Debit Debit Card
Gift Prepaid
Prepaid Prepaid Card
EBTCash EBT Cash
EBTFood EBT Food

Boolean Values

Value Explanation
Y True or Yes
N False or No






From the makers of Cloud9 Payment Processing Gateway and Creditline Credit Card Processing Software