Contact the Product Team for assistance representing SDK content externally to potential clients or partners.
The Ordway Software Development Kit (SDK) provides the ability for Payment Gateways to integrate with Ordway’s platform.
Table of Contents
- Supported Business Functionality
- Integration Steps
- Requests & Responses
- Gateway Configuration Objects
- Error Response Structure
Supported Business Functionality
- Credit Cards & ACH
- Establish Account with Payment Gateway
- Authenticate with Payment Gateway
- Customer - Get, Create
- Payment Method - Get, Create, Update
- Payment - Get, Create, Refund, Void, Reconcile
Integration Steps
Pre Conditions
Clients are responsible for establishing their new merchant account, negotiating rates, and contract details directly. Clients must have an active account with the Payment Gateway before Ordway can proceed.
Register New Payment Gateway
Ordway Dev/Operations teams will facilitate adding the new Payment Gateway to Ordway.
Step 1: Collect the following required information:
- Gateway Name
- Gateway Icon (URL for the gateway)
-
Payment Gateway Features - Provided via a YAML file to include:
- Customer
- Payment
- Refund
- Void
- Payment Methods
- Reconcile
- Production - The production configuration for the integration.
- Integration Configuration Profile Details - Refer to section below.
- TestMode - The test mode configuration for the integration
- Integration Configuration Profile Details - Refer to section below.
- Credit Card
- ACH
- Test Mode Support: True/False
- Supported Operations: True as default, but can be overridden.
- IntegrationConfiguration - The configuration information for the SDK integration
Step 2: Connect to Payment Gateway
- In Ordway, navigate to Menu > Setup > Payments > Payment Gateway.
- Select the new Payment Gateway from the available drop-down menu for Connect to Third Party Vendor & click Connect.
Requests & Responses
Get Payment Methods for Customer
Use this call to get payment method for a customer.
|
Name |
Type |
Required |
Parent |
Description |
|
Request |
||||
|
gateway_config |
Object |
true |
The gateway config object. |
|
|
customer_config |
Object |
true |
The customer config object. |
|
|
Response |
||||
|
methods |
Array (method) |
true |
The list of payment methods for the given customer. |
|
|
method |
object |
The structure of the payment method. |
||
|
method_uid |
String |
true |
method |
The unique payment method identifier. |
|
payment_type |
Int |
true |
method |
The integer number indicating the payment type: 0 - Credit Card 1 - ACH |
|
last4 |
String |
true |
method |
The obfuscated account number for display. |
|
type |
String |
true |
method |
The type of payment method for e.g. VISA, ECHK, etc. |
|
expiry |
String |
false |
method |
The expiry month and year for the given payment method applicable for credit cards. |
|
default |
boolean |
true |
method |
The flag to indicate if the given payment method is the default payment method or not. |
Get Payment Method Details
Use this call to get details for a single payment method while passing the method_uid (method unique identifier).
|
Name |
Type |
Required |
Parent |
Description |
|
Request |
||||
|
gateway_config |
Object |
true |
The gateway config object. |
|
|
customer_config |
Object |
true |
The customer config object. |
|
|
uuid |
String |
true |
The unique identifier for a payment method for the customer. |
|
|
Response |
||||
|
method |
object |
The structure of the payment method. |
||
|
uuid |
String |
true |
method |
The unique payment method identifier. |
|
method_type |
Int |
true |
method |
The integer number indicating the payment type: 0 - Credit Card 1 - ACH |
|
last4 |
String |
true |
method |
The obfuscated account number for display. |
|
token_id |
String |
false |
method |
The optional token id if stored against a method. |
|
brand |
String |
true |
method |
The type of payment method for e.g. VISA, ECHK, etc. |
|
year |
Int |
false |
method |
The expiry year for the given payment method applicable for credit cards. |
|
month |
Int |
false |
method |
The expiry month for the given payment method applicable for credit cards. |
|
default |
boolean |
true |
method |
The flag to indicate if the given payment method is the default payment method or not. |
|
opt |
object |
false |
method |
The object capturing any other optional details for the given payment method. |
Get Add Payment Method Form
Use this call to override the default Payment Method form provided by Ordway.
When the override flag for credit card form is turned on, use this method for painting the payment method input form. The SDK supports two interfaces one for credit card and one for ACH.
- GetAddCCMethodForm
- GetAddACHMethodForm
The structure of the request parameters will be the same.
|
Name |
Type |
Required |
Parent |
Description |
|
Request |
||||
|
gateway_config |
Object |
true |
The gateway config object. |
|
|
Response |
||||
|
form |
object |
The structure of the payment method. |
||
Add Payment Method
Use this call to add a new payment method for the given customer in the tenant. The parameters are a pass through from whatever is coming back from the form that was painted earlier.
|
Name |
Type |
Required |
Parent |
Description |
|
Request |
||||
|
gateway_config |
Object |
true |
The gateway config object. |
|
|
customer_config |
Object |
true |
The customer config object. |
|
|
params |
Object |
true |
The parameter that was returned back from the add form. |
|
|
Response |
||||
|
gateway_id |
string |
false |
The customer gateway id that should be stored against the customer. When provided, this will be stored to the customer profile if there was no customer profile stored previously for the given customer. |
|
|
method |
method |
true |
The payment method to be stored in the customer’s payment profile. |
|
Delete Payment Method
Use this call to delete a particular payment method. The response is either success or failure.
|
Name |
Type |
Required |
Parent |
Description |
|
Request |
||||
|
gateway_config |
Object |
true |
The gateway config object. |
|
|
customer_config |
Object |
true |
The customer config object. |
|
|
method_uids |
Array |
true |
The list of unique identifiers for the payment methods for bulk delete operation. |
|
|
Response |
||||
|
status |
The status for the delete request “succeeded” or “failed.” |
|||
|
method_uids |
Array |
true |
The list of method uids to delete from the ordway store. |
|
Create Payment
Use this call to create a payment request for the customer. The expectation is that the system already has created a payment record for the given payment request. The SDK will be called to make the final payment request.
|
Name |
Type |
Required |
Parent |
Description |
|
Request |
||||
|
gateway_config |
Object |
true |
The gateway config object. |
|
|
customer_config |
Object |
true |
The customer config object. |
|
|
payment_uid |
String |
true |
The unique reference of the payment being authorized. |
|
|
amount |
float |
false |
The payment amount to refund, if this is not provided then the entire payment amount will be refunded. |
|
|
currency |
String |
true |
The currency of the original payment. |
|
|
description |
String |
false |
The optional description field that will be a part of the payment request. Note: This depends on the payment gateway support. |
|
|
statement_descriptor |
String |
false |
The optional statement descriptor for non card charges that can appear on the customers statements. |
|
|
options |
Object |
false |
A set of key value pairs that can be tagged to the payment request. Note: This depends on the payment gateway support. |
|
|
method |
Object |
false |
The optional payment method information that can be passed while authorizing the payment request, this will be mutually exclusive with the method_uid. This is useful when the customer would like to authorize the payment w/o storing the card information. |
|
|
Response |
||||
|
status |
String |
true |
The status for the create payment request “succeeded” or “failed.” |
|
|
transaction_ref |
String |
true |
The successful payment transaction identifier, this is the ID that will be used to link to a successful refund request at the payment gateway. |
|
|
method |
object |
true |
The details of the payment method used to authorize the payment. |
|
|
amount |
float |
true |
The payment amount authorized. This can be used for reconciliations etc. |
|
|
fees |
float |
true |
The fees that were charged for the payment transaction, this is optional and will be defaulted to 0 if not provided. |
|
|
conversion_rate |
float |
false |
The conversion rate used. |
|
|
gateway_resp |
object |
true |
The actual gateway response stored for reference and debug purposes. |
|
|
resp_note |
String |
false |
This is an optional field that can be returned by the SDK that will be appended to the payment notes for further details of the payment transaction if required. |
|
|
payment_uid |
String |
true |
The unique reference of the payment sent as a part of the request. |
|
Refund Payment
Use this call to create a refund for an existing payment. The SDK will attempt to try a refund and if successful, the refund response will contain the details for the same. The table below captures the structure of the request and response.
|
Name |
Type |
Required |
Parent |
Description |
|
Request |
||||
|
gateway_config |
||||
|
transaction_ref |
String |
true |
The successful payment transaction identifier, this is the ID that will be used to link to a successful refund request at the payment gateway. |
|
|
amount |
float |
true |
The payment amount authorized. This can be used for reconciliations etc. |
|
|
gateway_resp |
object |
true |
The actual gateway response stored for reference and debug purposes. |
|
|
refund_note |
String |
false |
This is an optional field that can be returned by the SDK that will be appended to the refund notes for further details of the payment transaction if required. |
|
|
refund_uid |
String |
true |
The unique reference of the refund sent as a part of the request. |
|
|
reason |
String |
false |
The optional reason field that can be provided for the refund request. |
|
|
options |
Object |
false |
A set of key value pairs that can be tagged to the refund request, please note this will depend on the support by the payment gateway. |
|
|
Response |
||||
|
status |
String |
true |
The status for the create payment request “succeeded” or “failed.” |
|
|
transaction_ref |
String |
true |
The successful refund transaction identifier, this is the ID that will be used to link to a successful refund request at the payment gateway. |
|
|
amount |
float |
true |
The refunded amount. |
|
|
conversion_rate |
float |
false |
The conversion rate used. |
|
|
gateway_resp |
object |
true |
The actual gateway response stored for reference and debug purposes |
|
|
resp_note |
String |
false |
This is an optional field that can be returned by the SDK that will be appended to the refund notes for further details of the refund transaction if required. |
|
Void Transaction
Use this call to void a transaction that is currently under process. The only difference between a refund and a void is that refund is for a payment that has successfully been authorized and void is for a payment transaction that is still under process.
|
Name |
Type |
Required |
Parent |
Description |
|
Request |
||||
|
transaction_ref |
String |
true |
The successful payment transaction identifier, this is the ID that will be used to link to a successful refund request at the payment gateway. |
|
|
method |
object |
true |
The details of the payment method used to authorize the payment. |
|
|
amount |
float |
true |
The payment amount authorized. This can be used for reconciliations etc. |
|
|
fees |
float |
true |
The fees that were charged for the payment transaction, this is optional and will be defaulted to 0 if not provided. |
|
|
gateway_resp |
object |
true |
The actual gateway response stored for reference and debug purposes. |
|
|
resp_note |
String |
false |
This is an optional field that can be returned by the SDK that will be appended to the payment notes for further details of the payment transaction if required. |
|
|
payment_uid |
String |
true |
The unique reference of the payment sent as a part of the request. |
|
|
reason |
String |
false |
The optional reason field that can be provided for the refund request. |
|
|
opt |
Object |
false |
A set of key value pairs that can be tagged to the refund request. Note: This depends on the payment gateway support. |
|
|
Response |
||||
|
status |
String |
true |
The status for the create payment request “succeeded” or “failed.” |
|
|
transaction_ref |
String |
true |
The successful refund transaction identifier, this is the ID that will be used to link to a successful refund request at the payment gateway. |
|
|
amount |
float |
true |
The voided amount. |
|
|
gateway_resp |
object |
true |
The actual gateway response stored for reference and debug purposes |
|
|
resp_note |
String |
false |
This is an optional field that can be returned by the SDK that will be appended to the refund notes for further details of the refund transaction if required. |
|
Reconcile Payments
Use this call to reconcile any pending payments that are still in processing state.
|
Name |
Type |
Required |
Parent |
Description |
|
Request |
||||
|
gateway_config |
Object |
true |
The gateway config object. |
|
|
payments |
Array (payment) |
false |
The list of payment records that need to be reconciled. |
|
|
to |
Date |
false |
Datetime to start the search to, in ISO8601 format. |
|
|
from |
Date |
false |
Datetime to start the search to, in ISO8601 format. |
|
|
limit |
number |
false |
How many results to skip. |
|
|
offset |
number |
false |
How many results to return. Between 1 and 100, defaults to 20. |
|
|
customer_uid |
string |
false |
Customer ID to be filtered. |
|
|
Response |
||||
|
payments |
Array (payment) |
true |
The array of payment records to be updated. |
|
|
payment |
object |
false |
The payment object. |
|
All the records that were sent back will be updated in the system.
Gateway Configuration Object
This structure will capture the information for the gateway configuration for a given tenant.
The JSON structure of the configuration object is as follows:
|
Name |
Type |
Parent |
Description |
|
tenant_uid |
String |
The unique identifier for the tenant. |
|
|
tenant_config |
Object |
The tenant configuration object that will be stored for every tenant from the SDK. |
Customer Details Object
The structure of the customer details object that will be stored in the Ordway Platform and will be sent as a part of each transaction request for a particular customer of the tenant.
|
Name |
Type |
Required |
Parent |
Description |
|
uuid |
String |
true |
The unique identifier for the customer. |
|
|
gateway_id |
String |
false |
The unique customer id provided by the payment gateway if any. |
|
|
methods |
Array (method) |
false |
The array of payment methods for the given customer. |
|
|
method |
Object |
false |
The structure of the payment method to be stored in Ordway. |
|
|
method_uid |
String |
true |
method |
The unique payment method identifier. |
|
payment_type |
Int |
true |
method |
The payment type the different types of payments are: 0 - Credit Card 1 - ACH |
|
disp_acct_num |
String |
true |
method |
The obfuscated account number for display. |
|
type |
String |
true |
method |
The type of payment method for e.g. VISA, ECHK, etc. |
|
token |
String |
false |
method |
The optional token id if stored against a method. |
|
expiry |
String |
false |
method |
The expiry month and year for the given payment method applicable for credit cards. |
|
default |
boolean |
true |
method |
The flag to indicate if the given payment method is the default payment method or not. |
|
opt |
object |
false |
method |
The object capturing any other optional details for the given payment method. |
Payment Method Object
The structure of the payment object method includes one for display and one with details.
This table captures the detailed payment method structure.
|
Name |
Type |
Required |
Parent |
Description |
|
uuid |
String |
true |
method |
The unique payment method identifier. |
|
method_type |
String |
true |
method |
The integer number indicating the payment type: ‘credit_card’ ‘ach’ |
|
last4 |
String |
true |
method |
The obfuscated account number for display. |
|
token_id |
String |
false |
method |
The optional token id if stored against a method. |
|
brand |
String |
true |
method |
The type of payment method for e.g. VISA, ECHK, etc. |
|
year |
Int |
false |
method |
The expiry year for the given payment method applicable for credit cards. |
|
month |
Int |
false |
method |
The expiry month for the given payment method applicable for credit cards. |
|
default |
boolean |
true |
method |
The flag to indicate if the given payment method is the default payment method or not. |
|
opt |
object |
false |
method |
The object capturing any other optional details for the given payment method. |
This table captures the display version of the payment method.
|
Name |
Type |
Required |
Parent |
Description |
|
uuid |
String |
true |
method |
The unique payment method identifier. |
|
method_type |
Int |
true |
method |
The integer number indicating the payment type: credit_card ach |
|
last4 |
String |
true |
method |
The obfuscated account number for display. |
|
brand |
String |
true |
method |
The type of payment method for e.g. VISA, ECHK, etc. |
|
year |
Int |
false |
method |
The expiry year for the given payment method applicable for credit cards. |
|
month |
Int |
false |
method |
The expiry month for the given payment method applicable for credit cards. |
|
default |
boolean |
true |
method |
The flag to indicate if the given payment method is the default payment method or not. |
Payment Response Object
|
Name |
Type |
Required |
Parent |
Description |
|
status |
String |
true |
The status for the create payment request “succeeded” or “failed.” |
|
|
transaction_ref |
String |
true |
The successful payment transaction identifier, this is the ID that will be used to link to a successful refund request at the payment gateway. |
|
|
method |
object |
true |
The details of the payment method used to authorize the payment. |
|
|
amount |
float |
true |
The payment amount authorized. This can be used for reconciliations etc. |
|
|
fees |
float |
true |
The fees that were charged for the payment transaction, this is optional and will be defaulted to 0 if not provided. |
|
|
gateway_resp |
object |
true |
The actual gateway response stored for reference and debug purposes. |
|
|
resp_note |
String |
false |
This is an optional field that can be returned by the SDK that will be appended to the payment notes for further details of the payment transaction if required. |
|
|
payment_uid |
String |
true |
The unique reference of the payment sent as a part of the request. |
Error Response Structure
|
Name |
Type |
Required |
Parent |
Description |
|
errors |
Array (error) |
true |
The array of error objects that detail out the error. |
|
|
error |
Object |
The error object. |
||
|
code |
String |
true |
The unique codes defining the error. Refer to Error Codes below. |
|
|
message |
String |
false |
The error message detailing the cause of the issue. |
Error Codes
JSON error codes.
|
Code |
Description |
|
401 |
Payment method details not found. |
|
101 |
Payment gateway not reachable. |
|
422 |
Invalid or missing request parameters or format. |
|
402 |
Payment failed. |
Click here for Ordway Payment SDK Developer Guide
Comments
0 comments
Please sign in to leave a comment.