Seamless Pay

Overview

The Seamless Payments API is organized around REST, and responses are sent using JSON. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. Use our API to integrate your website, software application, mobile app and more. This documentation is a work in progress.

API Endpoints:

Sandbox: https://sandbox.seamlesspay.com
Production: https://api.seamlesspay.com

Authentication

In order to authenticate your account, you must first generate an API Key. Once you've created an account, generating an API key is simple:

Login to your Seamless Payments account Dashboard
Select "Api Keys" in left side bar
Click on "Reveal Secret Key" button

Your secret API key should never be shared publicly or accessible, such as committed code on GitHub, client-side code, etc.

If you are not using one of our SDKs, all HTTP requests must contain an Authorization header containing your base_64 encoded API key.

All API requests must be made using HTTPS. Calls made using plain HTTP will timeout. API requests without authentication will also timeout.

Idempotent Requests

The API supports idempotent requests to safely issue retries without worrying about accidentally performing the same operation twice. To perform an idempotent request, attach a unique key to any POST request made to the API via the optional idempotencyKey parameter. This should only be necessary for API calls that create side effects (ie this should not be necessary for calls that just query card info).

Stored Value

Our stored value API can be used to create a variety of integrated applications, such as gift card and rewards programs.

A stored-value card is a payments card with a monetary value stored on the card itself, not in an external account maintained by a financial institution. Our API makes it simple to create accounts and manage their value programmatically.

For your convenience, we provide JSON Schema definitions for testing and validating your raw requests. There are validator implementations in all major languages.

Test Cards

If permission Provide Third-Party Responses is OFF, test card numbers are:

4242424242424242
4012888888881881
4000056655665556
5555555555554444
5200828282828210
5105105105105100
378282246310005
371449635398431
6011111111111117
6011000990139424
30569309025904
38520000023237
3530111333300000
3566002020360505

If permission Provide Third-Party Responses is ON for processor SVS:

6006493880499919454

If permission Provide Third-Party Responses is ON for processor TCC:

2063025100129939
2063025100208604
2063025100319447
2063025100489025
2063025100553531
2063025100624857
2063025100793656
2063025100806258
2063025100999300

Creating a Gift Card

Creates a new stored value account (gift card) for the merchant associated with API key passed with the request.

Note that you must provide either cardNumber OR cardTrackTwo for requests. Track one data is not necessary for gift card transactions.

Property	Type	Description
`* amount`	`String`	Amount to add to stored value account.
`cardNumber`	`String`	Card number (if non-magnetic)
`cardTrackTwo`	`String`	Unencrypted track two data (if card present)
`idempotencyKey`	`String`	Optional

* Required

The response JSON will include the created account info as well as the merchant's name, id, and store number, if applicable.

POST

/v2/stored-value

Example Request (JSON Schema)

$ curl https://sandbox.seamlesspay.com/v2/stored-value \
  -H "Authorization: Bearer {BASE_64_API_KEY}" \
  -d cardNumber=6006493880499919561 \
  -d amount="99.99" \
  -d idempotencyKey="7c62e63ab7fb6d10166b70945dc48b52"

Example Response

{
  "amount": "99.99",
  "cardNumber": "6006493880499919561",
  "createdAt": "2017-07-14T14:10:31.259Z",
  "merchantId": "12345678954",
  "merchantName": "Awesome Hardware"
}

Delete a Gift Card

Remove stored value account (gift card) for the merchant associated with API key passed with the request.

Note that you must provide either cardNumber OR cardTrackTwo for requests. Track one data is not necessary for gift card transactions.

Property	Type	Description
`* cardNumber`	`String`	Card number (if non-magnetic)
`* cardTrackTwo`	`String`	Unencrypted track two data (if card present)

* Required

DELETE

/v2/stored-value/{cardNumber|cardTrackTwo}

Example Request

$ curl -X "DELETE" https://sandbox.seamlesspay.com/v2/stored-value/6006493880499919561 \
  -H "Authorization: Bearer {BASE_64_API_KEY}"

Example Response

