Payment Gateway SDK
The 360-One Payment Gateway SDK provides an easy to integrate interface for our payments API. When a payment takes place directly from a merchant’s server, using an SDK is the fastest way to accept custom payments. In the following examples, we’ll go over the most common requests made to the Payment Gateway, using each SDK.
Contents
- Overview
- Sale Example
- Pre-auth Example
- Re-auth Example
- Refund Example
- Credit Example
- Void Example
- Store card Example
Notes
The Java SDK communicates with the Payment Gateway by using a HTTP POST with the HttpURLConnection class. It does not have any dependencies outside standard Java classes. The minimum version of Java required is 1.5.
The C# SDK communicates with the Payment Gateway by using a HTTP POST with the HttpWebRequest class. The library was written using Microsoft .NET framework version 4.5, unless otherwise stated in the download above.
The PHP SDK communicates with the Payment Gateway by using a HTTP POST with the cURL extension. Please be sure cURL is configured in your PHP installation.
The Python SDK communicates with the Payment Gateway by using the httplib2 module. The module can be found here github.com/jcgregorio/httplib2.
Note Be sure to use the LIVE endpoint in a production site – all other transactions are simulated.
Overview
The Payment Gateway has several environments available for use:
- GatewayUrl.Cert The certification server will simulate authorizations. It’s codebase is a copy of the production environment.
- GatewayUrl.Test The test server will simulate authorizations. It’s codebase reflects what is currently in development.
- GatewayUrl.Live The live server should be used to process live authorizations.
Sale Example
A sale requests an authorization, then captures it upon approval. This means that so long as the transaction is approved, it will be funded once the day’s batch closes. This transaction type is common in environments such as digital downloads, fees / payments, and for goods that will ship immediately.
Request
- GatewaySettings settings = new GatewaySettings();
settings.credentials(“9410000xxxxx0000000x”, “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”)
.hostUrl(GatewaySettings.URL_CERT);Gateway gateway = new Gateway(settings);try {
GatewayRequest sRequest = new GatewayRequest(TransactionType.SALE)
.cardData(
new CcData()
.setCcNum(“4012888812348882”)
.setExpDate(“12/18”)
.setCvv(“123”)
)
.amount(“0.3”)
.setParameter(“invoice_number”, “123456”)
.setParameter(“client_reference_number”, “Java SDK Test”);
GatewayResponse sResponse = gateway.run(sRequest);
System.out.println(sResponse.toString());
} catch (MesRuntimeException e) {
e.printStackTrace();
}
The minimum data required for a sale, is the card information. An invoice number, and the cardholder’s street address / ZIP code are also recomended.
Output
- transaction_id=f74554bc55e73a3cbd8467195631ef5d&error_code=000&auth_response_text=Approval T8363H&avs_result=0&cvv2_result=M&auth_code=T8363H
[Approved:true] [6 resp fields] [HTTP:200] [duration:891.0ms]
When the transaction is approved, you may read the approval code, and any AVS / CVV match results from the response.
Pre-auth Example
A pre-auth just requests an authorization. This means that if the transaction is approved, it will not be funded until a settle message is sent to capture it. This transaction type is common in environments such as physical product purchases, where payment is not captured until a product ships.
Request
- GatewaySettings settings = new GatewaySettings();
settings.credentials(“9410000xxxxx0000000x”, “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”)
.hostUrl(GatewaySettings.URL_CERT)
.method(Settings.Method.POST);Gateway gateway = new Gateway(settings);try {
GatewayRequest pRequest = new GatewayRequest(TransactionType.PREAUTH)
.cardData(
new CcData()
.setCcNum(“4012888812348882”)
.setExpDate(“12/18”)
.setCvv(“123”)
)
.amount(“0.3”)
.setParameter(“invoice_number”, “123456”)
.setParameter(“client_reference_number”, “Java SDK Test”);
GatewayResponse pResponse = gateway.run(pRequest);
System.out.println(pResponse.toString());
} catch (MesRuntimeException e) {
e.printStackTrace();
}
The minimum data required for a pre-auth, is the card information. An invoice number, and the cardholder’s street address / ZIP code are also recomended.
Output
- transaction_id=cg4544gc55s73s3cbf8467195631esf6&error_code=000&auth_response_text=Approval T8363H&avs_result=0&cvv2_result=M&auth_code=T8363H
[Approved:true] [6 resp fields] [HTTP:200] [duration:898.0ms]
When the transaction is approved, you may read the approval code, and any AVS / CVV match results from the response.
Re-auth Example
A re-auth simply accepts a transaction ID from a previous authorization, and runs it again. Any additional fields you provide in the re-auth will override fields in the original request.
Request
- GatewaySettings settings = new GatewaySettings();
settings.credentials(“9410000xxxxx0000000x”, “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”)
.hostUrl(GatewaySettings.URL_CERT)
.method(Settings.Method.POST);Gateway gateway = new Gateway(settings);try {
GatewayRequest pRequest = new GatewayRequest(TransactionType.REAUTH)
.setParameter(“transaction_id”, “cg4544gc55s73s3cbf8467195631esf6”)
.setParameter(“invoice_number”, “123456”)
.setParameter(“client_reference_number”, “Java SDK Test”);
GatewayResponse pResponse = gateway.run(pRequest);
LOG.log(Level.INFO, pResponse.toString());
} catch (MesRuntimeException e) {
e.printStackTrace();
}
The minimum data required for a re-auth, is the transaction_id of a previous authorization.
Output
- transaction_id=xf46445c55s73g3cbf84s7195631e3sh&error_code=000&auth_response_text=Approval T8363H&avs_result=0&cvv2_result=M&auth_code=T8363H
[Approved:true] [6 resp fields] [HTTP:200] [duration:891.0ms]
When the transaction is approved, you may read the approval code, and any AVS / CVV match results from the response.
Refund Example
A refund will void a transaction (if the authorization is in the current batch), or issue a credit (if the authorization has been settled/funded). It is an easy and safe way to cancel a transaction, or give money back to a cardholder. It accepts a transaction_id from a previous Sale or Settle, meaning you don’t have to store sensitive card information for returns.
Request
- GatewaySettings settings = new GatewaySettings();
settings.credentials(“9410000xxxxx0000000x”, “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”)
.hostUrl(GatewaySettings.URL_CERT)
.method(Settings.Method.POST);Gateway gateway = new Gateway(settings);try {
GatewayRequest pRequest = new GatewayRequest(TransactionType.REFUND)
.setParameter(“transaction_id”, “d09e526b57763cf7a228d584c9a35886”)
.setParameter(“invoice_number”, “123456”)
.setParameter(“client_reference_number”, “Java SDK Test”);
GatewayResponse rResponse = gateway.run(pRequest);
LOG.log(Level.INFO, rResponse.toString());
} catch (MesRuntimeException e) {
e.printStackTrace();
}
The minimum data required for a refund, is the transaction_id of a previous authorization. If the transaction_amount is not provided, we assume you intend to refund 100% of the original authorization. In the event you wish to refund less than the authorized amount, simply send a transaction_amount between 0 and the full amount.
Output
- transaction_id=a4c7686353df386a9d36d072b32bcc73&error_code=000&auth_response_text=Refund Request Accepted – Void
[Approved:true] [3 resp fields] [HTTP:200] [duration:1291.0ms]
The response text will inform you whether the refund resulted in a void, or a credit.
Credit Example
A credit is giving funds directly to a card. This is generally discouraged, as the refund is much safer.
The credit transaction type is disabled by default. If a refund is not appropriate, contact the certification department to enable this functionality for your profile.
Request
- GatewaySettings settings = new GatewaySettings();
settings.credentials(“9410000xxxxx0000000x”, “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”)
.hostUrl(GatewaySettings.URL_CERT)
.method(Settings.Method.POST);Gateway gateway = new Gateway(settings);try {
GatewayRequest pRequest = new GatewayRequest(TransactionType.CREDIT)
.cardData(
new CcData()
.setCcNum(“4012888812348882”)
.setExpDate(“12/18”)
.setCvv(“123”)
)
.amount(“0.3”)
.setParameter(“invoice_number”, “123456”)
.setParameter(“client_reference_number”, “Java SDK Test”);
GatewayResponse pResponse = gateway.run(pRequest);
System.out.println(pResponse.toString());
} catch (MesRuntimeException e) {
e.printStackTrace();
}
A transaction resulting in a credit may be voided while it remains in the current open batch.
Output
- transaction_id=460613f58adf3a1d97f73c7ca40eb3cc&error_code=000&auth_response_text=Credit Accepted
[Approved:true] [3 resp fields] [HTTP:200] [duration:390.4ms]
Avoid issuing credits to a card other than the original authorization’s card. Doing so may cause confusion or loss of re-presentment rights in a chargeback situation. It is strongly advised to let the refund transaction type manage this for you to avoid this situation.
Void Example
A void cancels a transaction in the current open batch. The transaction may be an authorization, or credit. When an authorization is voided, the Payment Gateway will attempt to issue a reversal to the issuing bank, which can free up the cardholder’s open-to-buy (making them much happier).
Request
- GatewaySettings settings = new GatewaySettings();
settings.credentials(“9410000xxxxx0000000x”, “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”)
.hostUrl(GatewaySettings.URL_CERT)
.method(Settings.Method.POST);Gateway gateway = new Gateway(settings);try {
GatewayRequest pRequest = new GatewayRequest(TransactionType.VOID)
.setParameter(“transaction_id”, “460613f58adf3a1d97f73c7ca40eb3cc”)
.setParameter(“client_reference_number”, “Java SDK Test”);
GatewayResponse vResponse = gateway.run(pRequest);
LOG.log(Level.INFO, vResponse.toString());
} catch (MesRuntimeException e) {
e.printStackTrace();
}
A void request only accepts the transaction_id of an authorization, or credit which is in the current batch.
Output
- transaction_id=c731a9b8f3df3833be61393f922caee1&error_code=000&auth_response_text=Void Request Accepted
[Approved:true] [3 resp fields] [HTTP:200] [duration:390.4ms]
Store card Example
A store card, or tokenize request will accept information about a credit card, and return a substitutionary token. This token may be sent instead of a card number in any other request.
Request
- GatewaySettings settings = new GatewaySettings();
settings.credentials(“9410000xxxxx0000000x”, “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”)
.hostUrl(GatewaySettings.URL_CERT)
.method(Settings.Method.POST);Gateway gateway = new Gateway(settings);try {
GatewayRequest pRequest = new GatewayRequest(TransactionType.TOKENIZE)
.cardData(
new CcData()
.setCcNum(“4012888812348882”)
)
.setParameter(“client_reference_number”, “Java SDK Test”);
GatewayResponse tResponse = gateway.run(pRequest);
System.out.println(tResponse.toString());
} catch (MesRuntimeException e) {
e.printStackTrace();
}
Using tokenization can greatly reduce PCI compliance issues, since it relieves you from having to store encrypted card data on your server.
Output
- transaction_id=8936ab8defd03d92afb406c18f71919b&error_code=000&auth_response_text=Card Data Stored
[Approved:true] [3 resp fields] [HTTP:200] [duration:506.2ms]
The transaction_id in the response is the token itself. Store this for future use for the current customer.
