Codemate Payment Gateway

REST API Documentation

Version 1.8.1-beta

Version History
Version 1.8-beta 2011-12-06 Loban Amaan Rahman Basic Entity API completed Version 1.9-beta 2011-12-08 Loban Amaan Rahman Transaction API completed Basic Entity API revised Descriptions (and business logic) added Formatting complete Entity-Relationship-Diagram added Version 2.0-beta 2011-12-09 Loban Amaan Rahman Event API (for Prepaid Card and Subscription) complete Version 2.0 2011-12-09 Loban Amaan Rahman API Docs complete Companion Architecture Docs almost complete

Table of Contents
Version History......................................................2 Introduction...........................................................4 Common API.........................................................5 Common Responses.........................................5 Failure: Basic...............................................5 Failure: Object could not be Retrieved........5 Failure: Object could not be Created...........5 Success: Basic..............................................5 Success: Object Created..............................5 Basic Entity API....................................................6 User Profile.......................................................6 Retrieve........................................................6 Create...........................................................7 List All.........................................................7 Authenticate.................................................7 Prepaid Card.....................................................8 Retrieve........................................................8 Create...........................................................8 List All.........................................................9 List Usable...................................................9 List Not Usable............................................9 CreditAccount................................................10 Retrieve......................................................10 Create.........................................................10 Product............................................................11 Retrieve......................................................11 Create.........................................................11 Subscription....................................................12 Retrieve......................................................12 Create.........................................................12 Transaction API...................................................13 UpdateProfileTransaction...............................13 Retrieve......................................................13 Create.........................................................13 AddCreditTransaction....................................14 Retrieve......................................................14 Create.........................................................14 RechargeCreditTransaction............................15 Retrieve......................................................15 Create.........................................................15 TransferCreditTransaction..............................16 Retrieve......................................................16 Create.........................................................16 PurchaseProductTransaction..........................17 Retrieve......................................................17 Create.........................................................17 PurchaseSubscriptionTransaction...................18 Retrieve......................................................18 Create.........................................................18 Event API............................................................19 StartPrepaidCardEvent...................................19 EndPrepaidCardEvent....................................19 StartSubscriptionEvent...................................19 EndSubscriptionEvent....................................19

Introduction
The Codemate Payment Gateway is a re-usable extensible framework for payments of all kinds. All actions take place by creating Transaction Objects. This Command Design Pattern provides built-in logging, traceback, and rollback features. The framework provides a stable public Web API for client applications to use. The Web API is based on the principles for REST. The Default Plugin maintains persistence with a built-in MySQL Database. The implementation of each public interface can be extended with plugins, allowing for integration with numerous public backends (e.g. Paypal) or existing legacy backends. [Need more Information]

Common API
Common Responses
The following responses are used throughout the REST API tree. Each API call makes some form of customization to these basic responses.

Failure: Basic
This is default response for any sort of failure. Some of the API calls described below prescribe some recommendations for the {comment} parameter, but it can be anything.
Response Code: 400 Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <message> <status>ERROR</status> <comment>{comment}</comment> </message>

Failure: Object could not be Retrieved

This is the default response when an object cannot be retrieved. The type of the object is always specified. A more specific {comment} explaining why this failure occurred is recommended.
Response Code: 404 Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <message> <status>ERROR</status> <comment>{object} could not be Retrieved</comment> </message> Parameters: {object}: Entity Name, e.g. User Profile, Prepaid Card, etc. More specific {comment} is very welcome.

Failure: Object could not be Created

This is the default response when an object cannot be created. The type of the object is always specified. A more specific {comment} explaining why this failure occurred is recommended.
Response Code: 406 Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <message> <status>ERROR</status> <comment>{object} could not be Created</comment> </message> Parameters: {object}: Entity Name, e.g. User Profile, Prepaid Card, etc. More specific {comment} is very welcome