{
  "cardNumber": "6006493880499919561",
  "amount": "99.99",
  "merchantName": "Awesome Hardware",
  "merchantId": "12345678954",
  "createdAt": "2017-07-14T14:10:31.259Z"
}

Get Card Info

For convenience we provide a dead simple endpoint for querying card information.

Property	Type	Description
`cardNumber`	`String`	Card number (if non-magnetic)
`cardTrackTwo`	`String`	Unencrypted track two data (if card present)
`currency`	`String`	Card currency.
`*** pinNumber`	`String`	Optional, value used to restrict access to gift card

*** Card Pin Number – A value used to restrict access to gift card. This field is divided into two subfields; the first 4 digits are the secondary security code (SSC) to be used with bar coded accounts. The second subfield is a 4 digit PIN number used for any card not present transaction or when the magnetic strip is not available to add extra security for the card account. Each Sub-field should be right justified left zero filled.

Note that you must provide either cardNumber OR cardTrackTwo for requests. Track one data is not necessary for gift card transactions, however if track one data was provided it will be returned in response.

POST

/v2/stored-value/info

Example Request (JSON Schema)

$ curl https://sandbox.seamlesspay.com/v2/stored-value/info \
  -H "Authorization: Bearer {BASE_64_API_KEY}" \
  -d cardNumber=6006493880499919561 \
  -d currency="USD"

Example Response

{
  "merchantId": "5432198765",
  "cardNumber": "6006493880499919561",
  "amount": "988.12",
  "currency": "USD",
  "cardStatus": "Active",
  "createdAt": "2017-12-03T17:32:46.432Z"
}

Creating Gift Transactions

There are types of transactions, passed as type with request:

Type	Description
`GIFT`	Gift Card transaction

There are supported currencies of transactions, passed as currency with request:

Currency	Description
`USD`	United States Dollar
`CAD`	Canadian Dollar

There are methods of transaction, passed as method with request:

Method	Description
`cancel`	A non-financial request. Used when a merchant wants to cancel a previous transaction.
`redemption`	The requested amount is deducted from the working balance of the stored-value account. Similar to debiting a bank account.
`reload`	Adds value to card account.

Property	Type	Description
`* method`	`String`	The transaction method (enum)
`* type`	`String`	The transaction's type.
`* cardNumber`	`String`	Card number (if non-magnetic).
`* cardTrackTwo`	`String`	Unencrypted track two data (if card present).
`pinNumber`	`String`	Optional, value used to restrict access to gift card.
`* transactionId`	`String`	Required for `cancel` / `void` type
`* amount`	`String`	Transaction amount.
`currency`	`String`	Transaction currency.
`idempotencyKey`	`String`	Optional, see section above.

* Required

Note:

That you must provide either cardNumber OR cardTrackTwo for requests. Card track one data is not necessary for gift card transactions.
You must provide both returned transactionId and original amount value to cancel previous transaction. See example.
Card Pin Number – A value used to restrict access to gift card. This field is divided into two subfields; the first 4 digits are the secondary security code (SSC) to be used with bar coded accounts. The second subfield is a 4 digit PIN number used for any card not present transaction or when the magnetic strip is not available to add extra security for the card account. Each Sub-field should be right justified left zero filled.
If you attempt to redeem more than the stored value, our API will return a customerPayment value indicating the difference to be collected by alternative method.

POST

/v2/transactions

Example Request

$ curl https://sandbox.seamlesspay.com/v2/transactions \
  -H "Authorization: Bearer {BASE_64_API_KEY}" \
  -d type=GIFT \
  -d method=reload \
  -d amount=10 \
  -d currency=USD \
  -d idempotencyKey="7c62e63ab7fb6d10166b70945dc48b52"

Example Response

