PaySpine API Doc v1

PaySpine Merchant Accounts made Easy Credit Cards · Debit Cards · eChecks · eWallet · eMoney We make it simple for you to do business online!

Merchant Acquiring

Whitelabel Solution

Introduction

This Gateway API is organized around REST.

Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors.

We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your secret API key in any public website’s client-side code).

JSON will be returned in all responses from the API, including errors.

To make the Gateway API as explorable as possible, accounts have test-mode API keys as well as live-mode API keys. These keys can be active at the same time.

Data created with test-mode credentials will never hit the credit card networks and will never cost anyone money

Authentication

You authenticate to the Gateway API by providing one of your API keys in the request. You can manage your API keys from your account. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!

Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

Authorization: Basic NWZiUnBoUWl1ZEVBTEZoVUM0QnEyTzBselBPT

Payment Processing API

The API all merchants should integrate

Server-2-Server Processing

Status code list:

Status Name Description
1 success succesful transaction
-1 rejected rejected transaction
2 pending pending state, payment will automatically be updated
0 unknown when an error occurs in the middle of the transaction and status of the transaction is unknown
POST https://payspine.com/v1/pay/?cc_num=4141414141414141&cc_exp_month=10&cc_exp_year=2017&amount=23.99&currency=USD&note=TXN-3402&firstname=Amy&lastname=Pennington&email=amy@pennington.net&telephone=8702487433&address=69 Arlington Avenue&country=US&city=Pocahontas&state=AR&birthday=19570731&zipcode=72343&client_ip=12.45.32.94
Requestsexample 1
Headers
Authorization: Basic NWZiUnBoUWl1ZEVBTEZoVUM0QnEyTzBselBPT
Responses201404
Headers
Content-Type: application/json
Body
{
  "transaction": 3922,
  "fees": 12.33,
  "amount": 325.5,
  "currency": "USD",
  "status": 1,
  "msg": "transaction accepted",
  "errors": "invalid ip address"
}
Schema
{
  "type": "object",
  "properties": {
    "transaction": {
      "type": "integer",
      "description": "unique transaction id"
    },
    "payment": {
      "type": "integer",
      "description": "unique payment id"
    },
    "fees": {
      "type": "float"
    },
    "amount": {
      "type": "float"
    },
    "currency": {
      "type": "ISO-4216"
    },
    "status": {
      "enum": [
        -1,
        0,
        1,
        2
      ]
    },
    "msg": {
      "type": "string",
      "description": "transaction status"
    },
    "errors": {
      "type": "string",
      "description": "only exists when status = -1"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "transaction": 3922,
  "fees": 12.33,
  "amount": 325.5,
  "currency": "USD",
  "status": -1,
  "msg": "transaction rejected",
  "errors": "insufficient balance"
}
Schema
{
  "type": "object",
  "properties": {
    "transaction": {
      "type": "integer",
      "description": "unique transaction id"
    },
    "payment": {
      "type": "integer",
      "description": "unique payment id"
    },
    "fees": {
      "type": "float"
    },
    "amount": {
      "type": "float"
    },
    "currency": {
      "type": "ISO-4216"
    },
    "status": {
      "enum": [
        -1,
        0,
        1,
        2
      ]
    },
    "msg": {
      "type": "string",
      "description": "transaction status"
    },
    "errors": {
      "type": "string",
      "description": "only exists when status = -1"
    }
  }
}

Server-2-Server
POST/pay/{?cc_num,cc_exp_month,cc_exp_year,amount,currency,note,firstname,lastname,email,telephone,address,country,city,state,birthday,zipcode,client_ip}

Debit the specified amount from the passed credit/debit card and transfert that amount into the merchant’s account

URI Parameters
HideShow
cc_num
integer (required) Example: 4141414141414141

credit card number

cc_exp_month
integrer between 01 and 12 (required) Example: 10

the card expiration month

cc_exp_year
4 digit integer (required) Example: 2017

the card expiration year

cc_cvv
3 digit integer (required) Example: 123

the control number on the back of the card

amount
float (required) Example: 23.99

Amount to debit from the card

currency
ISO-4216 (required) Example: USD

Currency to use

note
string (required) Example: TXN-3402

Merchant unique identifier for the transaction

firstname
string (required) Example: Amy

cardholder firstname

lastname
string (required) Example: Pennington

cardholder lastname

email
email (required) Example: amy@pennington.net

cardholder email address

telephone
integer (required) Example: 8702487433

cardholder telephone number

address
string (required) Example: 69 Arlington Avenue

cardholder billing address

country
ISO-3166 (required) Example: US

cardholder billing country

city
string (required) Example: Pocahontas

cardholder billing city

state
ISO-3166-2 (optional) Example: AR

if country is US cardholder billing state

birthday
YYYYMMDD (required) Example: 19570731

cardholder birth date

zipcode
string (required) Example: 72343

cardholder billing address zipcode

client_ip
string (required) Example: 12.45.32.94

client ip address


China Union Pay

POST https://payspine.com/v1/cup/?firstname=Amy&lastname=Pennington&email=amy@pennington.net&telephone=8702487433&address=69 Arlington Avenue&country=US&city=Pocahontas&state=AR&birthday=19570731&zipcode=72343&note=TXN-958383&currency=CNY&client_ip=12.43.28.21&callback_url=http:/merchant.co/callback&redirect_url=http:/merchant.co/thankyou
Requestsexample 1
Headers
Authorization: Basic NWZiUnBoUWl1ZEVBTEZoVUM0QnEyTzBselBPT
Responses201
Headers
Content-Type: application/json
Body
{
  "transaction": 3922,
  "amount": 325.5,
  "currency": "USD",
  "redirect_url": "https://chinabank.cn/payment"
}
Schema
{
  "type": "object",
  "properties": {
    "transaction": {
      "type": "integer",
      "description": "unique transaction id"
    },
    "payment": {
      "type": "integer",
      "description": "unique payment id"
    },
    "amount": {
      "type": "float"
    },
    "currency": {
      "type": "ISO-4216"
    },
    "redirect_url": {
      "type": "url",
      "description": "user should be redirected to this url to complete the payment"
    }
  }
}

Union Pay
POST/cup/{?firstname,lastname,email,telephone,address,country,city,state,birthday,zipcode,note,currency,client_ip,callback_url,redirect_url}

Process a China Union Pay dabit card. the user will be redirected to a bank selection page then to his bank’s online banking platform. the steps will varie with banks

URI Parameters
HideShow
firstname
string (required) Example: Amy

cardholder firstname

lastname
string (required) Example: Pennington

cardholder lastname

email
email (required) Example: amy@pennington.net

cardholder email address

telephone
integer (required) Example: 8702487433

cardholder telephone number

address
string (required) Example: 69 Arlington Avenue

cardholder billing address

country
ISO-3166 (required) Example: US

cardholder billing country

city
string (required) Example: Pocahontas

cardholder billing city

state
ISO-3166-2 (optional) Example: AR

if country is US cardholder billing state

birthday
YYYYMMDD (required) Example: 19570731

cardholder birth date

zipcode
string (required) Example: 72343

cardholder billing address zipcode

note
string (required) Example: TXN-958383

merchant tracker for this transaction

currency
string (required) Example: CNY

preferred currency

client_ip
ip address (required) Example: 12.43.28.21
callback_url
url (required) Example: http://merchant.co/callback

a URL where we can notify you of the payment status

redirect_url
url (required) Example: http://merchant.co/thankyou

a URL where the buyer is redirected to after the transaction is finalized


3D-Secure

POST https://payspine.com/v1/c3ds/?firstname=Amy&lastname=Pennington&email=amy@pennington.net&telephone=8702487433&address=69 Arlington Avenue&country=US&city=Pocahontas&state=AR&birthday=19570731&zipcode=72343&note=TXN-958383&currency=CNY&client_ip=12.43.28.21&callback_url=http:/merchant.co/callback&redirect_url=http:/merchant.co/thankyou
Requestsexample 1
Headers
Authorization: Basic NWZiUnBoUWl1ZEVBTEZoVUM0QnEyTzBselBPT
Responses201
Headers
Content-Type: application/json
Body
{
  "transaction": 3922,
  "amount": 325.5,
  "currency": "USD",
  "redirect_url": "https://3dsecure.bank123.com/pay"
}
Schema
{
  "type": "object",
  "properties": {
    "transaction": {
      "type": "integer",
      "description": "unique transaction id"
    },
    "payment": {
      "type": "integer",
      "description": "unique payment id"
    },
    "amount": {
      "type": "float"
    },
    "currency": {
      "type": "ISO-4216"
    },
    "redirect_url": {
      "type": "url",
      "description": "user should be redirected to this url to complete the payment"
    }
  }
}

3D-Secure
POST/c3ds/{?firstname,lastname,email,telephone,address,country,city,state,birthday,zipcode,note,currency,client_ip,callback_url,redirect_url}

the merchant will have to collect redirect_url and redirects his user to that URL

the URL will lead to a bank selection page where the user will have to choose his bank, then fill up the card info directly on his bank’s website then submit.

The user will then be redirected to the initially passed value redirect_url that should be a page on the merchant’s website informing the user of the transaction status (a page that keeps polling for the transaction status until the callback occurs)

After the transaction is completed, a callback occurs, and the informations will be POSTed to the previously passed callback_url

the parameters are detailed below

those are the parameters that our gateway will POST to the merchant’s server when a transaction is completed or timed out.

Parameter Type Example
transaction integer transaction id
payment integer payment id
note string TNX-406939
amount decimal 1534.99
currency string CNY
timestamp date 2023-06-18 16:50:52
URI Parameters
HideShow
firstname
string (required) Example: Amy

cardholder firstname

lastname
string (required) Example: Pennington

cardholder lastname

email
email (required) Example: amy@pennington.net

cardholder email address

telephone
integer (required) Example: 8702487433

cardholder telephone number

address
string (required) Example: 69 Arlington Avenue

cardholder billing address

country
ISO-3166 (required) Example: US

cardholder billing country

city
string (required) Example: Pocahontas

cardholder billing city

state
ISO-3166-2 (optional) Example: AR

if country is US cardholder billing state

birthday
YYYYMMDD (required) Example: 19570731

cardholder birth date

zipcode
string (required) Example: 72343

cardholder billing address zipcode

note
string (required) Example: TXN-958383

merchant tracker for this transaction

currency
string (required) Example: CNY

preferred currency

client_ip
ip address (required) Example: 12.43.28.21
callback_url
url (required) Example: http://merchant.co/callback

a URL where we can notify you of the payment status

redirect_url
url (required) Example: http://merchant.co/thankyou

a URL where the buyer is redirected to after the transaction is finalized


Refund

POST https://payspine.com/v1/refund/?payment_id=39442&amount=78.44&currency=USD&note=string
Requestsexample 1
Headers
Authorization: Basic NWZiUnBoUWl1ZEVBTEZoVUM0QnEyTzBselBPT
Responses201
Headers
Content-Type: application/json
Body
{
  "id": 3922,
  "payment_id": 123332,
  "transaction_id": 32550,
  "amount": 49.33,
  "currency": "USD",
  "status": 1
}
Schema
{
  "type": "object",
  "properties": {
    "transaction": {
      "type": "integer",
      "description": "unique transaction id"
    },
    "payment": {
      "type": "integer",
      "description": "unique payment id"
    },
    "fees": {
      "type": "float"
    },
    "amount": {
      "type": "float"
    },
    "currency": {
      "type": "ISO-4216"
    },
    "status": {
      "enum": [
        -1,
        0,
        1,
        2
      ]
    },
    "msg": {
      "type": "string",
      "description": "transaction status"
    },
    "errors": {
      "type": "string",
      "description": "only exists when status = -1"
    }
  }
}

Refund
POST/refund/{?payment_id,amount,currency,note}

URI Parameters
HideShow
payment_id
integer (required) Example: 39442

payment id given in the response of the original transaction

amount
float (required) Example: 78.44

amount of the original transaction

currency
currency (required) Example: USD

currency of the original transaction

note
string (required) Example: string

unique identifier for this refund transaction


Recurring Billing API

for automated recurring debit.

Subscribe

POST https://payspine.com/v1/rebill/?cc_num=4141414141414141&cc_exp_year=1985&cc_exp_month=10&amount=23.99&currency=USD&note=TXN-3402&firstname=Amy&lastname=Pennington&email=amy@pennington.net&telephone=8702487433&address=69 Arlington Avenue&country=US&city=Pocahontas&state=AR&birthday=19570731&zipcode=72343&callback_url=http:/merchant.com/callback/xyz123&period=daily&period_count=6&start_date=2015-03-02 09:41:25
Requestsexample 1
Headers
Authorization: Basic NWZiUnBoUWl1ZEVBTEZoVUM0QnEyTzBselBPT
Responses201
Headers
Content-Type: application/json
Body
{
  "id": 3922,
  "amount": 39.99,
  "currency": "USD",
  "period": "monthly",
  "period_count": 6,
  "status": 1
}
Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "unique recurring billing id subscription"
    },
    "status": {
      "enum": [
        -1,
        0,
        1
      ]
    },
    "amount": {
      "type": "float"
    },
    "currency": {
      "type": "ISO-4216"
    },
    "period": {
      "enum": [
        "daily",
        "weekly",
        "fortnightly",
        "monthly",
        "quarterly",
        "semi-annually"
      ]
    },
    "period_count": {
      "type": "integer",
      "description": "number of periods to be executed"
    }
  }
}

