SurchX API (1.1)

Download OpenAPI specification:Download

The SurchX API is an HTTP API into SurchX Services.

Overview

SurchX is able to accurately estimate the Transaction Fee that can be included in an ecommerce order, subscription, or recurring charge system. The non-identifying information required to calculate a Transaction Fee is the order amount, delivery address region (U.S. State or ZipCode), and the first six or eight digits of the credit card number.

SurchX will never store any Personally Identifiable Information (PII)

The Transaction Fee must be displayed next to the total amount displayed to the card holder and it must be displayed with the label Transaction Fee. Full implementations will require a review against our Legal guidelines.

API Workflow

The SurchX Transaction Fee API is used whenever a credit card processing action will happen. Since Merchants have many choices on how the a shopping or recurring-charge service is implemented, the descriptions below typically assume an e-commerce shopping cart workflow with a non-consumer accessible backend for credit-card processing.

During e-commerce shopping cart progression or equivalent, there are points that the SurchX API needs to be called. When the NICN, Shipping State/Region and Total amount has been entered or modified, it is necessary to call the SurchX API to retrieve a Transaction Fee (which may be 0.00).

There are two additional components required to complete a SurchX workflow. A Merchant managed unique id representing the Order/Shopping-Cart entity and the credit card processing Authorization Code.

  • The Merchant orderId is used to facilitate the order processing workflow that is different across most ecommerce or ordering systems with regard to consumer facing logic and backend logic. SurchX requires the Merchant orderId as a unique lookup-key to ensure that persistence of the AuthCode is accurate.

  • The Merchant's credit card processing AuthCode is required for reconciliation workflows

API Token (for client side operations)

Include an Authorization http header with a bearer token for API authorization. This is required API endpoints which are expected to be called from an environment which a API Secret Key could not be kept secret. For example, any browser based API calls should use this form of authorization. Below is an example Http Header for authorization.

Authorization: Bearer ...0ksX2JtaI-EY3vLrjAbKUpJER365E0_Z6I-Lr5txru4...

Versioning

The API is can be changed in each release of SurchX, so API calls are versioned to ensure that clients don't break.

For SurchX 1.0 and to lock to this version, you prefix the URL with /v1.

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses.

Testing

The Merchant can use some pre-defined Campaign codes during test phases. These are internal identifies that must only be used during testing and not during production phases.

A campaign of abandonTest should be specified to facilitate A/B testing.

Curl

Below are a couple examples of command-line testing via curl

Call Transaction Fee Endpoint

  curl 'https://api-test.surchx.com/v1/ch' \
    -H 'Authorization: Bearer ...0ksX2JtaI-EY3vLrjAbKUpJER365E0_Z6I-Lr5txru4...' \
    -H 'Content-Type: application/json' \
    -H 'X-Requested-With: xhr' \
    --data-binary '{"nicn":"414709","processor":"SurchX","amount":100,"country":"840","region":"92130","campaign":["abandonTest"],"mTxId":"207fb94d"}'

Capture Endpoint

  curl 'https://api-test.surchx.com/v1/ch/capture' \
    -H 'Authorization: Bearer ...0ksX2JtaI-EY3vLrjAbKUpJER365E0_Z6I-Lr5txru4...' \
    -H 'Content-Type: application/json' \
    -H 'X-Requested-With: xhr' \
    --data-binary '{"mTxId":"207fb94d","authCode":"eebee37a-72995c5d"}'

Example NICNs

NICNType
343434AMEX
444433Visa
446203Visa Debit
555555Mastercard
601111Discover

Workflow Configuration

The required configuration for using the SurchX Transaction Fee API is a Bearer Token which designates the Merchant and further the processor configuration. A string based processor name or the MID (assigned by the processor) can be used as a key to find the processor definition.