Success: Basic
This is default response for any sort of failure. Some of the API calls described below prescribe some recommendations for the {comment} parameter, but it can be anything.
Response Code: 200 Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <message> <status>SUCCESS</status> <comment>{comment}</comment> </message>

Success: Object Created

This is the default response when an object is created successfully. The body is always the same as the response body when the very same object is retreived.
Response Code: 201 Body: [Same as Retrieve]

Basic Entity API

The following API calls are for the creation and retrieval of the five basic entities of the Payment Gateway: The User Profile, Prepaid Card, Credit Account, Product, and Subscription.

User Profile
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /UserProfile/{username} Parameters: {username}[unique]: 20 alphanumeric, e.g. scoobydoo Response Code: 200 Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <userProfile> <id>{id}</id> <username>{username}</username> <password>{password}</password> <email>{email}</email> <firstName>{firstName}</firstName> <lastName>{lastName}</lastName> <creditAccounts> ... </creditAccounts> <products> ... </products> <subscriptions> ... </subscriptions> <createdAt>{createdAt}</createdAt> <updatedAt>{updatedAt}</updatedAt> </userProfile> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {username}[unique]: 20 alphanumeric, e.g. scoobydoo {password}[optional]: 20 alphanumeric, e.g. Th1sIsMyP@ssw0rd {email}[optional]: 50 alphanumeric, e.g. scoobydoo@gmail.com {firstName}[optional]: 50 alphanumeric, e.g. Scooby {lastName}[optional]: 50 alphanumeric, e.g. Dooby {createdAt}: datetime, e.g. 2011-11-29T15:57:51+06:00 {updatedAt}: datetime, e.g. 2011-11-29T15:57:51+06:00 <creditAccounts>, <products>, and <subscriptions> tags each contain a list of Credit Accounts, Products, and Subscriptions that belong to the User Profile. The format is the same as the Retrieve response for each object.

Create
[Todo: Description]
Request Type: POST URL: /UserProfile Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <userProfile> <username>{username}</username> <password>{password}</password> <email>{email}</email> <firstName>{firstName}</firstName> <lastName>{lastName}</lastName> </userProfile> Parameters: [Same Retrieve] Response Code: 201 Body: [Same as Retrieve] Parameters: [Same as Retrieve]

List All
[Todo: Description]
Request Type: GET URL: /UserProfile Response Code: 200 Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <userProfiles> <userProfile> ... </userProfile> ... </userProfiles> Parameters: [Same as Retrieve]

Authenticate
[Todo: Description]
Request Type: POST URL: /UserProfile/Authenticate Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <userProfile> <username>{username}</username> <password>{password}</password> </userProfile> Response Code: 200 Body: [Success: Basic or Failure: Basic] Parameters: {comment}: User Profile Authenticated {comment}: User Profile NOT Authenticated

Prepaid Card
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /PrepaidCard/{code} Parameters: {code}[unique]: 20 alphanumeric, e.g. ELITE-123-532-234 Response Code: 200 Body: <prepaidCard> <id>{id}</id> <code>{code}</code> <pin>{pin}</pin> <amount>{amount}</amount> <startsAt>{startsAt}</startsAt> <endsAt>{endsAt}</endsAt> <usedAt>{usedAt}</usedAt> <createdAt>{startsAt}</startsAt> <updatedAt>{endsAt}</endsAt> </prepaidCard> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {code}[unique]: 20 alphanumeric, e.g. ELITE-123-532-234 {pin}: 20 alphanumeric, e.g. 123-X4TG-342F {amount}: 10.2 positive decimal , e.g. 10.23 or 1000.00 {startsAt}[optional]: datetime, e.g. 2011-11-29T15:57:51+06:00 {endsAt}[optional]: datetime, e.g. 2011-11-29T15:57:51+06:00 {usedAt}[optional]: datetime, e.g. 2011-11-29T15:57:51+06:00 {createdAt}: datetime, e.g. 2011-11-29T15:57:51+06:00 {updatedAt}: datetime, e.g. 2011-11-29T15:57:51+06:00

