FastShift API Documentation

(1)

1

FastShift API Documentation

1. Logo

2. Documentation Release Updates

3. Fast Shift Information

Contents

Introduction ... 2

List of the calls ... 2

Get Site Payment List ... 3

Example of the request: ... 3

Example of Successful Response: ... 3

Example of Failed Response: ... 3

Get Site Payment ... 6

Example of a Request ... 6

Example of Successful Response: ... 7

Example of Failed Response: ... 9

Create Order ... 9 Response Types ... 10 Successful Response ... 11 Data Response ... 11 Iframe Response ... 12 Redirect Response ... 11 Failed Response... 12 Request Error... 12

Client Error Response ... 12

Callback Format ... 13

Appendix ... 13

Error Codes ... 13

(2)

2

Introduction

In order to connect to FastShift system and make payments through it, one needs to have access

to the merchant’s Client ID, Secret Key, and Site ID. These credentials are necessary for

authentication and verification of the calls.

All the requests to our system are required to be in application/json format. Responses and

callbacks from FastShift will be in that format either.

Requests to FastShift system can be made in either production or staging environment. Base URL:

Staging https://api-staging.fastshift.com

Production https://api.fastshift.com

Each request to the API endpoints needs to be authenticated with a Bearer type token. The calculation of the token is the following:

1. Concatenate Partner’s(merchant’s) Client ID, a dash(-), and Client Secret

2. Calculate the hash of the created string with algorithm SHA 256

Example:

String = ClientID-ClientSecret Token= hash (‘sha256’, String)

This token is required to be in the header of each request along with the merchant’s Client ID. curl -X POST

-H "Content-Type: application/json"

-H "Authorization: Bearer TokenGeneratedByHashingAlgorithm" -H "Client: ClientID given to the merchant

List of the calls

There are several calls that are required to be made in order to complete the final transaction.

Each of these calls has its own required parameters. First is the GetSitePaymentList call, which

provides all the necessary payments systems for the merchant’s SiteID. Then GetSitePayment

call will provide data for the particular payment, and with an optional parameter, it can provide client’s wallet information for the selected payment. The final call is CreateOrder for which it is

(3)

3 required to send all the FastShift required fields along with the payment specific fields that you get in the second call.

Get Site Payment List

Endpoint

: /v1/site_payment_systems

In order to make this call, one needs to make a GET request and to pass the merchant’s Site ID as a query parameter.

Example of the request:

curl -X GET “/v1/site_payment_systems?site_id={MerchantsSiteID}” -H "Content-Type: application/json"

Response for this request can be either successful data response or failed request error. The response format is json.

Example of Successful Response:

Status is 1 which means that the request was successful and Type is also 1 which means that this call just gives You data and there is no other information that needs to be sent by us on your IPN url. { "status": 1, "message": "ok", "data": { "type": 1, "data": { "deposit": [ { "id": 5270, "payment_name": "CreditCard", "payment_id": 76, "logo": "76.jpg", "countries": [ "IT", "ES", "US" ],

"description": "Credit Card desctipiton",

"fields": [

{

"name": "amount",

"type": "amount",

(4)

4 } ], "currencies": [ { "iso_code": "EUR", "max_limit": 20000, "min_limit": 15 }, { "iso_code": "CAD", "max_limit": 2000, "min_limit": 1 }, { "iso_code": "GBP", "max_limit": 1000, "min_limit": 1 } ] }, { "id": 6580, "payment_name": "Neteller", "payment_id": 77, "logo": "77.jpg", "countries": [ "US" ],

"description": "Neteller desctipiton",

"fields": [ { "name": "email", "label": "Email", "required": 1, "type": "text" }, { "name": "amount", "label": "Amount", "required": 1, "type": "number" }, { "name": "secure_id",

"label": "Secure ID",

"required": 1, "type": "text" } ], "currencies": [ { "iso_code": "EUR", "max_limit": 100, "min_limit": 1

(5)

5 } ] } ], "withdraw": [ { "id": 5270, "payment_name": "CreditCard", "payment_id": 76, "logo": "76.jpg", "countries": [ "IT", "ES", "US" ],

"description": "Credit Card desctipiton",

"fields": [ { "name": "amount", "type": "amount", "label": "Amount" }, { "name": "card_token", "type": "text",

"label": "Card token",

"required": 1 } ], "currencies": [ { "iso_code": "EUR", "max_limit": 20000, "min_limit": 15 } ] }, { "id": 6580, "payment_name": "Neteller", "payment_id": 77, "logo": "77.jpg", "countries": [ "US" ],

"description": "Neteller desctipiton",

"fields": [ { "name": "email", "label": "Email", "type": "text" }, { "name": "amount",

(6)

6 "label": "Amount", "type": "number" } ], "currencies": [ { "iso_code": "EUR", "max_limit": 100, "min_limit": 1 } ] } ] }, "meta": null } }