{
  "merchantId": "32462476",
  "cardNumber": "6006493880499919454",
  "amount": "10.00",
  "currency": "USD",
  "status": "01",
  "statusDescription": "Approval",
  "createdAt": "2017-08-08T18:09:26.444Z",
  "transactionType": "reload",
  "transactionId": "TXN_01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

Example Response (Amount exceeds current value)

{
  "merchantId": "32462476",
  "cardNumber": "6006493880499919454",
  "amount": "6.00",
  "currency": "USD",
  "customerPayment": "4.00",
  "status": "109",
  "statusDescription": "Additional payment required to complete transaction",
  "createdAt": "2017-08-08T18:09:26.444Z",
  "transactionType": "redemption",
  "transactionId": "TXN_01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

Cancelling a Transaction

  $ curl https://sandbox.seamlesspay.com/v2/transactions \
    -H "Authorization: Bearer {BASE_64_API_KEY}" \
    -d type=GIFT \
    -d method=cancel \
    -d transactionId=TXN_01ARZ3NDEKTSV4RRFFQ69G5FAV

Example Response (Cancelled transaction)

{
  "merchantId": "12345",
  "amount": "4.00",
  "currency": "USD",
  "status": "107",
  "statusDescription": "Cancelled",
  "createdAt": "2017-08-08T18:09:26.444Z",
  "transactionType": "cancel",
  "transactionId": "TXN_05FRZ3NDEKTSV4RRFFQ69G5FZS"
}

Get a Gift Transaction

The transaction object

Property	Type	Description
`id`	`String`	Unique identifier for the object.
`cardNumber`	`String`	The card number.
`transactionType`	`String`	The transaction's type.
`authCode`	`String`	Third party service unique transaction ID.
`amount`	`Number`	Amount converted to default merchant's currency.
`amountOriginal`	`Number`	The transaction's amount.
`merchantId`	`String`	The merchant's identifier for the object.
`ipAddress`	`String`	The transaction's IP address.
`transId`	`String`	The transaction's id.
`invoice`	`String`	The transaction's invoice.
`status`	`String`	The transaction's status code.
`statusMessage`	`String`	The transaction's status description.
`currency`	`String`	The transaction's currency.
`tranDate`	`String`	The transaction's date.
`createdAt`	`String`	Time at which the object was created.
`updatedAt`	`String`	Time at which the object was updated.

GET

/v2/transactions/{TRANSACTION_ID}

$ curl https://sandbox.seamlesspay.com/v2/transactions/GCT_01BSV680614QDGSNA9GEKKBQ9M \
  -H "Authorization: Bearer {BASE_64_API_KEY}"

Example Response

{
  "id": "GCT_01BSV680614QDGSNA9GEKKBQ9M",
  "transactionType": "reload",
  "cardNumber": "2063025100129939",
  "amount": 5,
  "merchantId": "32469477",
  "tranDate": "2017-09-12T14:00:18.853Z",
  "ipAddress": "127.0.0.1",
  "amountOriginal": 1,
  "status": "01",
  "statusMessage": "Approval",
  "authCode": "3617",
  "transId": "TXN_01BSV6805ZWV0DCAZH4H4CP857",
  "updatedAt": "2017-04-03T17:04:28.941Z",
  "createdAt": "2017-04-03T17:04:28.941Z",
  "currency": "USD"
}

Listing Gift Transactions

Property	Type	Description
`filter`	`String`	Filter by apiKey, amount, transaction type
`cardNumber`	`String`	Filter by card number
`page`	`Number`	Page number
`count`	`Number`	Total items on page

* Required

GET

/v2/transactions

$ curl https://sandbox.seamlesspay.com/v2/transactions?filter=Name&page=1&count=10&cardNumber=2063025100129939 \
  -H "Authorization: Bearer {BASE_64_API_KEY}"

Example Response

{
  "total": 2,
  "data": [
    {
      "id": "GCT_01BSV680614QDGSNA9GEKKBQ9M",
      "transactionType": "reload",
      "cardNumber": "2063025100129939",
      "amount": 5,
      "merchantId": "32469466",
      "tranDate": "09/12/2017, 10:00:18 AM",
      "ipAddress": "::1",
      "amountOriginal": 1,
      "status": "01",
      "statusMessage": "Approval",
      "authCode": "3617",
      "transId": "TXN_01BSV6805ZWV0DCAZH4H4CP857",
      "updatedAt": "09/12/2017, 10:00:18 AM",
      "createdAt": "09/12/2017, 10:00:18 AM",
      "currency": "USD"
    },
    {
      "id": "GCT_01BSV6BH62K4H25AK89MQ18JY5",
      "transactionType": "reload",
      "cardNumber": "2063025100129939",
      "amount": 5,
      "merchantId": "32469466",
      "tranDate": "09/12/2017, 10:02:14 AM",
      "ipAddress": "::1",
      "amountOriginal": 1,
      "status": "01",
      "statusMessage": "Approval",
      "authCode": "3617",
      "transId": "TXN_01BSV6BH62DR1DNJEJNA7TD9R2",
      "updatedAt": "09/12/2017, 10:02:14 AM",
      "createdAt": "09/12/2017, 10:02:14 AM",
      "currency": "USD"
    }
  ],
  "pagination": {
    "count": 10,
    "page": 1,
    "size": 2,
    "pages": 1
  }
}

Example Request

$ curl https://sandbox.seamlesspay.com/v2/transactions?$or[0][status][$ne]=01&$or[1][currency]=USD \
  -H "Authorization: Bearer {BASE_64_SK_API_KEY}"

Status Codes

If you have any questions, please do not hesitate to contact customer support.

Return code	Return description
`01`	Approval
`02`	Inactive Card
`03`	Invalid Card Number
`04`	Invalid Transaction Code
`05`	Insufficient Funds
`06`	No Previous Authorizations
`07`	Invalid Message
`08`	No Card Found
`09`	Insufficient Funds due to Outstanding Pre-Authorization
`10`	Denial - No Previous Authorization
`11`	No Authorization Number
`12`	Invalid Authorization Number
`13`	Maximum Single Recharge Exceeded
`14`	Maximum Working Balance Exceeded
`15`	Host Unavailable
`16`	Invalid Card Status
`17`	Unknown Dealer/Store Code – Special Edit
`18`	Maximum Number of Recharges Exceeded
`19`	Invalid Card Verification Value (CVV) or Secondary Security Code (SSC)
`20`	Invalid PIN Number or PIN Locked
`21`	Card Already Issued
`22`	Card Not Issued
`23`	Card Already Used
`24`	Manual Transaction Not Allowed
`25`	Mag Stripe Read not Valid
`26`	Transaction Type Unknown
`27`	Invalid Tender Type
`28`	Invalid Customer Type
`29`	Unknown Error
`30`	Max number of redemption exceeded
`31`	Invalid currency code
`32`	Invalid Server ID (restaurant only – server ID code is invalid)
`33`	Frozen card, contact customer service
`34`	Invalid Amount (Does not match the pre-valued card dollar amount)
`35`	Unknown Error, please contact customer support
`36`	Rejected – Invalid transaction promotion-wide or invalid for originating merchant and store
`37`	Rejected – Invalid merchant and store combination for promotion
`38`	Rejected – Exceeded maximum number of promotion cards allowed for a single POS transaction
`42`	Transaction declined – transaction amount less than the required minimum
`99`	Failure retrieving data (Enhance Balance Inquiry Only)
`100`	Card Number required
`101`	Merchant not found
`102`	Gift Card Processor not configured
`103`	Gift card not found
`104`	Type required
`105`	Amount required
`106`	Gift Card Processor not supported
`107`	Transaction cancelled
`108`	Transaction not found
`109`	Additional payment required to complete transaction
`911`	Declined transaction

Example Error Responses

{
  "name": "GeneralError",
  "message": "Cannot read property 'returnCode' of undefined",
  "code": 500,
  "className": "general-error",
  "data": {},
  "errors": {}
}

{
  "name": "Unprocessable",
  "message": "Error",
  "code": 422,
  "className": "unprocessable",
  "data": {
    "statusCode": "21",
    "statusDescription": "Card Already Issued"
  },
  "errors": {}
}

{
  "name": "Unprocessable",
  "message": "Error",
  "code": 422,
  "className": "unprocessable",
  "data": {
    "statusCode": "100",
    "statusDescription": "Card number or Track Two required"
  },
  "errors": {}
}

{
  "name": "Unprocessable",
  "message": "Error",
  "code": 422,
  "className": "unprocessable",
  "data": {
    "statusCode": "101",
    "statusDescription": "Merchant not found"
  },
  "errors": {}
}

{
  "name": "Unprocessable",
  "message": "Error",
  "code": 422,
  "className": "unprocessable",
  "data": {
    "statusCode": "101",
    "statusDescription": "Merchant not found"
  },
  "errors": {}
}

{
  "name": "Unprocessable",
  "message": "Error",
  "code": 422,
  "className": "unprocessable",
  "data": {
    "statusCode": "06",
    "statusDescription": "No Previous Authorizations"
  },
  "errors": {}
}

{
  "name": "Unprocessable",
  "message": "System is temporarily unavailable, please try later",
  "code": 422,
  "className": "unprocessable",
  "errors": {}
}

Bin Lookup

Retrieves the details of bin

Property	Type	Description
`Bin`	`String`	The BIN value.
`IssuingBank`	`String`	This is the Issuer Bank name for the BIN.
`Country`	`String`	Three character alpha country code.
`CardBrand`	`String`	Detail Card Product - Visa, MasterCard, American Express, Discover, PIN Only (Non-Visa/MasterCard/AMEX/Discover).
`CardType`	`String`	Determines the card type (credit, debit, prepaid).
`CardDetail`	`String`	Determines the card usage (pin, signature etc.).
`DebitNetwork`	`String`	Debit Network/PINless value.
`DebitSignatureNetworkParticipant`	`String`	S = STAR Access.
`FSA`	`String`	FSA Indicator (Yes/No).
`PrepaidIndicator`	`String`	Prepaid Card (Yes/No).
`ProductID`	`String`	These values indicate card product sub categories (Purchase Card, Business Card, etc.) for Visa, MasterCard, and Discover.
`RegulatorIndicator`	`String`	Applies to US issued cards only (Visa, MasterCard, and Discover).
`CardClass`	`String`	Categorizes the BIN as a Business card, Corporate T&E card, Purchase card or Consumer card. Assists the POS device with prompting decisions – to collect addenda or not.

GET

/v2/bin-lookup/{BIN}

$ curl https://sandbox.seamlesspay.com/v2/bin-lookup/411111

Example Response

{
  "Bin": "411111",
  "IssuingBank": "Bank Name",
  "Country": "USA",
  "CardBrand": "Visa",
  "CardType": "Credit",
  "CardDetail": "True credit (No PIN/Signature capability).",
  "DebitNetwork": "ACCEL FISERV – Pinned POS",
  "DebitSignatureNetworkParticipant": "",
  "FSA": "No",
  "PrepaidIndicator": "No",
  "ProductID": "Visa Classic",
  "RegulatorIndicator": "N",
  "CardClass": "Consumer"
}

Overview

Authentication

Idempotent Requests

Stored Value

Test Cards

Creating a Gift Card

Example Request (JSON Schema)

Example Response

Delete a Gift Card

Example Request

Example Response

Get Card Info

Example Request (JSON Schema)

Example Response

Creating Gift Transactions

Example Request

Example Response

Example Response (Amount exceeds current value)

Cancelling a Transaction

Example Response (Cancelled transaction)

Get a Gift Transaction

Example Response

Listing Gift Transactions

Example Response

Querying Transactions

Equality

Example Request

Limit $limit

Example Request

Skip $skip

Example Request

Sort $sort

Example Request

Select $select

Example Request

In, Not In $in, $nin

Example Request

Less Than Range $lt, $lte

Example Request

Greater Than Range $gt, $gte

Example Request

Inequality $ne

Example Request

Or $or

Example Request

Status Codes

Example Error Responses

Bin Lookup

Example Response

Limit `$limit`

Skip `$skip`

Sort `$sort`

Select `$select`

In, Not In `$in`, `$nin`

Less Than Range `$lt`, `$lte`

Greater Than Range `$gt`, `$gte`

Inequality `$ne`

Or `$or`