Subscribe
POST/rebill/{?cc_num,cc_exp_year,cc_exp_month,amount,currency,note,firstname,lastname,email,telephone,address,country,city,state,birthday,zipcode,callback_url,period,period_count,start_date}

URI Parameters
HideShow
cc_num
integer (required) Example: 4141414141414141

credit card number to enroll

cc_exp_month
integer between 01 and 12 (required) Example: 10

card expiration month

cc_exp_year
4 digit integer (required) Example: 1985

card expiration year

amount
float (required) Example: 23.99

Amount to debit from the card

currency
ISO-4216 (required) Example: USD

Currency to use

note
string (required) Example: TXN-3402

Merchant unique identifier for the transaction

firstname
string (required) Example: Amy

cardholder firstname

lastname
string (required) Example: Pennington

cardholder lastname

email
email (required) Example: amy@pennington.net

cardholder email address

telephone
integer (required) Example: 8702487433

cardholder telephone number

address
string (required) Example: 69 Arlington Avenue

cardholder billing address

country
ISO-3166 (required) Example: US

cardholder billing country

city
string (required) Example: Pocahontas

cardholder billing city

state
ISO-3166-2 (optional) Example: AR

if country is US cardholder billing state

birthday
YYYYMMDD (required) Example: 19570731

cardholder birth date