Example of Failed Response:

{ "status": 0, "error": { "code": "100", "message": "unauthorized_client" } }

Get Site Payment

Endpoint

: /v1/site_payment_systems/{

sitePaymentId

}

This request gives you all the information concerning a particular payment system. The Payment

System ID is taken from the GetSitePaymentList call. In the successful response, each payment

system has its own ID (in the above example 5207is the ID of the Creditcard payment system).

This call can be made with an additional query parameter client_id, which will allow get the specific client’s wallet information for that payment system. This client_id is user’s ID in partner’s database that is sent us in CreateOrder call.

Example of a Request

1.Without Client Info

curl -X GET “/v1/site_payment_systems/{sitePaymentId}” -H "Content-Type: application/json"

(7)

7 -H "Client: ClientID given to the merchant

2.With Client Info curl -X GET

“/v1/site_payment_systems/{sitePaymentId}?client_id={ID}” -H "Content-Type: application/json"

The Response for this call can be either Successful Data Response or Failed Request Error. The

Response is in json format.

Example of Successful Response:

Without Client Info

{ "status": 1, "message": "ok", "data": { "type": 1, "data": { "id": 2, "payment_id": 76, "payment_name": "CreditCard", "deposit_fields": [ { "name": "amount", "type": "amount", "label": "Amount", "options": [] } ], "withdraw_fields": [ { "name": "amount", "type": "amount", "label": "Amount", "options": [] }, { "name": "card_token", "type": "text",

"required": 1,

"options": []

}

],

(8)

8 "withdraw_description": "CreditCard.withdraw.description" }, "meta": null } }

With Client Info

{ "status": 1, "message": "ok", "data": { "type": 1, "data": { "id": 5207, "payment_id": 76, "payment_name": "CreditCard", "deposit_fields": [ { "name": "amount", "type": "amount", "label": "Amount", "options": [] } ], "withdraw_fields": [ { "name": "amount", "type": "amount", "label": "Amount", "options": [] }, { "name": "card_token", "type": "text",

"required": 1, "options": [ { "value": "i2kiA2ZPSCWp+T19SlXpwg==", "label": "************0007" }, { "value": "VZ4lOT3vQqSsOwAD1XpBjQ==", "label": "************4415" } ] } ], "deposit_description": "CreditCard.deposit.description", "withdraw_description": "CreditCard.withdraw.description" },

(9)

9

"meta": null

} }

In the above two responses, the difference is, that when the request is done with a valid client ID, the client’s wallet information of the specified payment is provided if that information is required for the payment’s transaction.

Example of Failed Response:

{ "status": 0, "error": { "code": "", "message": "unknown_site_payment_system" } }

Create Order

Endpoint

: /v1/create_order

With this request, the deposit or withdrawal transaction is created. There are parameters that are

required for reaching this API endpoint. Additional parameters that are required for the selected

payment system need to be sent in the formData array. All the parameters are required to be sent in json format.

Parameter Field Name Mandatory Description