Workflow Typical

  • A Region attribute is required for accurate Transcation Fee calculations. In the US, you can pass a zip-code, a two letter state abbreviation, or a two letter abbreviation with a "US-" prefix. A Country code attribute can be included and should be the three digit country-code (see https://en.wikipedia.org/wiki/ISO_3166-1)
  • The typcal use-case of the Transaction Fee API includes the Amount, Region, and NICN attributes.

Workflow NICN Store

A NICN passed in without a Region or Amount will be stored for later use. For later use, a sTxId or mTxid along with a Region and an Amount is required to complete the workflow.

Nomenclature

PAN
Primary Account Number / "card number"
NICN
Non-Identifiable Card Number - This is defined as "all but the last 4" of the PAN. SurchX never handles more than 12 digits and therefore is not in conflict with PCI requirements or guidelines.
AuthCode
The authorization code returned from the Merchant's credit card processing capture process. The AuthCode will be used for reconciliation of fees.
Capture
The process of executing against a credit card processing gateway to establish an action against a consumer's credit card.
Token
A tokenized or obfuscated form of the PAN. This is primary used when Merchants have "outsourced" the web form inputs for PAN and card holder data
Transaction Fee
The SurchX calculated Transaction Fee that MUST be displayed to the card holder with the displayed title of Transaction Fee
mTxId
The Merchant shopping-cart order identifier unique in the Merchants system. This is used as a key to looking up existing Transaction Fee records for subsequent calculations or workflow stages
sTxId
The SurchX identifier unique in the SurchX system used as a key to looking up existing Transaction Fee records for subsequent calculations or workflow stages

Authentication

bearerAuth

Include an Authorization header with a bearer token for API authorization. A example Http Header should like like the following

Authorization: Bearer ...0ksX2JtaI-EY3vLrjAbKUpJER365E0_Z6I-Lr5txru4...
Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

merchantAdminBearerAuth

Include an Authorization header with a bearer token for API authorization. A example Http Header should like like the following

Authorization: Bearer ...0ksX2JtaI-EY3vLrjAbKUpJER365E0_Z6I-Lr5txru4...
Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

E-Commerce Cart

Working with shopping carts to determine Transaction Fees.

Get the transaction fee

Transient State

There is no "state" created when an orderId (mTxId) is not specified. In that case, you can consider the call Transient. However, when an orderId (mTxId) is sent with the request body, that orderId is considered a lookup-key for subsequent Transaction Fee calls as well as API calls which require a lookup-key.

SurchX Transaction Id (sTxId)

A SurchX generated UUID is included as part of the response. You are encouraged to use this sTxId value in subsequent calls where it is allowed. It will be used as a lookup-key for an existing record which mirrors the lifetime of a consumer's e-commerce transaction.

NICN State

You may utilize SurchX as state management for the NICN value. This is useful when you have multiple pages or progressions during your e-commerce flow and the NICN, Amount, and Region are not readily available for calls to this API endpoint all at the same time. You may pass a NICN; an optional sTxId or mTxId; and no Amount or Region and SurchX will maintain the NICN across calls. When the Amount and Region are available, the NICN will not be required for that call and will be used from previous endpoint calls. The lookup-key of sTxId or mTxId is mandatory when locating existing state.

Authorizations:
Request Body schema: application/json
campaign
Array of string

This is opaque data that is available for futher data analytics. This field is also used during A/B Test-Implementation phases.

data
Array of string

This is optional, opaque data that is available for futher data analytics.

country
string

The ISO Numerical Country Code. See https://en.wikipedia.org/wiki/ISO_3166-1. This is an optional field and will default to 840/US.

region
string

ZipCode or the ISO State Code. See https://en.wikipedia.org/wiki/ISO_3166-2:US. There are cases when region is optional.

processor
string

The MID or Name value of the processor to use for calculating Transaction Fees. This field is optional when the Merchant has only one configured processor. In that case the single, configured processor is used.

nicn
string

First six or eight digits although "all but the last four" are also valid. When this field is omitted, the NICN from a previous Transaction Fee API call is used.

amount
number
totalAmount
number

Use the totalAmount attribute when you want to caclculate the transaction fee using the amount attribute for a lesser amount that the overall transaction total (totalAmount). This is a use-case to support multiple Tenders of a Retail Transaction (amount) and still notify SurchX of the Retail Transaction total (totalAmount) to support business rules.

mTxId
string

A Merchant orderId or unique identifier in the Merchant e-commerce scope referencing the Order or Shopping Cart. This field is optional. If the mTxId is not known until the "capture" sequence, it may be passed at that time.

sTxId
string

The SurchX unique identifier in the SurchX scope referencing the persistence state of the Transaction Fee calculation

Responses

201

Transaction fee calculated.

400

Invalid input. See required parameters

401

Authorization information is missing or invalid

post /ch
https://api-test.surchx.com/v1/ch

Request samples

application/json
Copy
Expand all Collapse all
{
  • "campaign":
    [
    ],
  • "country": "840",
  • "region": "90210",
  • "processor": "SurchX",
  • "nicn": "414709",
  • "amount": 49.95,
  • "mTxId": "order-2018-09-01-0001",
  • "sTxId": "569f6973-db7a-454f-9f69-73db7a954f68"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "transactionFee": 3.04,
  • "sTxId": "569f6973-db7a-454f-9f69-73db7a954f68",
  • "message": "ok"
}

Set the Authoriziation Code (AuthCode) from an "Auth Only" processor call

After a successful Merchant card processing event and and Authorization Code (AuthCode) is available, this call associates the AuthCode with the previously calculated Transaction Fee. The AuthCode is used for reconciliation later.

Authorizations:
Request Body schema: application/json
mTxId
string

An optional Merchant orderId used as a lookup-key. This mTxId does not have to have been used previously in an transactionFee call. It will be recorded with the transaction.

sTxId
string

An optional SurchX transactionId used as a lookup-key

authCode
string

An optional authCode or id referencing the state of being captured

data
Array of string

This is opaque data that is available for futher data analytics.

Responses

201

AuthCode was stored successfully

400

Invalid input. See required parameters. A Merchant orderId or a SurchX transactionId is required as a lookup-key

401

Authorization information is missing or invalid

post /ch/authorize
https://api-test.surchx.com/v1/ch/authorize

Request samples

application/json
Copy
Expand all Collapse all
{
  • "mTxId": "2018-09-26-0000599",
  • "sTxId": "569f6973-db7a-454f-9f69-73db7a954f68",
  • "authCode": "az123456789"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "sTxId": "569f6973-db7a-454f-9f69-73db7a954f68"
}

Set the Authoriziation Code (AuthCode)

After a successful Merchant card processing event and and Authorization Code (AuthCode) is available, this call associates the AuthCode with the previously calculated Transaction Fee. The AuthCode is used for reconciliation later.

Authorizations:
Request Body schema: application/json
mTxId
string

An optional Merchant orderId used as a lookup-key. This mTxId does not have to have been used previously in an transactionFee call. It will be recorded with the transaction.

sTxId
string

An optional SurchX transactionId used as a lookup-key

authCode
string

An optional authCode or id referencing the state of being captured

data
Array of string

This is opaque data that is available for futher data analytics.

Responses

201

AuthCode was stored successfully

400

Invalid input. See required parameters. A Merchant orderId or a SurchX transactionId is required as a lookup-key

401

Authorization information is missing or invalid

post /ch/capture
https://api-test.surchx.com/v1/ch/capture

Request samples

application/json
Copy
Expand all Collapse all
{
  • "mTxId": "2018-09-26-0000599",
  • "sTxId": "569f6973-db7a-454f-9f69-73db7a954f68",
  • "authCode": "az123456789"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "sTxId": "569f6973-db7a-454f-9f69-73db7a954f68"
}

Calculate the appropriate transaction fee value to refund

During a Merchant refund process, this endpoint will help calculate the transaction fee that can be refunded to a consumer

Authorizations:
Request Body schema: application/json
mTxId
string

An optional Merchant orderId used as a lookup-key. This mTxId does not have to have been used previously in an transactionFee call. It will be recorded with the transaction.

sTxId
string

An optional SurchX transactionId used as a lookup-key

amount
string

An optional amount representing the total value refunding to consumer

Responses

200

A response with a "refund" value

400

Invalid input. See required parameters. A Merchant orderId or a SurchX transactionId is required as a lookup-key

401

Authorization information is missing or invalid

post /ch/refund
https://api-test.surchx.com/v1/ch/refund

Request samples

application/json
Copy
Expand all Collapse all
{
  • "mTxId": "2018-09-26-0000599",
  • "sTxId": "569f6973-db7a-454f-9f69-73db7a954f68",
  • "amount": 50
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "refund": 1.75
}

Merchant Management

Reseller integration

List all Merchants

Authorizations:

Responses

200

The Merchant

400

Invalid input. See required parameters

401

Authorization information is missing or invalid

get /merchant
https://api-test.surchx.com/v1/merchant

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get Merchant by ID

Authorizations:
path Parameters
merchantId
required
string

The ID of the merchant to retrieve

Responses

200

The Merchant

400

Invalid input. See required parameters

401

Authorization information is missing or invalid

get /merchant/{merchantId}
https://api-test.surchx.com/v1/merchant/{merchantId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "merchant":
    {
    }
}