zipcode
string (required) Example: 72343

cardholder billing address zipcode

callback_url
url (required) Example: http://merchant.com/callback/xyz123

callback url hosted by the merchant to inform with the new automated transactions

period
string (optional) Default: daily Example: daily

period at what the card will be automatically charger

Choices: daily weekly fortnighly monthly quarterly semi-annually

period_count
integer (required) Example: 6

number of periods before expiration of this recurring billing

start_date
datetime (required) Example: 2015-03-02 09:41:25

the exact moment to start the billing cycle


Unsubscribe

DELETE https://payspine.com/v1/rebill/?id=45403
Requestsexample 1
Headers
Authorization: Basic NWZiUnBoUWl1ZEVBTEZoVUM0QnEyTzBselBPT
Responses201
Headers
Content-Type: application/json
Body
{
  "id": 3922,
  "amount": 39.99,
  "currency": "USD",
  "period": "monthly",
  "period_count": 6,
  "status": 1
}
Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "unique recurring billing id subscription"
    },
    "status": {
      "enum": [
        -1,
        0,
        1
      ]
    },
    "amount": {
      "type": "float"
    },
    "currency": {
      "type": "ISO-4216"
    },
    "period": {
      "enum": [
        "daily",
        "weekly",
        "fortnightly",
        "monthly",
        "quarterly",
        "semi-annually"
      ]
    },
    "period_count": {
      "type": "integer",
      "description": "number of periods to be executed"
    }
  }
}

