How to Call API

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

1. 1. Request Header

Field Required Type Description
Authorization Mandatory string Used to validate request if legal or not. Please refer to "Authentication".
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)


2. 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".
Note: Conversant will send access credential for access key ID and access key secret to customer/partners who is going to call the APIs currently.
  • Authorization Header Format
Authorization:${signatureAlgorithm} ${accessKeyId}:${signature}


3. Signature Algorithm

  • Populate signing string
${HTTPMethod}+"\n"+${URI}+"\n"+${X-SFD-Date}+"\n"+${X-SFD-Nonce}+"\n"+${accessKeyId}+ "\n"+${requestBody}

e.g.

POST\n/v1.1/customer/1\n20180926T131000Z\n69527\V265i4K31j991E19\n
Note1: Request method should be converted to uppercase, e.g. GET
Note2: "\n" means 0x0A, LR.


  • 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);

4. 3. Example

4.1. 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

4.2. 3.2 Error Response Example

  • Error Response 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":"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":"AccessCredential.Invalid",
"message":"Access key id is not correct."
}
HTTP/1.1 401
{
"code":"Signature.NotMatch",
"message":"The request signature that we calculate does not match the signature that you provided."
}
© 2019 Conversant Solutions Pte Ltd. All rights reserved.            Updated 2019-04-01 15:55:40

results matching ""

    No results matching ""