How to Call API v2

This section is intended to describe how to call the SwiftFederation APIs.

1. Request Header

Field	Required	Type	Description
Authorization	Mandatory	string	Used to validate request if legal or not. Please refer to "Authentication v2".
Content-Type	Mandatory	string	Request content type. E.g. Content-Type: application/json; charset=utf-8
X-SFD-Date	Mandatory	string	Date of request. Format is yyyyMMdd'T'HHmmss'Z'. E.g. 20180328T173013Z. The difference between request date and server date can not exceed 1 hour.
X-SFD-Nonce	Mandatory	long	Random number. Recommend using 5 digits. (No longer than 18 digits)
X-SFD-Signature-Version	Mandatory	string	The version of the SwiftFederation signature protocol. Current version is 2.
X-SFD-*	Optional	string	The headers starting with 'X-SFD-' defined by service are optional. Different services might require other headers.

2. Authorization Signature Algorithm

Authorization Header Definition

Field	Description
signatureAlgorithm	Signature Algorithm. E.g. HMAC-SHA256
accessKeyId	Access key id that is assigned to customer to call APIs.
signature	Signature is the string which is signed based on request headers, request path, request method, access key ID and request body with access key secret. Please refer to Signature Algorithm v2.

Note: Customer or Partner can view access key ID and access key secret on SwiftFederation portal.

Authorization Header Format

Authorization:${signatureAlgorithm} ${accessKeyId}:${signature}

Signature Algorithm

Canonical header string

To create the canonical headers list, convert all header names to lowercase and remove leading spaces and trailing spaces. The following pseudocode describes how to construct the canonical list of headers:

CanonicalHeaders = ''

headers=()
headers.append('host')
for header in request.getHeaders():
  if header.startwith('x-sfd-'):
    headers.append(header)

for header in sort(lowercase(headers)):
  CanonicalHeaders += lowercase(header) + ':' + request.getHeader(header) + '\n'

Build the canonical headers list by sorting the (lowercase) headers by character code and then iterating through the header names. Construct each header according to the following rules:

Append the lowercase header name followed by a colon.
Append a comma-separated list of values for that header. Do not sort the values in headers that have multiple values.
Append a new line ('\n').

Note: You must include the host header at a minimum.

Canonical signing string

The signing string is assembled as below:

uppercase(${HTTPMethod})+"\n"+
${URI}+"\n"+
${CanonicalHeaders}+"\n"+
${accessKeyId}+ "\n"+
${requestBody}

Example Original headers

GET /v1.2/customer/1 HTTP/1.1
Host: base-api.swiftfederation.com

Authorization:HMAC-SHA256 V265i4K31j991E19:bc051d2e520a462e36455dc75b2bc68e9a135bbf4d2fefbf6d2fc1f28c5aa5dc
Content-Type:application/json; charset=utf-8
X-SFD-Date:20180926T131000Z
X-SFD-Nonce:69527
X-SFD-Signature-Version:2
X-SFD-FZone:SG

Example Canonical form request

GET\n
/v1.2/customer/1\n
host:base-api.swiftfederation.com\n
x-sfd-date:20180926T131000Z\n
x-sfd-fzone:SG\n
x-sfd-nonce:69527\n
x-sfd-signature-version:2\n

Note1: Request method should be converted to uppercase, e.g. GET.
Note2: "\n" means 0x0A, LR.
Note3: Put request parameter in ${requestBody} to do signature when http request method is 'GET'.

Generate Signature

Calculate signature of signing string by using HMAC-SHA256 algorithm with access key secret. And then use hex to encode signature to string.

byte[] signatureBytes = hmacSha256(${accessKeySecret}, ${signingString});

String signature = Hex.encodeHex(signatureBytes);

3. Example

3.1. Request Example

Request Example

GET /v1.1/customer/1 HTTP/1.1
Host: base-api.swiftfederation.com

Authorization:HMAC-SHA256 V265i4K31j991E19:bc051d2e520a462e36455dc75b2bc68e9a135bbf4d2fefbf6d2fc1f28c5aa5dc
Content-Type:application/json; charset=utf-8
X-SFD-Date:20180926T131000Z
X-SFD-Nonce:69527
X-SFD-Signature-Version:2

3.2. Error Response Example

Refer to Error Code Definition

HTTP/1.1 400
{
"code":"AccessKeyId.Invalid",
"message":"AccessKeyId is empty or invalid."
}

HTTP/1.1 400
{
"code":"AuthorizationFormat.Invalid",
"message":"Authorization format is invalid."
}

HTTP/1.1 400
{
"code":"Signature.Version.Invalid",
"message":"X-SFD-Signature-Version is not supported."
}

HTTP/1.1 400
{
"code":"Timestamp.Invalid",
"message":"X-SFD-Date is empty or invalid."
}

HTTP/1.1 400
{
"code":"Signature.Expired",
"message":"The value of X-SFD-Date should NOT be before current time 1 hour."
}

HTTP/1.1 400
{
"code":"Nonce.Invalid",
"message":"X-SFD-Nonce is empty or invalid."
}

HTTP/1.1 400
{
"code":"URI.Invalid",
"message":"URI is empty or invalid."
}

HTTP/1.1 400
{
"code":"Method.Invalid",
"message":"Method is empty or invalid."
}

HTTP/1.1 401
{
"code":"Signature.NotMatch",
"message":"The request signature that we calculate does not match the signature that you provided."
}

How to Call API(v2)