Create
[Todo: Description]
Request Type: POST URL: /PrepaidCard Body: <prepaidCard> <code>{code}</code> <pin>{pin}</pin> <amount>{amount}</amount> <startsAt>{startsAt}</startsAt> <endsAt>{endsAt}</endsAt> </prepaidCard> Parameters: [Same Retrieve] Response Code: 201 Body: [Same as Retrieve] Parameters: [Same as Retrieve]

List All
[Todo: Description]
Request Type: GET URL: /PrepaidCard Response Code: 200 Body: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <prepaidCards> <prepaidCard> ... </prepaidCard> ... </prepaidCards> Parameters: [Same as Retrieve]

List Usable
[Todo: Description]
Request Type: GET URL: /PrepaidCard/Usable Code: 200 Response

Body: [Same as List All, but only showing those Prepaid Cards that satisfy
ALL of the following have started not ended not been used

Parameters: [Same as Retrieve]

List Not Usable

[Todo: Description]
Request Type: GET URL: /PrepaidCard/NotUsable Response Code: 200 Body: [Same as List All, but only showing those Prepaid Cards that satisfy ANY of the following have not started ended been used Parameters: [Same as Retrieve]

CreditAccount
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /CreditAccount/{code} Parameters: {code}[unique]: 20 alphanumeric, e.g. scoobydoo-ELITE-01 Response Code: 200 Body: <creditAccount> <id>{id}</id> <userProfile> <code>{userProfileCode}</code> </userProfile> <code>{code}</code> <amount>{amount}</amount> <startsAt>{startsAt}</startsAt> <createdAt>{startsAt}</startsAt> <updatedAt>{endsAt}</endsAt> </creditAccount> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {userProfileCode}[existing]: 20 alphanumeric, e.g. scoobydoo {code}[unique]: 20 alphanumeric, e.g. scoobydoo-ELITE-01 {amount}: 10.2 positive decimal , e.g. 10.23 or 1000.00 {createdAt}: datetime, e.g. 2011-11-29T15:57:51+06:00 {updatedAt}: datetime, e.g. 2011-11-29T15:57:51+06:00

Create
[Todo: Description]
Request Type: POST URL: /CreditAccount Body: <creditAccount> <userProfile> <code>{userProfileCode}</code> </userProfile> <code>{code}</code> <amount>{amount}</amount> </creditAccount> Parameters: [Same Retrieve] Response Code: 201 Body: [Same as Retrieve] Parameters: [Same as Retrieve]

Product
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /Product/{code} Parameters: {code}[unique]: 20 alphanumeric, e.g. chair-ELITE-01 Response Code: 200 Body: <product> <id>{id}</id> <userProfile> <code>{userProfileCode}</code> </userProfile> <code>{code}</code> <name>{name}</name> <description>{description}</description> <quantity>{quantity}</quantity> <createdAt>{startsAt}</startsAt> <updatedAt>{endsAt}</endsAt> </product> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {userProfileCode}[existing]: 20 alphanumeric, e.g. scoobydoo {code}[unique]: 20 alphanumeric, e.g. chair-ELITE-01 {name}[optional]: 50 alphanumeric, e.g. IKEA Swing Chair {description}[optional]: 255 alphanumeric {quantity}: 10 positive integer , e.g. 10 or 1000 {createdAt}: datetime, e.g. 2011-11-29T15:57:51+06:00 {updatedAt}: datetime, e.g. 2011-11-29T15:57:51+06:00

Create
[Todo: Description]
Request Type: POST URL: /Product Body: <product> <userProfile> <code>{userProfileCode}</code> </userProfile> <code>{code}</code> <name>{name}</name> <description>{description}</description> <quantity>{quantity}</quantity> </product> Parameters: [Same Retrieve] Response Code: 201 Body: [Same as Retrieve] Parameters: [Same as Retrieve]

Subscription
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /Subscription/{code} Parameters: {code}[unique]: 20 alphanumeric, e.g. warcraft-ELITE-01 Response Code: 200 Body: <subscription> <id>{id}</id> <userProfile> <code>{userProfileCode}</code> </userProfile> <code>{code}</code> <name>{name}</name> <description>{description}</description> <startsAt>{startsAt}</startsAt> <endsAt>{endsAt}</endsAt> <createdAt>{startsAt}</startsAt> <updatedAt>{endsAt}</endsAt> </subscription> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {userProfileCode}[existing]: 20 alphanumeric, e.g. scoobydoo {code}[unique]: 20 alphanumeric, e.g. warcraft-ELITE-01 {name}[optional]: 50 alphanumeric, e.g. IKEA Swing Chair {description}[optional]: 255 alphanumeric {startsAt}[optional]: datetime, e.g. 2011-11-29T15:57:51+06:00 {endsAt}[optional]: datetime, e.g. 2011-11-29T15:57:51+06:00 {createdAt}: datetime, e.g. 2011-11-29T15:57:51+06:00 {updatedAt}: datetime, e.g. 2011-11-29T15:57:51+06:00

Create
[Todo: Description]
Request Type: POST URL: /Subscription Body: <subscription> <userProfile> <code>{userProfileCode}</code> </userProfile> <code>{code}</code> <name>{name}</name> <description>{description}</description> <startsAt>{startsAt}</startsAt> <endsAt>{endsAt}</endsAt> </subscription> Parameters: [Same Retrieve] Response Code: 201 Body: [Same as Retrieve]

Parameters: [Same as Retrieve]

Transaction API
The following API calls are for the creation and retrieval of all kinds of transactions that occur in the Payment Gateway. The

UpdateProfileTransaction
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /Transaction/UpdateProfile/{username} Parameters: {username}[unique]: 20 alphanumeric, e.g. scoobydoo Response Code: 200 Body: <updateProfileTransaction> <id>{id}</id> <userProfile> ... </userProfile> <createdAt>{createdAt}</createdAt> </transferCreditTransaction> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {creditAmount}: 10.2 positive/negative decimal , e.g. 10.23 or 100.00 or -39.50, to be added to the Credit Account {createdAt}: datetime, e.g. 2011-11-29T15:57:51+06:00

Create
[Todo: Description]
Request Type: POST URL: /Transaction/ UpdateProfile Body: <transferCreditTransaction> <sourceCreditAccount> <code>{sourceCreditAccountCode}</code> </sourceCreditAccount> <targetCreditAccount> <code>{targetCreditAccountCode}</code> ... </targetCreditAccount> <creditAmount>{creditAmount}</creditAmount> </transferCreditTransaction> Parameters: [Same as Retrieve] Response Code: 201 Body: [Same as Retrieve] Parameters: {sourceCreditAccountCode}[existing]: 20 alphanumeric, e.g. ELITE-123-123 {targetCreditAccountCode}[existing/new]: 20 alphanumeric, e.g. ELITE-1235 If {creditAccountCode} EXISTS, no other tags are required. However, if {creditAccountCode} does NOT EXIST, the remaining tags required to create a

new Credit Account must be included. [Rest is same as Retrieve]

AddCreditTransaction
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /Transaction/AddCredit/{id} Parameters: {id}[unique]: 10 long integer, e.g. 5 or 532345 Response Code: 200 Body: <addCreditTransaction> <id>{id}</id> <creditAccount> ... </creditAccount> <creditAmount>{creditAmount}</creditAmount> </addCreditTransaction> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {creditAmount}: 10.2 positive/negative decimal , e.g. 10.23 or 100.00 or -39.50, to be added to the Credit Account

Create
[Todo: Description]
Request Type: POST URL: /Transaction/AddCredit Body: <addCreditTransaction> <creditAccount> <code>{creditAccountCode}</code> ... </creditAccount> <creditAmount>{creditAmount}</creditAmount> </addCreditTransaction> Parameters: [Same as Retrieve] Response Code: 201 Body: [Same as Retrieve] Parameters: {creditAccountCode}[existing/new]: 20 alphanumeric, e.g. scooby-ELITE-01 If {creditAccountCode} EXISTS, no other tags are required. However, if {creditAccountCode} does NOT EXIST, the remaining tags required to create a new Credit Account must be included. [Rest is same as Retrieve]

RechargeCreditTransaction
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /Transaction/RechargeCredit/{id} Parameters: {id}[unique]: 10 long integer, e.g. 5 or 532345 Response Code: 200 Body: <rechargeCreditTransaction> <id>{id}</id> <prepaidCard> ... </prepaidCard> <creditAccount> ... </creditAccount> </rechargeCreditTransaction> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {creditAmount}: 10.2 positive/negative decimal , e.g. 10.23 or 100.00 or -39.50, to be added to the Credit Account

Create
[Todo: Description]
Request Type: POST URL: /Transaction/RechargeCredit Body: <rechargeCreditTransaction> <prepaidCard> <code>{prepaidCardCode}</code> </prepaidCard> <creditAccount> <code>{creditAccountCode}</code> ... </creditAccount> </rechargeCreditTransaction> Parameters: [Same as Retrieve] Response Code: 201 Body: [Same as Retrieve] Parameters: {prepaidCardCode}[existing]: 20 alphanumeric, e.g. ELITE-123-123 {creditAccountCode}[existing/new]: 20 alphanumeric, e.g. scooby-ELITE-01 If {creditAccountCode} EXISTS, no other tags are required. However, if {creditAccountCode} does NOT EXIST, the remaining tags required to create a new Credit Account must be included. [Rest is same as Retrieve]

TransferCreditTransaction
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /Transaction/TransferCredit/{id} Parameters: {id}[unique]: 10 long integer, e.g. 5 or 532345 Response Code: 200 Body: <transferCreditTransaction> <id>{id}</id> <sourceCreditAccount> ... </sourceCreditAccount> <targetCreditAccount> ... </targetCreditAccount> <creditAmount>{creditAmount}</creditAmount> </transferCreditTransaction> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {creditAmount}: 10.2 positive/negative decimal , e.g. 10.23 or 100.00 or -39.50, to be added to the Credit Account

Create
[Todo: Description]
Request Type: POST URL: /Transaction/TransferCredit Body: <transferCreditTransaction> <sourceCreditAccount> <code>{sourceCreditAccountCode}</code> </sourceCreditAccount> <targetCreditAccount> <code>{targetCreditAccountCode}</code> ... </targetCreditAccount> <creditAmount>{creditAmount}</creditAmount> </transferCreditTransaction> Parameters: [Same as Retrieve] Response Code: 201 Body: [Same as Retrieve] Parameters: {sourceCreditAccountCode}[existing]: 20 alphanumeric, e.g. ELITE-123-123 {targetCreditAccountCode}[existing/new]: 20 alphanumeric, e.g. ELITE-1555 If {creditAccountCode} EXISTS, no other tags are required. However, if {creditAccountCode} does NOT EXIST, the remaining tags required to create a new Credit Account must be included. [Rest is same as Retrieve]

PurchaseProductTransaction
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /Transaction/PurchaseProduct/{id} Parameters: {id}[unique]: 10 long integer, e.g. 5 or 532345 Response Code: 200 Body: <purchaseProductTransaction> <id>{id}</id> <creditAccount> ... </creditAccount> <product> ... </product> <unitPrice>{unitPrice}</unitPrice} <quantity>{quantity}</quantity> </purchaseProductTransaction> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {unitPrice}: 10.2 positive/negative decimal , e.g. 10.23 or 100.00 or -39.50, to be added to the Credit Account {quantity}: 10 positive integer , e.g. 10 or 1000

Create
[Todo: Description]
Request Type: POST URL: /Transaction/ PurchaseProduct Body: <purchaseProductTransaction> <creditAccount> <code>{creditAccountCode</code> </creditAccount> <product> <code>{productCode}</code> ... </product> <unitPrice>{unitPrice}</unitPrice} <quantity>{quantity}</quantity> </purchaseProductTransaction> Parameters: [Same as Retrieve] Response Code: 201 Body: [Same as Retrieve] Parameters: {creditAccountCode}[existing]: 20 alphanumeric, e.g. ELITE-123-123 {productCode}[existing/new]: 20 alphanumeric, e.g. chair-1555 If {productCode} EXISTS, no other tags are required. However, if {productCode} does NOT EXIST, the remaining tags required to create a new Product must be included.

[Rest is same as Retrieve]

PurchaseSubscriptionTransaction
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /Transaction/PurchaseSubscription/{id} Parameters: {id}[unique]: 10 long integer, e.g. 5 or 532345 Response Code: 200 Body: <purchaseSubscriptionTransaction> <id>{id}</id> <creditAccount> ... </creditAccount> <subscription> ... </subscription> <unitPrice>{unitPrice}</unitPrice} </purchaseSubscriptionTransaction> Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {unitPrice}: 10.2 positive/negative decimal , e.g. 10.23 or 100.00 or -39.50, to be added to the Credit Account