Unsubscribe
DELETE/rebill/{?id}

URI Parameters
HideShow
id
integer (required) Example: 45403

rebilling id returned by this gateway as a reponse of a rebill subscription request


Merchant Notify

POST https://payspine.com/v1/merchant-callback-url/?id=493922&amount=54.99&currency=EUR&period=daily&note=TXN-4948&period_count=6&total_occurrences=3
Responses201
This response has no content.

Notify
POST/merchant-callback-url/{?id,amount,currency,period,note,period_count,total_occurrences}

The parameters are POSTed to the merchant’s server, via the callback URL that was passed during the rebilling request

The notification will be periodically sent until we receive a response 200 ok from the merchant

The merchant should make sure that the provided callback_url can receive and process the data via a POST request.

URI Parameters
HideShow
id
integer (required) Example: 493922

given recurring billing id during the rebill request

amount
float (required) Example: 54.99

the amount to debit from the card

currency
ISO-4216 (required) Example: EUR

transaction currency

period
string (optional) Default: daily Example: daily

period at what the card will be automatically charger

Choices: daily weekly fortnighly monthly quarterly semi-annually

note
string (required) Example: TXN-4948

previously passed note during the rebilling request

period_count
integer (required) Example: 6

number of periods before expiration of this recurring billing

total_occurrences
integer (required) Example: 3

how many times the billing happened


Merchant Tools API

if your contract is multi-tiered, you may want to know your current rates (elsewhere than in the dashboard) for this we’ve added the following endpoint

Tiers

GET https://payspine.com/v1/tools/tiers
Requestsexample 1
Headers
Authorization: Basic NWZiUnBoUWl1ZEVBTEZoVUM0QnEyTzBselBPT
Responses201
Headers
Content-Type: application/json
Body
{
"currency" : "USD",
"min_vol" : 1,
"max_vol" : 50,000,
"mdr_fee" : 1.5,
"mdr_rate": 8.5

}

Tiers
GET/tools/tiers


Generated by aglio on 06 Jul 2016