site_id YES Merchant’s Site ID in our system

payment_id YES Selected Payment ID (Ex. 5207 is the ID of Credit

Card in the above example)

pay_way YES deposit/withdraw

client_id YES Client ID of the user in partners Database

internal_order_id YES The Transactions order ID, must be unique

success_url YES Redirection URL after Successful Transaction

cancel_url YES Redirection URL after Canceled Transaction

fail_url YES Redirection URL after Failed Transaction

(10)

10

country YES 2 letter Country Code

client_phone NO Client’s Phone Number

client_email YES Client’s valid email address

accept_language NO 2 letter language code

ip NO Client’s IP address

user_agent NO Client’s request agent

formData

amount YES Amount of the transaction

Other Payment specific parameters will be sent along with the amount field in the formData array.

Example of the request:

curl -X GET “

/v1/create_order

” -H "Content-Type: application/json"

-d “{ "site_id":"1", "payment_id":"5207", "country":"US", "currency":"EUR", "pay_way":"deposit", "client_id":"800", "internal_order_id":"125369", "success_url":"http://test.com/success", "cancel_url":"http://test.com/cancel", "fail_url":"http://test.com/fail", "client_email":"[email protected]", "formData":{"amount":"10000" } }”

For CreateOrder method, there are different responses available.

Response Types

FastShift system generates different responses for different requests.

1. If the request is correct but the data inputted by the user is wrong (parameters in

formData array), the system will give a Client Error Response.

2. If the request has some error and it is not the client’s fault (something is invalid in the

(11)

11

3. If both client input parameters and main request parameters are correct, the system will

give a Successful Response, which can be in 3 different ways:

 The response is successful and this is the final stage of the request. This response

provides information about transaction’s final status or gives some requested data.

 Second Successful Response is Redirect Response, where a redirection url is given in

the response, and the user needs to be redirected to that url. After the completion of the transaction a callback will be sent to the payment’s callback url.

 Third type of the Successful response is the Iframe Response. Once an Iframe

Response is given, an iframe needs to be opened and the final status of the transaction will be sent to the callback of the url for the payment.

Successful Response

Data Response Example

When the type parameter in the response data is 1, it means it is a Data response. It is considered successful when the “status” parameter is 1, the “message” parameter is “ok”.

{ "status": 1, "message": "ok", "data": { "type": 1, "data": {…} }

Redirect Response Example

When the type parameter in the response data is 2, it means it is a Redirect response. It is considered successful when the “status” parameter is 1, the “message” parameter is “ok” and there is a valid url in the data parameter.

{ "status": 1, "message": "ok", "data": { "type": 2, "data": { "method": "GET", "url": "http://checkout.fastshift.loc/merchant/1/deposit/188?SID=7536c2 72b99328a5f602c3e6b66c781080ec2a4bcfb2dc82d4868433322995b3", "target": "_blank", "fields": [] } } }

(12)

12 Iframe Response Example

When the type parameter in the response data is 3, it means it is an Iframe response. It is considered successful when the “status” parameter is 1, the “message” parameter is “ok” and there is a valid url in the data parameter.

{ "status": 1, "message": "ok", "data": { "type": 3, "data": { "method": "GET", "url": "http://checkout.fastshift.loc/merchant/1/deposit/188?SID=7536c2 72b99328a5f602c3e6b66c781080ec2a4bcfb2dc82d4868433322995b3", "target": "_blank", "fields": [] } } } Failed Response Request Error Example

When there is an error in the request, that is, one of the required parameters is missing and/or is invalid then a request error is given. The status of the request error is 0.

{ "status": 0, "error": { "code": "100", "message": "country_not_selected" } }

Client Error Response Example

When there is an error or invalid parameter in the data that was inputted by the client, then the client error response is given. In this case the status will be 1, but the type parameter in the data is 0. { "status": 1, "message": "ok", "data": { "type": 0, "error": "amount_exceeds_the_max_available_limit",

FastShift API Documentation