Create
[Todo: Description]
Request Type: POST URL: /Transaction/ PurchaseSubscription Body: <purchaseSubscriptionTransaction> <creditAccount> <code>{creditAccountCode</code> </creditAccount> <subscription> <code>{subscriptionCode}</code> ... </subscription> <unitPrice>{unitPrice}</unitPrice} </purchaseSubscriptionTransaction> Parameters: [Same as Retrieve] Response Code: 201 Body: [Same as Retrieve] Parameters: {creditAccountCode}[existing]: 20 alphanumeric, e.g. ELITE-123-123 {subscriptionCode}[existing/new]: 20 alphanumeric, e.g. chair-1555 If {subscriptionCode} EXISTS, no other tags are required. However, if {subscriptionCode} does NOT EXIST, the remaining tags required to create a new Subscription must be included. [Rest is same as Retrieve]

Transaction
[Todo: Description]

Retrieve
[Todo: Description]
Request Type: GET URL: /Transaction/{id} Parameters: {id}[unique]: 10 long integer, e.g. 5 or 532345 Response Code: 200 Body: [Same as Retrieve for the actual object] Parameters: {id}[primary]: 10 long integer, e.g. 5 or 532345 {unitPrice}: 10.2 positive/negative decimal , e.g. 10.23 or 100.00 or -39.50, to be added to the Credit Account

List by User Profile

[Todo: Description]
Request Type: GET URL: /Transaction/UserProfile/{username} Parameters: {username}[unique]: 20 alphanumeric, e.g. scoobydoo Response Code: 200 Body: [To Do] Parameters: [To Do]

Event API
StartPrepaidCardEvent
There is no REST API call for this. This entity is automatically created when a Prepaid Card starts (i.e. becomes available for use). Like all services, this service can be extended in plugins to do additional work. [To Do]

EndPrepaidCardEvent
There is no REST API call for this. This entity is automatically created when a Prepaid Card ends (i.e. expires). Like all services, this service can be extended in plugins to do additional work. [To Do]

StartSubscriptionEvent
There is no REST API call for this. This entity is automatically created when a Subscription starts. Like all services, this service can be extended in plugins to do additional work. [To Do]

EndSubscriptionEvent
There is no REST API call for this. This entity is automatically created when a Subscription starts. Like all services, this service can be extended in plugins to do additional work. [To Do]