Get Merchant Transaction Log

Authorizations:
path Parameters
merchantId
required
string

The ID of the merchant

query Parameters
skip
integer

number of items to skip (page number)

limit
integer

number of items to retrieve (page size)

Responses

200

Transaction Log Summary

400

Invalid input. See required parameters

401

Authorization information is missing or invalid

get /merchant/{merchantId}/txlog
https://api-test.surchx.com/v1/merchant/{merchantId}/txlog

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get Merchant Transaction Summary - group by day

Authorizations:
path Parameters
merchantId
required
string

The ID of the merchant

query Parameters
month
integer

The julian month to match/filter

day
integer

The julian day to match/filter

skip
integer

number of items to skip (page number)

limit
integer

number of items to retrieve (page size)

Responses

200

Transaction Log Summary

400

Invalid input. See required parameters

401

Authorization information is missing or invalid

get /merchant/{merchantId}/txlog/summary/month
https://api-test.surchx.com/v1/merchant/{merchantId}/txlog/summary/month

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "count": 0,
  • "totalAmount": 0
}

Get Merchant Transaction Summary - group by month and day

Authorizations:
path Parameters
merchantId
required
string

The ID of the merchant

query Parameters
month
integer

The julian month to match/filter

day
integer

The julian day to match/filter

skip
integer

number of items to skip (page number)

limit
integer

number of items to retrieve (page size)

Responses

200

Transaction Log Summary

400

Invalid input. See required parameters

401

Authorization information is missing or invalid

get /merchant/{merchantId}/txlog/summary/day
https://api-test.surchx.com/v1/merchant/{merchantId}/txlog/summary/day

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "count": 0,
  • "totalAmount": 0
}