Integration Developers Guide
Version 1.3 – December 22nd, 2010
Integration Developers Guide
Version 1.3 - December 22nd, 2010
Contents
1.
Introduction .......................................................................................................................................... 2
2.
Overall Operation.................................................................................................................................. 2
3.
Transaction Flow and Content .............................................................................................................. 2
4.
3.1.
Transfer Funds .............................................................................................................................. 2
3.2.
Mass Transfer Funds – not implemented yet ............................................................................... 3
3.3.
Request Money – not implemented yet ....................................................................................... 5
3.4.
Refund Transaction – not implemented yet ................................................................................. 6
3.5.
Cancel Subscription – not implemented yet ................................................................................. 7
3.6.
Subscription List – not implemented yet ...................................................................................... 8
3.7.
Balance Inquiry – not implemented yet...................................................................................... 10
3.8.
Transaction History – not implemented yet ............................................................................... 11
Testing Your Code in The Sandbox...................................................................................................... 13
4.1.
Creating Test Accounts ............................................................................................................... 13
4.2.
Sandbox Fields ............................................................................................................................ 13
4.3.
Sandbox Sample Call ................................................................................................................... 13
Appendix A – Response Codes .................................................................................................................... 14
Appendix B – Transaction Types ................................................................................................................. 14
www.paxum.com – © Paxum Inc. All rights reserved.
Page 1
Integration Developers Guide
Version 1.3 – December 22nd, 2010
1. Introduction
The purpose of the interface described in this document is to expose value added services to 3 rd parties,
by accepting transactions submitted by remote peer processes to our payment platform.
Modifications to this specification can be accepted upon request and provided that all the involved parts
agree in the changes. Modification requests can be sent to support@paxum.com .
2. Overall Operation
Supported operations can be submitted by using the HTTP/HTTPS Web protocol.
The overall operations meet a request / response model, where a client process establishes a
connection against the front end to our transactional server to submit a request that have to be applied
to a resource. The server replies with either a single record response, a multiple record response or with
an error indication. Only one request can be submitted over a single connection.
Successful transactions return the requested data, if exits, response code, response description and the
fee for the request.
Connectivity issues can be hidden by the transport used as done by SSL or HTTP but still this point
requires attention when going through the Internet as several routers and firewalls are in between.
3. Transaction Flow and Content
3.1. Transfer Funds
This transaction is used to transfer funds from one account to another. For now only checking to
checking transfers are allowed.
Field Name
Len
Type
Comments
fromEmail
N/A
Alp-Num The email associated with the account from which
the amount is deducted
toEmail
N/A
Alp-Num The email associated with the account where the
amount is transfered to
amount
N/A
currency
N/A
Alp-Num the currency code (e.g. USD)
key
N/A
Alp-Num MD5(MD5(password) + toEmail + amount +
currency)
Real
The amount to be transfered
www.paxum.com – © Paxum Inc. All rights reserved.
Page 2
Integration Developers Guide
Version 1.3 – December 22nd, 2010
This request is responded by a message with the following content:
Field Name
Len
Type
Comments
ResponseCode
N/A
Alp-Num The response code; 00 = Success;
ResponseDescription
N/A
Alp-Num Human readable response
Fee
N/A
Real
Fee for the current transaction
Request Sample:
https://www.paxum.com /payment/api/transfer.php
POST
fromEmail=payer@domain.com&toEmail=payee@domain.com&amount=10.00&currency=USD&key=1060b7b46a3b
d36b3a0d66e0127d0517
Response Sample:
<?xml version="1.0"?>
<TransferFundsResponse>
<ResponseCode>00</ResponseCode>
<ResponseDescription>Approved or Completed Successfully</ ResponseDescription >
<Fee>0.00</Fee>
</TransferFundsResponse>
Working Sample(s):
sampleTransfer.php
3.2. Mass Transfer Funds – not implemented yet
This transaction is used to mass transfer funds from one account to a list of accounts. For now only
checking to checking transfers are allowed.
Field Name
fromEmail
Len
N/A
Type
Comments
Alp-Num The email associated with the account from which
the amount is deducted
www.paxum.com – © Paxum Inc. All rights reserved.
Page 3
Integration Developers Guide
Version 1.3 – December 22nd, 2010
Field Name
data
Len
N/A
Type
Comments
Alp-Num List of accounts to be paid. One account should be
like this:
email,amount,currency,description\n
email,amount,currency,description\n
...
key
N/A
Alp-Num MD5(MD5(password) + data)
This request is responded by a message with the following content:
Field Name
Len
Type
Comments
ResponseCode
N/A
Alp-Num The response code; 00 = Success;
ResponseDescription
N/A
Alp-Num Human readable response
Fee
N/A
Real
Fee for the current transaction
Request Sample:
https://www.paxum.com /payment/api/transferMass.php
POST
fromEmail=payer@domain.com&key=1060b7b46a3bd36b3a0d66e0127d0517&
data=payee1@domain.com,10.00,USD,description1\npayee2@domain.com,15.00,USD,description2\n
payee3@domain.com,7.00,USD,description3\n
Response Sample:
<?xml version="1.0"?>
<TransferFundsResponse>
<ResponseCode>00</ResponseCode>
<ResponseDescription>Approved or Completed Successfully</ ResponseDescription >
<Fee>0.00</Fee>
</TransferFundsResponse>
Working Sample(s):
sampleTransferMass.php
www.paxum.com – © Paxum Inc. All rights reserved.
Page 4
Integration Developers Guide
Version 1.3 – December 22nd, 2010
3.3. Request Money – not implemented yet
This transaction is used to request funds from one account. For now only checking to checking transfers
are allowed.
Field Name
Len
Type
Comments
toEmail
N/A
Alp-Num The email associated with the account where the
amount is transfered to. This is the account initiating
the transfer
fromEmail
N/A
Alp-Num The email associated with the account from which
the amount is deducted
amount
N/A
currency
N/A
Alp-Num the currency code (e.g. USD)
key
N/A
Alp-Num MD5(MD5(password) + fromEmail + amount +
currency)
Real
The amount to be transfered (requested amount)
This request is responded by a message with the following content:
Field Name
Len
Type
Comments
ResponseCode
N/A
Alp-Num The response code; 00 = Success;
ResponseDescription
N/A
Alp-Num Human readable response
Fee
N/A
Real
Fee for the current transaction
Request Sample:
https://www.paxum.com /payment/api/requestMoney.php
POST
toEmail=payee@domain.com&fromEmail=payer@domain.com&
amount=10.00&currency=USD&key=1060b7b46a3bd36b3a0d66e0127d0517
Response Sample:
<?xml version="1.0"?>
<TransferFundsResponse>
<ResponseCode>00</ResponseCode>
<ResponseDescription>Approved or Completed Successfully</ ResponseDescription >
<Fee>0.00</Fee>
</TransferFundsResponse>
www.paxum.com – © Paxum Inc. All rights reserved.
Page 5
Integration Developers Guide
Version 1.3 – December 22nd, 2010
Working Sample(s):
sampleRequestMoney.php
3.4. Refund Transaction – not implemented yet
This is used to refund a transaction.
Field Name
Len
Type
Comments
fromEmail
N/A
Alp-Num The email associated with the account from which
the amount is deducted
transId
N/A
Alp-Num The ID of thetransaction to be refunded
key
N/A
Alp-Num MD5(MD5(password) + transId)
This request is responded by a message with the following content:
Field Name
Len
Type
Comments
ResponseCode
N/A
Alp-Num The response code; 00 = Success;
ResponseDescription
N/A
Alp-Num Human readable response
Fee
N/A
Real
Fee for the current transaction
Request Sample:
https://www.paxum.com /payment/api/transferRefund.php
POST
email=payee@domain.com&transId=67373&key=1060b7b46a3bd36b3a0d66e0127d0517
Response Sample:
<?xml version="1.0"?>
<TransferFundsResponse>
<ResponseCode>00</ResponseCode>
<ResponseDescription>Approved or Completed Successfully</ ResponseDescription >
<Fee>0.00</Fee>
www.paxum.com – © Paxum Inc. All rights reserved.
Page 6
Integration Developers Guide
Version 1.3 – December 22nd, 2010
</TransferFundsResponse>
Working Sample(s):
sampleTransferRefund.php
3.5. Cancel Subscription – not implemented yet
This is used to cancel a subscription.
Field Name
Len
Type
Comments
fromEmail
N/A
Alp-Num The email associated with the account from which
the amount is deducted
subscriptionId
N/A
Alp-Num The subscription ID to be canceled
key
N/A
Alp-Num MD5(MD5(password) + subscriptionId)
This request is responded by a message with the following content:
Field Name
Len
Type
Comments
ResponseCode
N/A
Alp-Num The response code; 00 = Success;
ResponseDescription
N/A
Alp-Num Human readable response
Fee
N/A
Real
Fee for the current transaction
Request Sample:
https://www.paxum.com /payment/api/subscriptionCancel.php
POST
fromEmail=payee@domain.com&subscriptionId=67373&key=1060b7b46a3bd36b3a0d66e0127d0517
Response Sample:
<?xml version="1.0"?>
<TransferFundsResponse>
<ResponseCode>00</ResponseCode>
<ResponseDescription>Approved or Completed Successfully</ ResponseDescription >
www.paxum.com – © Paxum Inc. All rights reserved.
Page 7
Integration Developers Guide
Version 1.3 – December 22nd, 2010
<Fee>0.00</Fee>
</TransferFundsResponse>
Working Sample(s):
sampleSubscriptionCancel.php
3.6. Subscription List – not implemented yet
This is used to get a list of subscriptions.
Field Name
Len
Type
Comments
fromEmail
N/A
Alp-Num The email associated with the account from which
the amount is deducted
key
N/A
Alp-Num MD5(MD5(password))
This request is responded by a message with the following content:
Field Name
Len
Type
Comments
ResponseCode
N/A
Alp-Num The response code; 00 = Success;
ResponseDescription
N/A
Alp-Num Human readable response
Fee
N/A
Real
Subscription/Id
N/A
Int
Unique identifier of the subscription
Subscription/ FromAccountId
N/A
Int
The account ID from where the amount is deducted
Subscription/ Amount
N/A
Real
Subscription/ Currency
N/A
Subscription/ StartDate
N/A
Date
The date when the subscription started
Subscription/EndDate*
N/A
Date
The date when the subscription should end
Subscription/ UserCancel*
N/A
Int
Fee for the current transaction
The amount to be dedcuted
Alp-Num The Currency Code (USD)
1 if the subscription will be valid until the user cancel
it
www.paxum.com – © Paxum Inc. All rights reserved.
Page 8
Integration Developers Guide
Version 1.3 – December 22nd, 2010
Field Name
Len
Type
Subscription/ Transactions*
N/A
Int
Subscription/
N/A
PaymentInterval
Comments
The number of times the amount to be deducted
before the subscription expires (is cancelled)
1 = every week
2 = every 2 weeks
3 = every month
4 = every 3 months
5 = every 6 months
6 = annually
* Only one of these fields will have a value, depending the type of the subscription
Request Sample:
https://www.paxum.com /payment/api/subscriptionList.php
POST
fromEmail=payee@domain.com&key=1060b7b46a3bd36b3a0d66e0127d0517
Response Sample:
<?xml version="1.0"?>
<TransferFundsResponse>
<ResponseCode>00</ResponseCode>
<ResponseDescription>Approved or Completed Successfully</ ResponseDescription >
<Fee>0.00</Fee>
<Subscriptions>
<Subscription>
<Id>12345</Id>
<FromAccountId>34763473</FromAccountId>
<ToAccountId>3476578734</ToAccountId>
<Amount>100.00</Amount>
<Currency>USD</Currency>
<StartDate>2011-01-03</StartDate>
<EndDate>2011-12-03</EndDate>
<UserCancel/>
<Transactions/>
<PaymentInterval>3</PaymentInterval >
</Subscription>
...
</Subscriptions>
</TransferFundsResponse>
Working Sample(s):
www.paxum.com – © Paxum Inc. All rights reserved.
Page 9
Integration Developers Guide
Version 1.3 – December 22nd, 2010
sampleSubscriptionList.php
3.7. Balance Inquiry – not implemented yet
Supply the current balances of a cardholder account.
Field Name
Len
Type
Comments
fromEmail
N/A
Alp-Num The email address used during login
account
N/A
Num
The ID of the account (optional, if ommited all
balances are returned)
key
N/A
String
MD5(MD5(password) + fromEmail + account)
This request is responded by a message with the following content:
Field Name
Len
Type
Comments
ResponseCode
N/A
Alp-Num The response code; 00 = Success;
ResponseDescription
N/A
Alp-Num Human readable response
Fee
N/A
Real
Fee for the current transaction
Account/AccountId
N/A
Num
The ID of the account for which the balance was
requested
Account/Type
N/A
Num
Account type: 1001 = Checking; 2002 = Mastercard;
Account/Balance
N/A
Real
The balance of the account
Account/Currency
3
Alp-Num The three letters currency code
Request Sample:
https://www.paxum.com /payment/api/balance.php
POST
fromEmail=payee@domain.com&account=21312434344&key=1060b7b46a3bd36b3a0d66e0127d0517
Response Sample:
www.paxum.com – © Paxum Inc. All rights reserved.
Page 10
Integration Developers Guide
Version 1.3 – December 22nd, 2010
<?xml version="1.0"?>
<BalanceInquiryResponse>
<ResponseCode>00</ResponseCode>
<ResponseDescription>Approved or Completed Successfully</ ResponseDescription >
<Fee>0.00</Fee>
<Account>
<AccountId>21312434344</AccountId>
<Balance>3254.17</Balance>
<Type>1001</Type>
<Currency>USD</Currency>
</Account>
</BalanceInquiryResponse>
Working Sample(s):
sampleBalance.php
3.8. Transaction History – not implemented yet
Supply the transaction history of a cardholder account.
Field Name
Len
Type
Comments
email
N/A
Alp-Num The email address used during login
account
N/A
Num
The ID of the account
fromDate
N/A
Date
Start date of the statement (yyyy-mm-dd)
toDate
N/A
Date
End date of the statement (yyyy-mm-dd)
pageSize
N/A
Num
Number of results per page (optional, default = 10)
pageNumber
N/A
Num
Which page to be returned (optional, default = 1)
key
N/A
String
MD5(MD5(password) + email +
account+fromDate+toDate+pageSize+pageNumber)
This request is responded by a message with the following content:
Field Name
ResponseCode
Len
N/A
Type
Comments
Alp-Num The response code; 00 = Success;
www.paxum.com – © Paxum Inc. All rights reserved.
Page 11
Integration Developers Guide
Version 1.3 – December 22nd, 2010
Field Name
Len
Type
Comments
ResponseDescription
N/A
Alp-Num Human readable response
Fee
N/A
Real
Fee for the current transaction
Transaction/ TransactionId
N/A
Num
The unique ID of the transaction
Transaction/
TransactionTypeId
N/A
Num
Type of the transaction (see Appendix B –
Transaction Types)
Transaction/
TransactionDate
N/A
Date
The date of the transaction
Transaction/ Amount
N/A
Real
The amount of teh transaction
Transaction/Currency
N/A
The currency
Transaction/ Description
N/A
The description of the transaction
Request Sample:
https://www.paxum.com /payment/api/transactions.php
POST
email=payee@domain.com&account=21312434344&fromDate=2010-10-01&toDate=2010-1031&pageSize=25&pageNumber=1&key=1060b7b46a3bd36b3a0d66e0127d0517
Response Sample:
<?xml version="1.0"?>
<TransactionHistoryResponse>
<ResponseCode>00</ResponseCode>
<ResponseDescription>Approved or Completed Successfully</ ResponseDescription >
<Fee>0.00</Fee>
<Transactions>
<Transaction>
<TransactionId>6733321</ TransactionId >
<TransactionTypeId>16</TransactionTypeId >
<TransactionDate>2010-10-17 14:33:20</ TransactionDate >
<Amount>150.00</ Amount >
<Currency> USD</Currency>
<Description>POS Purchase Markham ON CA</Description>
</Transaction>
... ...
</ Transactions >
</TransactionHistoryResponse>
www.paxum.com – © Paxum Inc. All rights reserved.
Page 12
Integration Developers Guide
Version 1.3 – December 22nd, 2010
Working Sample(s):
sampleTransactions.php
4. Testing Your Code in The Sandbox
4.1. Creating Test Accounts
To test the code during development you need to have at least one active Paxum account. You need two
accounts to test transactions that involve more than one account (e.g. Transfer Funds). It doesn’t matter
the account type. It could be either Business or Personal.
To open up an account with Paxum you must go to https://www.paxum.com and click on Sign up
button, then follow the instructions on the screen.
4.2. Sandbox Fields
Use the account credentials to submit all your requests and to be sure you are not generating any live
transactions you have to add two more parameters to each request:
Field Name
Len
Type
Comments
sandbox
N/A
Alp-Num Set the value to ON
return
N/A
Alp-Num The error code you wold like to receive back after
the input data is validated. E.g. 00, 51, ...
4.3. Sandbox Sample Call
In the following example we will test in the sandbox the case of “Not Sufficient Funds” for “Transfer
Funds”.
Request Sample:
https://www.paxum.com /payment/api/transfer.php
www.paxum.com – © Paxum Inc. All rights reserved.
Page 13
Integration Developers Guide
Version 1.3 – December 22nd, 2010
POST
fromEmail=payer@domain.com&toEmail=payee@domain.com&amount=10.00&currency=USD&key=1060b7b46a3b
d36b3a0d66e0127d0517&sandbox=ON&return=51
Please note that we added &sandbox=ON&return=51 at the end of the posted data.
Response Sample:
<?xml version="1.0"?>
<TransferFundsResponse>
<ResponseCode>51</ResponseCode>
<ResponseDescription> Sandbox mode set to ON</ ResponseDescription >
<Fee>0.00</Fee>
</TransferFundsResponse>
Please note that when the sandbox mode is ON the human readable description for the returned error
code is “Sandbox mode set to ON” and not the ones listed in Appendix A.
Appendix A – Response Codes
Code
00
03
30
51
55
IP
P5
Description
Approved or Completed Successfully
Invalid Merchant
Format Error
Not Sufficient Funds
Incorrect PIN
Invalid Payee
Currency Conversion Error
Appendix B – Transaction Types
Code
1
2
3
4
5
6
7
Description
Auction Goods
Goods
Auction Services
Services
Quasi Cash
Payments
Money Requests
www.paxum.com – © Paxum Inc. All rights reserved.
Page 14
Integration Developers Guide
Version 1.3 – December 22nd, 2010
8
9
10
11
12
13
14
16
Funds Added
Funds Withdrawn
Currency Conversion
Balance Transfer
Refunds
Fees
Transfer
Purchase
www.paxum.com – © Paxum Inc. All rights reserved.
Page 15