Introduction
This documentation describes the acquiring REST API and resources provided by RS2. The API is designed in accordance with the JSON:API Specification. Various resources are presented which can be used to cover a variety of use cases.
How to use this document
This document is made up into the following two main sections:
The first part from the left side bar contains generic information on the JSON:API specification on which this API is based on, the API Schema documentation describing each resource and endpoint in detail and the Errors section. These sections are generic and can be used as a technical reference during API integration in order to find information about attributes, their data types, supported resource relationships and other technical specifications.
The second part describes in detail various use cases and indicate the flow and sequence of requests required to fulfil a particular task. Request and response examples are provided in each use case.
Version
This documentation represents version 1.171.46464+1.432bd702 (rel-171) of the RS2 Acquiring API API generated on Thu 24 Apr 2025 13:18:04 UTC
JSON:API
The Acquiring API API is mostly based on the JSON:API v1.0 specification. All JSON:API resources are marked as such in the API Schema documentation by having their type set to JSON:API Resource while non-JSON:API JSON objects are marked as JSON Object. JSON:API resources benefit from all the functionality as per the specification such as inclusion of related resources in response body, specifying in requests which fields to return in order to minimize message data, sorting, pagination and filtering. For a full and detailed list of JSON:API functionality, please refer to the official JSON:API documentation @ https://jsonapi.org/format/1.0.
Resources
Resources represent specific BankWORKS items of data. Resources can be interacted with using the following HTTP methods. For resource HTTP method support please refer to the API schema section of this document.
- GET: Resource retrieval
- POST: Creation of a new resource of a given type.
- PATCH: Modification of a resource. The resource ID must be specified in the URL.
- DELETE: Deletion of a resource. The resource ID must be specified in the URL.
Anatomy of a resource:
- id: unique identifier
- type: Type of resource
- attributes: Properties of a resource
- relationships: Relationships between the resource and other JSON API resources
- links: Links to the related resource
- meta: Non standard meta-information about a resource not representable as an attribute or relationship
Resource relationships
Relationships allow resources to be linked together. Relationships also allow other features such as filtering and resource inclusion to be used in context of the related resource. Please refer to the below sections for more information on resource inclusion and filtering.
GET /merchants/clientNumber=10050000/addresses
The above example returns the addresses resources linked to a particular merchant.
Resource Inclusion (compound documents)
Resource inclusion allows multiple related resources to be included in a single response. The url parameter include as shown in the below examples:
GET /merchants?include=addresses,contracts
In the above example the addresses and contracts are returned in the response.
The dot notation can be used to include related resources in the response
GET /merchants/clientNumber=12345678?include=contracts.accounts
When using the include feature, the response would contain the relationship information between the main resource and the included resource as well as the resources included in the included object as shown in the below snippit.
{
"data": [
{
"id": "clientNumber=10050000",
"type": "merchants",
"attributes": {
...
}
}
],
"relationships": {
"addresses": {
"data": [
{
"id": "clientNumber=00000105&addressCategory=001&effectiveDate=2024-06-06",
"type": "addresses"
},
{
"id": "clientNumber=00000105&addressCategory=006&effectiveDate=2024-06-06",
"type": "addresses"
}
]
}
},
"included": [
{
"id": "clientNumber=00000105&addressCategory=001&effectiveDate=2024-06-06",
"type": "addresses",
"attributes": {
"addressLine1": "Standard Address",
"addressLine2": "150, Fifth Avenue",
"city": "New York",
"postCode": "10011",
}
},
{
"id": "clientNumber=00000105&addressCategory=006&effectiveDate=2024-06-06",
"type": "addresses",
"attributes": {
"addressLine1": "Another Standard Address",
"addressLine2": "150, Fifth Avenue",
"city": "New York",
"postCode": "10011",
}
}
]
}
Filtering
Filtering allows a response to return a subset of the available resources that match the criteria requested. The full format of the filter operator is as follows:
filter [resource type] [attribute / attribute path][operator]=value
For example: &filter[payments][paymentDate][LE]=2023-04-14
Available filtering operators:
| Operator | Description |
|---|---|
| EQ | Equals operator where values match exactly |
| NEQ | Not equals where values do not match |
| LIKE | Where the values matches the specified pattern. It is usually not case-sensitive and makes use of % as wildcard, but
may different depending on the underlying implementation Note: The % character should be URL encoded %25 |
| LT | Lower than the specified value |
| LE | Lower than or equal to the specified value |
| GT | Greater than the specified value |
| GE | Greater than or equal to the specified value |
Example: Filtering by attribute
The first example is a simple attribute filter.
GET /merchants?filter[companyName][EQ]=ANA
The second example filters on a nested object's attribute and an additional attribute (multi-attribute filtering).
GET /merchants?filter[mainContactDetails.contactName][LIKE]=%25Smith&filter[status][EQ]=001
Example: Filtering a resource collection by a nested relationship property
Note: the optional resource type [merchants] is provided to indicate that the merchants resource is to be filtered by the country attribute of it's addresses relationship. The result would have been the same without the [merchants] and [EQ] operators.
GET /merchants?filter[merchants][addresses.country][EQ]=MLT
Sparse Fieldsets
Response attributes can be minified to avoid returning any necessary resource attributes. The fields url parameter is used for this purpose and can be applied to the main resource being requested as well any included resources. In case of multiple resource types being returned, the resource type should be indicated with the sorting as shown in the below example:
GET /merchants/clientNumber=10050000?include=addresses&fields[merchants]=clientNumber,status,tradeName&fields[addresses]=postCode,state,country
The response would contain the ID's of the resources being included as well as the resources included. Refer to the compound documents section for an example.
Sorting
The resource response may be sorted by a number of attributes in ascending or descending order. In the below examples a list of payments with a paymentDate value that fits within a particular date range is returned sorted by clientNumber in ascending order and paymentDate in reverse chronological order (notice the - sign)
The sort url parameter is used to indicate sorting.
GET /payments?filter[payments][paymentDate][GE]=2023-04-10&filter[payments][paymentDate][LE]=2023-04-14&sort=clientNumber,-paymentDate
Pagination
Pagination allows control over the number of resources returned in the response per page. If no pagination is set, the default is 20 resources per page. The page[offset] (to skip a number of resources, 0 being the first resource) and page[limit] (the number of resources to be returned per page).
The respons includes links to the other pages:
- first: First page of data
- last: Last page of data
- prev: Previous page of data
- next: Next page of data
Simple example to return a single resource per page:
GET /merchants?page[limit]=1
{
"data": [
{
"id": "clientNumber=10050000",
"type": "merchants",
"attributes": {
...
}
}
],
"links": {
"first": "/wsm/jsonapi/merchants?page[limit]=1",
"last": "/wsm/jsonapi/merchants?page[limit]=1&page[offset]=3",
"next": "/wsm/jsonapi/merchants?page[limit]=1&page[offset]=1"
},
"meta": {
"totalResourceCount": 4
}
}
Below is a slightly more complex example which returns the contract records belonging to a merchant using the merchant → contracts relationship. In addition the a list of records effective as of the current posting date are returned sorted in reverse chronological order and a page limit of 1 resource per is assigned. Such an example is a way of returning the current effective record out of a collection having the effectiveDate attribute.
GET /merchants/clientNumber=10050002/contracts?filter[effectiveDate][LE]=2024-06-06&sort=-effectiveDate&page[limit]=1
API Schema
The below is a list of endpoints and resources used by the API.
/oauth2/token
Format: JSON Object
/oauth2/logout
Format: JSON Object
/api/user-management/userpassword
Format: JSON Object
/accountBalanceTransfers
Format: JSON:API Resource
/accountDefinitions
Format: JSON:API Resource
/accountFeeDefinitions
Format: JSON:API Resource
/accounts
Format: JSON:API Resource
/addresses
Format: JSON:API Resource
/authorisations
Format: JSON:API Resource
/authorisationsAddendum
Format: JSON:API Resource
/balanceCycles
Format: JSON:API Resource
/billingCycleDefinitions
Format: JSON:API Resource
/brokers
Format: JSON:API Resource
/cardSchemeAddendum
Format: JSON:API Resource
/chargeRules
Format: JSON:API Resource
/clientMappings
Format: JSON:API Resource
/clientReferences
Format: JSON:API Resource
/clientRelations
Format: JSON:API Resource
/clientTariffDefinitions
Format: JSON:API Resource
/clientTariffTemplates
Format: JSON:API Resource
/clientTariffRules
Format: JSON:API Resource
/contractDefinitions
Format: JSON:API Resource
/contracts
Format: JSON:API Resource
/devices
Format: JSON:API Resource
/deviceFeeDefinitions
Format: JSON:API Resource
/disputeCases
Format: JSON:API Resource
/disputeCaseActions
Format: JSON:API Resource
/disputeCaseHistory
Format: JSON:API Resource
/feeRules
Format: JSON:API Resource
/fundingClients
Format: JSON:API Resource
/kycClients
Format: JSON:API Resource
/mandateInformation
Format: JSON:API Resource
/merchants
Format: JSON:API Resource
/merchantsAddendum
Format: JSON:API Resource
/merchantsAddendumUsa
Format: JSON:API Resource
/merchantsAddendumColombia
Format: JSON:API Resource
/merchantClientTariffs
Format: JSON:API Resource
/merchantTaxStatus
Format: JSON:API Resource
/merchantTransactionTariffs
Format: JSON:API Resource
/merchantVelocityParameters
Format: JSON:API Resource
/miscellaneousBatches
Format: JSON:API Resource
/miscellaneousBatchSlips
Format: JSON:API Resource
/payments
Format: JSON:API Resource
/paymentRejects
Format: JSON:API Resource
/paymentRejectSundries
Format: JSON:API Resource
/paymentInstructions
Format: JSON:API Resource
/postingDate
Format: JSON:API Resource
/presentments
Format: JSON:API Resource
/productChargeDefinitions
Format: JSON:API Resource
/riskRuleParameters
Format: JSON:API Resource
/rs2HostAuthorisations
Format: JSON:API Resource
/serviceDefinitions
Format: JSON:API Resource
/serviceFeeDefinitions
Format: JSON:API Resource
/services
Format: JSON:API Resource
/settlementPackages
Format: JSON:API Resource
/settlementSchemes
Format: JSON:API Resource
/transferInstructions
Format: JSON:API Resource
/transactionTariffDefinitions
Format: JSON:API Resource
/transactionTariffRules
Format: JSON:API Resource
/transactionTariffTemplates
Format: JSON:API Resource
Errors
API errors are identified by their response HTTP status codes. The below is a list of error codes that can be returned by the API:
| HTTP Code | Description |
|---|---|
| 400 |
Bad Request - Your request is invalid. Examples of bad requests are:
|
| 401 | Unauthorized - Invalid values in either the Authorization header or the refresh_token in body. This can be caused due to expirted tokens or invalid credentials. |
| 403 |
Forbidden - You do not have access rights to the content or to perform an action. Examples of forbidden requests are:
|
| 404 | Not Found - Requested resource does not exists. |
Resource Errors List
Refer to the errors list for a list of errors that can be returned by each resource. In case the error list is not available, kindly ask whoever provided this documentation to send it to you separately.
400 - Bad Request
Example:
{
"errors": [
{
"status": "400",
"title": "BAD_REQUEST",
"detail": "A non-numeric value cannot be used in a range filter"
}
]
}
Below is a detailed list of HTTP 400 - Bad Request errors that can be returned by the API.
| Detail | Error Description |
|---|---|
| Filters on the primary resource are not supported when performing a Find One Request | Filtering should not be applied when sending a GET request on a specific resource. |
| This value is not supported with the <filter_operator_used> operator | Invalid value used for performing a the requested filter operation. |
| Different values for attributes required to have the same value were inputted. | The same attribute was provided with different values in the request body. Please ensure that no duplicate attributes are sent. |
| Invalid filtering value passed | An invalid value was passed to a filtering request. |
| Invalid value passed for <id_field> in id | The resource ID contains an invalid value. This could be related to a data issue. |
| Invalid ID <id> | Invalid ID value passed, please ensure a correct ID format is provided. Resource ID’s are provided in response to GET and POST requests. |
| Only the EQ operator can be used when filtering with the id. | Filtering should not be applied when sending a GET request on a specific resource. |
| Value provided in the filter is not correct | An incorrect value was passed to one of the query parameters. |
| Attribute <attribute_name> exceeded the range of <range_limit> in the filter. | The filter provided exceeds the maximum allowed range amount. Please limit filter range to the range limit indicated. |
| One of the following attributes must be used in the filters: <attribute_name> | Get request requires mandatory filtering by the attributes indicated in the error message. |
| Attribute <attribute_name> cannot be used in an expression having NOT as its operator | NOT operator cannot be used for filtering the attribute, please use a different filtering operator. |
| Operator <operator_used> is not supported with attribute <attribute_name>. Please use any of the following operators: EQ / LT/ LE / GT/ GE | The operator used in the filtering is not supported. Please ensure the correct filtering operator is used. |
| Attribute <attribute_name> and operator <operator_used> can only be used once in a single expression | Invalid filter range. Multiple instances of the same operator on the same attribute were used. |
| Attribute <attribute_name> with operator <operator_used> must have a corresponding filter with GT/GE in a single expression | Invalid filter range operators used. When filter range is mandatory, for example date filter, a range with LT/LE and GT/GE must be supplied. |
| Attribute <attribute_name> with operator <operator_used> must have a corresponding filter with LT/LE in a single expression | Invalid filter range operators used.. When filter range is mandatory, for example date filter, a range with LT/LE and GT/GE must be supplied. |
| A non-numeric value cannot be used in a range filter | Invalid value provided in a range filter. Please ensure a numeric range is supplied. |
401 - Unauthorized
Example:
{
"errors": [
{
"status": "401",
"title": "UNAUTHORIZED",
"detail": "User not authenticated"
}
]
}
Below is a detailed list of HTTP 401 - Unauthorized errors that can be returned by the API.
| Detail | Error Description |
|---|---|
| User not authenticated | Ensure that a valid token is supplied for the user. |
| Full authentication is required to access this resource | Ensure that a valid token is supplied in the request. |
403 - Forbidden
Example:
{
"errors": [
{
"status": "403",
"title": "FORBIDDEN",
"detail": "Method Not Supported!"
}
]
}
Below is a detailed list of HTTP 403 - Forbidden errors that can be returned by the API.
| Detail | Error Description |
|---|---|
| Method Not Supported! | The HTTP method requested is not supported for the given resource or relationship. Please refer to the API Schema documentation for more information on the methods supported. |
404 - Not Found
Example:
{
"errors": [
{
"status": "404",
"title": "Record not found!",
"detail": "Record not found!"
}
]
}
Below is a detailed list of HTTP 404 - Not Found errors that can be returned by the API.
| Detail | Error Description |
|---|---|
| Record not found! | DELETE request did not find a record based on the resource ID provided. |
422 - Unprocessable Entity
Below is a detailed list of HTTP 422 - Unprocessable Entity errors that can be returned by the API.
| Detail | Error Description |
|---|---|
| May not be empty | Indicated field in the pointer cannot be null. |
| Not a valid value | An invalid attribute value was provided. Please review the attribute documentation for more information on acceptable values and format. |
| Length must be between <min-value> and <max-value> | Indicated field length in the pointer is not between |
| Must match <regex pattern> | The value provided for the attribute indicated in the pointer does not pass the regex validation. Please ensure the value passed is valid. |
| Not a well-formed email address | The value provided for the attribute indicated in the pointer is not a valid email address. Please ensure the value passed is a valid email address. |
| Both value and currency must be passed | The value provided for the attribute indicated in the pointer is not a valid monetary amount. Please ensure that both the value and currency are provided. |
| Value must match one of the values in the list | The value provided for the attribute indicated in the pointer must be one of the values in the list. Please review the attribute documentation for more information on acceptable values. |
Authentication
Authentication is based on OAuth2. In order to perform any API request, you need to first obtain a valid access token. This needs to be included as an Authorization header in each subsequent request. Note that the access token has a limited lifespan and would need to be refreshed if it expires. This is possible by using the refresh token in order to obtain a new valid access token.
Please contact our help desk if you need a set of credentials to access the APIs.
Access Token
To request an access token, provide the base64 encoded value of username:password in the Authorization header (eg. Basic dXNlcm5hbWU6cGFzc3dvcmQ=) with a grant_type key set to ‘client_credentials’ in the x-www-form-urlencoded body. As an example of how to get and manage tokens, please refer to the below simple pseudo-code.
func getAccessToken (string loginname) {
get accessTokenObject from session
// eg. taking into consideration 5 seconds grace time to cater for possible latency / network slowdowns
if (now + 5 seconds) > accessTokenObject.timeoutTime; {
accessTokenObject = call refreshToken(loginName, accessTokenObject.refreshToken)
update accessTokenObject in session
}
return accessTokenObject.accessToken
}
Request
POST https://wsmdemo.rs2.com/wsm/oauth2/token
Request Headers
| Authorization | {{authorizationHeader}} |
|---|
Request Body
An object of type oauth2/token with the following attributes:
| Name | Description | |
|---|---|---|
|
grant_type
string
required
|
The OAuth2 grant type. The value should always be either ‘client_credentials’. |
|
Response
HTTP 200 (OK)
Response body will contain the created object of type oauth2/token .
Refresh Token
To refresh an access token, provide the base64 encoded value of username: preceeded by Basic in the Authorization header (eg. Basic dXNlcm5hbWU6) along with the grant_type set to _refreshtoken and the value of the refresh_token in the x-www-form-urlencoded body.
Request
POST https://wsmdemo.rs2.com/wsm/oauth2/token
Request Headers
| Authorization | {{authorizationHeader}} |
|---|
Request Body
An object of type oauth2/token with the following attributes:
| Name | Description | |
|---|---|---|
|
refresh_token
string
required
|
The value of the refresh token that is used to obtain a new access token after it has expired. |
|
|
grant_type
string
required
|
The OAuth2 grant type. The value should always be either ‘refresh_token’. |
|
Response
HTTP 200 (OK)
Response body will contain the created object of type oauth2/token .
Change User Password
Updates user’s password, providing the new password in the request body.
Request
PUT https://wsmdemo.rs2.com/wsm/api/user-management/userpassword
Request Headers
| Content-Type | application/json |
|---|---|
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
Request Body
An object of type api/user-management/userpassword with the following attributes:
| Name | Description | |
|---|---|---|
|
newPassword
string
required
|
The new password for the user represented in the access token request from Authorization header. The new password must meet the following requirements for security:
|
|
Response
HTTP 200 (OK)
Logout - Revoke Access Token
This request will invalidate the access token associated with the request. This should be used whenever the requested token is not required anymore for security credentials clean up.
Request
POST https://wsmdemo.rs2.com/wsm/oauth2/logout
Request Headers
| Content-Type | application/x-www-form-urlencoded |
|---|---|
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
Request Body
An object of type oauth2/logout with the following attributes:
| Name | Description | |
|---|---|---|
|
no-content
|
||
Response
HTTP 200 (OK)
Response body will contain the created object of type oauth2/logout .
Service Contract Definitions
This section provides example use cases related to the retrieval of business setup rules linked to a service contract. In BankWORKS, a service contract is the main grouping of accounts, serivices, fee and charge setup that can be assigned to a merchant.
Merchants are limited to the accounts and services offerred within the service contract assigned. The use cases covered here reflect the actual service contract setup and does not include any merchant specific information. That will be covered in a dedicated Client Information section.
The requests provided are intended to serve as examples for retrieval of such data. Our API provides more flexibility, allowing additional filtering to be applied or even the inclusion of multiple related resources in a single request.
Contract Fees & Charges Rules
This section provides request samples for the retrieval of contract based fees & charges setup. Any individual merchant fee setup would be handled in the client information section.
Service Fees
Services fees are periodical fees that can be generated by BankWORKS for merchant billing of any non-acquiring, miscellaneous services assigned. These are grouped by service contract and also by client tariff. In addition, services fees can be contract-based (part of the service contract) or else individual merchant overrides. This means that a merchant may only have a specific overrides of available contract based fees.
This example request is intended for the retrieval of all contract based service fees linked to a particular service contract regardless of the clientTariff. In some cases, such as client boarding, it would be necessary to include additional filters such as the clientTariff.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/serviceFeeDefinitions?filter[serviceContractId]=100&filter[isContractFee]=true&sort=serviceContractId,clientTariff
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[serviceContractId] | 100 |
|---|---|
| filter[isContractFee] | true |
| sort | serviceContractId,clientTariff |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type serviceFeeDefinitions .
Device Fees
Retrieve all available contract based device fees. Device are quite similar to service fees, grouped by service contract and client tariff. Device fees are also split into contract-based and individual overrides. This request focuses on contract based fees. Individual ovverrides which would apply to a single terminal are covered in the devices section of this document.
The below request example will retrieve all the availble contract based devices linked to a serviceDefinitions resource.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/deviceFeeDefinitions?filter[isContractFee]=true&filter[serviceDefinitions.id]=serviceId=500%26serviceContractId=100%26cardBrand=000%26cardOrganization=000%26serviceType=999%26effectiveDate=2020-04-01&sort=clientTariff,-effectiveDate
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[isContractFee] | true |
|---|---|
| filter[serviceDefinitions.id] | serviceId=500%26serviceContractId=100%26cardBrand=000%26cardOrganization=000%26serviceType=999%26effectiveDate=2020-04-01 |
| sort | clientTariff,-effectiveDate |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type deviceFeeDefinitions .
Product Charges
Product charges are transaction charge rules for acquiring services. Product charges are grouped by service contract and by clientTariff. In addition, product charges can be contract based, part of the service contract structure, or merchant specific (for bespoke merchant transaction charge pricing). The below request example retrieves all the CONTRACT based rules linke dto a particular service contract sorted by tariff. Merchants can be assigned charges by tariff which can either be at contract level, merchantTranTariff or client services level, clientTariff.
For certain use cases including merchant boarding it would be necessary to filter by clientTariff in order to drill down the list further.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/productChargeDefinitions?filter[serviceContractId]=100&filter[isContractFee]=true&sort=serviceContractId,clientTariff
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[serviceContractId] | 100 |
|---|---|
| filter[isContractFee] | true |
| sort | serviceContractId,clientTariff |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type productChargeDefinitions .
Account Fees
Account fees are periodical fees that can be generated by BankWORKS for merchant billing of any account types assigned. These are grouped by service contract and client tariff. In addition, account fees can be contract-based (part of the service contract) or else individual specific merchant overrides of a contract based fee. This means that a merchant may only have a specific overrides of available contract based fees.
This example request is intended for the retrieval of all contract based account fees linked to a particular service contract regardless of the clientTariff. In some cases, such as client boarding, it would be necessary to include additional filters such as the clientTariff.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/accountFeeDefinitions?filter[serviceContractId]=100&filter[isContractFee]=true&sort=serviceContractId,clientTariff
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[serviceContractId] | 100 |
|---|---|
| filter[isContractFee] | true |
| sort | serviceContractId,clientTariff |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type accountFeeDefinitions .
Account Type Definitions
An account type definition represents an individual combination of an account type (such as payment account) with a currency. These account types are grouped by service contractDefinitions. This request example returns all the available accountDefinitions linked to a single service contract and sorted by accountTypeId and accountCurrency values. Additional filtering may also be added in order to return the desired subset of accounts available.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contractDefinitions/serviceContractId=113/accountDefinitions?sort=accountTypeId,accountCurrency
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| sort | accountTypeId,accountCurrency |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type accountDefinitions .
Merchant Contract Definitions
This call will get/retrieve the list of available pre-defined client contract definitions in BankWorks. The list of definitions in the response could be used by any third-party vendor or partners for selection of service contracts available via their user interface.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contractDefinitions?filter[contractType]=002
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[contractType] | 002 |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type contractDefinitions .
Device Service Definitions
A device service definition represents the a service blueprint for a merchant device. Multiple device services may be available representing the various device types on offer. In order for a merchant to be assigned a device, the merchant must have the device service asssigned in services.
This request provides an example of how device services can be retrieved from the serviceDefinitions resource. Device services can be defined at member level. The serviceDefinitions resource also has an effectiveDate which indicates when the rule comes into effect. This needs to be updated according to the use case being covered, usually replaced with the current date. In addition to the filtering, the result is sorted by serviceId and effectiveDate in reverse chronological order.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contractDefinitions/serviceContractId=113/serviceDefinitions?filter[serviceBeneficiary]=001&filter[effectiveDate][LE]=2020-04-01&sort=serviceId,-effectiveDate
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[serviceCategory] | 022 |
|---|---|
| filter[serviceBeneficiary] | 001 |
| filter[effectiveDate][LE] | 2020-04-01 |
| sort | serviceId,-effectiveDate |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type serviceDefinitions .
Broker Contract Definitions
This call will get/retrieve the list of available broker service contracts.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contractDefinitions?filter[contractType]=009
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[contractType] | 009 |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type contractDefinitions .
Misc Service Definitions
Miscellaneous services represent any non device or card acquiring services on offer that certain merchants may need to be assigned for billing purposes.
This request provides an example of how such miscellaneous services can be retrieved from the serviceDefinitions resource. The serviceDefinitions resource also has an effectiveDate which indicates when the rule comes into effect. This needs to be updated according to the use case being covered, usually replaced with the current date. In addition to the filtering, the result is sorted by serviceId and effectiveDate in reverse chronological order.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contractDefinitions/serviceContractId=113/serviceDefinitions?filter[serviceCategory][NEQ]=001,002,005,022&filter[serviceBeneficiary]=001&filter[effectiveDate][LE]=2020-04-01&sort=serviceId,-effectiveDate
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[serviceCategory][NEQ] | 001,002,005,022 |
|---|---|
| filter[serviceBeneficiary] | 001 |
| filter[effectiveDate][LE] | 2020-04-01 |
| sort | serviceId,-effectiveDate |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type serviceDefinitions .
Acquiring Service Definitions
An acquiring service defines the card brand(s) that can be acquired by merchants.
This request provides an example of how acquiring services can be retrieved from the serviceDefinitions resource. Acquiring services can be defined at member level and multiple resources may exist for a single service ID. This is mainly because an individual service ID can be composed of multiple cardOrganization, cardBrand setup lines. The serviceDefinitions resource also has an effectiveDate which indicates when the rule comes into effect. This needs to be updated according to the use case being covered, usually replaced with the current date. In addition to the filtering, the result is sorted by serviceId, cardOrganization, cardBrand and effectiveDate in reverse chronological order.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contractDefinitions/serviceContractId=113/serviceDefinitions?filter[serviceCategory]=002&filter[serviceBeneficiary]=001&filter[effectiveDate][LE]=2020-04-01&sort=serviceId,cardOrganization,cardBrand,-effectiveDate
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[serviceCategory] | 002 |
|---|---|
| filter[serviceBeneficiary] | 001 |
| filter[effectiveDate][LE] | 2020-04-01 |
| sort | serviceId,cardOrganization,cardBrand,-effectiveDate |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type serviceDefinitions .
Settlement Schemes
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/settlementSchemes?filter[settlementMethod]=077&filter[settlementCategory]=203&filter[clearingChannel]=718&filter[serviceContractId]=051&include=contracts
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[settlementMethod] | 077 |
|---|---|
| filter[settlementCategory] | 203 |
| filter[clearingChannel] | 718 |
| filter[serviceContractId] | 051 |
| include | contracts |
Response
Settlement Schemes : HTTP 200 (OK)
Settlement Schemes : HTTP 200 (OK)
Settlement Schemes : HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type settlementSchemes with contractsas included resources.
Merchant Boarding
Merchant Onboarding
This collection will cover the sequential calls for merchant boarding. Merchants can be boarded as standalone merchants or under a parent client, part of a billing and settlement hierarchy.
A top-down approach must be followed when boarding a new merchant hierarchy. This means that merchants would need to be defined as follows:
Group client - top level merchant creation, followed by
Sub-Group - a sub-group merchant resides at any level as long as it sits between a group and a member level merchant. A hierarchy can contain any number of sub-group level merchants.
Member client - The bottom level (leaf node) of the hierarchy, also referred to as the MID level or outlet level. In BankWORKS trasactions are acquired at this level.
Each merchant, requires a number of resources to be defined. For example a merchant will require a contract, multiple addresses, accounts, services among other resources. The requests in this section provide information on all resources that can be defined at merchant boarding stage. The approach taken, groups a number of requests based on their dependency. In summary:
The merchant is defined first
Any resource linked directly to the merchant is defined in the subsequent request
Any resource linked to the merchant contract is finally defined
Payment Instructions linked to the merchant.
The merchant is activated in BankWORKS.
Some important points to note:
- A merchant is not active in BankWORKS prior to processing. During boarding, the merchants will have a status indicating that the merchant is in process of being defined. Following the definition of all merchant resources, it is necessary to activate the merchant. More information is available in the example requests provided. Merchants that are are in the process of being onboarded have a ttl (time to live) value. More on this on the note below.
- During hierarchy onboarding it is necessary to full define a merchant and any related resources before moving on to the child merchant. More information about each individual resource is provided per request, as well as a generic description in the API Schema section of this document.
A note on - meta: (object) - ttl: (integer)
The remaining time to live in seconds of the resource. Once the value reaches 0, the resource will expire, and hence deleted. This attribute applies only to merchants and all its relevant resources which are not yet onboarded i.e. status in progress (023) or in error (024). The ttl will be set once the resource is posted and will be reset once the resource is patched or a related resource is posted or patched. The ttl value will be set 2592000 seconds (30 days), however, RS2 reserves the right to change this value.
1. Add Merchant Details
This call is the first step for onboarding and is MANDATORY to be created per client level in the hierarchy or a standalone merchant to be onboarded. This request defines the main merchant client details in BankWORKS. The merchant resource will also be used for linkage to the resources to be defined in the next request. A successful merchant creation will return the resource created as a confirmation as well as the resource ID.
Every merchant created to bankWORKS using WSM API will be marked with a specific status value of 023 (In Process), indicating that the merchant is not yet active in BankWORKS. After creation of the merchant followed by the related and required API resources for onboarding, the status of the merchant can be set to either 001 (Active) or 003 (Suspended) by sending a PATCH request to the merchant resource. Suspended status will only apply for member level merchants if needed. This change in status is the final request and is covered in the final request of the onboarding flow..
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchants
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchants with the following attributes:
| Name | Description | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
clientNumber
string (8)
|
8-digit BankWORKS client number unique that is unique per institution. System generated if not provided during new merchant definition. A unique number must be provided if user defined. |
|||||||||||||
|
status
string (3)
|
Indicates the state of the merchant. New merchants that are not yet processed will have a status of ‘023’ to indicate a merchant in status. |
|||||||||||||
|
clientType
string (3)
|
Multiple client types may be available for a merchant to indicate a particular type of merchant. If not provided during merchant creation, the status will default to 002 (Merchant). Refer to API Data Mapping documentation for possible values. |
|||||||||||||
|
shortName
string (26)
|
Merchant’s short name. If not provided during merchant creation, the tradeName value will be used. |
|||||||||||||
|
firstName
string (15)
|
First name of the merchant owner. For the USA market this would be the first name of the owner if the merchant is a sole proprietor. Required for USA merchants with legalForm of 029 - Sole Proprietor. |
|||||||||||||
|
middleName
string (15)
|
Middle name of the merchant owner. For USA merchants having a legalform of 029 - Sole Proprietor, the middleName would be used to store the middle initial followed by a full-stop (.) as per the Visa Acquirer Merchant Master File requirements. |
|||||||||||||
|
lastName
string (26)
|
Last name of the merchant owner. For the USA market this would be the last name of the owner if the merchant is a sole proprietor. Required for USA merchants with legalForm of 029 - Sole Proprietor. |
|||||||||||||
|
companyName
string (45)
required
|
The merchant company name. |
|||||||||||||
|
tradeName
string (25)
required
|
The name under which the company is trading. |
|||||||||||||
|
registrationNumber
string (15)
|
The merchant registration number. |
|||||||||||||
|
vatRegion
string (3)
|
Merchant’s VAT region. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
language
string (3)
required
|
Merchant’s language. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
legalForm
string (3)
required
|
Related to the legal form of the merchant. Such as:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
businessClass
string (4)
required
|
The ISO 4-digit business classification code. |
|||||||||||||
|
vatRegistrationNumber
string (15)
|
Merchant’s VAT number. |
|||||||||||||
|
ourReference
string (20)
|
A reference number used for clearing purposes, typically the merchant ID. |
|||||||||||||
|
domesticMcc
string (4)
|
The ISO 4-digit domestic merchant category code. |
|||||||||||||
|
mainContactDetails
object
|
Object grouping main merchant contact information.
|
|||||||||||||
|
rbsClientNumber
string (20)
|
External merchant reference number. |
|||||||||||||
|
website
string (100)
|
Merchant website address details. |
|||||||||||||
|
eCommerceIndicator
string (3)
|
Indicates if the merchant business is eCommerce based or a traditional business. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
processingRegion
string (3)
required
|
Defines the processing region of the merchant. Used for transaction processing. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
taxRegion
string (3)
|
Merchant’s tax region. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
taxCountry
string (3)
required
|
The ISO 3-letter country code of the merchant’s country for tax information. In cases where value consists of 3 digits:
|
|||||||||||||
| Relationships | ||||||||||||||
|
merchantAddendum
|
Additional attributes related to the merchant. |
|||||||||||||
|
merchantAddendumUsa
|
Additional attributes specifically for merchants based in USA. |
|||||||||||||
|
merchantAddendumColombia
|
Additional attributes specifically for merchants based in Colombia. |
|||||||||||||
|
clientMappings
|
All client mappings available related to the merchant. |
|||||||||||||
|
originalMerchant
|
This is the originating (old) merchant for which this merchant has been moved from. This is only done via PATCH request. Please see Merchant Entity Move use case for proper usage. |
|||||||||||||
|
clientRelations
|
All virtual links related to the merchant. |
|||||||||||||
|
merchantTaxStatus
|
All tax status records related to the merchant. |
|||||||||||||
|
disputeCases
|
All dispute cases related to the merchant. |
|||||||||||||
|
kycClients
|
All KYC/AML clients related to the merchant. |
|||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type merchants .
2. Create Addresses, Addendums, Contract, Settlement, References
This request has multiple calls to onboarding and will create merchant Addresses, Addendum and Addendum USA, Contract, and Settlement Information information (if client is a billing level). These represent direct resources that can be linked to the merchant defined in previous step without any dependecy to other merchant resources.
ADDRESS CREATION:
This call will create merchant address/es depending on what address categories are required upon onboarding. Below are the minimum requirements and each category is equivalent to 1 API request: - Standard Address (addressCategory 001) required by BankWORKS and representing the main merchant address. In most cases this would have the same address attributes as the clearing address mentioned in the next point. - Clearing Address (addressCategory 022) is needed for outward clearing file to be sent to card schemes. This address should represent the physical location of the merchant and will most likely be the same as the Standard address.
Other addresses optional address categories are available and may be used if required. Every address to be created must be linked to the merchant being onboarded. Refer to mandatory relationship for more information.
ADDENDUM CREATION:
Additional merchant attributes may required. There are 2 different addendum resources available: - merchantsAddendum: Contains any potential addendum attributes not part of the primary merchant record. - merchantsAddednumUsa: Similar to merchantsAddendum however USA region specific, applicable for USA merchants.
Both of these addendum records are OPTIONAL.
CONTRACT CREATION:
Creation of a contract resource for a new client and is MANDATORY for onboarding may it be standalone merchant or per client level in a hierarchy. In case of a hierarchical merchant, the parent merchant contract must be linked as a relationship. Refer to mandatory relationships for more information
SETTLEMENT INFORMATION CREATION:
This will define the settlement information including RBS bank account number of the merchant and is MANDATORY only if a billing level account is to be created and for the account types which are not configured. Multiple settlement information/package can be added (up to 99). This number will be set automatically and stored in settlementNumber as part of the resource ID.
For settlementPackages with related fundingClient, it is to be associated in the relationship from the request apart from merchant relationship/linkage:
CLIENT REFERENCES CREATION:
This call is OPTIONAL and will can be used to add any client reference values necessary at onboarding stage. Client references are miscellaneous reference properties that may be requried for a merchant. Multiple references can be defined during onboarding, one for each reference type supported. These reference types are usually institution spefic values. Refer to clientReferences for more details.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/json-patch+json |
| Accept | application/json-patch+json |
| Crnk-Compact | true |
Request Body
This request body contains of a numer of JSON Patch operations to perform bulk actions on the addresses, merchantsAddendum, merchantsAddendumUsa, contracts, settlementPackages and clientReferences JSON:API resources. Follow the example in order to see how to perform the JSON Patch call. Below are the JSON:API resource objects accepted in this JSON Patch call.
addresses object
| Name | Description | |
|---|---|---|
|
addressCategory
string (3)
required
|
The address category identifier for the returned client address resource are the following but not limited to:
A client must have at least a standard (001) and a clearing (022) address. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the address becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, the current posting date is automatically assumed. |
|
|
expiryDate
date-only
|
The date in ISO 8601 format when the address record is no longer taken into consideration. Can be used for temporary addresses. Date must be in the future. |
|
|
addressLine1
string (35)
required
|
Address line typically used for building information but not limited to house name, number, floor, unit and block number. |
|
|
addressLine2
string (35)
|
Address line typically used for street information such as street number and name. |
|
|
addressLine3
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
addressLine4
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
addressLine5
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
contactName
string (35)
|
Main contact name for the address. |
|
|
city
string (35)
required
|
Client’s city. |
|
|
state
string (3)
|
3 digit identifier for the client’s state/region. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
country
string (3)
required
|
The ISO 3-letter country code. In cases where value consists of 3 digits, 000 means not applicable and 999 means applicable to all countries. |
|
|
postCode
string (20)
required
|
Client’s postcode. |
|
|
poBox
string (10)
|
P.O. Box details. |
|
|
addressLanguage
string (3)
|
3-digit identifier for the client address language. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
telephone1
string (15)
|
Primary address fixed line number, for example, a client’s home or business telephone number. |
|
|
telephone2
string (15)
|
Secondary address fixed line number for example a secondary business telephone number. |
|
|
faxWork
string (15)
|
Office fax number. |
|
|
deliveryMethod
string (3)
|
3-digit value indicating the preferred delivery option for correspondence. Defaulted to not applicable (000) if not provided. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
emailAddress
string (60)
|
Client’s e-mail address. This is required if deliveryMethod is set to 500 (E-mail). |
|
| Relationships | ||
|
merchant
required |
Link to the merchant resource ID previously defined in the merchant resource creation stage. |
|
|
kycClient
|
KYC/AML client who owns the address information. An address can only belong to one client. |
|
merchantsAddendum object
| Name | Description | |
|---|---|---|
|
seasonalMerchant
string (3)
|
Flag to indicate if the merchant is a seasonal merchant or not. Such as:
Refer to BankWorks (API) Data Mapping documentation for possible values.) |
|
|
feeProgramIndicator
string (3)
|
The fee program indicator used for the VISA Base 2 clearing file. |
|
|
visaInterchangeProgram
string (10)
|
Stores the value of the Visa interchange program value. |
|
|
visaInterchangeProgramQualification
string (3)
|
The ISO 3-digits used to determine the tier of the interchange. |
|
|
mastercardInterchangeProgram
string (10)
|
Stores the value of the MasterCard AID. |
|
|
mastercardInterchangeProgramQualification
string (3)
|
The ISO 3-digits used to determine the tier of the interchange. |
|
|
socialSecurityNumber
string (9)
|
This attribute will contain the SSN, and it is required for Discover. It is also required when the The value of this attribute in the response will always be returned in masked format. |
|
|
vatTaxIndicator
string (6)
|
Tax tariff that will be charged to merchant related to merchant VAT. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
municipalCode
string (7)
|
The municipality code of the place where the transaction occurred. |
|
|
merchantCountryOfOrigin
string (3)
|
Mastercard requirement for government owned merchants. The country of origin for government-controlled merchants must always be populated. This includes when the government-controlled merchant’s home country is the country where the government-controlled merchant is physically located and when the government-controlled merchant’s home country is not the country where the government-controlled merchant is physically located. The format is in ISO 3-letter country code. E.g. NZL (New Zealand) Refer to API Data Mapping documentation for account definitions available for the institution. |
|
|
url
string (76)
|
The merchant’s main website address. This value is also required for merchants acquiring MasterCard eCommerce and in case there is no main service telephone number (mainContactDetails.serviceTelephone). |
|
|
independentSalesOrganisation
string (11)
|
Independent Sales Organisation ID value provided by Mastercard. This value is equivalent to the merchantsAddendumUsa.independentSalesOrganisation attribute. |
|
| Relationships | ||
|
merchant
required |
Link to the merchant resource ID previously defined in the merchant resource creation stage. |
|
merchantsAddendumUsa object
| Name | Description | |
|---|---|---|
|
url
string (76)
|
Merchant URL information. |
|
|
independentSalesOrganisation
string (11)
|
Independent Sales Organisation ID value provided by Mastercard. This value is equivalent to the merchantsAddendum.independentSalesOrganisation attribute. |
|
|
taxId
string (9)
|
TAX ID/TIN number used by the IRS. Requirement of the 1099k form report. This is required when the
|
|
|
taxIdNumberType
string (3)
|
Indicates the type of TAX ID/TIN number used by the IRS. Requirement of the 1099k form report. When this is set to 002 SSN, the |
|
|
information
string (200)
|
Information about what product/services are sold by the merchant. |
|
|
visaInternationalAcquirerFeeFlag
string (3)
|
Flag indicating whether the Visa International Acquirer Fee is to be posted to client rather than institution account. Such as:
|
|
|
federalTaxTariff
string (6)
|
Indicates the Federal tax fee tariff. |
|
| Relationships | ||
|
merchant
required |
Link to the merchant resource ID previously defined in the merchant resource creation stage. |
|
contracts object
| Name | Description | |
|---|---|---|
|
status
string (3)
|
Indicates the status of the client contract. If not provided, this will be defaulted to 001 (Active). Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientLevel
string (3)
required
|
Indicates the BankWORKS hierarchical level for the client contract. The following values are possible:
|
|
|
effectiveDate
date-only
|
The date in ISO 8601 format on which the hierarchy link record becomes effective for the client. The value can be future dated and cannot be less than the posting date. If not provided, posting date +1 value is assumed only post-boarding. |
|
|
settlementMethod
string (3)
required
|
Indicates the method how the client will settle with the bank. Identifies how outstanding balances are settled. Required only when onboarding a new client. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
postingMethod
string (3)
|
The tariff under which the client falls when posting to the clients account. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientTariff
string (6)
required
|
Indicates the client tariff package assigned. Required only when onboarding a new client. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
transactionChargesTariff
string (6)
|
Indicates the applicable transaction charges tariff. Transaction charges are represented as productChargeDefinitions. This is an optional field and if not provided will default to not applicable 000000. If a tariff value is provided, the merchant services clientTariff value will not apply. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
chargeTierLevel
string (3)
|
Enables setting up of the same fee with different value high and value low triggers. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientScheme
string (6)
|
Indicates the rebate tariff applicable for the contract. |
|
|
contractReference
string (8)
|
Merchant contract document reference. |
|
|
bankReference
string (8)
|
External additional reference number of the merchant with the bank. |
|
|
institutionAccountOfficer
string (3)
|
Officer in charge of the client contract. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientBranch
string (3)
|
Contract application branch details. Related to the institutionAccountOfficer. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
tierGroup
string (3)
|
An identifier used to group a set of rates that need to be applied during tiered pricing generation. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
entityId
string (3)
|
Entity identifier used to split GL entries and transactions generated for financial activity in a single processing institution across multiple legal entities. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
riskRuleGroupId
string (3)
|
Identifier for the set of rules applies in the risk module. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
|
contractDefinition
required |
Link to a merchant contract definition. These are available as business rules. Refer to merchant contract definition retrieval for more information. |
|
|
merchant
required |
Link to the merchant resource ID previously defined in the merchant resource creation stage. |
|
|
parentContracts
|
If defining a merchant that is part of a hierarchy below the GROUP level, the parent merchant contract needs to be provided. Standalone MEMBER level clients do not require a parent contract to be linked to. |
|
|
riskRuleParameters
|
One or more risk rule parameters this client contract is linked to. |
|
settlementPackages object
| Name | Description | |||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
settlementCategory
string (3)
|
Settlement information category descriptor such as Payable or Receivable. |
|||||||||||||||||||||||||||||||
|
accountCurrency
string (3)
|
The currency of the counter bank account in SWIFT currency code format. In cases where value consists of 3 digits:
|
|||||||||||||||||||||||||||||||
|
bankClearingNumber
string (8)
|
Information regarding the account’s bank details. For USA merchants, this must be a 9-digit value. |
|||||||||||||||||||||||||||||||
|
contingencyLiabilityAccount
string (11)
|
The RBS account that is used in case the counter RBS bank account is not able to fullfil the RECEIVABLE obligation. |
|||||||||||||||||||||||||||||||
|
correspondingBankAccount
string (16)
|
The NOSTRA/VOSTRO bank account of the affiliate institution. |
|||||||||||||||||||||||||||||||
|
correspondingBankNumber
string (35)
|
The bank number of the affiliate institution where the counter bank Nostro/Vostro are domiciled. |
|||||||||||||||||||||||||||||||
|
receiverCountryCode
string (3)
|
The country where the bank account information is located. In cases where value consists of 3 digits:
|
|||||||||||||||||||||||||||||||
|
noteText
string (2000)
|
Free text notes on the settlement package. |
|||||||||||||||||||||||||||||||
|
payableDetails
object
|
|
|||||||||||||||||||||||||||||||
|
receivableDetails
object
|
|
|||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||
|
merchant
required |
Link to the merchant resource ID previously defined in the merchant resource creation stage. |
|||||||||||||||||||||||||||||||
|
fundingClient
|
Optional link to the funding bank to indicate source of funds for merchant settlement. Refer to the funding client section for more information. |
|||||||||||||||||||||||||||||||
|
mandateInformation
|
SEPA DD mandate information for which the settlement is related to. |
|||||||||||||||||||||||||||||||
clientReferences object
| Name | Description | |
|---|---|---|
|
referenceType
string (3)
|
Identifies the type of institution-specific client reference type. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
referenceValue
string (36)
|
Value of client reference. E.g. 1234000-ABC |
|
| Relationships | ||
|
merchant
required |
The merchant owner of the reference property. |
|
Response
Sample 1 - with Error : HTTP 200 (OK)
Sample 2 - Successful : HTTP 200 (OK)
Response body will contain the result of the JSON PATCH operation for the following resources: addresses merchantsAddendum merchantsAddendumUsa contracts settlementPackages clientReferences
2.1 Revert Addresses, Addendums, Contract, Settlement , References
This is a sample rollback call for deleting the previous bulk call. Only include deletion for the successful operations from previous bulk request.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/json-patch+json |
| Accept | application/json-patch+json |
| Crnk-Compact | true |
Request Body
Response
HTTP 200 (OK)
3. Create Accounts, Services, CardSchemeAddendum, Tax Status, Mandate Information, Risk Rule Parameters
ACCOUNTS CREATION:
This call is MANDATORY for merchant onboarding. Every account boarded forms part of an account hierarchy (based on the Account Type and Currency combination, for example Payment Account EUR) which is based on the same strucutre as a client hierarchy. Each account hierarchy should have a billing and settlement point level. The billing point should be available per hierarchy branch/path. Billing level accounts require a settlementPackage to be linked to. This can be any settlementPackage resource defined earlier during onboarding. More information on the attributes and relationships is available below.
SERVICES CREATION:
This call is OPTIONAL. A merchant can have a number of optional services defined during onboarding. Mandatory services are automatically created during merchant onboarding processing, part of the final step. An individual service resource must be created for each service to be onboarded and must be based on existing service definition rules part of the merchant’s service contract. More information information is available in the relationships section.
CARD SCHEME ADDENDUM CREATION
This call is OPTIONAL. A merchant can have a number of optional card scheme addenda defined during onboarding. More information information is available in the API schema relationships section.
RISK RULE PARAMETERS CREATION
This call is OPTIONAL. Prior to creation of this resource, risk should be enabled for the merchant contract via riskRuleGroupId attribute on this request.
Note: Record ID generated during onboarding is only an initialized value. A GET request on Client Risk Parameters via Client Number should be performed after the client has been onboarded in order to retrieve the actual ID for this resource. Any POST request after onboarding will automatically generate the actual recordId.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/json-patch+json |
| Accept | application/json-patch+json |
| Crnk-Compact | true |
Request Body
This request body contains of a numer of JSON Patch operations to perform bulk actions on the accounts, services, merchantTaxStatus, mandateInformation and riskRuleParameters JSON:API resources. Follow the example in order to see how to perform the JSON Patch call. Below are the JSON:API resource objects accepted in this JSON Patch call.
accounts object
| Name | Description | |
|---|---|---|
|
clientAccountName
string (35)
|
Field representing the merchant account alias. |
|
|
accountNumberRbs
string (28)
|
External account number reference. |
|
|
statementGeneration
string (3)
|
Indicates the statement generation rule applicable for this account. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
statementType
string (3)
|
Indicates the type of statement applicable for this account. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
|
accountDefinition
required |
Link to a account definition business rule. This must be availabe in the client contract definition assigned ealier, during merchant contract creation. Refer to the account definition retrieval by service contract request for more information. |
|
|
settlementPackage
|
Optional, settlementPackage only needs to be linked to if the account is at billing level. Providing a settlementPackage automatically sets the account billingLevel to 001 - indicating a billingLevel account |
|
|
contracts
required |
Link to the merchant contract defined during contract creation. |
|
|
paymentInstructions
|
Payment instructions defined for the account. |
|
|
billingAccounts
|
The billing account within the account hierarchy. |
|
|
balanceCycles
|
The account balances per cycle. |
|
services object
| Name | Description | |
|---|---|---|
|
clientNumber
string
|
The BankWORKS 8-digit client number. |
|
|
groupNumber
string
|
Indicates the client hierarchy group the service relates to. Refer to contracts relationship below for linking service to contract. |
|
|
serviceId
string
|
BankWORKS service identifier. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
serviceCategory
string (3)
|
Indicates the service category of the client service. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
status
string (3)
|
Indicates the current status of the client service. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the client service becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, posting date +1 value is assumed only post-boarding. |
|
|
expiryDate
date-only
|
The date in ISO 8601 format when the client service expires and no longer applies. |
|
|
clientTariff
string (6)
required
|
Indicates the applicable transaction charge rules. The tariff only applies if the related merchant contract does not have a transactionChargesTariff value of “000000”. Defaults to “000000” if not provided. Applicable only to card based acquiring services. For miscellaneous service tariff, refer to the contracts resource. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
reviewDate
date-only
|
Indicates the service revision date in ISO 8601 format. |
|
| Relationships | ||
|
serviceDefinitions
required |
A client service must be based on a serviceDefinition rule. The serviceDefinition rule must be available in the client contractDefinition linked to during merchant contract creation. Various types of merchant services can be applied for, refer to **Acquiring Services and **Miscellaneous Services for more information. |
|
|
contracts
required |
Link to the merchant contract defined during contract creation. |
|
merchantTaxStatus object
| Name | Description | |
|---|---|---|
|
taxType
string (3)
|
Indicates the type of merchant tax. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
taxStatus
string (3)
|
Indicates the current status of merchant tax type. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format on which the merchant tax status record becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, posting date value is assumed. |
|
|
expiryDate
date-only
|
The date in ISO 8601 format when the merchant tax status can no longer be used. |
|
|
recordDate
date-only
|
The date in ISO 8601 format on which the merchant tax status record is created. Defaulted to the current posting date when a new record is created |
|
| Relationships | ||
|
merchant
required |
Merchant information related to merchant tax status record. |
|
mandateInformation object
| Name | Description | |
|---|---|---|
|
uniqueMandateReference
string (35)
required
|
A unique 35-character reference for the signed mandate |
|
|
instrumentCode
string (3)
|
Type of the mandate whether it is a business-to-client or business-to-business scheme. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
firstOccurrence
string (3)
|
This will indicate whether the mandate is first occurrence or not. By default it will be set to No (000). Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
signatureDate
date-only (8)
required
|
Date of which the mandate was signed or authorised. |
|
| Relationships | ||
|
settlementPackages
required |
Bank account settlement information which this mandate belongs to. |
|
riskRuleParameters object
| Name | Description | |
|---|---|---|
|
recordId
string (15)
|
The identifier generated which is unique for every record. Note: Record ID generated pre-onboarding is only an initialized value. A GET request on Get Client Risk Parameters via Client Number should be performed after the client has been onboarded in order to retrieve the actual ID for this resource. Any POST request after onboarding will automatically generate the actual recordId. |
|
|
ruleParameter
string (6)
required
|
The risk rule parameter for which the risk rule applies to. |
|
|
isContractRule
boolean
|
This flag will indicate whether the risk rule parameter is a contract-generated (true) or client-defined (false). |
|
|
clientId
number
|
The identifier generated for client-defined risk rule parameters. Note: Client ID generated pre-onboarding is only an initialized value. A GET request on Get Client Risk Parameters via Client Number should be performed after the client has been onboarded in order to retrieve the actual clientId for this resource. Any POST request after onboarding will automatically generate the actual clientId. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the risk parameter will take into effect. |
|
|
expiryDate
date-only
|
Expiry date of risk rule parameter in ISO 8601 format. |
|
|
value
string
required
|
The risk rule value applied for the specified rule parameter. Value format varies depending on the rule parameter’s data type. Refer to BankWorks (API) Data Mapping documentation for possible values. Example:
|
|
|
currency
string (3)
|
The risk rule currency to be specified in case rule parameter requires an amount value. This should be in 3-letter ISO SWIFT format. Example: USD, EUR |
|
|
description
string (3)
|
Free-text description for the risk rule parameter. |
|
|
recordDate
date-only (3)
|
The date in ISO 8601 format on which the risk rule parameter record is created. Defaulted to the current posting date when a new record is created. |
|
| Relationships | ||
|
contracts
required |
Merchant contract/s for which the rule parameter applies to. |
|
Response
Sample 1 - with error : HTTP 200 (OK)
Sample 2 - Successful : HTTP 200 (OK)
Response body will contain the result of the JSON PATCH operation for the following resources: accounts services merchantTaxStatus mandateInformation riskRuleParameters
3.1 Revert Accounts, Services, CardSchemeAddendum, Tax Status, mandate Information
This is a sample rollback call for deleting the previous bulk call. Only include deletion for the successful operations from previous bulk request.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/json-patch+json |
| Accept | application/json-patch+json |
| Crnk-Compact | true |
Request Body
Response
HTTP 200 (OK)
4. Add Payment Instructions
A request to create new payment instructions record.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/paymentInstructions
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type paymentInstructions with the following attributes:
| Name | Description | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
transactionType
string (3)
required
|
Defines the transaction type assigned to the outgoing transaction. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||||||||
|
paymentBase
decimal (18)
|
Fixed base amount applied to the generated payment. Defaulted to zero if not sent. |
|||||||||||||||||||
|
paymentPercentage
decimal (11)
|
Percentage amount based on the total payable amount. This is applied to the payment base. Defaulted to zero if not sent. |
|||||||||||||||||||
|
paymentMinimum
decimal (18)
|
Minimum amount generated should paymentBase paymentPercentage not reach the minimum threshold. Defaulted to zero if not sent. |
|||||||||||||||||||
|
paymentMaximum
decimal (18)
|
Maximum amount generated should paymentBase paymentPercentage go over the mamximum threshold. Defaulted to zero if not sent. |
|||||||||||||||||||
|
executionCountLimit
int (11)
|
The total payment instruction execution count limit. This is compared with the execution counter and when the threshold defined is reached, the instruction no longer executes. |
|||||||||||||||||||
|
notes
string (1300)
|
Allows a generic text description to be provided with the rule for reference purposes. |
|||||||||||||||||||
|
paymentCategory
string (3)
required
|
Indicates the settlement category of the payment instruction. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||||||||
|
clearingChannel
string (3)
required
|
Defines the outgoing clearing channel assigned to the payment transactions generated. The destinationSettleAccount relationship (see below) is required when passing a value of “018”, indicating the Outward On-Us channel. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||||||||
|
trigger
object
|
|
|||||||||||||||||||
|
destinationSettlement
object
|
An object containing attributes associated with the destination account applicable for partial payments. Partial payments allow acquirers to split merchant settlement, providing a separate account for posting the partial payment amount. The attributes within this object are read only. To define the additional destination account for partial payment please refer to the destinationSettleAccount relationship.
|
|||||||||||||||||||
|
executionAmountLimit
decimal (11)
|
The total limit threshold allowed for the payment instruction rule. This works in conjunction with the executionAmountPaid. Once this limit is reached, the payment instruction rule no longer executes. |
|||||||||||||||||||
| Relationships | ||||||||||||||||||||
|
account
required |
Accounts which this payment instructions will be applied. |
|||||||||||||||||||
|
destinationSettleAccount
|
Relationship to an accounts resource belonging to the entity receiving a percentage of the settlement. This applies to merchant partial payment scenarios. |
|||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type paymentInstructions .
5. Process Merchant
Reference resource: merchants
This call is MANDATORY and the last step to onboard a merchant.
After the required API onboarding resources are created, status of the merchant needs to be set to either 001 (Active) or 003 (Suspended) by sending a PATCH request to merchants API. Please note that Suspended status will only apply for MEMBER level (transacting) merchants if necessary.
This PATCH request triggers the AIM and APM to process the merchant application. When the back-end application processing is successful, an API response of 200 or 201 (successful) will be passed as well indicating an merchant is onboarded successfully with that status.
In case there are any processing errors, the error details will be indicated in the response and the merchant status will be set to 024 (In Error).
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
Response
Sample - Active Merchant : HTTP 200 (OK)
Sample 1 - with Error : HTTP 422 (Unprocessable Entity)
Amex OptBlue
The Amex OptBlue merchant program requires an authorized signer and up to four business owners to be defined for the prospective merchant. In BankWORKS both individual types can be supported via the kycClients API. These individuals can be registered following merchant activation and must be linked to the OptBlue merchant as indicated in these use cases.
A use case for retrieval of the merchant OptBlue status has also been provided as a separate use case.
Get Amex OptBlue Merchants
Retrieve all the Amex OptBlue merchant details that is stored in BankWORKS.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants?filter[contracts][cardSchemeAddendums.cardOrganisation]=004&filter[contracts][cardSchemeAddendums.amex.direct]=002&include=kycClients
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[contracts][cardSchemeAddendums.cardOrganisation] | 004 |
|---|---|
| filter[contracts][cardSchemeAddendums.amex.direct] | 002 |
| include | kycClients |
Response
Get Amex OptBlue Merchants : HTTP 200 (OK)
Get Amex OptBlue Merchants w/ KYC Clients : HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type kycClients with kycClientsas included resources.
Get Merchants KYC Clients
Retrieve all the Amex OptBlue merchant details that is stored in BankWORKS.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=22550339?include=kycClients
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[contracts][cardSchemeAddendums.cardOrganisation] | 004 |
|---|---|
| filter[contracts][cardSchemeAddendums.amex.direct] | 002 |
| include | kycClients |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type kycClients with kycClientsas included resources.
Add Authorized Signer
A request to create a new Authorized signer/KYC client to store to BankWORKS. This must be link to any ISO that is available in BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/kycClients
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type kycClients with the following attributes:
| Name | Description | |
|---|---|---|
|
clientStatus
string (3)
|
Indicates the status of KYC/AML client. If not provided will be defaulted to 001 (Active). Examples include:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientType
string (3)
|
Defines the type of client record. For example, a business owner. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
title
string (3)
|
Indicates the KYC/AML client salutation. If not provided will be defaulted to 000 (n/a). Examples include:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
firstName
string (15)
required
|
The first name of the private individual. |
|
|
lastName
string (26)
required
|
The last name of the private individual. |
|
|
dateOfBirth
date-only
required
|
The date of birth in ISO 8601 format. |
|
|
socialSecurityNumber
string (9)
|
Indicates the unique social security number of the client. The value of this attribute in the response will always be returned in masked format. |
|
| Relationships | ||
|
merchants
|
Merchant resource to which the KYC/AML client is linked to. |
|
|
addresses
|
The addresses linked to the KYC client. |
|
Response
Add Authorized Signer - Successful 1 : HTTP 201 (Created)
Add Authorized Signer - Successful 2 : HTTP 201 (Created)
Add Authorized Signer - Error : HTTP 403 (Forbidden)
Response body will contain the created JSON:API resource of type kycClients .
Edit Authorized Signer
A request to modify the information of an existing Authorized signer/KYC client in BankWORKS.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/kycClients/{{kycClientId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type kycClients with the following attributes:
| Name | Description | |
|---|---|---|
|
clientStatus
string (3)
|
Indicates the status of KYC/AML client. If not provided will be defaulted to 001 (Active). Examples include:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientType
string (3)
|
Defines the type of client record. For example, a business owner. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
title
string (3)
|
Indicates the KYC/AML client salutation. If not provided will be defaulted to 000 (n/a). Examples include:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
firstName
string (15)
|
The first name of the private individual. |
|
|
lastName
string (26)
|
The last name of the private individual. |
|
|
dateOfBirth
date-only
|
The date of birth in ISO 8601 format. |
|
|
socialSecurityNumber
string (9)
|
Indicates the unique social security number of the client. The value of this attribute in the response will always be returned in masked format. |
|
| Relationships | ||
|
merchants
|
Merchant resource to which the KYC/AML client is linked to. |
|
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type kycClients .
Get Authorized Signer
Retrieve the Authorized signer/KYC client details that are stored in BankWORKS.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/kycClients?filter[clientType]=021
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[clientType] | 021 |
|---|---|
| include | addresses,merchants |
Response
Get Authorized Signer : HTTP 200 (OK)
Get Authorized Signer w/ Addresses and Merchants : HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type kycClients with addresses,merchantsas included resources.
Add Authorized Signer Address
This request will create an address (Address Category - Guarantor 018) linked to Authorized signer/KYC client.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/addresses
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type addresses with the following attributes:
| Name | Description | |
|---|---|---|
|
addressCategory
string (3)
required
|
The address category identifier for the returned client address resource are the following but not limited to:
A client must have at least a standard (001) and a clearing (022) address. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the address becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, the current posting date is automatically assumed. |
|
|
expiryDate
date-only
|
The date in ISO 8601 format when the address record is no longer taken into consideration. Can be used for temporary addresses. Date must be in the future. |
|
|
addressLine1
string (35)
required
|
Address line typically used for building information but not limited to house name, number, floor, unit and block number. |
|
|
addressLine2
string (35)
|
Address line typically used for street information such as street number and name. |
|
|
addressLine3
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
addressLine4
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
addressLine5
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
contactName
string (35)
|
Main contact name for the address. |
|
|
city
string (35)
required
|
Client’s city. |
|
|
state
string (3)
|
3 digit identifier for the client’s state/region. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
country
string (3)
required
|
The ISO 3-letter country code. In cases where value consists of 3 digits, 000 means not applicable and 999 means applicable to all countries. |
|
|
postCode
string (20)
required
|
Client’s postcode. |
|
|
poBox
string (10)
|
P.O. Box details. |
|
|
addressLanguage
string (3)
|
3-digit identifier for the client address language. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
telephone1
string (15)
|
Primary address fixed line number, for example, a client’s home or business telephone number. |
|
|
telephone2
string (15)
|
Secondary address fixed line number for example a secondary business telephone number. |
|
|
faxWork
string (15)
|
Office fax number. |
|
|
deliveryMethod
string (3)
|
3-digit value indicating the preferred delivery option for correspondence. Defaulted to not applicable (000) if not provided. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
emailAddress
string (60)
|
Client’s e-mail address. This is required if deliveryMethod is set to 500 (E-mail). |
|
|
recordDate
date-only
|
The date in ISO 8601 format for when the address record was created. |
|
| Relationships | ||
|
kycClient
required |
KYC/AML client who owns the address information. An address can only belong to one client. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type addresses .
Add Business Owner
A request to create a new Business owner/KYC client to store to BankWORKS. This must be link to any ISO that is available in BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/kycClients
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type kycClients with the following attributes:
| Name | Description | |
|---|---|---|
|
clientStatus
string (3)
|
Indicates the status of KYC/AML client. If not provided will be defaulted to 001 (Active). Examples include:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientType
string (3)
|
Defines the type of client record. For example, a business owner. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
title
string (3)
|
Indicates the KYC/AML client salutation. If not provided will be defaulted to 000 (n/a). Examples include:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
firstName
string (15)
required
|
The first name of the private individual. |
|
|
lastName
string (26)
required
|
The last name of the private individual. |
|
|
dateOfBirth
date-only
required
|
The date of birth in ISO 8601 format. |
|
|
socialSecurityNumber
string (9)
|
Indicates the unique social security number of the client. The value of this attribute in the response will always be returned in masked format. |
|
| Relationships | ||
|
merchants
|
Merchant resource to which the KYC/AML client is linked to. |
|
|
addresses
|
The addresses linked to the KYC client. |
|
Response
Add Business Owner - Successful 1 : HTTP 201 (Created)
Add Business Owner - Successful 2 : HTTP 201 (Created)
Add Business Owner - Error : HTTP 403 (Forbidden)
Response body will contain the created JSON:API resource of type kycClients .
Edit Business Owner
A request to modify the information of an existing Business owner/KYC client in BankWORKS.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/kycClients/{{kycClientId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type kycClients with the following attributes:
| Name | Description | |
|---|---|---|
|
clientStatus
string (3)
|
Indicates the status of KYC/AML client. If not provided will be defaulted to 001 (Active). Examples include:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientType
string (3)
|
Defines the type of client record. For example, a business owner. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
title
string (3)
|
Indicates the KYC/AML client salutation. If not provided will be defaulted to 000 (n/a). Examples include:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
firstName
string (15)
|
The first name of the private individual. |
|
|
lastName
string (26)
|
The last name of the private individual. |
|
|
dateOfBirth
date-only
|
The date of birth in ISO 8601 format. |
|
|
socialSecurityNumber
string (9)
|
Indicates the unique social security number of the client. The value of this attribute in the response will always be returned in masked format. |
|
| Relationships | ||
|
merchants
|
Merchant resource to which the KYC/AML client is linked to. |
|
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type kycClients .
Get Business Owners
Retrieve the Business owner/KYC client details that are stored in BankWORKS.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/kycClients?filter[clientType]=020
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[clientType] | 020 |
|---|---|
| include | addresses,merchants |
Response
Get Business Owners : HTTP 200 (OK)
Get Business Owners w/ Addresses and Merchants : HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type kycClients with addresses,merchantsas included resources.
Add Business Owner Address
This request will create an address (Address Category - Guarantor 018) linked to Business owner/KYC client.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/addresses
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type addresses with the following attributes:
| Name | Description | |
|---|---|---|
|
addressCategory
string (3)
required
|
The address category identifier for the returned client address resource are the following but not limited to:
A client must have at least a standard (001) and a clearing (022) address. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the address becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, the current posting date is automatically assumed. |
|
|
expiryDate
date-only
|
The date in ISO 8601 format when the address record is no longer taken into consideration. Can be used for temporary addresses. Date must be in the future. |
|
|
addressLine1
string (35)
required
|
Address line typically used for building information but not limited to house name, number, floor, unit and block number. |
|
|
addressLine2
string (35)
|
Address line typically used for street information such as street number and name. |
|
|
addressLine3
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
addressLine4
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
addressLine5
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
contactName
string (35)
|
Main contact name for the address. |
|
|
city
string (35)
required
|
Client’s city. |
|
|
state
string (3)
|
3 digit identifier for the client’s state/region. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
country
string (3)
required
|
The ISO 3-letter country code. In cases where value consists of 3 digits, 000 means not applicable and 999 means applicable to all countries. |
|
|
postCode
string (20)
required
|
Client’s postcode. |
|
|
poBox
string (10)
|
P.O. Box details. |
|
|
addressLanguage
string (3)
|
3-digit identifier for the client address language. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
telephone1
string (15)
|
Primary address fixed line number, for example, a client’s home or business telephone number. |
|
|
telephone2
string (15)
|
Secondary address fixed line number for example a secondary business telephone number. |
|
|
faxWork
string (15)
|
Office fax number. |
|
|
deliveryMethod
string (3)
|
3-digit value indicating the preferred delivery option for correspondence. Defaulted to not applicable (000) if not provided. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
emailAddress
string (60)
|
Client’s e-mail address. This is required if deliveryMethod is set to 500 (E-mail). |
|
|
recordDate
date-only
|
The date in ISO 8601 format for when the address record was created. |
|
| Relationships | ||
|
kycClient
required |
KYC/AML client who owns the address information. An address can only belong to one client. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type addresses .
Merchant Hierarchy Boarding
This use case section illustrates a sample sequential hierarchical merchant onboarding from top to bottom client level.
BankWORKS support multi-level hierarchies, the group being the top most level, the member being the outlet level (bottom level). Sub-groups are any nodes in between the group and member level.
The following example is intended to highlight an example how the /merchantApplications endpoint can be used for hierarchical onboarding.
1. GROUP LEVEL (Non-billing)
This call creates and processes a merchant application in a single request through the API gateway without the need to send individual creation and, in case of failure, revert requests as shown in the merchant onboarding use case above. This request is an orchestration of multiple calls into one but still follows the requirements mentioned in the main documentation for each resource. Please note that the access token must be valid for more than 30 seconds for this orchestration to take place.
The following resources are supported:
| Resource | Description |
|---|---|
| merchant (required) | This is the main resource to which everything is related to. This must be provided at the top-level. |
| merchantAddendum | The merchant addendum is related to the merchant and can be provided as part of the merchant resource. |
| merchantAddendumUsa | The USA merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for USA merchants. |
| merchantAddendumColombia | The Colombia merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for Colombia merchants. |
| clientReferences | The client references are related to the merchant and can be provided as an array and part of the merchant resource. |
| merchantTaxStatus | The tax types assigned to the merchant and their current status. |
| addresses (required) | The addresses are related to the merchant and must be provided as an array and part of the merchant resource. |
| contracts (required) | The contract is related to the merchant and must be provided as a single-element array and part of the merchant resource. clientLevel attribute should be set to 002 (Group level). |
| services | The services are linked to a merchant through the contract and can be provided as an array and part of the contract resource. |
| riskRuleParameters | The risk rule parameters defined specifically for the merchant linked through the contract and can be provided as an array and part of the contract resource. |
| settlementPackages | The settlement packages are related to the merchant and can be provided as an array and part of the merchant resource. |
| mandateInformation | A signed authorization (issued in a paper or electronic format) for SEPA direct debit payment in EURO currency given to the creditor by the debtor. It can be provided related to settlement package. |
| paymentInstructions | The payment instructions are linked to a merchant through the account. |
| accounts (required) | Accounts can be defined at two different levels:
|
For further details on the resources to be provided in the request, please refer to the individual requests in the merchant onboarding use case above.
In case of a successful onboarding, all the merchant data (including the generated IDs) will be retrieved and returned.
In case there are any errors, any successful resources created prior to the failing resource will be reverted and another merchant application with the correct data must be sent again. In order to identify the problematic resource which has thrown the error, make sure to refer to the pointer value found inside the meta element of the corresponding error. This will contain the path of the resource in error (if any). In cases where the resource is part of an array, a zero-based index will be included to identify the specific resource.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantApplications
Request Headers
| Content-Type | application/vnd.api+json |
|---|---|
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
Request Body
Response
HTTP 201 (Created)
2. SUB-GROUP LEVEL (Non-billing)
This call creates and processes a merchant application in a single request through the API gateway without the need to send individual creation and, in case of failure, revert requests as shown in the merchant onboarding use case above. This request is an orchestration of multiple calls into one but still follows the requirements mentioned in the main documentation for each resource. Please note that the access token must be valid for more than 30 seconds for this orchestration to take place.
The following resources are supported:
| Resource | Description |
|---|---|
| merchant (required) | This is the main resource to which everything is related to. This must be provided at the top-level. |
| merchantAddendum | The merchant addendum is related to the merchant and can be provided as part of the merchant resource. |
| merchantAddendumUsa | The USA merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for USA merchants. |
| merchantAddendumColombia | The Colombia merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for Colombia merchants. |
| clientReferences | The client references are related to the merchant and can be provided as an array and part of the merchant resource. |
| merchantTaxStatus | The tax types assigned to the merchant and their current status. |
| addresses (required) | The addresses are related to the merchant and must be provided as an array and part of the merchant resource. |
| contracts (required) | The contract is related to the merchant and must be provided as a single-element array and part of the merchant resource. clientLevel attribute should be set to 003 (Sub-group level). |
| services | The services are linked to a merchant through the contract and can be provided as an array and part of the contract resource. |
| riskRuleParameters | The risk rule parameters defined specifically for the merchant linked through the contract and can be provided as an array and part of the contract resource. |
| settlementPackages | The settlement packages are related to the merchant and can be provided as an array and part of the merchant resource. |
| mandateInformation | A signed authorization (issued in a paper or electronic format) for SEPA direct debit payment in EURO currency given to the creditor by the debtor. It can be provided related to settlement package. |
| paymentInstructions | The payment instructions are linked to a merchant through the account. |
| accounts (required) | Accounts can be defined at two different levels:
|
For further details on the resources to be provided in the request, please refer to the individual requests in the merchant onboarding use case above.
In case of a successful onboarding, all the merchant data (including the generated IDs) will be retrieved and returned.
In case there are any errors, any successful resources created prior to the failing resource will be reverted and another merchant application with the correct data must be sent again. In order to identify the problematic resource which has thrown the error, make sure to refer to the pointer value found inside the meta element of the corresponding error. This will contain the path of the resource in error (if any). In cases where the resource is part of an array, a zero-based index will be included to identify the specific resource.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantApplications
Request Headers
| Content-Type | application/vnd.api+json |
|---|---|
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
Request Body
Response
HTTP 201 (Created)
3. MEMBER LEVEL (Billing)
This call creates and processes a merchant application in a single request through the API gateway without the need to send individual creation and, in case of failure, revert requests as shown in the merchant onboarding use case above. This request is an orchestration of multiple calls into one but still follows the requirements mentioned in the main documentation for each resource. Please note that the access token must be valid for more than 30 seconds for this orchestration to take place.
The following resources are supported:
| Resource | Description |
|---|---|
| merchant (required) | This is the main resource to which everything is related to. This must be provided at the top-level. |
| merchantAddendum | The merchant addendum is related to the merchant and can be provided as part of the merchant resource. |
| merchantAddendumUsa | The USA merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for USA merchants. |
| merchantAddendumColombia | The Colombia merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for Colombia merchants. |
| clientReferences | The client references are related to the merchant and can be provided as an array and part of the merchant resource. |
| merchantTaxStatus | The tax types assigned to the merchant and their current status. |
| addresses (required) | The addresses are related to the merchant and must be provided as an array and part of the merchant resource. |
| contracts (required) | The contract is related to the merchant and must be provided as a single-element array and part of the merchant resource. clientLevel attribute should be set to 001 (Member level). |
| services | The services are linked to a merchant through the contract and can be provided as an array and part of the contract resource. |
| riskRuleParameters | The risk rule parameters defined specifically for the merchant linked through the contract and can be provided as an array and part of the contract resource. |
| settlementPackages (required) | The settlement packages are related to the merchant and can be provided as an array and part of the merchant resource. |
| mandateInformation | A signed authorization (issued in a paper or electronic format) for SEPA direct debit payment in EURO currency given to the creditor by the debtor. It can be provided related to settlement package. |
| paymentInstructions | The payment instructions are linked to a merchant through the account. |
| accounts (required) | Accounts can be defined at two different levels:
|
For further details on the resources to be provided in the request, please refer to the individual requests in the merchant onboarding use case above.
In case of a successful onboarding, all the merchant data (including the generated IDs) will be retrieved and returned.
In case there are any errors, any successful resources created prior to the failing resource will be reverted and another merchant application with the correct data must be sent again. In order to identify the problematic resource which has thrown the error, make sure to refer to the pointer value found inside the meta element of the corresponding error. This will contain the path of the resource in error (if any). In cases where the resource is part of an array, a zero-based index will be included to identify the specific resource.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantApplications
Request Headers
| Content-Type | application/vnd.api+json |
|---|---|
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
Request Body
Response
HTTP 201 (Created)
Payfac Standard Sub-Merchants
BankWORKS offers the possibility of onboarding sub-merchants linked to a payment facilitator merchant aggregator account.
In order to onboard sub-merchants the payment facilitator should have a merchant set-up at the group level of the merchant hierarchy. Payment facilitator merchants (sub-merchants) can be onboarded underneath the group level merchant, by following a top-down approach.
The following use cases provide a sample flow as to how:
- The payment facilitator merchant and it’s respective contract can be identified.
- With that contract known a sub-merchant may be onboarded underneath the payment facilitator hiearchy.
- Definition the sub-merchant to payment facilitator client relation.
Sub-merchants can be defined as member level clients directly underneath the group (payment facilitator client) or else they can be defined underneath sub-merchant subgroup clients. In the case of a sub-group the parent contract of the sub-group must be used to link any child sub-merchant nodes.
Note: For Amex OptBlue sub-merchants additional steps to register authorized signers and beneficiary owners are required. Please review the Amex OptBlue use case section for more information.
1 Get payfac contract
Returns the contracts belonging to a paymetn facilitator merchant (client type 023), an alternative to this filter may be the merchant ID (merchant.ourReference) for a more direct search of the payment facilitator merchant. Contracts are further filtered by effective date and clientLevel set at group level. Results are sorted by effective date and group number and a single resource per page is returned in case there are older contract records related to the payment facilitator merchant.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contracts?include=merchant&filter[merchant.clientType]=023&filter[clientLevel]=002&filter[effectiveDate][LE]=2024-04-30&filter[contracts][status]=001&sort=groupNumber,-effectiveDate&page[limit]=1&fields[contracts]=clientLevel,groupNumber&fields[merchants]=clientNumber
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| include | merchant |
|---|---|
| filter[merchant.clientType] | 023 |
| filter[clientLevel] | 002 |
| filter[effectiveDate][LE] | 2024-04-30 |
| filter[contracts][status] | 001 |
| sort | groupNumber,-effectiveDate |
| page[limit] | 1 |
| fields[contracts] | clientLevel,groupNumber |
| fields[merchants] | clientNumber |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type kycClients with merchantas included resources.
2.1 Sub-Merchant -> Sub-Group
Sub-merchants at sub-group level are defined in order to set up an intermediate level between the payment facilitator level and the transacting sub-merchant (member) level merchants. Sub-groups may be linked to either the payment facilitator contract via parentContracts, or else to another sub-group. This is similar to how merchant hiearchies are defined.
This call creates and processes a merchant application in a single request through the API gateway without the need to send individual creation and, in case of failure, revert requests as shown in the merchant onboarding use case above. This request is an orchestration of multiple calls into one but still follows the requirements mentioned in the main documentation for each resource. Please note that the access token must be valid for more than 30 seconds for this orchestration to take place.
The following resources are supported:
| Resource | Description |
|---|---|
| merchant (required) | This is the main resource to which everything is related to. This must be provided at the top-level. |
| merchantAddendum | The merchant addendum is related to the merchant and can be provided as part of the merchant resource. |
| merchantAddendumUsa | The USA merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for USA merchants. |
| merchantAddendumColombia | The Colombia merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for Colombia merchants. |
| clientReferences | The client references are related to the merchant and can be provided as an array and part of the merchant resource. |
| merchantTaxStatus | The tax types assigned to the merchant and their current status. |
| addresses (required) | The addresses are related to the merchant and must be provided as an array and part of the merchant resource. |
| contracts (required) | The contract is related to the merchant and must be provided as a single-element array and part of the merchant resource. clientLevel attribute should be set to 003 (Sub-group level). |
| services | The services are linked to a merchant through the contract and can be provided as an array and part of the contract resource. |
| riskRuleParameters | The risk rule parameters defined specifically for the merchant linked through the contract and can be provided as an array and part of the contract resource. |
| settlementPackages | The settlement packages are related to the merchant and can be provided as an array and part of the merchant resource. |
| mandateInformation | A signed authorization (issued in a paper or electronic format) for SEPA direct debit payment in EURO currency given to the creditor by the debtor. It can be provided related to settlement package. |
| paymentInstructions | The payment instructions are linked to a merchant through the account. |
| accounts (required) | Accounts can be defined at two different levels: 1. billing level - can be passed as an array and part of the respective settlementPackage resource 2. non-billing level - can be passed as an array and part of the contract resource |
For further details on the resources to be provided in the request, please refer to the individual requests in the merchant onboarding use case above.
In case of a successful onboarding, all the merchant data (including the generated IDs) will be retrieved and returned.
In case there are any errors, any successful resources created prior to the failing resource will be reverted and another merchant application with the correct data must be sent again. In order to identify the problematic resource which has thrown the error, make sure to refer to the pointer value found inside the meta element of the corresponding error. This will contain the path of the resource in error (if any). In cases where the resource is part of an array, a zero-based index will be included to identify the specific resource.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantApplications
Request Headers
| Content-Type | application/vnd.api+json |
|---|---|
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
Request Body
Response
2.2 Sub-Merchant -> Member
Member level sub-merchants are the transaction level merchants, at the outlet level. These sub-merchants may either be linked to a sub-group sub-merchant contract or group level payment facilitator merchant contract, depending on the hierarchical structure.
This call creates and processes a merchant application in a single request through the API gateway without the need to send individual creation and, in case of failure, revert requests as shown in the merchant onboarding use case above. This request is an orchestration of multiple calls into one but still follows the requirements mentioned in the main documentation for each resource. Please note that the access token must be valid for more than 30 seconds for this orchestration to take place.
The following resources are supported:
| Resource | Description |
|---|---|
| merchant (required) | This is the main resource to which everything is related to. This must be provided at the top-level. |
| merchantAddendum | The merchant addendum is related to the merchant and can be provided as part of the merchant resource. |
| merchantAddendumUsa | The USA merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for USA merchants. |
| merchantAddendumColombia | The Colombia merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for Colombia merchants. |
| clientReferences | The client references are related to the merchant and can be provided as an array and part of the merchant resource. |
| merchantTaxStatus | The tax types assigned to the merchant and their current status. |
| addresses (required) | The addresses are related to the merchant and must be provided as an array and part of the merchant resource. |
| contracts (required) | The contract is related to the merchant and must be provided as a single-element array and part of the merchant resource. clientLevel attribute should be set to 001 (Member level). |
| services | The services are linked to a merchant through the contract and can be provided as an array and part of the contract resource. |
| riskRuleParameters | The risk rule parameters defined specifically for the merchant linked through the contract and can be provided as an array and part of the contract resource. |
| settlementPackages (required) | The settlement packages are related to the merchant and can be provided as an array and part of the merchant resource. |
| mandateInformation | A signed authorization (issued in a paper or electronic format) for SEPA direct debit payment in EURO currency given to the creditor by the debtor. It can be provided related to settlement package. |
| paymentInstructions | The payment instructions are linked to a merchant through the account. |
| accounts (required) | Accounts can be defined at two different levels: 1. billing level - can be passed as an array and part of the respective settlementPackage resource 2. non-billing level - can be passed as an array and part of the contract resource |
For further details on the resources to be provided in the request, please refer to the individual requests in the merchant onboarding use case above.
In case of a successful onboarding, all the merchant data (including the generated IDs) will be retrieved and returned.
In case there are any errors, any successful resources created prior to the failing resource will be reverted and another merchant application with the correct data must be sent again. In order to identify the problematic resource which has thrown the error, make sure to refer to the pointer value found inside the meta element of the corresponding error. This will contain the path of the resource in error (if any). In cases where the resource is part of an array, a zero-based index will be included to identify the specific resource.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantApplications
Request Headers
| Content-Type | application/vnd.api+json |
|---|---|
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
Request Body
Response
3 Sub-merchant to payfac client relation
Definition of the sub-merchant to payment facilitator linkage. The sourceClient should contain the clientNumber value of the new-sub merchant.
The destinationClient should contain the clientNumber of the payment facilitator group level merchant.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/clientRelations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type clientRelations with the following attributes:
| Name | Description | |
|---|---|---|
|
sourceClient
string (8)
required
|
The source client number of the virtual link. |
|
|
destinationClient
string (8)
required
|
The destination client number of the virtual link. |
|
|
linkType
string (3)
required
|
Indicates the link type of the virtual link record such as:
Refer to API Data Mapping documentation for other possible values. |
|
|
status
string (3)
|
The current status of the virtual link.
Refer to API Data Mapping documentation for other possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the virtual link becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, the current posting date is automatically assumed. |
|
Response
Response body will contain the created JSON:API resource of type clientRelations .
Standalone Merchant - Single Request Onboarding
This call creates and processes a merchant application in a single request through the API gateway without the need to send individual creation and, in case of failure, revert requests as shown in the merchant onboarding use case above. This request is an orchestration of multiple calls into one but still follows the requirements mentioned in the main documentation for each resource. Please note that the access token must be valid for more than 30 seconds for this orchestration to take place.
The following resources are supported:
| Resource | Description |
|---|---|
| merchant (required) | This is the main resource to which everything is related to. This must be provided at the top-level. |
| merchantAddendum | The merchant addendum is related to the merchant and can be provided as part of the merchant resource. |
| merchantAddendumUsa | The USA merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for USA merchants. |
| merchantAddendumColombia | The Colombia merchant addendum is related to the merchant and can be provided as part of the merchant resource. This is applicable only for Colombia merchants. |
| clientReferences | The client references are related to the merchant and can be provided as an array and part of the merchant resource. |
| merchantTaxStatus | The tax types assigned to the merchant and their current status. |
| addresses (required) | The addresses are related to the merchant and must be provided as an array and part of the merchant resource. |
| contracts (required) | The contract is related to the merchant and must be provided as a single-element array and part of the merchant resource. |
| services | The services are linked to a merchant through the contract and can be provided as an array and part of the contract resource. |
| riskRuleParameters | The risk rule parameters defined specifically for the merchant linked through the contract and can be provided as an array and part of the contract resource. |
| settlementPackages | The settlement packages are related to the merchant and can be provided as an array and part of the merchant resource. |
| mandateInformation | A signed authorization (issued in a paper or electronic format) for SEPA direct debit payment in EURO currency given to the creditor by the debtor. It can be provided related to settlement package. |
| paymentInstructions | The payment instructions are linked to a merchant through the account. |
| accounts (required) | Accounts can be defined at two different levels:
|
For further details on the resources to be provided in the request, please refer to the individual requests in the merchant onboarding use case above.
In case of a successful onboarding, all the merchant data (including the generated IDs) will be retrieved and returned.
In case there are any errors, any successful resources created prior to the failing resource will be reverted and another merchant application with the correct data must be sent again. In order to identify the problematic resource which has thrown the error, make sure to refer to the pointer value found inside the meta element of the corresponding error. This will contain the path of the resource in error (if any). In cases where the resource is part of an array, a zero-based index will be included to identify the specific resource.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantApplications
Request Headers
| Content-Type | application/vnd.api+json |
|---|---|
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
Request Body
Response
Logic Validation Error : HTTP 403 (Forbidden)
Attribute Validation Error : HTTP 422 (Unprocessable Entity (WebDAV) (RFC 4918))
Appl Proc Error : HTTP 422 (Unprocessable Entity (WebDAV) (RFC 4918))
Single Request - Successful : HTTP 201 (Created)
CardSchemeAddendum Integration : HTTP 201 (Created)
Risk Rule Parameter Integration (Single Request) : HTTP 201 (Created)
Merchant Entity Move
This use case is for moving a Merchant entity to a new client (also a Merchant type).
Please see Merchant Move request for more details.
Get Old Merchant
This is a sample request to retrieve and store the old merchant. This will provide the oldClientId variable as an example in the next request for entity move.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants?filter[clientNumber]=00000199&fields=id
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[clientNumber] | 00000199 |
|---|---|
| fields | id |
Response
HTTP 200 (OK)
Merchant Move
This call will make an entity move from old client to a new client. Both should be under Merchant client type and should have the same MID (merchant ID - which can be found in merchants.ourReference attribute). It is also assumed that both merchants are successfully boarded during this stage.
If this use case is performed right after the new merchant is boarded successfully, the newClientId (as an example variable) can be retrieved from the last PATCH call for merchant application onboarding.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchants/{{newClientId}}/relationships/originalMerchant
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
Response
HTTP 204 (No Content)
Confirm Entity Links
This call will retrieve the entity link between old and new client created by entity move request previously executed to confirm a successful entity move.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/{{newClientId}}?include=originalMerchant&fields=companyName
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| include | originalMerchant |
|---|---|
| fields | companyName |
Response
HTTP 200 (OK)
Closing a link
This call will close any active link of the merchant ID provided in the URL endpoint.
A null value for originating merchant should be passed in order to trigger this closure.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchants/{{newClientId}}/relationships/originalMerchant
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
Response
Broker Boarding
This contains sequential onboarding calls for a Broker or Partner.
IMPORTANT NOTE:
- In cases where a broker or a partner needs to onboard a merchant or another broker underneath its level or hierarchy, a link will be automatically established (in the background) during onboarding a child entity via the last API call of this section or of Merchant Onboarding.
- It is assumed that broker already have user access rights to our APIs for him to onboard child entities underneath its level. Once a link has been established, the parent broker should only have access rights to his profile and the child entities onboarded by him.
1. Create Broker
This will create main details of a Broker / Partner.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/brokers
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type brokers with the following attributes:
| Name | Description | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
clientNumber
string (8)
|
8-digit BankWORKS client number that is unique per institution. System generated if not provided during new broker definition. A unique number must be provided if user defined. |
|||||||||||
|
clientType
string (3)
required
|
Indicates the broker’s client type. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||
|
shortName
string (26)
|
Broker’s short name. If not provided during broker creation, the tradeName value will be used. |
|||||||||||
|
companyName
string (45)
required
|
The broker company name. |
|||||||||||
|
tradeName
string (40)
required
|
The name under which the company is trading. |
|||||||||||
|
registrationNumber
string (15)
|
The broker registration number. |
|||||||||||
|
language
string (3)
required
|
Broker’s language. Refer to API Data Mapping documentation for account definitions available for the institution. |
|||||||||||
|
legalForm
string (3)
required
|
Related to the legal form of the broker, such as:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||
|
businessClass
string (4)
|
The ISO 4-digit business classification code. Refer to API Data Mapping documentation for account definitions available for the institution. |
|||||||||||
|
vatRegistrationNumber
string (15)
|
A reference number used for clearing purposes. |
|||||||||||
|
mainContactDetails
object
|
|
|||||||||||
|
rbsClientNumber
string (20)
|
External broker reference number. ^\d*$ |
|||||||||||
|
website
string (100)
|
Broker website address details. |
|||||||||||
|
taxCountry
string (3)
required
|
The ISO 3-letter country code of the broker’s country for tax information. In cases where value consists of 3 digits:
Refer to API Data Mapping documentation for account definitions available for the institution. |
|||||||||||
| Relationships | ||||||||||||
Response
Response body will contain the created JSON:API resource of type brokers .
2. Create Standalone Broker Contract
Creation of a partner contract. This is only for standalone partners such as those who do not belong in a partner hierarchy.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/contracts
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type contracts with the following attributes:
| Name | Description | |
|---|---|---|
|
status
string (3)
|
Indicates the status of the client contract. If not provided, this will be defaulted to 001 (Active). Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientLevel
string (3)
required
|
Indicates the BankWORKS hierarchical level for the client contract. The following values are possible:
|
|
|
effectiveDate
date-only
|
The date in ISO 8601 format on which the hierarchy link record becomes effective for the client. The value can be future dated and cannot be less than the posting date. If not provided, posting date +1 value is assumed only post-boarding. |
|
|
settlementMethod
string (3)
required
|
Indicates the method how the client will settle with the bank. Identifies how outstanding balances are settled. Required only when onboarding a new client. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
postingMethod
string (3)
|
The tariff under which the client falls when posting to the clients account. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientTariff
string (6)
required
|
Indicates the client tariff package assigned. Required only when onboarding a new client. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
transactionChargesTariff
string (6)
|
Indicates the applicable transaction charges tariff. Transaction charges are represented as productChargeDefinitions. This is an optional field and if not provided will default to not applicable 000000. If a tariff value is provided, the merchant services clientTariff value will not apply. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
chargeTierLevel
string (3)
|
Enables setting up of the same fee with different value high and value low triggers. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientScheme
string (6)
|
Indicates the rebate tariff applicable for the contract. |
|
|
contractReference
string (8)
|
Merchant contract document reference. |
|
|
bankReference
string (8)
|
External additional reference number of the merchant with the bank. |
|
|
institutionAccountOfficer
string (3)
|
Officer in charge of the client contract. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientBranch
string (3)
|
Contract application branch details. Related to the institutionAccountOfficer. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
tierGroup
string (3)
|
An identifier used to group a set of rates that need to be applied during tiered pricing generation. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
entityId
string (3)
|
Entity identifier used to split GL entries and transactions generated for financial activity in a single processing institution across multiple legal entities. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
riskRuleGroupId
string (3)
|
Identifier for the set of rules applies in the risk module. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
|
contractDefinition
required |
Link to a broker contract definition. These are available as business rules. |
|
|
broker
required |
Link to the broker resource ID previously defined in the broker resource creation stage. |
|
|
parentContracts
|
Links to the parent contract, one level up the client hierarchy. The parent contract will have the current effective data as well as past or possible future effective iterations. The current effective can be determined by the effectiveDate value. |
|
|
riskRuleParameters
|
One or more risk rule parameters this client contract is linked to. |
|
Response
Response body will contain the created JSON:API resource of type contracts .
3. Create Settlement Package
This will define the settlement information including RBS bank account number of the broker and is MANDATORY only if a billing level account is to be created.
Multiple settlement information/package can be added (up to 99). This number will be set automatically and stored in settlementNumber as part of the resource ID.
For settlementPackages with related fundingClient, it is to be associated in the relationship from the request apart from broker relationship/linkage:
"fundingClient": {
"data": {
"type": "fundingClients",
"id": "{{fundingClientId}}"
}
}
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/settlementPackages
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
Response
4. Create Broker Account
This call is to create a broker account in BankWorks. This can be a billing or non-billing account.
Relationships associated with accounts should also include the following:
- broker contract obtained from the previous call
- accountDefinition obtained from Business Setup Configuration - Account & Service Definitions.
settlementPackages is only required to be passed if account is in billing level.
"settlementPackage": { "data": { "type": "settlementPackages", "id": "clientNumber=10050000&settlementNumber=01" } }
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/accounts
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
Response
5. Create Standard Address
Creation of broker / partner addresses. Minimum requirement for broker address creation:
- should create at least one Standard address (addressCategory 001)
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/addresses
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
Response
6. Create Service
Creation of broker / partner services. This call is optional.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/services
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
Response
7. Process Application
This call will onboard a broker or partner in BankWorks in Active (001) status.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/brokers/{{brokerId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
Response
Client Information
The client information section provides sample requests for managing any resource attributed to BankWORKS clients. In a BankWORKS a client is a term covering a number of third parties that would be linked to an insitution grouped into broad collections of client types. For example: - Merchants: All institution clients with acquiring capabilities for example, traditional merchants, ecommerce merchants, sole traders etc. - Brokers: Third party service that act between a merchant and institution reselling or providing a subset of the acquirer institution services offerred. A typical example would be an ISO client.
Merchants
A collection of request examples related to the merchant client. In BankWORKS a merchant client is broad term encompassing clients with transaction acquiring capabilities for example standard merchants, sole traders etc.
List of Merchants
This call retrieves a list of available merchants. It is possible request a specific list of merchant attributes, filter the list and sort by sending additional URL parameters.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants?include=clientRelations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| include | clientRelations |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type merchants with clientRelationsas included resources.
Merchant Search
The merchant resource may be filtered either directly using any of the available merchant attributes, or by filtering on the available relationship attributes. In this example request, merchants having an address in Malta are being returned. Furthermore, we are simplyfing the response by requesting only the tradeName, clientNumber and status attributes with the merchant resource. The country, postCode and state attributes of the addresses are being returned with the addresses resource included in the response.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants?include=addresses&filter[addresses.country]=CAN&fields[merchants]=clientNumber,status,tradeName&fields[addresses]=postCode,state,country
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| include | addresses |
|---|---|
| filter[addresses.country] | CAN |
| fields[merchants] | clientNumber,status,tradeName |
| fields[addresses] | postCode,state,country |
Response
HTTP 200 (OK)
Response body will contain the result of the JSON PATCH operation for the following resources: merchants addresses
Modify a Merchant
A request to modify a merchant properties. Refer to the list of amendable attributes provided for reference.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchants with the following attributes:
| Name | Description | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
status
string (3)
|
Indicates the current state of the merchant. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
clientType
string (3)
|
Indicates the merchant’s client type. If not provided during merchant creation, it will be defaulted to 002 (Merchant). Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
shortName
string (26)
|
Merchant’s short name. If not provided during merchant creation, the tradeName value will be used. |
|||||||||||||
|
firstName
string (15)
|
First name of the merchant owner. For the USA market this would be the first name of the owner if the merchant is a sole proprietor. Required for USA merchants with legalForm of 029 - Sole Proprietor. |
|||||||||||||
|
middleName
string (15)
|
Middle name of the merchant owner. For USA merchants having a legalform of 029 - Sole Proprietor, the middleName would be used to store the middle initial followed by a full-stop (.) as per the Visa Acquirer Merchant Master File requirements. |
|||||||||||||
|
lastName
string (26)
|
Last name of the merchant owner. For the USA market this would be the last name of the owner if the merchant is a sole proprietor. Required for USA merchants with legalForm of 029 - Sole Proprietor. |
|||||||||||||
|
companyName
string (45)
|
The merchant company name. |
|||||||||||||
|
tradeName
string (25)
|
The name under which the company is trading. |
|||||||||||||
|
registrationNumber
string (15)
|
The merchant registration number. |
|||||||||||||
|
vatRegion
string (3)
|
Merchant’s VAT region. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
language
string (3)
|
Merchant’s language. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
legalForm
string (3)
|
Related to the legal form of the merchant. Such as:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
businessClass
string (4)
|
The ISO 4-digit business classification code. |
|||||||||||||
|
vatRegistrationNumber
string (15)
|
Merchant’s VAT number. |
|||||||||||||
|
ourReference
string (20)
|
A reference number used for clearing purposes, typically the merchant ID. |
|||||||||||||
|
domesticMcc
string (4)
|
The ISO 4-digit domestic merchant category code. |
|||||||||||||
|
mainContactDetails
object
|
Object grouping main merchant contact information.
|
|||||||||||||
|
rbsClientNumber
string (20)
|
External merchant reference number. |
|||||||||||||
|
website
string (100)
|
Merchant website address details. |
|||||||||||||
|
eCommerceIndicator
string (3)
|
Indicates if the merchant business is eCommerce based or a traditional business. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
processingRegion
string (3)
|
Defines the processing region of the merchant. Used for transaction processing. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
taxRegion
string (3)
|
Merchant’s tax region. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||
|
taxCountry
string (3)
|
The ISO 3-letter country code of the merchant’s country for tax information. In cases where value consists of 3 digits:
|
|||||||||||||
| Relationships | ||||||||||||||
|
merchantAddendumColombia
|
Additional attributes specifically for merchants based in Colombia. |
|||||||||||||
|
clientMappings
|
All client mappings available related to the merchant. |
|||||||||||||
|
originalMerchant
|
This is the originating (old) merchant for which this merchant has been moved from. This is only done via PATCH request. Please see Merchant Entity Move use case for proper usage. |
|||||||||||||
|
clientRelations
|
All virtual links related to the merchant. |
|||||||||||||
|
merchantTaxStatus
|
All tax status records related to the merchant. |
|||||||||||||
|
disputeCases
|
All dispute cases related to the merchant. |
|||||||||||||
|
kycClients
|
All KYC/AML clients related to the merchant. |
|||||||||||||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type merchants .
Merchant Addendum Data
A collection requests on the merchant additional data resources which may contain a number of additional prorties, flags and reference values for a merchant: - merchantsAddendum - merchantsAddendum - clientReferences
Retrieve Addendum Data
Retrieve generic merchant addiditional data. A merchant may have one addendum record available.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000/merchantAddendum
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
Retrieve Addendum Data - Successful 1 : HTTP 200 (OK)
Retrieve Addendum Data - Successful 2 : HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type merchantsAddendum .
Modify Addendum Data
A request to modify a merchant properties. Refer to the list of amendable attributes provided for reference.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchantsAddendum/clientNumber=10050000
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantsAddendum with the following attributes:
| Name | Description | |
|---|---|---|
|
seasonalMerchant
string (3)
|
Flag to indicate if the merchant is a seasonal merchant or not. Such as:
Refer to BankWorks (API) Data Mapping documentation for possible values.) |
|
|
feeProgramIndicator
string (3)
|
The fee program indicator used for the VISA Base 2 clearing file. |
|
|
visaInterchangeProgram
string (10)
|
Stores the value of the Visa interchange program value. |
|
|
visaInterchangeProgramQualification
string (3)
|
The ISO 3-digits used to determine the tier of the interchange. |
|
|
mastercardInterchangeProgram
string (10)
|
Stores the value of the MasterCard AID. |
|
|
mastercardInterchangeProgramQualification
string (3)
|
The ISO 3-digits used to determine the tier of the interchange. |
|
|
socialSecurityNumber
string (9)
|
This attribute will contain the SSN, and it is required for Discover. It is also required when the The value of this attribute in the response will always be returned in masked format. |
|
|
vatTaxIndicator
string (6)
|
Tax tariff that will be charged to merchant related to merchant VAT. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
municipalCode
string (7)
|
The municipality code of the place where the transaction occurred. |
|
|
merchantCountryOfOrigin
string (3)
|
Mastercard requirement for government owned merchants. The country of origin for government-controlled merchants must always be populated. This includes when the government-controlled merchant’s home country is the country where the government-controlled merchant is physically located and when the government-controlled merchant’s home country is not the country where the government-controlled merchant is physically located. The format is in ISO 3-letter country code. E.g. NZL (New Zealand) Refer to API Data Mapping documentation for account definitions available for the institution. |
|
|
url
string (76)
|
The merchant’s main website address. This value is also required for merchants acquiring MasterCard eCommerce and in case there is no main service telephone number (mainContactDetails.serviceTelephone). |
|
|
independentSalesOrganisation
string (11)
|
Independent Sales Organisation ID value provided by Mastercard. This value is equivalent to the merchantsAddendumUsa.independentSalesOrganisation attribute. |
|
| Relationships | ||
Response
Modify Addendum Data - Successful 1 : HTTP 200 (OK)
Modify Addendum Data - Successful 2 : HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type merchantsAddendum .
Create Addendum Data
A request to create a merchant addendum data record. A merchant can only have one merchantsAddendum resource, which can also be defined during merchant onboarding stage.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantsAddendum
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantsAddendum with the following attributes:
| Name | Description | |
|---|---|---|
|
seasonalMerchant
string (3)
|
Flag to indicate if the merchant is a seasonal merchant or not. Such as:
Refer to BankWorks (API) Data Mapping documentation for possible values.) |
|
|
feeProgramIndicator
string (3)
|
The fee program indicator used for the VISA Base 2 clearing file. |
|
|
visaInterchangeProgram
string (10)
|
Stores the value of the Visa interchange program value. |
|
|
visaInterchangeProgramQualification
string (3)
|
The ISO 3-digits used to determine the tier of the interchange. |
|
|
mastercardInterchangeProgram
string (10)
|
Stores the value of the MasterCard AID. |
|
|
mastercardInterchangeProgramQualification
string (3)
|
The ISO 3-digits used to determine the tier of the interchange. |
|
|
socialSecurityNumber
string (9)
|
This attribute will contain the SSN, and it is required for Discover. It is also required when the The value of this attribute in the response will always be returned in masked format. |
|
|
vatTaxIndicator
string (6)
|
Tax tariff that will be charged to merchant related to merchant VAT. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
municipalCode
string (7)
|
The municipality code of the place where the transaction occurred. |
|
|
merchantCountryOfOrigin
string (3)
|
Mastercard requirement for government owned merchants. The country of origin for government-controlled merchants must always be populated. This includes when the government-controlled merchant’s home country is the country where the government-controlled merchant is physically located and when the government-controlled merchant’s home country is not the country where the government-controlled merchant is physically located. The format is in ISO 3-letter country code. E.g. NZL (New Zealand) Refer to API Data Mapping documentation for account definitions available for the institution. |
|
|
url
string (76)
|
The merchant’s main website address. This value is also required for merchants acquiring MasterCard eCommerce and in case there is no main service telephone number (mainContactDetails.serviceTelephone). |
|
|
independentSalesOrganisation
string (11)
|
Independent Sales Organisation ID value provided by Mastercard. This value is equivalent to the merchantsAddendumUsa.independentSalesOrganisation attribute. |
|
| Relationships | ||
|
merchant
required |
Merchant related to the addendum record. |
|
Response
Create Addendum Data - Successful 1 : HTTP 201 (Created)
Create Addendum Data - Successful 2 : HTTP 201 (Created)
Response body will contain the created JSON:API resource of type merchantsAddendum .
Delete Addendum
Delete a generic merchant addendum resource.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/merchantsAddendum/clientNumber=10050000
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 204 (No Content)
Retrieve Addendum USA Data
Retrieve USA regional merchant addiditional data. This optional resource might be required for certain USA based merchants.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000/merchantAddendumUsa
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type merchantsAddendumUsa .
Modify Addendum USA Data
A request to modify a merchant properties. Refer to the list of amendable attributes provided for reference.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchantsAddendumUsa/clientNumber=00000068
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantsAddendumUsa with the following attributes:
| Name | Description | |
|---|---|---|
|
url
string (76)
|
Merchant URL information. |
|
|
independentSalesOrganisation
string (11)
|
Independent Sales Organisation ID value provided by Mastercard. This value is equivalent to the merchantsAddendum.independentSalesOrganisation attribute. |
|
|
taxId
string (9)
|
TAX ID/TIN number used by the IRS. Requirement of the 1099k form report. This is required when the
|
|
|
taxIdNumberType
string (3)
|
Indicates the type of TAX ID/TIN number used by the IRS. Requirement of the 1099k form report. When this is set to 002 SSN, the |
|
|
information
string (200)
|
Information about what product/services are sold by the merchant. |
|
|
visaInternationalAcquirerFeeFlag
string (3)
|
Flag indicating whether the Visa International Acquirer Fee is to be posted to client rather than institution account. Such as:
|
|
|
federalTaxTariff
string (6)
|
Indicates the Federal tax fee tariff. |
|
| Relationships | ||
Response
Modify Addendum USA Data - Error : HTTP 422 (Unprocessable Entity)
Modify Addendum USA Data - Successful : HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type merchantsAddendumUsa .
Create Addendum USA Data
A request to create a merchant addendum USA data record. A merchant can only have one merchantsAddendumUSA resource, which can also be defined during merchant onboarding stage. This would apply only for USA region merchants.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantsAddendumUsa
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantsAddendumUsa with the following attributes:
| Name | Description | |
|---|---|---|
|
url
string (76)
|
Merchant URL information. |
|
|
independentSalesOrganisation
string (11)
|
Independent Sales Organisation ID value provided by Mastercard. This value is equivalent to the merchantsAddendum.independentSalesOrganisation attribute. |
|
|
taxId
string (9)
|
TAX ID/TIN number used by the IRS. Requirement of the 1099k form report. This is required when the
|
|
|
taxIdNumberType
string (3)
|
Indicates the type of TAX ID/TIN number used by the IRS. Requirement of the 1099k form report. When this is set to 002 SSN, the |
|
|
information
string (200)
|
Information about what product/services are sold by the merchant. |
|
|
visaInternationalAcquirerFeeFlag
string (3)
|
Flag indicating whether the Visa International Acquirer Fee is to be posted to client rather than institution account. Such as:
|
|
|
federalTaxTariff
string (6)
|
Indicates the Federal tax fee tariff. |
|
| Relationships | ||
|
merchant
required |
Addendum record for merchant based in USA. |
|
Response
Create Addendum USA Data - Error 1 : HTTP 500 (Internal Server Error)
Create Addendum USA Data - Error 2 : HTTP 422 (Unprocessable Entity)
Create Addendum USA Data - Successful : HTTP 201 (Created)
Response body will contain the created JSON:API resource of type merchantsAddendumUsa .
Delete Addendum USA
Delete a USA regional merchant addendum resource.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/merchantsAddendum/clientNumber=00000068
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 204 (No Content)
Retrieve Addendum Colombia
Retrieve Colombian merchant additional data that is related to merchant taxes. This optional resource might be required for certain Colombian based merchants.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000/merchantAddendumColombia
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type merchantsAddendumColombia .
Modify Addendum Colombia
A request to modify a Colombian merchant’s additional properties. Refer to the list of amendable attributes provided for reference.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchantsAddendumColombia/{{merchantsAddendumColombiaId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantsAddendumColombia with the following attributes:
| Name | Description | |
|---|---|---|
|
department
string (3)
|
Indicates the department code of the merchant that will be used for calculation of merchant tax ReteICA (Municipality Tax). Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
municipalCode
string (5)
|
Indicates the municipal code of the merchant that will be used for calculation of merchant tax ReteICA (Municipality Tax). Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
municipalTaxIndicator
boolean
|
This is used if the merchant will be charged with the municipality tax (ReteICA). |
|
|
incomeTaxIndicator
string (6)
|
Tax tariff that will be charged to merchant related to merchant income (ReteFuente). |
|
|
vatTaxIndicator
string (6)
|
Tax tariff that will be charged to merchant related to merchant VAT (ReteIVA). |
|
| Relationships | ||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type merchantsAddendumColombia .
Create Addendum Colombia
A request to create a Colombian merchant’s addendum data record. A merchant can only have one merchantsAddendumColombia resource, which can also be defined during merchant onboarding stage. This would only apply for Colombian and already onboarded merchants.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantsAddendumColombia
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantsAddendumColombia with the following attributes:
| Name | Description | |
|---|---|---|
|
department
string (3)
|
Indicates the department code of the merchant that will be used for calculation of merchant tax ReteICA (Municipality Tax). Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
municipalCode
string (5)
|
Indicates the municipal code of the merchant that will be used for calculation of merchant tax ReteICA (Municipality Tax). Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
municipalTaxIndicator
boolean
|
This is used if the merchant will be charged with the municipality tax (ReteICA). |
|
|
incomeTaxIndicator
string (6)
|
Tax tariff that will be charged to merchant related to merchant income (ReteFuente). |
|
|
vatTaxIndicator
string (6)
|
Tax tariff that will be charged to merchant related to merchant VAT (ReteIVA). |
|
| Relationships | ||
|
merchant
required |
Merchant information related to addendum record. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type merchantsAddendumColombia .
Delete Addendum Colombia
Delete Colombian merchant addendum identified by an ID. This is only allowed for merchants that are not yet on-boarded.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/merchantsAddendumColombia/{{merchantsAddendumColombiaId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 204 (No Content)
Get Client Reference
Retrieval of all available merchant client reference values.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000/clientReferences
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type clientReferences .
Update Client Reference
Amend the value of an existing client reference property.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/clientReferences/{{clientReferenceId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type clientReferences with the following attributes:
| Name | Description | |
|---|---|---|
|
referenceValue
string (36)
|
Value of client reference. E.g. 1234000-ABC |
|
| Relationships | ||
Response
HTTP 201 (Created)
Response body will contain the updated JSON:API resource of type clientReferences .
Create Client Reference
Creation of a new client reference value for a merchant.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/clientReferences
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type clientReferences with the following attributes:
| Name | Description | |
|---|---|---|
|
referenceType
string (3)
required
|
Identifies the type of institution-specific client reference type. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
referenceValue
string (36)
|
Value of client reference. E.g. 1234000-ABC |
|
| Relationships | ||
|
merchant
required |
The merchant owner of the reference property. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type clientReferences .
Delete Client Reference
Delete a client reference resource.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/clientReferences/{{clientReferenceId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
Funding Clients
This section concerns funding information. In BankWORKS, funding clients represent the funding banks from which an institution may set up as a source of funds for merchant settlement. Funding banks are represented as clients in BankWORKS, categorised differently from other clients such as merchants.
Get a list of funding clients
Retrieve a full list of available funding clients. Funding clients may be used to link merchant settlement information to a funding bank. This may apply to both merchant boarding and client servicing scenarios.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/fundingClients
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type fundingClients .
Search for a funding client
An example search request for funding clients by companyName. Any desired attribute of a fundingClients resource may be used. This request can help identify a funding bank by using one or more attributes for filtering. Funding clients may be used to link merchant settlement information to a funding bank. This may apply to both merchant boarding and client servicing scenarios.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/fundingClients?filter[fundingClients][companyName]=ABC Bank
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Parameters
| filter[fundingClients][companyName] | ABC Bank |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type fundingClients .
Brokers
Various request examples related to an institution broker client. The broker client is broad categorisation of various client types that represent third parties working in partnership with the institution. Examples would include ISOs with merchant onboarding and servicing capabilities etc.
Broker Search
An example request of broker search by an attribute. Brokers may be filtered by one or more attributes. Depending on the filtering criteria and uniquess of the attributes selected, a list or a single broker may be returend. It is possible to filter by relationship attributes as well as request a specific response format by selecting the desired attributes as well sort by attribute(s).
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/brokers?filter[companyName]=Test
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[ourReference] | {{MID}} |
|---|---|
| filter[companyName] | Test |
Response
Response body will contain the requested JSON:API resource of type brokers .
List of Brokers
This call retrieves a list of available institution brokers. It is possible request a specific list of broker attributes using sparse fieldsets, filter the list and sort by sending additional URL parameters.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/brokers?include=clientRelations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| include | clientRelations |
|---|
Response
Response body will contain the requested JSON:API resource of type brokers with clientRelationsas included resources.
Modify a Broker
A request to modify a merchant properties. Refer to the list of amendable attributes provided for reference.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/brokers/{{brokerId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type brokers with the following attributes:
| Name | Description | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
status
string (3)
|
Indicates the broker current status. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||
|
clientType
string (3)
|
Indicates the broker’s client type. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||
|
shortName
string (26)
|
Broker’s short name. If not provided during broker creation, the tradeName value will be used. |
|||||||||||
|
companyName
string (45)
|
The broker company name. |
|||||||||||
|
tradeName
string (40)
|
The name under which the company is trading. |
|||||||||||
|
registrationNumber
string (15)
|
The broker registration number. |
|||||||||||
|
language
string (3)
|
Broker’s language. Refer to API Data Mapping documentation for account definitions available for the institution. |
|||||||||||
|
legalForm
string (3)
|
Related to the legal form of the broker, such as:
Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||
|
businessClass
string (4)
|
The ISO 4-digit business classification code. Refer to API Data Mapping documentation for account definitions available for the institution. |
|||||||||||
|
vatRegistrationNumber
string (15)
|
A reference number used for clearing purposes. |
|||||||||||
|
mainContactDetails
object
|
|
|||||||||||
|
rbsClientNumber
string (20)
|
External broker reference number. ^\d*$ |
|||||||||||
|
website
string (100)
|
Broker website address details. |
|||||||||||
|
taxCountry
string (3)
|
The ISO 3-letter country code of the broker’s country for tax information. In cases where value consists of 3 digits:
Refer to API Data Mapping documentation for account definitions available for the institution. |
|||||||||||
| Relationships | ||||||||||||
Response
Response body will contain the updated JSON:API resource of type brokers .
Addresses
Client address retrieval and maintenance requests. These would apply to the available client types supported, for example merchant and broker.
Client Addresses
Retrieve all the client addresses. In this example, a particular merchant\’s addresses are being returned. This would also apply to other client types such as a broker client. The result is also being sorted by addressCategory which defines the type of address as well as effectiveDate in reverse chronological order. Additional date filtering may be required if the desired result should filter out any future effective address entries from the result.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000/addresses?sort=addressCategory,-effectiveDate
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| sort | addressCategory,-effectiveDate |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type addresses .
Delete Address Record
Delete an address identified by an ID. This is only allowed for addresses which have a future dated effectiveDate value. It is not possible to delete currently effective or historical address records.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/addresses/clientNumber=00000002&addressCategory=022&effectiveDate=2020-05-01
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 204 (No Content)
Modify Address Record
A request to modify an existing future effective address record. The request can also be used to modify an address that has an effective date equal to the current posting date. For example, a newly address record was entered and set to be immediately effetctive. A problem was found and required an amendent to this record, using a PATCH request as shown here would allow modification of that address record. For future effective amendents new records need to be inserted. Refer to the POST request example for more information. The amendable resource attributes have been provided in the below table.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/addresses/clientNumber=00000002&addressCategory=022&effectiveDate=2020-05-01
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type addresses with the following attributes:
| Name | Description | |
|---|---|---|
|
expiryDate
date-only
|
The date in ISO 8601 format when the address record is no longer taken into consideration. Can be used for temporary addresses. Date must be in the future. |
|
|
addressLine1
string (35)
|
Address line typically used for building information but not limited to house name, number, floor, unit and block number. |
|
|
addressLine2
string (35)
|
Address line typically used for street information such as street number and name. |
|
|
addressLine3
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
addressLine4
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
addressLine5
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
contactName
string (35)
|
Main contact name for the address. |
|
|
city
string (35)
|
Client’s city. |
|
|
state
string (3)
|
3 digit identifier for the client’s state/region. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
country
string (3)
|
The ISO 3-letter country code. In cases where value consists of 3 digits, 000 means not applicable and 999 means applicable to all countries. |
|
|
postCode
string (20)
|
Client’s postcode. |
|
|
poBox
string (10)
|
P.O. Box details. |
|
|
addressLanguage
string (3)
|
3-digit identifier for the client address language. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
telephone1
string (15)
|
Primary address fixed line number, for example, a client’s home or business telephone number. |
|
|
telephone2
string (15)
|
Secondary address fixed line number for example a secondary business telephone number. |
|
|
faxWork
string (15)
|
Office fax number. |
|
|
deliveryMethod
string (3)
|
3-digit value indicating the preferred delivery option for correspondence. Defaulted to not applicable (000) if not provided. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
emailAddress
string (60)
|
Client’s e-mail address. This is required if deliveryMethod is set to 500 (E-mail). |
|
| Relationships | ||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type addresses .
New Address Record
Creation of a new address record may cover 2 main use cases: - Defining a completely new record for a client, such adding a new type (addressCategory) of address to an existing client - Creating future effective changes to existing addresses. For example, a merchant would be moving to a new trading address within 6 months and a new address entry would be created with that future effectiveDate value. This can also be used to enter a new address modification that is immediately effective.
Note Should a modification on an address record effective on the same day the modification is to be made, a PATCH request needs to be sent. BankWORKS allows only 1 record per effectiveDate for a client address identified by a particular addressCategory.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/addresses
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type addresses with the following attributes:
| Name | Description | |
|---|---|---|
|
addressCategory
string (3)
required
|
The address category identifier for the returned client address resource are the following but not limited to:
A client must have at least a standard (001) and a clearing (022) address. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the address becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, the current posting date is automatically assumed. |
|
|
expiryDate
date-only
|
The date in ISO 8601 format when the address record is no longer taken into consideration. Can be used for temporary addresses. Date must be in the future. |
|
|
addressLine1
string (35)
required
|
Address line typically used for building information but not limited to house name, number, floor, unit and block number. |
|
|
addressLine2
string (35)
|
Address line typically used for street information such as street number and name. |
|
|
addressLine3
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
addressLine4
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
addressLine5
string (35)
|
Extra address properties that might be required and are not catered for by the attributes available. |
|
|
contactName
string (35)
|
Main contact name for the address. |
|
|
city
string (35)
required
|
Client’s city. |
|
|
state
string (3)
|
3 digit identifier for the client’s state/region. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
country
string (3)
required
|
The ISO 3-letter country code. In cases where value consists of 3 digits, 000 means not applicable and 999 means applicable to all countries. |
|
|
postCode
string (20)
required
|
Client’s postcode. |
|
|
poBox
string (10)
|
P.O. Box details. |
|
|
addressLanguage
string (3)
|
3-digit identifier for the client address language. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
telephone1
string (15)
|
Primary address fixed line number, for example, a client’s home or business telephone number. |
|
|
telephone2
string (15)
|
Secondary address fixed line number for example a secondary business telephone number. |
|
|
faxWork
string (15)
|
Office fax number. |
|
|
deliveryMethod
string (3)
|
3-digit value indicating the preferred delivery option for correspondence. Defaulted to not applicable (000) if not provided. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
emailAddress
string (60)
|
Client’s e-mail address. This is required if deliveryMethod is set to 500 (E-mail). |
|
| Relationships | ||
|
merchant
|
If address is a merchant address, provide the merchant resource ID |
|
|
broker
|
If address is a broker address, provide the broker resource ID |
|
|
kycClient
|
KYC/AML client who owns the address information. An address can only belong to one client. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type addresses .
Settlement Information
External RBS client settlement information. Client settlement information would be required for clients at billing and settlement point. A client in BankWORKS may have up to 99 settlement packages defined.
Delete Settlement Package
Delete a client settlementPackage.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/settlementPackages/{{settlementPackagesId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 204 (No Content)
Client Settlement Packages
Return the a particular client’s settlementPackages. This would apply to any client type that may have settlementPackages such as merchants or brokers.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000/settlementPackages
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type settlementPackages .
List of Settlement Packages
Return all available client settlement records. Additional URL parameters may be provided in order to filter, sort or return specific attribute values as well.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/settlementPackages
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type settlementPackages .
Modify Settlement Package
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/settlementPackages/clientNumber=10050000&settlementNumber=01
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type settlementPackages with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
settlementCategory
string (3)
|
Settlement information category descriptor such as Payable or Receivable. |
|||||||||||||||||||||||||||||||
|
accountCurrency
string (3)
|
The currency of the counter bank account in SWIFT currency code format. In cases where value consists of 3 digits:
|
|||||||||||||||||||||||||||||||
|
bankClearingNumber
string (8)
|
Information regarding the account’s bank details. For USA merchants, this must be a 9-digit value. |
|||||||||||||||||||||||||||||||
|
contingencyLiabilityAccount
string (11)
|
The RBS account that is used in case the counter RBS bank account is not able to fullfil the RECEIVABLE obligation. |
|||||||||||||||||||||||||||||||
|
correspondingBankAccount
string (16)
|
The NOSTRA/VOSTRO bank account of the affiliate institution. |
|||||||||||||||||||||||||||||||
|
correspondingBankNumber
string (35)
|
The bank number of the affiliate institution where the counter bank Nostro/Vostro are domiciled. |
|||||||||||||||||||||||||||||||
|
receiverCountryCode
string (3)
|
The country where the bank account information is located. In cases where value consists of 3 digits:
|
|||||||||||||||||||||||||||||||
|
noteText
string (2000)
|
Free text notes on the settlement package. |
|||||||||||||||||||||||||||||||
|
payableDetails
object
|
|
|||||||||||||||||||||||||||||||
|
receivableDetails
object
|
|
|||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||
|
fundingClient
|
Funding bank for this merchant settlement package. |
|||||||||||||||||||||||||||||||
|
mandateInformation
|
SEPA DD mandate information for which the settlement is related to. |
|||||||||||||||||||||||||||||||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type settlementPackages .
Create Settlement Package
Creating a new settlement package linked to an existing client. An individual client may have up to 99 different settlement packages defined. Only merchants residing at billing point would require settlementPackages to be set up.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/settlementPackages
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type settlementPackages with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
settlementCategory
string (3)
|
Settlement information category descriptor such as Payable or Receivable. |
|||||||||||||||||||||||||||||||
|
accountCurrency
string (3)
required
|
The currency of the counter bank account in SWIFT currency code format. In cases where value consists of 3 digits:
|
|||||||||||||||||||||||||||||||
|
bankClearingNumber
string (8)
|
Information regarding the account’s bank details. For USA merchants, this must be a 9-digit value. |
|||||||||||||||||||||||||||||||
|
contingencyLiabilityAccount
string (11)
|
The RBS account that is used in case the counter RBS bank account is not able to fullfil the RECEIVABLE obligation. |
|||||||||||||||||||||||||||||||
|
correspondingBankAccount
string (16)
|
The NOSTRA/VOSTRO bank account of the affiliate institution. |
|||||||||||||||||||||||||||||||
|
correspondingBankNumber
string (35)
|
The bank number of the affiliate institution where the counter bank Nostro/Vostro are domiciled. |
|||||||||||||||||||||||||||||||
|
receiverCountryCode
string (3)
|
The country where the bank account information is located. In cases where value consists of 3 digits:
|
|||||||||||||||||||||||||||||||
|
noteText
string (2000)
|
Free text notes on the settlement package. |
|||||||||||||||||||||||||||||||
|
payableDetails
object
|
|
|||||||||||||||||||||||||||||||
|
receivableDetails
object
|
|
|||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||
|
merchant
|
Link settlementPackage being defined to an existing merchant client. Although optional, a settlementPackage must be linked to a client. |
|||||||||||||||||||||||||||||||
|
broker
|
Link settlmentPackage being defined to an existing broker client |
|||||||||||||||||||||||||||||||
|
fundingClient
|
Optional link to funding client to indicate source of funds for merchant settlement. |
|||||||||||||||||||||||||||||||
|
mandateInformation
|
SEPA DD mandate information for which the settlement is related to. |
|||||||||||||||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type settlementPackages .
Mandate Information
This section will contain valid API requests to create, modify, and retrieve SEPA direct debit mandate information.
Get Mandate Information
Retrieve a SEPA mandate using any attribute filter such as uniqueMandateReference and / or include settlementPackages to know what settlement information the mandate is related to.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/mandateInformation/{{mandateInformationId}}?include=settlementPackages
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[uniqueMandateReference] | MANDJMH002 |
|---|---|
| include | settlementPackages |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type mandateInformation with settlementPackagesas included resources.
Create Mandate Information
This request will create a new SEPA mandate and should be linked to existing settlement information via settlemenPackage API.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/mandateInformation
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
Response
HTTP 201 (Created)
Patch Mandate Information
This request will modify any attributes of SEPA mandate information provided by the related settlementPackage/s present for which the mandate is linked to.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/mandateInformation/{{mandateInformationId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
Response
HTTP 200 (OK)
Card Scheme Addendum
Get Card Scheme Addendum
Retrieve a card scheme addendum details.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/cardSchemeAddendum?filter[contracts.merchant.id]=clientNumber=10050000
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[contracts.merchant.id] | clientNumber=10050000 |
|---|
Response
Get Card Scheme Addendum - Not Found : HTTP 200 (OK)
Get Card Scheme Addendum - Successful 1 : HTTP 200 (OK)
Get Card Scheme Addendum - Successful 2 : HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type cardSchemeAddendum .
Add Card Scheme Addendum
This call is used to add the Card Scheme Addendum.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/cardSchemeAddendum
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type cardSchemeAddendum with the following attributes:
| Name | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardOrganisation
string (3)
required
|
Indicates the card scheme for the addendum entry. Valid values:
The cardOrganisation value determines the applicable card scheme object such as ‘visa’, ‘mastercard’ etc.. The object ‘pinDebit’ refers to any card scheme not represented by an individual object such as Star or NYCE. |
|||||||||||||||
|
effectiveDate
date-only
|
Indicates the cardSchemeAddendum resource when it will become effective. If no value is provided prior to onboarding a new merchant the value defaults to the posting date available during merchant boarding. Otherwise defaulted to the next processing date (posting date + 1). |
|||||||||||||||
|
visa
object
|
Applicable for cardOrganisation value 003.
|
|||||||||||||||
|
mastercard
object
|
Applicable for cardOrganisation value 002.
|
|||||||||||||||
|
amex
object
|
Applicable for cardOrganisation value 004.
|
|||||||||||||||
|
discover
object
|
Applicable for cardOrganisation value 023.
|
|||||||||||||||
|
diners
object
|
Applicable for cardOrganisation value 006.
|
|||||||||||||||
|
pinDebit
object
|
Applicable to any ONE of the following cardOrganisation values 032, 033, 034, 035, 036, 037, 038, 039, 040, 041.
|
|||||||||||||||
| Relationships | ||||||||||||||||
|
contracts
required |
The contract applicable to this cardSchemeAddendum. |
|||||||||||||||
Response
Add Card Scheme Addendum - Error 0 : HTTP 422 (Unprocessable Entity)
Add Card Scheme Addendum - Error 1 : HTTP 422 (Unprocessable Entity)
Add Card Scheme Addendum - Successful 1 : HTTP 201 (Created)
Add Card Scheme Addendum - Successful 2 : HTTP 201 (Created)
Response body will contain the created JSON:API resource of type cardSchemeAddendum .
Add Card Scheme Addendum - Amex
This call is used to add the Card Scheme Addendum.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/cardSchemeAddendum
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type cardSchemeAddendum with the following attributes:
| Name | Description | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardOrganisation
string (3)
required
|
Indicates the card scheme for the addendum entry. Valid values:
The cardOrganisation value determines the applicable card scheme object such as ‘visa’, ‘mastercard’ etc.. The object ‘pinDebit’ refers to any card scheme not represented by an individual object such as Star or NYCE. |
|||||||||||||
|
effectiveDate
date-only
|
Indicates the cardSchemeAddendum resource when it will become effective. If no value is provided prior to onboarding a new merchant the value defaults to the posting date available during merchant boarding. Otherwise defaulted to the next processing date (posting date + 1). |
|||||||||||||
|
amex
object
|
Applicable for cardOrganisation value 004.
|
|||||||||||||
| Relationships | ||||||||||||||
|
contracts
required |
The contract applicable to this cardSchemeAddendum. |
|||||||||||||
Response
Add Card Scheme Addendum - Amex - Error : HTTP 400 (Bad Request)
Add Card Scheme Addendum - Amex - Successful : HTTP 201 (Created)
Response body will contain the created JSON:API resource of type cardSchemeAddendum .
Modify Card Scheme Addendum
This call is to modify the existing card scheme addendum information.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/cardSchemeAddendum/{{cardSchemeAddendumId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type cardSchemeAddendum with the following attributes:
| Name | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
visa
object
|
Applicable for cardOrganisation value 003.
|
|||||||||||||||
|
mastercard
object
|
Applicable for cardOrganisation value 002.
|
|||||||||||||||
|
amex
object
|
Applicable for cardOrganisation value 004.
|
|||||||||||||||
|
discover
object
|
Applicable for cardOrganisation value 023.
|
|||||||||||||||
|
diners
object
|
Applicable for cardOrganisation value 006.
|
|||||||||||||||
|
pinDebit
object
|
Applicable to any ONE of the following cardOrganisation values 032, 033, 034, 035, 036, 037, 038, 039, 040, 041.
|
|||||||||||||||
| Relationships | ||||||||||||||||
Response
Modify Card Scheme Addendum - Error 0 : HTTP 401 (Unauthorized)
Modify Card Scheme Addendum - Error 1 : HTTP 422 (Unprocessable Entity)
Modify Card Scheme Addendum - Error 2 : HTTP 403 (Forbidden)
Modify Card Scheme Addendum - Successful 1 : HTTP 200 (OK)
Modify Card Scheme Addendum - Successful 2 : HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type cardSchemeAddendum .
Delete Card Scheme Addendum
This call is to delete the existing card scheme addendum information by specifying the resource Id.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/cardSchemeAddendum/{{cardSchemeAddendumId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
Delete Card Scheme Addendum - Error : HTTP 403 (Forbidden)
Delete Card Scheme Addendum - Successful : HTTP 204 (No Content)
Client Mapping
Add Client Mapping
This call is used to add the client mapping record of a particular merchant.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/clientMappings
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type clientMappings with the following attributes:
| Name | Description | |
|---|---|---|
|
transactionCurrency
string (3)
|
Indicates the currency applicable to the client mapping. Default value when it is not pass is 999 - means applicable to all currencies. |
|
|
groupNumber
string (8)
|
8-digit number indicating a billing and settlement hiearchical group. In this case, the group number indicates the hierarchy the contract form parts of. This field’s value is auto-generated. |
|
|
businessClass
string (4)
|
The ISO 4-digit business classification code that the client mapping value is applies to. Default value when it is not pass is 9999 - means applicable to all business classification. |
|
|
cardOrganisation
string (3)
|
Indicates the card scheme of client mapping. Default value when it is not pass is 999 - means applicable to all card organization. Valid values:
The cardOrganisation value determines the applicable card scheme object such as visa, mastercard etc.. The object pinDebit refers to any card scheme not represented by an individual object such as Star or NYCE. |
|
|
acquiringBin
string (6)
|
Indicates the acquiring bank BIN number that the client mapping value applies to. Default value when it is not pass is 999999 - means applicable to all acquiring bank. |
|
|
sequenceNumber
string (3)
required
|
A value indicating the type of merchant ID which based on setup might be automatically generated or provided manually. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
allGroups
boolean
|
All merchant contract groups or not. Every mechant contract is bound to group which defines the hierarchy. Setting this value to true will apply the ID to all available merchant groups should the merchant have more than one service contract assigned. Otherwise, if false, the related contract needs to be linked to. |
|
|
referenceNumber
string (20)
|
Client mapping reference value which can either be automatically generated or entered manually depending on the sequenceNumber value and associated setup. Generation method of 020 and 021 will trigger the automatic generation value for this field. |
|
| Relationships | ||
|
merchant
required |
Link the mapping value to the merchant client. |
|
|
contracts
|
Optional link to the merchant contract in order to link the mapping value to a particular hierarchy group. This will be REQUIRED should the allGroups value provided be false. |
|
Response
Response body will contain the created JSON:API resource of type clientMappings .
Add Client Mapping with Contract
This call is used to add the client mapping record of a particular merchant.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/clientMappings
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type clientMappings with the following attributes:
| Name | Description | |
|---|---|---|
|
transactionCurrency
string (3)
|
Indicates the currency applicable to the client mapping. Default value when it is not pass is 999 - means applicable to all currencies. |
|
|
groupNumber
string (8)
|
8-digit number indicating a billing and settlement hiearchical group. In this case, the group number indicates the hierarchy the contract form parts of. This field’s value is auto-generated. |
|
|
businessClass
string (4)
|
The ISO 4-digit business classification code that the client mapping value is applies to. Default value when it is not pass is 9999 - means applicable to all business classification. |
|
|
cardOrganisation
string (3)
|
Indicates the card scheme of client mapping. Default value when it is not pass is 999 - means applicable to all card organization. Valid values:
The cardOrganisation value determines the applicable card scheme object such as visa, mastercard etc.. The object pinDebit refers to any card scheme not represented by an individual object such as Star or NYCE. |
|
|
acquiringBin
string (6)
|
Indicates the acquiring bank BIN number that the client mapping value applies to. Default value when it is not pass is 999999 - means applicable to all acquiring bank. |
|
|
sequenceNumber
string (3)
required
|
A value indicating the type of merchant ID which based on setup might be automatically generated or provided manually. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
allGroups
boolean
|
All merchant contract groups or not. Every mechant contract is bound to group which defines the hierarchy. Setting this value to true will apply the ID to all available merchant groups should the merchant have more than one service contract assigned. Otherwise, if false, the related contract needs to be linked to. |
|
|
referenceNumber
string (20)
|
Client mapping reference value which can either be automatically generated or entered manually depending on the sequenceNumber value and associated setup. Generation method of 020 and 021 will trigger the automatic generation value for this field. |
|
| Relationships | ||
|
merchant
required |
Link the mapping value to the merchant client. |
|
|
contracts
|
Optional link to the merchant contract in order to link the mapping value to a particular hierarchy group. This will be REQUIRED should the allGroups value provided be false. |
|
Response
Response body will contain the created JSON:API resource of type clientMappings .
Get Client Mappings
Retrieve a client mapping details then include either the merchant, brokers or contracts to know for example the merchant information of the client mapping.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/clientMappings?filter[merchant.id]=clientNumber=88800641&sort=cardOrganisation
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[merchant.id] | clientNumber=88800641 |
|---|---|
| sort | cardOrganisation |
Response
Response body will contain the requested JSON:API resource of type clientMappings .
Modify Client Mapping
This call is to modify existing client mapping information. A client mapping resource ID is needed to only modify a specific client mapping.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/clientMappings/{{clientMappingId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type clientMappings with the following attributes:
| Name | Description | |
|---|---|---|
|
groupNumber
string (8)
|
8-digit number indicating a billing and settlement hiearchical group. In this case, the group number indicates the hierarchy the contract form parts of. This field’s value is auto-generated. |
|
|
referenceNumber
string (20)
|
Client mapping reference value which can either be automatically generated or entered manually depending on the sequenceNumber value and associated setup. Generation method of 020 and 021 will trigger the automatic generation value for this field. |
|
| Relationships | ||
Response
Response body will contain the updated JSON:API resource of type clientMappings .
Delete Client Mapping
This call is to delete existing client mapping information by specifying the resource Id.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/clientMappings/{{clientMappingId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
Response body will contain the deleted JSON:API resource of type clientMappings .
Client Relation
Add Client Relation
This call is used to add a new client virtual link record.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/clientRelations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type clientRelations with the following attributes:
| Name | Description | |
|---|---|---|
|
sourceClient
string (8)
required
|
The source client number of the virtual link. |
|
|
destinationClient
string (8)
required
|
The destination client number of the virtual link. |
|
|
linkType
string (3)
required
|
Indicates the link type of the virtual link record such as:
Refer to API Data Mapping documentation for other possible values. |
|
|
status
string (3)
|
The current status of the virtual link.
Refer to API Data Mapping documentation for other possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the virtual link becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, the current posting date is automatically assumed. |
|
Response
Add Client Relation - Successful : HTTP 201 (Created)
Add Client Relation - Error (Source not found) : HTTP 404 (Not Found)
Add Client Relation - Error (Dest not found) : HTTP 404 (Not Found)
Add Client Relation - Error (Link Type) : HTTP 404 (Not Found)
Response body will contain the created JSON:API resource of type clientRelations .
Get Client Relations
Retrieve all the virtual links between clients.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/clientRelations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type clientMappings .
Modify Client Relation
This call is to modify an existing virtual link record. A client relation resource ID is needed to only modify a specific client virtual link record.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/clientRelations/{{clientRelationId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type clientRelations with the following attributes:
| Name | Description | |
|---|---|---|
|
status
string (3)
|
The current status of the virtual link.
Refer to API Data Mapping documentation for other possible values. |
|
Response
Modify Client Relation - Successful : HTTP 200 (OK)
Modify Client Relation - Error : HTTP 422 (Unprocessable Entity)
Response body will contain the updated JSON:API resource of type clientRelations .
Delete Client Relation
This call is to delete an existing client virtual link record by specifying the resource Id.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/clientRelations/{{clientRelationId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
Delete Client Relation - Successful : HTTP 204 (No Content)
Delete Client Relation - Error : HTTP 403 (Forbidden)
Response body will contain the deleted JSON:API resource of type clientRelations .
Merchant Tax Staus
This section will contain valid API requests to create, modify, and retrieve Merchant tax status.
Merchant Tax Status
Retrieve merchant tax status record history. A merchant may have one tax status record available.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000/merchantTaxStatus
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
Merchant Tax Status - Error : HTTP 200 (OK)
Merchant Tax Status - Successful : HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type merchantTaxStatus .
Modify Merchant Tax Status
A request to modify an existing future effective merchant tax status record. The request can also be used to modify the merchant tax status that has an effective date equal to the current posting date. Then for future effective amendments new records need to be inserted. Refer to the POST request example for more information. The amendable resource attributes have been provided in the below table.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchantTaxStatus/{{merchantTaxStatusId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantTaxStatus with the following attributes:
| Name | Description | |
|---|---|---|
|
taxType
string (3)
|
Indicates the type of merchant tax. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
taxStatus
string (3)
|
Indicates the current status of merchant tax type. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format on which the merchant tax status record becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, posting date value is assumed. |
|
|
expiryDate
date-only
|
The date in ISO 8601 format when the merchant tax status can no longer be used. |
|
|
recordDate
date-only
|
The date in ISO 8601 format on which the merchant tax status record is created. Defaulted to the current posting date when a new record is created |
|
| Relationships | ||
|
merchant
|
Merchant information related to merchant tax status record. |
|
Response
Modify Merchant Tax Status - Error 1 : HTTP 404 (Not Found)
Modify Merchant Tax Status - Error 2 : HTTP 422 (Unprocessable Entity)
Modify Merchant Tax Status - Successful : HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type merchantTaxStatus .
Delete Merchant Tax Status
Delete merchant taxt status record identified by an ID. This is only allowed for those records which have a future dated effectiveDate value. It is not possible to delete currently effective or historical merchant tax status records.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/merchantTaxStatus/{{merchantTaxStatusId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 204 (No Content)
New Merchant Tax Status
The POST request can be sent whenever a merchant tax status record is effective in the past needs to be modified by creating either:
- a new merchant tax status record to be effective immediately (effectiveDate set to the current posting date or null). This can be done in cases the current effective record is a past entry.
- a new merchant tax status record to be future effective. This modifications to be set in the future which will be effective on a particular date
Note: Should the current effective merchant tax status record have an effectiveDate value that is equal to the current posting date, a PATCH request needs to be sent.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantTaxStatus
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantTaxStatus with the following attributes:
| Name | Description | |
|---|---|---|
|
taxType
string (3)
required
|
Indicates the type of merchant tax. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
taxStatus
string (3)
required
|
Indicates the current status of merchant tax type. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format on which the merchant tax status record becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, posting date value is assumed. |
|
|
expiryDate
date-only
required
|
The date in ISO 8601 format when the merchant tax status can no longer be used. |
|
|
recordDate
date-only
|
The date in ISO 8601 format on which the merchant tax status record is created. Defaulted to the current posting date when a new record is created |
|
| Relationships | ||
|
merchant
|
Merchant information related to merchant tax status record. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type merchantTaxStatus .
Velocity Parameters
Velocity Parameters section covers the management of merchant velocity rules. Creation and modification of merchant velocity parameter can be done only at service level, contract level setup cannot be created or modified through API.
Delete Merchant Velocity Parameters
A request to delete an individual mercahnt velocity parameter. Deletion can be done only for merchant level rules, contract level rules cannot be deleted.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/merchantVelocityParameters/{{merchantVelocityParametersId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 204 (No Content)
Merchant Velocity Parameters
In this example, the merchant velocity parameters linked to a client contract are being returned. In order to identify a merchant contract refer to the client contract example.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contracts/clientNumber=10050000&groupNumber=00000001&effectiveDate=2020-04-01&clientLevel=001/merchantVelocityParameters
Request Headers
| Accept | application/vnd.api+json |
|---|---|
| Content-Type | application/vnd.api+json |
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type merchantVelocityParameters .
Modify Merchant Velocity Parameters
A request to modify an existing individual merchant velocity parameter. Contract level velocity parameter cannot be updated.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchantVelocityParameters/{{merchantVelocityParametersId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type merchantVelocityParameters with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
dailyLimitAmount
object
|
Total amount of transactions allowed for this velocity parameter within a 24-hour period. Note that the limit amount currencies MUST match. Maximum allowed length for the value attribute (including decimal point) is 18.
|
|||||||
|
dailyLimitFrequency
number
|
Total number of transactions allowed for this velocity parameter within a 24-hour period. maximum: 99999999 |
|||||||
|
singleTransactionLimit
object
|
Maximum transaction amount allowed for a single transaction for this velocity parameter. Note that the limit amount currencies MUST match. Maximum allowed length for the value attribute (including decimal point) is 18.
|
|||||||
|
notificationPercent
number
|
The percentage of the limit after which, notifications should be considered. maximum: 99 |
|||||||
|
notificationPercentInterval
number
|
The percentage interval upon which the notification is triggered. maximum: 99 |
|||||||
|
isContractParameter
boolean
|
Indicates if the merchant velocity parameter is a contract level rule, part of the service contract setup, or a merchant specific rule. |
|||||||
|
allServices
boolean
|
Indicates if the rule applies to all merchant services or not. |
|||||||
| Relationships | ||||||||
|
services
required |
Services that the merchant velocity parameter is applicable to. Services are returned regardless of their effectiveDate value. |
|||||||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type merchantVelocityParameters .
Create Merchant Velocity Parameters
A request to create new individual merchant velocity parameter. Contract level velocity rules cannot be created.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantVelocityParameters
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type merchantVelocityParameters with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
dailyLimitAmount
object
|
Total amount of transactions allowed for this velocity parameter within a 24-hour period. Note that the limit amount currencies MUST match. Maximum allowed length for the value attribute (including decimal point) is 18.
|
|||||||
|
dailyLimitFrequency
number
|
Total number of transactions allowed for this velocity parameter within a 24-hour period. maximum: 99999999 |
|||||||
|
singleTransactionLimit
object
|
Maximum transaction amount allowed for a single transaction for this velocity parameter. Note that the limit amount currencies MUST match. Maximum allowed length for the value attribute (including decimal point) is 18.
|
|||||||
|
notificationPercent
number
|
The percentage of the limit after which, notifications should be considered. maximum: 99 |
|||||||
|
notificationPercentInterval
number
|
The percentage interval upon which the notification is triggered. maximum: 99 |
|||||||
|
transactionType
string (3)
|
Indicates the type of transaction that the velocity parameter is applicable to. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
transactionCurrency
string (3)
|
Indicates the transaction currency the velocity parameter applies to. The transaction currency is in 3-letter ISO SWIFT format. Value 999 is not allowed. In cases where value consists of 3 digits:
|
|||||||
|
cardBrand
string
|
Indicates the card brand the velocity parameter applies to. This works in conjunction with the related merchant service. A value of 999, indicating that the velocity rule applies to all card brands is also acceptable. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
countryGroup
string
|
Identifies the country grouping the velocity parameter applies to. The country grouping is a virtual group of countries that is defined to classify a number of countries under a common banner, for example high risk countries, blocked countries etc. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
isContractParameter
boolean
|
Indicates if the merchant velocity parameter is a contract level rule, part of the service contract setup, or a merchant specific rule. |
|||||||
|
allServices
boolean
|
Indicates if the rule applies to all merchant services or not. |
|||||||
| Relationships | ||||||||
|
services
required |
Services that the merchant velocity parameter is applicable to. Services are returned regardless of their effectiveDate value. |
|||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type merchantVelocityParameters .
Client Contracts
In BankWORKS, a client contract represents a service contract assignment to a merchant or other clients that can be assigned service contracts, such as brokers. This results in the contract being assigned a groupNumber indicating the hierarchy group. This applies to both standalone and hierarchical merchants. Each contract modification has an effectiveDate property indicating when that record becomes effective from a processing point of view.
Delete Contract
Delete a client contract. Deletion is only supported for future effective contracts, having an effective date greater than the current posting date.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/contracts/clientNumber=10050000&groupNumber=00000001&effectiveDate=2020-04-01&clientLevel=001
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
Client Contracts
A request to retrieve client contracts. In this request example, additional filtering has been applied to filter by effectiveDate to be less or equal than the current date. The result is also being sorted by groupNumber and effectiveDate in descending order. This will result in the latest and current effetive contract being returned first, followed by a list of historical versions of the contract organised by reverse chronoligical order.
There can be cases where the future effective contract amendments would also be desired. In this case the filtering criteria can be amended as necessary. It is also possible to filter further using other attributes and also relationship based filtering if desired.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000/contracts?filter[effectiveDate][LE]=2020-04-01&sort=groupNumber,-effectiveDate
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[effectiveDate][LE] | 2020-04-01 |
|---|---|
| sort | groupNumber,-effectiveDate |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type contracts .
Modify Contract Record
New contract records can be defined in order to ‘modify’ an existing client contract. Client contracts have an effectiveDate property which indicates the applicable contract setup for a given day (by retrieving the current effective contract). BankWORKS allows direct modification of client contracts only in specific scenarios, this covered in a separate PATCH request below.
The POST request can be sent whenever a client contract is effective in the past and needs to be modified by creating either: - a new contract record to be effective immediately (effectiveDate set to the current posting date). This can be done in cases the current effective contract is a past entry. - a new contract record to be future effective. This modifications to be set in the future which will be effective on a particular date
Note: Should the current effective contract record have an effectiveDate value that is equal to the current posting date, a PATCH request needs to be sent.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/contracts/clientNumber=10050000&groupNumber=00000001&effectiveDate=2020-04-01&clientLevel=001
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type contracts with the following attributes:
| Name | Description | |
|---|---|---|
|
status
string (3)
|
The status of the contract record, may be used to modify the contract status for example, for contract closure use cases. Refer to API Data Mapping documentation for possible values. |
|
|
settlementMethod
string (3)
|
Indicates the method how the client will settle with the bank. Identifies how outstanding balances are settled. Required only when onboarding a new client. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
postingMethod
string (3)
|
The tariff under which the client falls when posting to the clients account. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientTariff
string (6)
|
The client tariff value selecting the account fees, service fees, device fee rules applicable. Refer to API Data Mapping documentation for possible values. |
|
|
transactionChargesTariff
string (6)
|
Indicates the applicable transaction charges tariff. Transaction charges are represented as productChargeDefinitions. This is an optional field and if not provided will default to not applicable 000000. If a tariff value is provided, the merchant services clientTariff value will not apply. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
chargeTierLevel
string (3)
|
Enables setting up of the same fee with different value high and value low triggers. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientScheme
string (6)
|
Indicates the rebate tariff applicable for the contract. |
|
|
contractReference
string (8)
|
Merchant contract document reference. |
|
|
bankReference
string (8)
|
External additional reference number of the merchant with the bank. |
|
|
institutionAccountOfficer
string (3)
|
Officer in charge of the client contract. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientBranch
string (3)
|
Contract application branch details. Related to the institutionAccountOfficer. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
tierGroup
string (3)
|
An identifier used to group a set of rates that need to be applied during tiered pricing generation. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
entityId
string (3)
|
Entity identifier used to split GL entries and transactions generated for financial activity in a single processing institution across multiple legal entities. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
riskRuleGroupId
string (3)
|
Identifier for the set of rules applies in the risk module. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
|
riskRuleParameters
|
One or more risk rule parameters this client contract is linked to. |
|
Response
Response body will contain the updated JSON:API resource of type contracts .
Create Contract Record
New contract records can be defined in order to ‘modify’ an existing client contract. Client contracts have an effectiveDate property which indicates the applicable contract setup for a given day (by retrieving the current effective contract). BankWORKS allows direct modification of client contracts only in specific scenarios, this covered in a separate PATCH request below.
The POST request can be sent whenever a client contract is effective in the past and needs to be modified by creating either: - a new contract record to be effective immediately (effectiveDate set to the current posting date). This can be done in cases the current effective contract is a past entry. - a new contract record to be future effective. This modifications to be set in the future which will be effective on a particular date
Note: Should the current effective contract record have an effectiveDate value that is equal to the current posting date, a PATCH request needs to be sent.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/contracts
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type contracts with the following attributes:
| Name | Description | |
|---|---|---|
|
status
string (3)
|
The status of the contract record, may be used to modify the contract status for example, for contract closure use cases. Refer to API Data Mapping documentation for possible values. |
|
|
clientLevel
string (3)
|
Indicates the position of the current node resource within the group hierarchy. The top most level is identified as the Group level, the bottom level is the Member level. Any level in between the group and member levels is referred to as a Sub-group level node. Required only when onboarding a new client. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format on which the hierarchy link record becomes effective for the client. The value can be future dated and cannot be less than the posting date. If not provided, posting date +1 value is assumed only post-boarding. |
|
|
settlementMethod
string (3)
|
Indicates the method how the client will settle with the bank. Identifies how outstanding balances are settled. Required only when onboarding a new client. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
postingMethod
string (3)
|
The tariff under which the client falls when posting to the clients account. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientTariff
string (6)
|
The client tariff value selecting the account fees, service fees, device fee rules applicable. Refer to API Data Mapping documentation for possible values. |
|
|
transactionChargesTariff
string (6)
|
Indicates the applicable transaction charges tariff. Transaction charges are represented as productChargeDefinitions. This is an optional field and if not provided will default to not applicable 000000. If a tariff value is provided, the merchant services clientTariff value will not apply. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
chargeTierLevel
string (3)
|
Enables setting up of the same fee with different value high and value low triggers. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientScheme
string (6)
|
Indicates the rebate tariff applicable for the contract. |
|
|
contractReference
string (8)
|
Merchant contract document reference. |
|
|
bankReference
string (8)
|
External additional reference number of the merchant with the bank. |
|
|
institutionAccountOfficer
string (3)
|
Officer in charge of the client contract. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientBranch
string (3)
|
Contract application branch details. Related to the institutionAccountOfficer. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
tierGroup
string (3)
|
An identifier used to group a set of rates that need to be applied during tiered pricing generation. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
entityId
string (3)
|
Entity identifier used to split GL entries and transactions generated for financial activity in a single processing institution across multiple legal entities. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
riskRuleGroupId
string (3)
|
Identifier for the set of rules applies in the risk module. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
|
contractDefinition
required |
Service contract definition the client contract is linked to. |
|
|
merchant
|
Link to the merchant resource if a merchant contract is being defined. A contract must be linked to a client. |
|
|
broker
|
Link to the broker resource if a broker contract is being defined. A contract must be linked to a client. |
|
|
riskRuleParameters
|
One or more risk rule parameters this client contract is linked to. |
|
Response
Response body will contain the created JSON:API resource of type contracts .
Risk Rule Parameters
This section contains API request examples for consuming Risk Rule Parameters. This API resource contain both contract-defined and client-specific risk parameters. Contract-defined parameters only serve as default parameter that will apply in case there are no client-specific rules created.
Contract (Default) Risk Rule Parameters
This request will retrieve the contract risk rule parameters. Only GET request is allowed for this resource.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/riskRuleParameters?filter[isContractRule]=true&sort=ruleParameter,-effectiveDate
Request Headers
| Accept | application/vnd.api+json |
|---|---|
| Content-Type | application/vnd.api+json |
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
| crnk-compact | true |
Request Parameters
| filter[isContractRule] | true |
|---|---|
| sort | ruleParameter,-effectiveDate |
| filter[ruleParameter] | 000001 |
| filter[ruleParameter] | 000002 |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type riskRuleParameters .
Client Risk Parameters via Client Number
This sample request will return risk rule parameters of a specified client via clientNumber taken from contract’s relationship to merchant, sorted by the most effective record first.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/riskRuleParameters?sort=ruleParameter,-effectiveDate&filter[contracts.merchant.clientNumber]=44900116
Request Headers
| Accept | application/vnd.api+json |
|---|---|
| Content-Type | application/vnd.api+json |
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
| crnk-compact | true |
Request Parameters
| sort | ruleParameter,-effectiveDate |
|---|---|
| filter[contracts.merchant.clientNumber] | 44900116 |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type riskRuleParameters .
Create Risk Rule Parameters
POST can be used to create a new client specific risk rule parameter. It may also be used to superseed an effective client risk rule parameter in case changes are required. The earliest a risk rule parameter can be set to is the current posting date.
Prior to this request, the client contract’s riskRuleGroupId attribute should have been defined (not equal to 000) and the contract resource ID should be included in the request’s relationship.
Contract-defined risk rule parameters cannot be created.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/riskRuleParameters
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type riskRuleParameters with the following attributes:
| Name | Description | |
|---|---|---|
|
recordId
string (15)
|
The identifier generated which is unique for every record. |
|
|
ruleParameter
string (6)
required
|
The risk rule parameter for which the risk rule applies to. |
|
|
isContractRule
boolean
|
This flag will indicate whether the risk rule parameter is a contract-generated (true) or client-defined (false). |
|
|
clientId
number
|
The identifier generated for client-defined risk rule parameters. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the risk parameter will take into effect. |
|
|
expiryDate
date-only
|
Expiry date of risk rule parameter in ISO 8601 format. |
|
|
value
string
required
|
The risk rule value applied for the specified rule parameter. Value format varies depending on the rule parameter’s data type. Refer to BankWorks (API) Data Mapping documentation for possible values. Example:
|
|
|
currency
string (3)
|
The risk rule currency to be specified in case rule parameter requires an amount value. This should be in 3-letter ISO SWIFT format. Example: USD, EUR |
|
|
description
string (3)
|
Free-text description for the risk rule parameter. |
|
|
recordDate
date-only (3)
|
The date in ISO 8601 format on which the risk rule parameter record is created. Defaulted to the current posting date when a new record is created. |
|
| Relationships | ||
|
contracts
required |
Merchant contract/s for which the rule parameter applies to. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type riskRuleParameters .
Modify Risk Rule Parameters
A request to modify an existing client-specific risk rule parameter. This request is only for modifications of present or future effective records.
Contract level risk parameter cannot be updated.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/riskRuleParameters/{{riskRuleParametersId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type riskRuleParameters with the following attributes:
| Name | Description | |
|---|---|---|
|
recordId
string (15)
|
The identifier generated which is unique for every record. |
|
|
ruleParameter
string (6)
|
The risk rule parameter for which the risk rule applies to. |
|
|
isContractRule
boolean
|
This flag will indicate whether the risk rule parameter is a contract-generated (true) or client-defined (false). |
|
|
clientId
number
|
The identifier generated for client-defined risk rule parameters. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the risk parameter will take into effect. |
|
|
expiryDate
date-only
|
Expiry date of risk rule parameter in ISO 8601 format. |
|
|
value
string
|
The risk rule value applied for the specified rule parameter. Value format varies depending on the rule parameter’s data type. Refer to BankWorks (API) Data Mapping documentation for possible values. Example:
|
|
|
currency
string (3)
|
The risk rule currency to be specified in case rule parameter requires an amount value. This should be in 3-letter ISO SWIFT format. Example: USD, EUR |
|
|
description
string (3)
|
Free-text description for the risk rule parameter. |
|
|
recordDate
date-only (3)
|
The date in ISO 8601 format on which the risk rule parameter record is created. Defaulted to the current posting date when a new record is created. |
|
| Relationships | ||
|
contracts
|
Merchant contract/s for which the rule parameter applies to. |
|
Response
Past Effective Record cannot be updated : HTTP 403 (Forbidden)
Invalid value format - rule parameter value should be iof type integer : HTTP 400 (Bad Request)
Successful response : HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type riskRuleParameters .
Delete Risk Rule Parameters
A request to delete a client risk rule parameter. Deletion is only allowed for records that has not taken into effect yet (future-effective).
Contract-defined risk rules cannot be deleted.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/riskRuleParameters/{{riskRuleParametersId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 403 (Forbidden)
Client Accounts
Client indicates any BankWORKS client-sub accounts such as, merchant payment accounts, fee collect accounts etc. A client account is part of the client contract and must be based on an account definition.
This section covers a number of use cases including, client account retrieval, new account creation and various modifications such as account status change. Refer to the individual use cases for more details.
Account
Use cases in this section will be used to retrieve, create and modify an existing account.
Client Accounts
A request to retrieve client accounts. In BankWORKS, client accounts are linked to a contract and based on a definition. In this example, filtering is being applied to retrieve accounts by a specific merchant client. The accountDefinitions linked to the account is being returned in order to display some properties that the client account is inheriting.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/accounts/?filter[contracts.merchant.id]=clientNumber=10050000&include=accountDefinition&fields[accountDefinitions]=accountTypeId,accountCurrency&fields[accounts]=accountNumber,accountCurrency,status,clientAccountName,accountNumberRbs,billingLevel,activeDate
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[contracts.merchant.id] | clientNumber=10050000 |
|---|---|
| include | accountDefinition |
| fields[accountDefinitions] | accountTypeId,accountCurrency |
| fields[accounts] | accountNumber,accountCurrency,status,clientAccountName,accountNumberRbs,billingLevel,activeDate |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type accounts with accountDefinitionas included resources.
Create a New Client Account
A request to create a new client account. This must be linke to an accountDefinition that is available in the client service contract.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/accounts
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type accounts with the following attributes:
| Name | Description | |
|---|---|---|
|
clientAccountName
string (35)
|
Field representing the merchant account alias. |
|
|
accountNumberRbs
string (28)
|
External account number reference. |
|
|
statementGeneration
string (3)
|
Indicates the statement generation rule applicable for this account. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
statementType
string (3)
|
Indicates the type of statement applicable for this account. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
|
accountDefinition
required |
Link to a account definition business rule. This must be availabe in the client contract definition assigned ealier, during merchant contract creation. Refer to the account definition retrieval by service contract request for more information. |
|
|
settlementPackage
|
Optional, settlementPackage only needs to be linked to if the account is at billing level. Providing a settlementPackage automatically sets the account billingLevel to 001 - indicating a billingLevel account |
|
|
contracts
required |
Link to the merchant contract. |
|
|
paymentInstructions
|
Payment instructions defined for the account. |
|
|
billingAccounts
|
The billing account within the account hierarchy. |
|
|
balanceCycles
|
The account balances per cycle. |
|
Response
Response body will contain the created JSON:API resource of type accounts .
Modify Client Account
Request to modify a merchant account identified by it’s ID. Refer to table below for more information on what can be amended.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/accounts/{{accountId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type accounts with the following attributes:
| Name | Description | |
|---|---|---|
|
clientAccountName
string (35)
|
Field representing the merchant account alias. |
|
|
status
string (3)
|
Account status, provide the desired value to performa an account status change. Refer to API Data Mapping documentation for possible values. |
|
|
accountNumberRbs
string (28)
|
External account number reference. |
|
|
statementGeneration
string (3)
|
Indicates the statement generation rule applicable for this account. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
statementType
string (3)
|
Indicates the type of statement applicable for this account. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
|
paymentInstructions
|
Payment instructions defined for the account. |
|
|
billingAccounts
|
The billing account within the account hierarchy. |
|
|
balanceCycles
|
The account balances per cycle. |
|
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type accounts .
Account Balance Cycles
Get Balance Cycles
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/balanceCycles
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 200 (OK)
Get Balance Cycle with Account
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/balanceCycles/{{balanceCycleId}}?include=account
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-compact | true |
Request Parameters
| include | account |
|---|
Response
HTTP 200 (OK)
Get Account with Balance Cycles
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/accounts/{{accountId}}?include=balanceCycles&filter[balanceCycles][cycleEndDate]=2021-09-30
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-compact | true |
Request Parameters
| include | balanceCycles |
|---|---|
| filter[balanceCycles][cycleEndDate] | 2021-09-30 |
| sort | balanceCycles.cycleEndDate |
| filter[balanceCycles][processingStatus] | 004 |
Response
Get Account with Balance Cycles - Specific Cycle : HTTP 200 (OK)
Get Account with Balance Cycles - filter Current Cycle only : HTTP 200 (OK)
Get Account Balance Cycles
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/balanceCycles?filter[account.id]={{accountId}}&sort=-cycleEndDate
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Parameters
| filter[account.id] | {{accountId}} |
|---|---|
| sort | -cycleEndDate |
| filter[processingStatus] | 004 |
Response
HTTP 200 (OK)
Account Balance Transfer
Use cases in this section will be used to create, update, and delete sundry account balance transfers. This also includes retrieval of related source and destination accounts involved in the transaction.
All Account Balance Transfer
This request will retrieve all records for account balance transfers.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/accountBalanceTransfers
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-compact | true |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type accountBalanceTransfers .
One Account Balance Transfer
This request will retrieve one record for account balance transfer via resource ID provided.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/accountBalanceTransfers/{{accountBalanceTransfersId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-compact | true |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type accountBalanceTransfers .
Create Account Balance Transfer
This request will create an account balance transfer. Source and destination accounts should be provided in the relationships.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/accountBalanceTransfers
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type accountBalanceTransfers with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
transferType
string (3)
required
|
Defines the type of transfer being effected. Examples may include: 403 (Redemption Cash), 404 (Redemption Air Miles), 416 (Redemption Qualifying Miles), 950 (Misc. DR transaction), 951 (Misc. CR transaction). Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
transferAmount
object
required
|
The amount being transferred in the currency of the source account.
|
|||||||
|
transactionNarrative
string (100)
|
A free-text transaction description, up to 100 characters. If not provided, this will be defaulted to the transfer type narrative. |
|||||||
| Relationships | ||||||||
|
sourceAccount
required |
Relationship to the source transfer account. |
|||||||
|
destinationAccount
required |
Relationship to the destination transfer account. |
|||||||
Response
Create Account Balance Transfer - Error 1 : HTTP 404 (Not Found)
Create Account Balance Transfer - Error 2 : HTTP 422 (Unprocessable Entity)
Create Account Balance Transfer - Error 3 : HTTP 400 (Bad Request)
Create Account Balance Transfer - Error 4 : HTTP 403 (Forbidden)
Create Account Balance Transfer - Successful : HTTP 201 (Created)
Response body will contain the created JSON:API resource of type accountBalanceTransfers .
Update Account Balance Transfer
Updates are not allowed for Completed (002) status.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/accountBalanceTransfers/{{accountBalanceTransfersId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type accountBalanceTransfers with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
transferType
string (3)
|
Defines the type of transfer being effected. Examples may include: 403 (Redemption Cash), 404 (Redemption Air Miles), 416 (Redemption Qualifying Miles), 950 (Misc. DR transaction), 951 (Misc. CR transaction). Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
transferAmount
object
|
The amount being transferred in the currency of the source account.
|
|||||||
|
transactionNarrative
string (100)
|
A free-text transaction description, up to 100 characters. If not provided, this will be defaulted to the transfer type narrative. |
|||||||
| Relationships | ||||||||
|
sourceAccount
|
Relationship to the source transfer account. |
|||||||
|
destinationAccount
|
Relationship to the destination transfer account. |
|||||||
Response
Update Account Balance Transfer - Error 1 : HTTP 400 (Bad Request)
Update Account Balance Transfer - Error 2 : HTTP 400 (Bad Request)
Update Account Balance Transfer - Successful : HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type accountBalanceTransfers .
Delete Account Balance Transfer
Deletion is not allowed for transfers which has been Completed (002).
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/accountBalanceTransfers/{{accountBalanceTransfersId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 204 (No Content)
Response body will contain the deleted JSON:API resource of type accountBalanceTransfers .
Source Account of Balance Transfer
This will retrieve the related source account for a specific transfer.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/accountBalanceTransfers/{{accountBalanceTransfersId}}/sourceAccount
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type accounts .
Destination Account of Balance Transfer
This will retrieve the destination account of the specific transfer record.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/accountBalanceTransfers/{{accountBalanceTransfersId}}/destinationAccount
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-compact | true |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type accounts .
Client Services
The services section covers the client service assignments. A BankWORKS client can be assigned any service as long as the service is part of the service contract (determined by the available client contract).
A client service must always be based on a service definition blueprint. These are part of the service contract definition and can be broadly categorised as: - Acquiring Services: Acquiring of card based transactions - Miscellaneous Service: Non-card based services that can be billed by an institution - Device Services: Terminal services, required for a merchant to apply for devices.
Delete Service
Delete a client service record. Deletion is only supported for future effective services.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/services/{{serviceId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 204 (No Content)
Client Services
Retrieval of client services regardless of the serviceCategory value. In this example, filtering is being applied to the group (implying a single service contract). Also, additional filtering has been applied to filter by effectiveDate to be less or equal than the current date. The result is also being sorted by groupNumber and effectiveDate in descending order. This will result in the latest and current effetive service being returned first, followed by a list of historical versions of the client serivce organised in reverse chronoligical order.
There can be cases where the future effective client services would also be desired. In this case the filtering criteria can be amended as necessary.
Note: It is also possible to filter further using other attributes and also relationship based filtering if desired such as the serviceCategory.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/services?filter[clientNumber]={{serviceMerchantId}}&filter[groupNumber]={{serviceGroupId}}&filter[effectiveDate][LE]=2020-04-01&sort=groupNumber,serviceCategory,-effectiveDate
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[clientNumber] | {{serviceMerchantId}} |
|---|---|
| filter[groupNumber] | {{serviceGroupId}} |
| filter[effectiveDate][LE] | 2020-04-01 |
| sort | groupNumber,serviceCategory,-effectiveDate |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type services .
Create Service Record
New client service records can be defined in order to ‘modify’ an existing client service (service definition already assigned to merchant contract) or else applying for a service entirely (new service definition). Client services have an effectiveDate property which indicates when the particular record is effective. BankWORKS allows direct modification of client contracts only in specific scenarios, this covered in a separate PATCH request below.
The POST request can be sent whenever a client service is effective in the past and needs to be modified by creating either: - a new service record to be effective immediately (effectiveDate set to the current posting date). This can be done in case the current effective service is a past entry. - a new service record to be future effective.
Note: Should the current effective service record have an effectiveDate value that is equal to the current posting date, a PATCH request needs to be sent.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/services
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type services with the following attributes:
| Name | Description | |
|---|---|---|
|
status
string (3)
|
Indicates the current status of the client service. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
effectiveDate
date-only
|
The date in ISO 8601 format when the client service becomes effective. The value can be future dated and cannot be less than the posting date. If not provided, posting date +1 value is assumed only post-boarding. |
|
|
clientTariff
string (6)
|
Indicates the applicable transaction charge rules. The tariff only applies if the related merchant contract does not have a transactionChargesTariff value of “000000”. Defaults to “000000” if not provided. Applicable only to card based acquiring services. For miscellaneous service tariff, refer to the contracts resource. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
|
serviceDefinitions
required |
Link to the definition rule the service is based on. The service selected must be available within the service contract linked to the client. |
|
|
contracts
required |
Link to the client contract the service will be linked to. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type services .
Modify Service Record
Modification of a client service is allowed when the record is future dated or when the record to be modified is effective on the same posting date as the modification. In this request example, the status of service is being set to inactive.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/services/{{serviceId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type services with the following attributes:
| Name | Description | |
|---|---|---|
|
status
string (3)
|
Indicates the current status of the client service. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
clientTariff
string (6)
|
Indicates the applicable transaction charge rules. The tariff only applies if the related merchant contract does not have a transactionChargesTariff value of “000000”. Defaults to “000000” if not provided. Applicable only to card based acquiring services. For miscellaneous service tariff, refer to the contracts resource. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type services .
Disputes
The use cases contained within this section expose the merchant DMS (Dispute Management System) APIs. These typically apply to clients using the RS2 DMS module for their dispute case management and allow clients to manage disputes on behalf of merchants, performing actions such as:
Case retrieval
Retrieval of case history
Retrieval of possible actions that can be taken on behalf of a merchant given the case status.
Case evidence retrieval
Submitting a case action on behalf of merchants
For more information on our Dispute Managment System please contact your respective RS2 project manager.
Get Merchant's Cases
Retrieve a list of cases belonging to a single merchant. Results are sorted by daysToAction in ascending order in order to show the most urgent cases first. Additional filtering may be applied on other attributes such as caseStatus as needed.
An alternative to this approach would be the /merchants to /disputeCases relationship.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/disputeCases?filter[clientNumber]={{clientNumber}}&sort=daysToAction&page[limit]=5
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[clientNumber] | {{clientNumber}} |
|---|---|
| sort | daysToAction |
| page[limit] | 5 |
Response
HTTP 200 (OK)
Get Merchant's Cases by Card Org
Similar to the Get Merchant’s Cases use case with additional filtering on the transactionDate and reduces the results to a single card scheme. In this example cardOrganisation 003 (Visa).
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/disputeCases?filter[clientNumber]={{clientNumber}}&filter[transactionDate][GE]={{dateRangeStart}}&filter[transactionDate][LE]={{dateRangeEnd}}&filter[cardOrganization][EQ]={{cardOrganization}}&page[limit]=5
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[clientNumber] | {{clientNumber}} |
|---|---|
| filter[transactionDate][GE] | {{dateRangeStart}} |
| filter[transactionDate][LE] | {{dateRangeEnd}} |
| filter[cardOrganization][EQ] | {{cardOrganization}} |
| page[limit] | 5 |
Response
HTTP 200 (OK)
Get Dispute Case History
Retrieval of case history for a specific case identified by the resource ID. The history will include all actions taken including document attachment actions without including the actual evidence uploaded. Evidence needs to be requested separately, this ensures a smaller payload size.
Results are sorted to ensure the response reflects the sequence of events.
Additional filtering, sorting or retrieval of specific attributes may be applied as URL parameters.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/disputeCases/{{disputeCaseId}}/disputeCaseHistory?sort=sundryHistoryId&page[limit]=10
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| sort | sundryHistoryId |
|---|---|
| page[limit] | 10 |
Response
Get Dispute Case History - Error : HTTP 404 (Not Found)
Get Dispute Case History - Successful : HTTP 200 (OK)
Get Evidence Document
This example use case shows how a document can be retrieved. Documents attachments are treated as actions and have their own action rule ID (106 - Attached Document).
In order to retrieve a document, a disputeCaseHistory resource having action type 106 needs to be individually called and the document fields specifically requested using sparsefieldsets as indicated in this example fields=document,descriptiveDocName,fileExtension) along with the other attributes in the request. This will help to manage the high volume traffic.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/disputeCaseHistory/{{disputeCaseHistoryId}}?fields=document,descriptiveDocName,fileExtension
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| fields | document,descriptiveDocName,fileExtension |
|---|
Response
HTTP 200 (OK)
Get Dispute Case Actions
This retrieves the list of actions which can be taken on a particular dispute case identified by the disputeCases resource ID.
The response will provide information on what actions are possible including any action requriements such as attachment of evidence or notes.
One of the disputeCaseActions resource ID provided in the response will be required in order to submit an action. Refer to the POST request.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/disputeCases/{{disputeCaseId}}/disputeCaseActions
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
Get Dispute Case Actions - Error : HTTP 404 (Not Found)
Get Dispute Case Actions - Successful : HTTP 200 (OK)
Register Merchant Action
Taking a merchant action entails sending a POST request on disputeCaseHistory. Case actions must be linked to the original case and the action resource IDs (refer to relationships).
Single actions such as this example apply only for actions that do not require additional evidence to be uploaded. For such cases, please refer ot the Register Document Attachement example.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/disputeCaseHistory
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type disputeCaseHistory with the following attributes:
| Name | Description | |
|---|---|---|
|
caseType
string (3)
|
The dispute type that indicates the current stage of the case such as Retrieval Request, 1st Chargeback, Re-presentment, Pre-Arbitration, Arbitration, etc. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
noteText
string (500)
|
User entered note on action taken. Whether this is required or not is driven by the notesRequired attribute noted in disputeCaseActions. |
|
|
feesConfirmation
boolean
|
Indicates whether the merchant accepted the amount to be paid for this action. This is related to the feesConfirmation attribute in disputeCaseActions. |
|
|
riskAccepted
boolean
|
Indicates whether the merchant accepted the risk when the days to action, i.e. the merchant action time frame is equal to 0. |
|
|
plannedRefundDate
date-only
|
The date in ISO 8601 format when the actual refund date will be carried out. |
|
| Relationships | ||
|
disputeCase
required |
POSTABLE only. To link to case when taking an action. |
|
|
disputeCaseAction
required |
POSTABLE only. To link to case action when taking an action. |
|
Response
Register Merchant Action - Error : HTTP 400 (Bad Request)
Register Merchant Action - Successful : HTTP 201 (Created)
Response body will contain the created JSON:API resource of type disputeCaseHistory .
Register Document Attachment
This request is similar to the merchant action registration example however in this case multiple requests are sent. This use case applies only for actions requiring the submission of evidence (action 106). Document attachments must be linked to another action. Multiple documents can also be attached in relation to a main action for example (204 - Merchant Reject Chargeback).
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/disputeCaseHistory
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type disputeCaseHistory with the following attributes:
| Name | Description | |
|---|---|---|
|
caseType
string (3)
|
The dispute type that indicates the current stage of the case such as Retrieval Request, 1st Chargeback, Re-presentment, Pre-Arbitration, Arbitration, etc. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
noteText
string (500)
|
User entered note on action taken. Whether this is required or not is driven by the notesRequired attribute noted in disputeCaseActions. |
|
|
feesConfirmation
boolean
|
Indicates whether the merchant accepted the amount to be paid for this action. This is related to the feesConfirmation attribute in disputeCaseActions. |
|
|
document
string
|
File evidence document in any format provided that matched up to the fileExtension attribute. This should be in base 64 encoded representation. For retrieval, this is an on-demand attribute i.e. not retrieved automatically but only retrieved if specified as an included field. |
|
|
documentName
string
|
Document name provided by the merchant. |
|
|
descriptiveDocName
string
|
An autogenerated document name assigned by BankWORKS system when a document is attached to a case. This system generated document name is generated using a configured naming convention and guarantees the uniqueness of the case by adding a sequence number. (only available for document attachements action - 106) |
|
|
fileExtension
string
|
This is the file extension of the document provided (e.g. jpg, pdf, etc.) Applicable for document attachment actions only - 106. |
|
|
riskAccepted
boolean
|
Indicates whether the merchant accepted the risk when the days to action, i.e. the merchant action time frame is equal to 0. |
|
|
plannedRefundDate
date-only
|
The date in ISO 8601 format when the actual refund date will be carried out. |
|
| Relationships | ||
|
disputeCase
required |
POSTABLE only. To link to case when taking an action. |
|
|
disputeCaseAction
required |
POSTABLE only. To link to case action when taking an action. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type disputeCaseHistory .
Merchant Hierarchy
A section containing sample calls relating to the merchant billing and settlement hierarchy. In BankWORKS the hierarchy represents the billing structure which is composed of:
- Group (top most level), a single client representing the merchant group.
- Member (bottom of the hierarchy), the transacting level merchants at the very end of the hierarchy nodes.
- Sub-Group (between a group and member), any client residing between a group and member level client. Any level in between a group and a member would be a sub-group level.
Get hierarchy using groupNumber
Returns a merchant hierarchy using groupNumber identifying the merchant hierarchy along with all nodes returning the current effective contracts and past contract versions.
IMPORTANT POINTS: - response will not be in a top-down level format - in order to indicate which parent node the merchant belongs to, parentContracts has been included in the relationships - if merchant already has history of contract records, provide the effective date which is less than the date today and sorted in descending order. The most effective contract will be the first record returned in the response for each client node in the hierarchy.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contracts?filter[groupNumber]={{groupNumber}}&sort=-effectiveDate&include=parentContracts&filter[effectiveDate][LE]=2020-04-01
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[groupNumber] | {{groupNumber}} |
|---|---|
| sort | -effectiveDate |
| include | parentContracts |
| filter[status] | 00 |
| fields[merchants] | ourReference |
| fields | id |
| filter[effectiveDate][LE] | 2020-04-01 |
Response
HTTP 200 (OK)
Get Merchant Groups
Returns the merchant’s active groups, with the results sorted by groupNumber, and effectiveDate in reverse chronoligical order. A number attributes are selected to simplify the response and the contractDefinition is being included to indicate the serviceContractId of the hierarchical group.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000/contracts?filter[effectiveDate][LE]=2020-04-01&filter[status]=001&sort=groupNumber,-effectiveDate&fields=effectiveDate,groupNumber,contractReference,clientLevel&fields[contractDefinitions]=serviceContractId&include=contractDefinition
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[effectiveDate][LE] | 2020-04-01 |
|---|---|
| filter[status] | 001 |
| sort | groupNumber,-effectiveDate |
| fields | effectiveDate,groupNumber,contractReference,clientLevel |
| fields[contractDefinitions] | serviceContractId |
| fields[merchants] | ourReference |
| include | contractDefinition |
Response
HTTP 200 (OK)
Response body will contain the result of the JSON PATCH operation for the following resources: contracts contractDefinitions
Get Member level of a hierarchy
Retrieve the transacting level contracts of a particular hierarchy identified by the groupNumber value.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contracts?filter[groupNumber]={{groupNumber}}&filter[clientLevel]=001&fields=id&include=parentContracts
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[clientNumber] | 00000229 |
|---|---|
| filter[groupNumber] | {{groupNumber}} |
| filter[clientLevel] | 001 |
| include | merchant.addresses,accounts.settlementPackage |
| fields | id |
| include | parentContracts |
Response
HTTP 200 (OK)
Get Direct Child Contracts
This call will return the direct Children contracts beneath the Group or Sub-Group Level merchant.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contracts/clientNumber=10050000&groupNumber=00000001&effectiveDate=2020-04-01&clientLevel=001/childContracts?include=merchant
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| include | merchant |
|---|
Response
HTTP 200 (OK)
Get Child Hierarchy
This call will return all the children contracts beneath the Group or Sub-Group Level merchant.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/contracts/clientNumber=10050000&groupNumber=00000001&effectiveDate=2020-04-01&clientLevel=001/childHierarchy?include=parentContracts,merchant
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| include | parentContracts,merchant |
|---|
Response
HTTP 200 (OK)
Merchant Devices
This section deals with merchant devices which can be applied to merchants at the transacting level (member level of a hierarchy). In BankWORKS, devices can be added to merchants having the respective device service assigned. This means that prior to defining a new merchant device: - The merchant must have a device service assinged. - If no device service is available, assign the service to the merchant first.
Note: Device services must be available in the merchant service contract in order to be available for assignment. The below requests are provided with the assumption that the merchant would already have device services assigned.
Merchant Device Fees Rules
Device fees can be set at contract level or individual terminal level. Contract level fees are inherited part of the service contract setup. In case further individual terminal fee overrides are required, it is possible to define an individual fee.
Essentially, device fees are service fees linked to the device service. More information on contract based fees may be found in the contract-based device fees section.
Retrieve Device Fees
Returns the individual device fee setup related to the filtered terminal id.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/devices/clientNumber=00001953&terminalId=00001954/deviceFeeDefinitions
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
Delete an Individual Device Fee
Delete an individual device Fee. At a minimum the record being deleted must have an effectiveDate value that is at least 1 day ahead of the current posting date. Deletion of the current effective or past setup rules is not allowed.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/deviceFeeDefinitions/{{deviceFeeDefinitionsId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 204 (No Content)
Create Individual Device Fee
Define a new individual terminal fee. These must be based on an existing contract-based fee which is already part of the merchant service contract. Attributes not passed in the body will inherit the contract based value.
Device fees have an effectiveDate property which indicates when the particular record is effective. BankWORKS allows direct modification of individual device fees only in specific scenarios, this is covered in a separate PATCH request below.
The POST request can be sent whenever an individual fee is effective in the past and needs to be modified by creating either: - a new fee record to be effective immediately (effectiveDate set to the current posting date). This can be done in cases the current effective fee is a past entry. - a new fee record to be future effective.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/deviceFeeDefinitions
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type deviceFeeDefinitions with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
effectiveDate
date-only
|
Date when the device fee becomes. Defaults to the current posting date unless provided. Dates prior to the current posting date are not allowed. |
|||||||
|
expiryDate
date-only
|
Defines the date when the fee will expire and hence will no longer be generated. |
|||||||
|
feeBase
object
|
The base amount of the fee in relation to the value on which it is calculated.
|
|||||||
|
feeMinimum
object
|
The minimum fee amount that will always be generated if calculated percentage is lower.
|
|||||||
|
feeMaximum
object
|
The maximum fee amount that will always be generated if calculated percentage is higher.
|
|||||||
|
feeMode
string (3)
|
The flag which indicates whether the fee is to be generated or suppressed. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
fixedPeriod
number (3)
|
Number of days due after the period reference. |
|||||||
|
periodReference
string (3)
|
Determines the value date of the fee, eg. Posting Date. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
referenceOperator
string (3)
|
Sign operator related to fixedPeriod following the periodReference. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
triggerPeriod
string (3)
|
The frequency when the defined fee will be processed e.g. Daily, End of Cycle etc. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
| Relationships | ||||||||
|
devices
required |
Link to the merchant device. |
|||||||
|
contractFees
required |
Link to the contract contract-based fee that will be overriden with this terminal fee. |
|||||||
Response
POST Individual Terminal Fee - client 00001953, tid 00001954 : HTTP 201 (Created)
POST Individual Terminal Fee - future effective : HTTP 201 (Created)
Response body will contain the created JSON:API resource of type deviceFeeDefinitions .
Modify an Individual Device Fee
Modification of an individual device fee is allowed when the record is future dated or when the record to be modified is effective on the same posting date as the modification.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/deviceFeeDefinitions/recordIdNumber=0000104671
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type deviceFeeDefinitions with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
expiryDate
date-only
|
Defines the date when the fee will expire and hence will no longer be generated. |
|||||||
|
feeBase
object
|
The base amount of the fee in relation to the value on which it is calculated.
|
|||||||
|
feeMinimum
object
|
The minimum fee amount that will always be generated if calculated percentage is lower.
|
|||||||
|
feeMaximum
object
|
The maximum fee amount that will always be generated if calculated percentage is higher.
|
|||||||
|
feeMode
string (3)
|
The flag which indicates whether the fee is to be generated or suppressed. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
fixedPeriod
number (3)
|
Number of days due after the period reference. |
|||||||
|
periodReference
string (3)
|
Determines the value date of the fee, eg. Posting Date. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
referenceOperator
string (3)
|
Sign operator related to fixedPeriod following the periodReference. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
|
triggerPeriod
string (3)
|
The frequency when the defined fee will be processed e.g. Daily, End of Cycle etc. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||
| Relationships | ||||||||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type deviceFeeDefinitions .
Delete Device
Deletion of a merchant device.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/devices/{{memberDeviceId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 204 (No Content)
Merchant Devices
Retrieval of merchant devices. A merchant device is linked to a service and subsequently to a merchant contract.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/devices?filter[services.contracts.merchant.id]=clientNumber=10050000
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[services.contracts.merchant.id] | clientNumber=10050000 |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type devices .
Create New Device
This call is used to add a merchant terminal/device, applicable to transacting level (member level) merchants. A device must be based on a device service
Note: In order for a device creation request to be accepted, the merchant must have the MID available in the ourReference attribute.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/devices
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type devices with the following attributes:
| Name | Description | |
|---|---|---|
|
terminalId
string (8)
required
|
Terminal ID assigned to the device. |
|
|
serialNumber
string (16)
|
Terminal serial number. |
|
|
status
string (3)
required
|
Indicates the current terminal status. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
terminalType
string (3)
|
The model terminal type if it is a virtual POS, specific POS model or kind of POS terminal. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
terminalProfile
string (3)
|
A 3-character index-based value which determines the use of a POS device. E.g. Petrol-Unattended or Retail POS. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
currency
string (3)
required
|
The currency of the device in ISO 3-letter SWIFT format. In cases where value consists of 3 digits:
|
|
|
contactName
string (35)
|
Contact person responsible for the terminal. |
|
|
posCapability
string (3)
required
|
The terminal capability for PAN PIN entry. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
endOfDayIndicator
string (3)
required
|
Defines the end-of-day method. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
|
services
required |
Link to the client service representing the device. This must be a serviceCategory 022 service, representing a device. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type devices .
Modify Device
Request to modify a merchant device identified by it’s ID. Refer to table below for more information on what can be amended.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/devices/clientNumber=00001953&terminalId=00001954
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type devices with the following attributes:
| Name | Description | |
|---|---|---|
|
serialNumber
string (16)
|
Terminal serial number. |
|
|
status
string (3)
|
Indicates the current terminal status. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
terminalType
string (3)
|
The model terminal type if it is a virtual POS, specific POS model or kind of POS terminal. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
terminalProfile
string (3)
|
A 3-character index-based value which determines the use of a POS device. E.g. Petrol-Unattended or Retail POS. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
contactName
string (35)
|
Contact person responsible for the terminal. |
|
|
posCapability
string (3)
|
The terminal capability for PAN PIN entry. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
endOfDayIndicator
string (3)
|
Defines the end-of-day method. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
| Relationships | ||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type devices .
Miscellaneous Batch Input
This resource represents Miscellaneous transactions i.e. adjustments manually entered in BankWorks. This is composed of miscellaenousBatches (batch) and its indivividual transactions (miscellaneousBatchSlips). Requests are sequentially placed from creation of batch to individual slips and down to Approving the miscellaneous batch and slips for processing. Delete, Get, and Patch requests (except for item 3) are optional in case some changes are needed.
1. Add New Batch
Creation of miscellaneous batch for the related transaction slips entry.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/miscellaneousBatches
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type miscellaneousBatches with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
numberOriginalSlip
string (11)
|
Free text reference up to 11 characters. This field can be used to refer to an external (outside of BankWORKS) transaction. If this is null/empty, it will be generated similar with transactionSlip. |
|||||||
|
totalBatchAmount
object
|
If it is 0, the totalBatchAmount can be calculated by calculating the Sum of transactionAmountGross values provided in the slips. This should be done upon sending a PATCH request to set the processingStatus to ‘008’, as this would indicate that all the required slips have been entered and linked to the batch. In order to calculate this amount the following need to be considered: -Transaction amount of the individual slips -Transaction type of each slip. The transaction type determines the respective DR/CR indicator. To determine if a transaction is a debit or credit AT DESTINATION, the BWT_BATCH_TRANSACTIONS entry will need to be checked with the equivalent in BWT_BATCH_TRANSACTIONS in order to retrieve the DESTINATION_SIGN. The first character of the DESTINATION_SIGN field indicates whether the transaction will be a C (Credit) or D (Debit) at destination. -Finally once the amount is converted to the destination sign. The REVERSAL_FLAG value must be considered. A credit (plus) to the merchant account that is reversed (REVERSAL_FLAG = 001) results in a debit to the merchant account (minus) and vice versa. Alternatively, if provided, the totalBatchAmount Value must match with the Sum of the slip amounts provided. This value would be validated when approving the transaction for processing by setting processingStatus to ‘008’. Total Batch Amount currency, indicates the currency of the batch. Any transactions linked to the batch must match with this batch currency.
|
|||||||
|
numberOfSlips
number
|
If not provided, the number of slips can be calculated on the number of individual transaction slips provided in the slips list.This should be done upon sending a PATCH request to set the processingStatus to ‘008’, as this would indicate that all the required slips have been entered and linked to the batch. Alternatively, if provided, the numberOfSlips value should match with the count of slips provided. This value would be validated when approving the transaction for processing by setting processingStatus to ‘008’ |
|||||||
| Relationships | ||||||||
Response
HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type miscellaneousBatches .
1.1 Get Batches
Returns a batches and related transactions (miscellaneousBatchSlips).
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/miscellaneousBatches/?include=transactions,transactions.account
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Parameters
| include | transactions,transactions.account |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type miscellaneousBatches with transactions,transactions.accountas included resources.
1.2 Update or Cancelled Batch
This to update other batch attributes or cancellation of batch for unprocessed transactions.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/miscellaneousBatches/{{miscellaneousBatchId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type miscellaneousBatches with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
numberOriginalSlip
string (11)
|
Free text reference up to 11 characters. This field can be used to refer to an external (outside of BankWORKS) transaction. If this is null/empty, it will be generated similar with transactionSlip. |
|||||||
|
processingStatus
string (3)
|
The processing status indicates the current state of the batch. A batch initially has an Entered (007) status. The batch can be set to Cancelled (017). However, the batch or transactions related to this batch can still be modified or add a new transactions. Then the batch can be set to Approved (008) for processing. Once a batch of transactions is successfully processed, the processingStatus will indicate a value of Loaded (005). |
|||||||
|
totalBatchAmount
object
|
If it is 0, the totalBatchAmount can be calculated by calculating the Sum of transactionAmountGross values provided in the slips. This should be done upon sending a PATCH request to set the processingStatus to ‘008’, as this would indicate that all the required slips have been entered and linked to the batch. In order to calculate this amount the following need to be considered: -Transaction amount of the individual slips -Transaction type of each slip. The transaction type determines the respective DR/CR indicator. To determine if a transaction is a debit or credit AT DESTINATION, the BWT_BATCH_TRANSACTIONS entry will need to be checked with the equivalent in BWT_BATCH_TRANSACTIONS in order to retrieve the DESTINATION_SIGN. The first character of the DESTINATION_SIGN field indicates whether the transaction will be a C (Credit) or D (Debit) at destination. -Finally once the amount is converted to the destination sign. The REVERSAL_FLAG value must be considered. A credit (plus) to the merchant account that is reversed (REVERSAL_FLAG = 001) results in a debit to the merchant account (minus) and vice versa. Alternatively, if provided, the totalBatchAmount Value must match with the Sum of the slip amounts provided. This value would be validated when approving the transaction for processing by setting processingStatus to ‘008’. Total Batch Amount currency, indicates the currency of the batch. Any transactions linked to the batch must match with this batch currency.
|
|||||||
|
numberOfSlips
number
|
If not provided, the number of slips can be calculated on the number of individual transaction slips provided in the slips list.This should be done upon sending a PATCH request to set the processingStatus to ‘008’, as this would indicate that all the required slips have been entered and linked to the batch. Alternatively, if provided, the numberOfSlips value should match with the count of slips provided. This value would be validated when approving the transaction for processing by setting processingStatus to ‘008’ |
|||||||
| Relationships | ||||||||
Response
HTTP 202 (Accepted)
Response body will contain the updated JSON:API resource of type miscellaneousBatches .
1.3 Delete Batch
Deletion of batch for unprocessed transactions.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/miscellaneousBatches/{{miscellaneousBatchId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 500 (Internal Server Error)
Response body will contain the deleted JSON:API resource of type miscellaneousBatches .
2. Add New Batch Slip
Creation of individual transaction slips that will compose the related batch.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/miscellaneousBatchSlips
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type miscellaneousBatchSlips with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
numberOriginalSlip
string (11)
|
Free text reference up to 11 characters. This field can be used to refer to an external (outside of BankWORKS) transaction. If this is null/empty, it will be generated similar with transactionSlip. |
|||||||
|
transactionType
string (3)
required
|
Type of transaction i.e. Miscellaneous Debit (950), Miscellaneous Credit (951), etc. |
|||||||
|
transactionCategory
string (3)
required
|
This value is used to identify what category the transaction belongs to, e.g Charges & Fees, Adjustments, etc. |
|||||||
|
transactionDate
date-only
|
Date of the transaction. Must be less than or equal to the current posting date. |
|||||||
|
valueDate
date-only
|
The date from when action can be taken upon a transaction. |
|||||||
|
transactionAmountGross
object
required
|
The amount of the individual transaction. Must be greater than 0 and the currency value must match with the batch currency!
|
|||||||
|
reversalFlag
string (3)
|
Indicator used to identify if the transaction is reversed or not. Defaulted to 000 (No). |
|||||||
|
cardAlias
string
|
This information is currently not supported. |
|||||||
|
cardNumber
string
|
This entry is currently not supported. Only a relationship to account is required during POST. |
|||||||
|
narrative
string (30)
|
Free text reference. If not provided default to the transactionType TEXTUAL description. |
|||||||
| Relationships | ||||||||
|
batch
required |
A transaction must always be linked to a batch. Note, transaction can only be linked to a batch if changes are allowed, i.e processing status either Entered (007) or Error (003). |
|||||||
|
account
required |
A transaction must always be linked to an account. |
|||||||
Response
HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type miscellaneousBatchSlips .
2.1 Get Batch Slips
Retrieval of a specified individual batch slip including the batch (/miscellaneousBatches) and related account (/accounts).
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/miscellaneousBatchSlips?include=batch,account
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Parameters
| include | batch,account |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type miscellaneousBatchSlips with batch,accountas included resources.
2.2 Update Batch Slip
Amendment of any batch slips entered which status is Entered (007), In Error (003) or Cancelled (017) only.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/miscellaneousBatchSlips/{{miscellaneousBatchSlipId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type miscellaneousBatchSlips with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
numberOriginalSlip
string (11)
|
Free text reference up to 11 characters. This field can be used to refer to an external (outside of BankWORKS) transaction. If this is null/empty, it will be generated similar with transactionSlip. |
|||||||
|
transactionType
string (3)
|
Type of transaction i.e. Miscellaneous Debit (950), Miscellaneous Credit (951), etc. |
|||||||
|
transactionCategory
string (3)
|
This value is used to identify what category the transaction belongs to, e.g Charges & Fees, Adjustments, etc. |
|||||||
|
transactionDate
date-only
|
Date of the transaction. Must be less than or equal to the current posting date. |
|||||||
|
valueDate
date-only
|
The date from when action can be taken upon a transaction. |
|||||||
|
transactionAmountGross
object
|
The amount of the individual transaction. Must be greater than 0 and the currency value must match with the batch currency!
|
|||||||
|
reversalFlag
string (3)
|
Indicator used to identify if the transaction is reversed or not. Defaulted to 000 (No). |
|||||||
|
cardAlias
string
|
This information is currently not supported. |
|||||||
|
cardNumber
string
|
This entry is currently not supported. Only a relationship to account is required during POST. |
|||||||
|
narrative
string (30)
|
Free text reference. If not provided default to the transactionType TEXTUAL description. |
|||||||
| Relationships | ||||||||
Response
HTTP 202 (Accepted)
Response body will contain the updated JSON:API resource of type miscellaneousBatchSlips .
2.3 Delete Batch Slip
Deletion of batch slips according to the qualified status.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/miscellaneousBatchSlips/{{miscellaneousBatchSlipId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 500 (Internal Server Error)
Response body will contain the deleted JSON:API resource of type miscellaneousBatchSlips .
3. Approve Batch
Approving the batch by setting the processing status to Approved (008) to be sent to processing.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/miscellaneousBatches/{{miscellaneousBatchId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type with the following attributes:
| Name | Description |
|---|
Response
HTTP 202 (Accepted)
Response body will contain the updated JSON:API resource of type miscBatches .
Payments
Section covering payment transactions. Payments settle BankWORKS accounts against a third party RBS account. Funds may be transferred to and from the third party account, depending on the scenario. For instance to settle a fee account, amounts may be transferred from the third party account towards the fee account, whereas to settle a payment account retail, funds will have to be transferred to the third party account.
Get Payments
Retrieval of all payment transactions that fall within a specified date range. The results are sorted by clientNumber and paymentDate in descending order with a page limit of 10 resources (payments) per page.
The attribute paymentDate must be included in the filter. The maximum range is 95 days (31 + 30 + 31 days = 92 days) + 2 timezone offset + 1 extra.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/payments?filter[payments][paymentDate][GE]=2024-01-01&filter[payments][paymentDate][LE]=2024-12-31&sort=clientNumber,-paymentDate&page[offset]=0&page[limit]=10
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[payments][paymentDate][GE] | 2024-01-01 |
|---|---|
| filter[payments][paymentDate][LE] | 2024-12-31 |
| sort | clientNumber,-paymentDate |
| page[offset] | 0 |
| page[limit] | 10 |
Response
HTTP 200 (OK)
Get Payments by Client Number
This GET request returns a list filtered by the clientNumber property. Results are filtered by paymentDate range. Results are sorted by paymentDate in descending order and limited to 3 resources per page. Pagination can be removed if not required. Further URL paramters such as fields can be used to limit the attributes returned if desired.
The attribute paymentDate must be included in the filter. The maximum range is 95 days (31 + 30 + 31 days = 92 days) + 2 timezone offset + 1 extra.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/payments?filter[payments][clientNumber]=00000064&filter[payments][paymentDate][GE]=2024-01-01&filter[payments][paymentDate][LE]=2024-12-31&sort=-paymentDate&page[offset]=0&page[limit]=3
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[payments][clientNumber] | 00000064 |
|---|---|
| filter[payments][paymentDate][GE] | 2024-01-01 |
| filter[payments][paymentDate][LE] | 2024-12-31 |
| sort | -paymentDate |
| page[offset] | 0 |
| page[limit] | 3 |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type payments .
Get Payments By Merchant and Account Type ID
This GET request returns a list of payments for a particular client number, and date range. Payments are retrieved for all merchant accounts defined as accountType 012. Filtering can be applied for other account types as needed. Results are sorted by paymentDate in descending order and 4 results per page are returned.
The attribute paymentDate must be included in the filter. The maximum range is 95 days (31 + 30 + 31 days = 92 days) + 2 timezone offset + 1 extra.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/payments?filter[payments][clientNumber]=00000028&filter[payments][paymentDate][GE]=2024-12-08&filter[payments][paymentDate][LE]=2024-12-11&filter[payments][account.accountDefinition.accountTypeId]=052&&sort=-paymentDate&page[offset]=0&page[limit]=4
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[payments][clientNumber] | 00000028 |
|---|---|
| filter[payments][paymentDate][GE] | 2024-12-08 |
| filter[payments][paymentDate][LE] | 2024-12-11 |
| filter[payments][account.accountDefinition.accountTypeId] | 052 |
| sort | -paymentDate |
| page[offset] | 0 |
| page[limit] | 4 |
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type payments .
Payment Rejects
Section covering payment reject transactions. These are the rejected transactions that were received back in a reject file and were loaded into the system. The user can take an action to either resubmit or modify any of the information that may have led to the problem.
Get All Payment Rejects
Retrieval of all payment reject transactions. The results are sorted by clientNumber and transactionsDate in descending order with a page limit of 10 resources (paymentRejects) per page.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/paymentRejects?sort=clientNumber,-transactionDate&page[offset]=0&page[limit]=10
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| sort | clientNumber,-transactionDate |
|---|---|
| page[offset] | 0 |
| page[limit] | 10 |
Response
HTTP 200 (OK)
Get All Loaded Reject Sundries
An example request to return all loaded status reject sundries without focusing on a particular merchant.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/paymentRejectSundries?filter[processingStatus]=005
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[processingStatus] | 005 |
|---|
Response
HTTP 200 (OK)
Get Reject Sundry
A request to retrieve the payment reject sundry instruction associated with the outward payment. This will only be available when rejectedPayment attribute is 001 (Yes). Refer to GET payments use cases for examples on how payments can be retrieved.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/payments/{{paymentId}}/paymentRejectSundry
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
Take Action on Reject
Payment rejects can be either approved or written off. This PATCH request is provided as an example of taking an action on a payment reject identified via the previous request.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/paymentRejectSundries/{{paymentRejectSundryId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type paymentRejectSundries with the following attributes:
| Name | Description | |
|---|---|---|
|
investigationStatus
string (3)
required
|
Investigation status to be provided when taking an action on the reject. Must be provided when taking an action. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
noteText
string (2000)
required
|
Freetext attribute for recording the reason for the action taken. Must be provided when taking an action. |
|
|
processingStatus
string (3)
|
Indicates the current processing status of the Sundry instruction. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|
|
actionTaken
string (3)
required
|
Indicates the action take on the payment reject sundry.
|
|
| Relationships | ||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type paymentRejectSundries .
Payment Instructions
In BankWORKS, the payment instructions are settlement instruction rules that drive account settlement process. In this regard, payment instructions are very similar to settlementSchemes, the main difference being that payment instructions are defined for a particular merchant account.
Payment instructions are defined for a contract group or individual client and may affect a number of different accounts.Payment instructions allow for more fine grained settlement rules to be defined per merchant account.
Payment Instructions
Retrieval of payment instruction records linked to a merchant account. In this particular example, filtering is being applied on the related accounts resource to return payment instructions defined for a particular merchant account identified by the BankWORKS account number.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/paymentInstructions?filter[account.accountNumber]=10050002002
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[account.accountNumber] | 10050002002 |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type paymentInstructions .
Add Payment Instructions
A request to create new payment instructions record.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/paymentInstructions
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type paymentInstructions with the following attributes:
| Name | Description | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
transactionType
string (3)
required
|
Defines the transaction type assigned to the outgoing transaction. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||||||||
|
paymentBase
decimal (18)
|
Fixed base amount applied to the generated payment. Defaulted to zero if not sent. |
|||||||||||||||||||
|
paymentPercentage
decimal (11)
|
Percentage amount based on the total payable amount. This is applied to the payment base. Defaulted to zero if not sent. |
|||||||||||||||||||
|
paymentMinimum
decimal (18)
|
Minimum amount generated should paymentBase paymentPercentage not reach the minimum threshold. Defaulted to zero if not sent. |
|||||||||||||||||||
|
paymentMaximum
decimal (18)
|
Maximum amount generated should paymentBase paymentPercentage go over the mamximum threshold. Defaulted to zero if not sent. |
|||||||||||||||||||
|
executionCountLimit
int (11)
|
The total payment instruction execution count limit. This is compared with the execution counter and when the threshold defined is reached, the instruction no longer executes. |
|||||||||||||||||||
|
notes
string (1300)
|
Allows a generic text description to be provided with the rule for reference purposes. |
|||||||||||||||||||
|
paymentCategory
string (3)
required
|
Indicates the settlement category of the payment instruction. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||||||||
|
clearingChannel
string (3)
required
|
Defines the outgoing clearing channel assigned to the payment transactions generated. The destinationSettleAccount relationship (see below) is required when passing a value of “018”, indicating the Outward On-Us channel. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||||||||
|
trigger
object
|
|
|||||||||||||||||||
|
executionAmountLimit
decimal (11)
|
The total limit threshold allowed for the payment instruction rule. This works in conjunction with the executionAmountPaid. Once this limit is reached, the payment instruction rule no longer executes. |
|||||||||||||||||||
| Relationships | ||||||||||||||||||||
|
account
required |
Accounts which this payment instructions will be applied. |
|||||||||||||||||||
|
destinationSettleAccount
|
Relationship to an accounts resource belonging to the entity receiving a percentage of the settlement. This applies to merchant partial payment scenarios. |
|||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type paymentInstructions .
Modify Payment Instructions
Request to modify a payment instruction identified by it’s instructionIdNumber. Refer to table below for more information on what can be amended.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/paymentInstructions/{{paymentInstructionId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type paymentInstructions with the following attributes:
| Name | Description | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
transactionType
string (3)
required
|
Defines the transaction type assigned to the outgoing transaction. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||||||||
|
paymentBase
decimal (18)
|
Fixed base amount applied to the generated payment. Defaulted to zero if not sent. |
|||||||||||||||||||
|
paymentPercentage
decimal (11)
|
Percentage amount based on the total payable amount. This is applied to the payment base. Defaulted to zero if not sent. |
|||||||||||||||||||
|
paymentMinimum
decimal (18)
|
Minimum amount generated should paymentBase paymentPercentage not reach the minimum threshold. Defaulted to zero if not sent. |
|||||||||||||||||||
|
paymentMaximum
decimal (18)
|
Maximum amount generated should paymentBase paymentPercentage go over the mamximum threshold. Defaulted to zero if not sent. |
|||||||||||||||||||
|
executionCountLimit
int (11)
|
The total payment instruction execution count limit. This is compared with the execution counter and when the threshold defined is reached, the instruction no longer executes. |
|||||||||||||||||||
|
notes
string (1300)
|
Allows a generic text description to be provided with the rule for reference purposes. |
|||||||||||||||||||
|
paymentCategory
string (3)
required
|
Indicates the settlement category of the payment instruction. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||||||||
|
clearingChannel
string (3)
required
|
Defines the outgoing clearing channel assigned to the payment transactions generated. The destinationSettleAccount relationship (see below) is required when passing a value of “018”, indicating the Outward On-Us channel. Refer to BankWorks (API) Data Mapping documentation for possible values. |
|||||||||||||||||||
|
trigger
object
|
|
|||||||||||||||||||
|
executionAmountLimit
decimal (11)
|
The total limit threshold allowed for the payment instruction rule. This works in conjunction with the executionAmountPaid. Once this limit is reached, the payment instruction rule no longer executes. |
|||||||||||||||||||
| Relationships | ||||||||||||||||||||
|
account
|
if there is chanage on binded account |
|||||||||||||||||||
|
destinationSettleAccount
|
Relationship to an accounts resource belonging to the entity receiving a percentage of the settlement. This applies to merchant partial payment scenarios. |
|||||||||||||||||||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type paymentInstructions .
Delete Payment Instruction
Delete a payment instruction record.
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/paymentInstructions/{{paymentInstructionId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 204 (No Content)
Response body will contain the deleted JSON:API resource of type paymentInstructions .
Pricing
This use case section covers pricing using the tariff based pricing approach. Two types of tariffs can be set up using this method, transaction charge tariff covering per-transaction charges and client tariffs covering account and service fees. Both tariffs are linked to the merchant contract (see /contracts resource).
This method of pricing requires a source tariff to be identified as the starting point and allows certain rules to be overridden prior to processing the tariff request. Refer to each section for more details on the flow.
Transaction Charge Tariff
Transaction charges are grouped under a merchant transaction charge tariff. Clients are assigned this transaction charge tariff to the contract which determines the applicable fees (see /contracts).
The pricing resources allow institution or broker clients to define new pricing tariffs that are based on existing setup. In order to define a new transaction charge tariff:
1) The source transaction charge tariff needs to be first identified. Refer to steps 1 and 2 which provide examples on how a list of tariff and it’s contents can be retrieved.
2) A POST request can be sent with the new tariff description linking to the source tariff via a relationship. This results in the new tariff being cloned off the source tariff with the default rates. Refer to step 3 for more information.
3) Amendable rates can be overridden on the new tariff as desired. Refer to Step 4.
4) Finally the tariff can be processed by amending the processing status.
Once a tariff is created it can be be assigned to existing or clients being defined in BankWORKS.
NOTE: Unprocessed tariffs have a time-to-live (ttl) property which determines how long in seconds these will be available before automatically being cleaned up.
1. Retrieve transaction charge tariffs by Service Contract Id
A request to return a list of available (processed) transaction charges tariffs belonging to a service contract.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchantTransactionTariffs?filter[serviceContractId]=101&filter[processed]=true
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[serviceContractId] | 101 |
|---|---|
| filter[processed] | true |
Response
HTTP 200 (OK)
2. Retrieve transaction charge tariff rules
Return the transaction charge tariff contents of a particular tariff by the resource ID which is identified in the previous step.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchantTransactionTariffs/{{merchantTransactionTariffId}}/transactionTariffRules
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[serviceContractId] | 101 |
|---|---|
| filter[processed] | true |
Response
HTTP 200 (OK)
3. Define a new transaction charge tariff
Definition of a new transaction charge tariff based on a source template identified in the previous steps. This will result in a new transaction charge tariff that is a copy of the old transaction charge tariff but with processed status false.
The new transaction charge tariff and it’s contents can be retrieved by sending a GET request similar to Step 2.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantTransactionTariffs
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantTransactionTariffs with the following attributes:
| Name | Description | |
|---|---|---|
|
description
string
required
|
Descriptive name of the tariff. Up to 25 characters. |
|
| Relationships | ||
|
sourceTemplate
required |
The source tariff to be cloned for modification. The tariff must be processed. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type merchantTransactionTariffs .
4. Update transaction charge tariff rules
Amendable rules of an unprocessed transaction charge tariff can be modified by submitting a PATCH request on the respective rule resource ID. Please refer to the below list of amendable fields. Only unprocessed tariffs can be modified. This step may be repeated as necessary.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/transactionTariffRules/{{transactionTariffRuleId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type transactionTariffRules with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
feePercent
number
|
The percentage value used to generate the fee for product based on fee trigger setup. Maximum allowed length (including decimal point) is 11. |
|||||||
|
feeMinimum
object
|
Indicates the minimum value that can be charged for the product if the feeBase and feePercent values are LOWER than this value. Note that all fee amount currencies MUST match. Maximum allowed length (including decimal point) is 11.
|
|||||||
|
feeMaximum
object
|
Indicates the maximum value that can be charged for the product if the feeBase and feePercent values are GREATER than this value. Note that all fee amount currencies MUST match. Maximum allowed length (including decimal point) is 11.
|
|||||||
|
feeBase
object
|
The standard amount generated for the product fee. Note that all fee amount currencies MUST match. Maximum allowed length (including decimal point) is 11.
|
|||||||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type transactionTariffRules .
5. Process the new transaction charge tariff
This call, which is the final step in defining a new transaction charge tariff, is MANDATORY.
This PATCH request triggers the process to transfer the newly cloned transaction charge tariff from interim storage to Oracle DB. An API response of 200 or 201 (successful), indicating that the tariff was successfully processed and activated, will also be passed when the processing is completed.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchantTransactionTariffs/{{merchantTransactionTariffId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantTransactionTariffs with the following attributes:
| Name | Description | |
|---|---|---|
|
description
string
|
Descriptive name of the tariff. Up to 25 characters. |
|
|
processed
boolean
required
|
Set to true to process or activate the newly cloned transaction tariffs. |
|
| Relationships | ||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type merchantTransactionTariffs .
Retrieve list of unprocessed transaction charge tariffs
Return the tariff contents of a particular tariff by the resource ID which is identified in the previous step.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchantTransactionTariffs?filter[processed]=false
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[processed] | false |
|---|
Response
HTTP 200 (OK)
Client Tariff
Client tariffs group account and service fees under an identifier. Clients are assigned a client tariff to the contract which determines the applicable fees (see /contracts).
The pricing resources allow institution or broker clients to define new pricing tariffs that are based on existing setup. In order to define a new client tariff:
1) The source client tariff needs to be first identified. Refer to steps 1 and 2 which provide examples on how a list of tariff and it’s contents can be retrieved.
2) A POST request can be sent with the new tariff description linking to the source tariff via a relationship. This results in the new tariff being cloned off the source tariff with the default rates. Refer to step 3 for more information.
3) Amendable rates can be overridden on the new tariff as desired. Refer to Step 4.
4) Finally the tariff can be processed by amending the processing status.
Once a tariff is created it can be be assigned to existing or clients being defined in BankWORKS.
NOTE: Unprocessed tariffs have a time-to-live (ttl) property which determines how long in seconds these will be available before automatically being cleaned up.
1. Retrieve client tariffs by Service Contract Id
A request to return a list of available (processed) tariffs belonging to a service contract.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchantClientTariffs?filter[serviceContractId]=101&filter[processed]=true
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[serviceContractId] | 101 |
|---|---|
| filter[processed] | true |
Response
HTTP 200 (OK)
2. Retrieve client tariff rules
Return the tariff contents of a particular tariff by the resource ID which is identified in the previous step.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchantClientTariffs/{{merchantClientTariffId}}/clientTariffRules
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[serviceContractId] | 101 |
|---|---|
| filter[processed] | true |
Response
HTTP 200 (OK)
3. Define a new tariff
Definition of a new tariff based on a source template identified in the previous steps. This will result in a new tariff that is a copy of the old tariff but with processed status false.
The new tariff and it’s contents can be retrieved by sending a GET request similar to Step 2.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/merchantClientTariffs
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantClientTariffs with the following attributes:
| Name | Description | |
|---|---|---|
|
description
string
required
|
Descriptive name of the tariff. Up to 25 characters. |
|
| Relationships | ||
|
sourceTemplate
required |
The source tariff to be cloned for modification. The tariff must be processed. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type merchantClientTariffs .
4. Update tariff rules
Amendable rules of an unprocessed tariff can be modified by submitting a PATCH request on the respective rule resource ID. Please refer to the below list of amendable fields. Only unprocessed tariffs can be modified. This step may be repeated as necessary.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/clientTariffRules/{{clientTariffRuleId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type clientTariffRules with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
feePercent
number
|
The percentage value used to generate the fee for account fee trigger setup. Maximum allowed length (including decimal point) is 11. |
|||||||
|
feeMinimum
object
|
Indicates the minimum value that can be charged for the account if the feeBase and feePercent values are LOWER than this value. Note that all fee amount currencies MUST match. Maximum allowed length (including decimal point) is 11.
|
|||||||
|
feeMaximum
object
|
Indicates the maximum value that can be charged for the account if the feeBase and feePercent values are GREATER than this value. Note that all fee amount currencies MUST match. Maximum allowed length (including decimal point) is 11.
|
|||||||
|
feeBase
object
|
The standard amount generated for the account fee. Note that all fee amount currencies MUST match. Maximum allowed length (including decimal point) is 11.
|
|||||||
Response
4. Update tariff rules - Successful : HTTP 200 (OK)
4. Update tariff rules - Error 1 : HTTP 403 (Forbidden)
4. Update tariff rules - Error 2 : HTTP 403 (Forbidden)
Response body will contain the updated JSON:API resource of type clientTariffRules .
5. Process the new tariff
This call, which is the final step in defining a new client tariff, is MANDATORY.
This PATCH request triggers the process to transfer the newly cloned client tariff from interim storage to Oracle DB. An API response of 200 or 201 (successful), indicating that the tariff was successfully processed and activated, will also be passed when the processing is completed.
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/merchantClientTariffs/{{merchantClientTariffId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type merchantClientTariffs with the following attributes:
| Name | Description | |
|---|---|---|
|
description
string
|
Descriptive name of the tariff. Up to 25 characters. |
|
|
processed
boolean
required
|
Set to true to process or activate the newly cloned client tariffs. |
|
| Relationships | ||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type merchantClientTariffs .
Retrieve list of unprocessed tariffs
Return the tariff contents of a particular tariff by the resource ID which is identified in the previous step.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchantClientTariffs?filter[processed]=false
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[processed] | false |
|---|
Response
HTTP 200 (OK)
Template Based Pricing
bankWORKS introduce a new pricing template system which allows a number of pricing templates to be defined by an acquirer on behalf of their brokers. Each tariff template would belong to a pricing model and can be assigned to a broker entity. The broker would have access to these templates which in theory define the set of charges and fees that the broker can negotiate with their merchant.
Two new group of resources, representing the merchant transaction tariff templates (BWT_ACCOUNT_CONDITION_SET GROUP C) and merchant client tariff templates (BWT_ACCOUNT_CONDITION_SET GROUP A). In each group it can define a new transaction charge tariff definitions or client tariff definitions that is base on a template.
Transaction Charge Tariff by Template
Two new resources, one representing the merchant transaction tariff templates available, the other for defining new transaction charge tariff definitions.
1. Get Transaction Tariff Templates
Returns transaction charge templates based on the available pricing models. Only one template per pricing model is available.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/transactionTariffTemplates
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
2. Get Template Charge Rules
Returns transaction charge rules based on the available pricing models.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/transactionTariffTemplates/{{transactionTariffTemplateId}}/chargeRules
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
3. Get Charge Rules
Returns transaction charge rules regardless of the effective date.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/chargeRules?filter[clientTariff]=900017
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[clientTariff] | 900017 |
|---|
Response
HTTP 200 (OK)
4. Get Transaction Tariff Definition
Returns transaction definition that contain the charge rules.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/transactionTariffDefinitions/{{transactionTariffDefinitionId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
5. Add Transaction Tariff
Accepts a set of rules. Related to a transactionTariffTemplates. Please note that the chargeRules will return a null value. In case this information is required a separate GET request is required.
EndFragment
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/transactionTariffDefinitions
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type transactionTariffDefinitions with the following attributes:
| Name | Description | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
chargeRules
object
|
This is an array of new transaction charges rules that are to be define based on the transaction tariff template.
|
|||||||||||||
| Relationships | ||||||||||||||
|
transactionTariffTemplate
required |
A new merchant tariff should be based on an existing transaction tariff template rule. |
|||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type transactionTariffDefinitions .
Client Tariff by Template
Two new resources, one representing the client tariff templates available, the other for defining new client tariff definitions.
The main three fee types represented under a client tariff include:
- Account Fees (FEE_CATEGORY 001)
- Service Fees (FEE_CATEGORY 002)
- Device Fees (FEE_CATEGORY 015)
1. Get Client Tariff Templates
Returns client tariff templates based on the available fee models. Only one template per fee model is available.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/clientTariffTemplates
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
2. Get Template Fee Rules
Returns client fee rules based on the available fee models.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/clientTariffTemplates/{{clientTariffTemplateId}}/feeRules
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
3. Get Fee Rules
Returns the client tariff fee rules regardless of the effective date.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/feeRules?filter[conditionSet]=900012
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[conditionSet] | 900012 |
|---|
Response
HTTP 200 (OK)
4. Get Client Tariff Definition
Returns client tariff definition that contain the fee rules.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/clientTariffDefinitions/{{clientTariffDefinitionId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[conditionSet] | 600003 |
|---|
Response
HTTP 200 (OK)
5. Add Client Tariff
Accepts a set of rules. Related to a clientTariffTemplates. Please note that the feeRules will return a null value. In case this information is required a separate GET request is required.
EndFragment
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/clientTariffDefinitions
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type clientTariffDefinitions with the following attributes:
| Name | Description | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
feeRules
object
|
This is an array of client fee new rules that are to be define based on the client tariff template.
|
|||||||||||||
| Relationships | ||||||||||||||
|
clientTariffTemplate
required |
A new client tariff definition should be based on an existing client tariff template rule. |
|||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type clientTariffDefinitions .
Sundry Transfer Instruction
Get All Transfer Instructions
Retrieval of all sundry transfer instructions regardless of processing status.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/transferInstructions
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Parameters
| include | destinationAccount,remainderAccount,sourceAccount |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type transferInstructions with destinationAccount,remainderAccount,sourceAccountas included resources.
Get Transfer Instruction
Retrieval of all sundry transfer instructions regardless of processing status.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/transferInstructions/{{transferInstructionId}}?include=destinationAccount,remainderAccount,sourceAccount
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Parameters
| include | destinationAccount,remainderAccount,sourceAccount |
|---|
Response
HTTP 200 (OK)
Response body will contain the requested JSON:API resource of type transferInstructions with destinationAccount,remainderAccount,sourceAccountas included resources.
Add New Transfer Instruction
Creation of a new sundry transfer instruction.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/transferInstructions
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type transferInstructions with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
originalTransactionSlip
string (11)
required
|
The transaction slip value of the transaction to be transferred. |
|||||||
|
transactionAmount
object
|
Either this amount or accountAmount must be provided. If this amount is provided and it is less than the original slip’s transaction amount, it means that it is a partial transfer.
|
|||||||
|
accountAmount
object
|
Either this amount or transactionAmount must be provided. If this amount is provided and it is less than the original slip’s account amount, it means that it is a partial transfer.
|
|||||||
|
narrative
string (50)
|
Free text reference. Either this or notes or both. If not provided default to original slip’s merchant name. |
|||||||
|
notes
string (100)
|
Free text reference. Either this or narrative or both. |
|||||||
| Relationships | ||||||||
|
destinationAccount
required |
The write-off, loss, or merchant payment or hold (or any other as needed) account. |
|||||||
|
remainderAccount
|
Can be provided only in the POST in case of partial transfer. It is not mandatory. |
|||||||
Response
HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type transferInstructions .
Edit Transfer Instruction
Can be edited only if the transfer instruction status is NOT Completed (002).
Request
PATCH https://wsmdemo.rs2.com/wsm/jsonapi/transferInstructions/{{transferInstructionId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Request Body
A JSON:API resource of type transferInstructions with the following attributes:
| Name | Description | |||||||
|---|---|---|---|---|---|---|---|---|
|
originalTransactionSlip
string (11)
|
The transaction slip value of the transaction to be transferred. |
|||||||
|
transactionAmount
object
|
Either this amount or accountAmount must be provided. If this amount is provided and it is less than the original slip’s transaction amount, it means that it is a partial transfer.
|
|||||||
|
accountAmount
object
|
Either this amount or transactionAmount must be provided. If this amount is provided and it is less than the original slip’s account amount, it means that it is a partial transfer.
|
|||||||
|
narrative
string (50)
|
Free text reference. Either this or notes or both. If not provided default to original slip’s merchant name. |
|||||||
|
notes
string (100)
|
Free text reference. Either this or narrative or both. |
|||||||
| Relationships | ||||||||
|
destinationAccount
|
The write-off, loss, or merchant payment or hold (or any other as needed) account. |
|||||||
|
remainderAccount
|
Can be provided only in the POST in case of partial transfer. It is not mandatory. |
|||||||
Response
HTTP 200 (OK)
Response body will contain the updated JSON:API resource of type transferInstructions .
Delete Transfer Instruction
Can be deleted only if the transfer instruction status is NOT Completed (002).
Request
DELETE https://wsmdemo.rs2.com/wsm/jsonapi/transferInstructions/{{transferInstructionId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
Response
HTTP 204 (No Content)
Response body will contain the deleted JSON:API resource of type transferInstructions .
Authorizations
This section contains a list of online authorization use cases that can be handled using the API.
Auth & Capture
Presents an authorization and capture advice to settle the authorization. An optional addendum request is included which can be used to pass L2/L3 data prior to capture. Please review the use cases for more information on the authorization message request.
1. Authorisation
Represents an authorization use case, a transaction request to block cardholder funds. Authorizations need to be Captured in order for the transaction to proceed for settlement.
In case of an HTTP status code 202 response indicating an issue communicating with the card network or responseCode 96 (System Error), the client should reverse the auth, please refer to the Reversals use-case for more information on reversals. Following a successful reversal a new authorisation should be sent.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0100’ must be provided to indicate a first pre-authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
|
Optional attribute. Can be passed the following:
Applicable to Diners / Discover only
Diners only
|
|||||||||||||||||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
purchaseIdentifier
String (26)
|
This field contains the equivalent of Visa DE62 Subfield 7. Position 1 is the purchase identifier format. As listed below are the valid values:
Position 2-26 is the purchase identifier, this contains the order number. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
specialConditionIndicator
string (1)
|
A special authorization flag used for various purposes. Example: 9 - Debt Repayment |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Mandatory relationship linking the pre-authorization request with the merchant. |
|||||||||||||||||||||||||||||||||||||
Response
1. Authorisation - Status Code 201 : HTTP 201 (Created)
1. Authorisation - Status Code 202 : HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type authorisations .
2. Addendum L2/L3 Data (Optional)
Optional request to submit
L2/L3 data related to the original pre-authorization. It is possible to send multiple addendum messages linked to the original pre-auth. A sequence is available in such cases, please refer to the attribute documentation for more information on this. Currently only Corporate Card data is supported.
In case of an HTTP status code 404 response, the client should re-send the same request after 5 seconds (for a maximum of 3 attempts).
In case of an HTTP status code 202 response indicating an issue communicating with the card network, the client can safely re-send the authorization supplying an updated stan and a transmissionDate attribute values. Do not reverse the addendum authorization.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisationsAddendum
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisationsAddendum with the following attributes:
| Name | Description | |
|---|---|---|
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|
|
transmissionDate
date-time
required
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|
|
stan
string (6)
required
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|
|
addendumType
string (5)
required
|
Represents a descriptor identifying the type of addendum. Accepted values: CORPT - (corporate card line item) |
|
|
addendumSequence
number
required
|
The addendum sequence number must be provided specifying the addendum number starting from ‘1’. If more than one addendum authorisation is sent, the correct sequence increment must be provided. For example:
|
|
|
addendumJson
string (2000)
required
|
Generic attribute which accepts a JSON object as a string, containing the necessary addendum record format. Following the intial response, this information is not sent back in GET calls. Data cannot exceed 2000 bytes in size. Please note that the specification is available as a separate document. Please contact your respective RS2 Project Manager for more information. |
|
| Relationships | ||
|
originalAuth
required |
The addendum authorisation must be linked to the original pre-auth message. |
|
Response
Response body will contain the created JSON:API resource of type authorisationsAddendum .
3. Capture
The capture advice is sent linked to pre-authorization transaction in order to fulfill a pre-authorization request and debit the cardholder. The settlement advice message can be sent within 14 days from when the original authorization was sent. If a reversal on the authorization is received and the capture advice message is received, the capture advice will be declined with responseCode value of ‘12’ - Invalid Transaction.
In case of an HTTP status code 202 response indicating an issue communicating with the card network or responseCode 96 (System Error), the client can safely re-send the authorization supplying an updated stan and a transmissionDate attribute values. Do not reverse the capture authorization.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
messageTypeId
string (4)
required
|
‘0220’ must be provided to indicate a completion advice. |
|||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||
|
amount
object
required
|
The final full amount needs to be sent with the completion advice request.
|
|||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||
|
authIndicator
string (2)
required
|
Must be passed:
|
|||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||
|
reasonCode
string (2)
required
|
‘00’ must be provided to indicate a request for advice approval. |
|||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||
|
hasAddendum
boolean
|
This flag should only be sent with a capture advice request (0220) whenever addendum data is sent via an 0340 message type. An example would be corporate cards L2/L3 data. |
|||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||
|
specialConditionIndicator
string (1)
|
A special authorization flag used for various purposes. Example: 9 - Debt Repayment |
|||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||
| Relationships | ||||||||||
|
merchant
required |
Mandatory relationship linking the completion with the merchant. |
|||||||||
|
originalAuth
required |
Mandatory relationship to the original pre-authorization to be captured. |
|||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type authorisations .
Incremental Pre-Auths
Incremental authorizations allow the initial authorized amount provided in the pre-authorization to be increased by sending a subsequent pre-authorisation. Multiple incremental pre-authorization requests can be sent. In order to settle the transaction a completion advice needs to be provided. More information on these messages may be found under the respective use case.
1. First Pre-Auth
This use case covers the initital pre-authorization request in a potential chain of followup incremental pre-authorizations.
In case of an HTTP status code 202 response indicating an issue communicating with the card network, the client should reverse the auth, please refer to the Reversals use-case for more information on reversals. Following a successful reversal a new pre-auth should be sent.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0100’ must be provided to indicate a first pre-authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
required
|
Must be passed to indicate either:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
specialConditionIndicator
string (1)
|
A special authorization flag used for various purposes. Example: 9 - Debt Repayment |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Mandatory relationship linking the pre-authorization request with the merchant. |
|||||||||||||||||||||||||||||||||||||
Response
1. First Pre-Auth - Status Code 201 : HTTP 201 (Created)
1. First Pre-Auth - Status Code 202 : HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type authorisations .
2. Subsequent Incremental Auth
This use case covers any additional pre-authorization that may follow the intital pre-authorisations. Subsequent authorisations have some varying attribute values.
In case of an HTTP status code 202 response indicating an issue communicating with the card network, the client should reverse the auth, please refer to the Reversals use-case for more information on reversals. Following a successful reversal a new pre-auth should be sent.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0100’ must be provided to indicate a first pre-authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
The requested amount of the pre-auth incremental.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
required
|
Must be passed:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||||||||||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
specialConditionIndicator
string (1)
|
A special authorization flag used for various purposes. Example: 9 - Debt Repayment |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
required
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Mandatory relationship linking the pre-authorization incremental request with the merchant. |
|||||||||||||||||||||||||||||||||||||
|
originalAuth
required |
Mandatory relationship to the original pre-authorization. |
|||||||||||||||||||||||||||||||||||||
Response
2. Subsequent Incremental Auth - Status Code 201 : HTTP 201 (Created)
2. Subsequent Incremental Auth - Status Code 202 : HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type authorisations .
3. Completion
This is the final authorization that would need to be sent to close off a chain of incremental pre-authorizations.
A pre-authorization completion matching a declined pre-authorization will be declined. The completion will also be declined if the requested amount value is greater than the pre-authorization requested amount.
In case of an HTTP status code 202 response indicating an issue communicating with the card network, the client can safely re-send the authorization supplying an updated stan and a transmissionDate attribute values. Do not reverse the completion authorization.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
messageTypeId
string (4)
required
|
‘0220’ must be provided to indicate a completion advice. |
|||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||
|
amount
object
required
|
The final full amount needs to be sent with the completion advice request.
|
|||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||
|
authIndicator
string (2)
required
|
Must be passed:
|
|||||||||||||||||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||
|
reasonCode
string (2)
required
|
‘00’ must be provided to indicate a request for advice approval. |
|||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||
|
specialConditionIndicator
string (1)
|
A special authorization flag used for various purposes. Example: 9 - Debt Repayment |
|||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||
|
merchant
required |
Mandatory relationship linking the pre-authorization incremental request with the merchant. |
|||||||||||||||||||||||
|
originalAuth
required |
Mandatory relationship to the original pre-authorization. |
|||||||||||||||||||||||
Response
3. Completion - Status Code 201 : HTTP 201 (Created)
3. Completion - Status Code 202 : HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type authorisations .
Recurring & COF Auth
Credentials-on-file use cases covering cardholder (CIT) and merchant (MIT) initiated transactions. The use cases in this section cover the main properties of a credentials-on-file transaction from a generic point of view. For specific use cases such as an authorisation and capture flow, refer to the respective use case section in addition to the below use cases.
1. Initial Transaction
The initial cardholder initiated transaction. This is similar to an authorisation or financial authorsisation (refer auth & capture, pre-auth incremental and purchase use). The main variation is the authIndicator value - see note on authIndicator below.
In case of an HTTP status code 202 response indicating an issue communicating with the card network, the client should reverse the auth, please refer to the Reversals use-case for more information on reversals. Following a successful reversal a new pre-auth should be sent.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
0100 - Authorisation or Pre-Authorisation request. This will require either capture or completion request depending on the case. Please refer to the Auth and Capture or Incremental Pre-Auths use cases for additional information. 0200 - Financial Authorisation. This can be sent for a financial auth message such as a purchase or even a refund. Also refer to Purchases and Refunds use cases for more information. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
A 2-digit code indicating the processing code of the transaction type.
|
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
required
|
Must be passed to indicate either:
|
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
hasAddendum
boolean
|
This flag should only be sent with a capture advice request (0220) whenever addendum data is sent via an 0340 message type. An example would be corporate cards L2/L3 data. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
specialConditionIndicator
string (1)
|
A special authorization flag used for various purposes. Example: 9 - Debt Repayment |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Mandatory relationship linking the pre-authorization request with the merchant. |
|||||||||||||||||||||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type authorisations .
2.1 CIT Subsequent Transaction
Cardholder initiated subsequent use case example. Auth indicator does not need to be provided unless the transaction is a pre-author subsequent incremental pre-auth (refer to Pre-auth incremental for more information).
In case of an HTTP status code 202 response indicating an issue communicating with the card network, the client should reverse the auth, please refer to the Reversals use-case for more information on reversals. Following a successful reversal a new pre-auth should be sent.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
0100 - Authorisation or Pre-Authorisation request. This will require either capture or completion request depending on the case. Please refer to the Auth and Capture or Incremental Pre-Auths use cases for additional information. 0200 - Financial Authorisation. This can be sent for a financial auth message such as a purchase or even a refund. Also refer to Purchases and Refunds use cases for more information. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
The requested amount of the pre-auth incremental.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
A 2-digit code indicating the processing code of the transaction type.
|
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
|
Must be passed to indicate either:
|
|||||||||||||||||||||||||||||||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
hasAddendum
boolean
|
This flag should only be sent with a capture advice request (0220) whenever addendum data is sent via an 0340 message type. An example would be corporate cards L2/L3 data. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
specialConditionIndicator
string (1)
|
A special authorization flag used for various purposes. Example: 9 - Debt Repayment |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Mandatory relationship linking the pre-authorization incremental request with the merchant. |
|||||||||||||||||||||||||||||||||||||
|
originalAuth
|
Optional relationship in case the authorisation is part of a pre-authorisation chain. |
|||||||||||||||||||||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type authorisations .
2.2 MIT Subsequent Transaction
This use case covers Merchant-Initiated-Transaction (MIT) sub-sequent transactions which are split into either:
Industry Practice (Incremental, Resubmission, Reauthorization, Delayed Charges, No Show)
Standing Instruction (Installments, Recurring, Unscheduled Credential on File)
In case of an HTTP status code 202 response indicating an issue communicating with the card network, the client should reverse the auth, please refer to the Reversals use-case for more information on reversals. Following a successful reversal a new pre-auth should be sent.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
0100 - Authorisation or Pre-Authorisation request. This will require either capture or completion request depending on the case. Please refer to the Auth and Capture or Incremental Pre-Auths use cases for additional information. 0200 - Financial Authorisation. This can be sent for a financial auth message such as a purchase or even a refund. Also refer to Purchases and Refunds use cases for more information. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
The requested amount of the pre-auth incremental.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
A 2-digit code indicating the processing code of the transaction type.
|
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
required
|
Industry Practice Incremental Pre-Auths
Discover Only
Standing Instruction (Depending on the reason for which the credentials are stored on file) Incremental Pre-Auths
Discover Only
|
|||||||||||||||||||||||||||||||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
hasAddendum
boolean
|
This flag should only be sent with a capture advice request (0220) whenever addendum data is sent via an 0340 message type. An example would be corporate cards L2/L3 data. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
specialConditionIndicator
string (1)
|
A special authorization flag used for various purposes. Example: 9 - Debt Repayment |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Mandatory relationship linking the pre-authorization incremental request with the merchant. |
|||||||||||||||||||||||||||||||||||||
|
originalAuth
|
Optional relationship in case the authorisation is part of a pre-authorisation chain. |
|||||||||||||||||||||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type authorisations .
Purchases
This section covers the purchase authorization (sales) transactions supported. Currently we cover card-not-present transaction for both eCommerce and MOTO use cases.
eCommerce
An eCommerce purchase authorization, supporting 3D Secure/UCAF and AVS functionality. The authorization must be linked to a merchant resource in BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
|
Optional attribute. Can be passed the following:
Applicable to Diners / Discover only
Diners only
|
|||||||||||||||||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||||||||||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Linked merchant from where the authorization originated. |
|||||||||||||||||||||||||||||||||||||
Response
eCommerce - Status Code 201 : HTTP 201 (Created)
eCommerce - Status Code 202 : HTTP 202 (Accepted)
eCommerce - Merchant Not Found : HTTP 404 (Not Found)
Response body will contain the created JSON:API resource of type authorisations .
Purchase by Installments
An eCommerce purchase by installments example.
The cardholder agrees to store the credential-on-file to establish an installment plan and initiates a first transaction in a series. The installment plan should reflect the single purchase of goods/services with a known amount and set frequency over a specified duration.
Please note that for Colombian domestic transactions addiotional attributes may be required for installments. Refer to the colombia object for more details.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
required
|
I = Payment by Installments |
|||||||||||||||||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||||||||||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
|
installments
object
required
|
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Linked merchant from where the authorization originated. |
|||||||||||||||||||||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type authorisations .
MOTO
The posCondition attribute will need to be used to make a distinction between Mail Order and Telephone Order authorizations. The authorization must be linked to a merchant resource in BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
|
Optional attribute. Can be passed the following:
Applicable to Diners / Discover only
Diners only
|
|||||||||||||||||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||||||||||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Linked merchant from where the authorization originated. |
|||||||||||||||||||||||||||||||||||||
Response
MOTO - Status Code 201 : HTTP 201 (Created)
MOTO - Status Code 202 : HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type authorisations .
Payment Facilitator
Payment facilitator - Purchase authorization; support for the payment facilitator object that is sent to BankWORKS for processing. The authorization must be linked to a merchant resource in BankWORKS.
Note: This use case applies only to payment facilitators that do not have sub-merchants on-boarded on BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
|
Optional attribute. ‘R’ can be passed to indicate a recurring transaction. |
|||||||||||||||||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||||||||||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Merchant who was linked to the payment facilitator from where the authorization originated. |
|||||||||||||||||||||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type authorisations .
Marketplace
Marketplace - Purchase authorization; support for the payment facilitator object, which contains the values required for Marketplace authorization sent to BankWORKS for processing. The authorization must be linked to a merchant resource in BankWORKS.
Note: This use case applies only to payment facilitators that do not have sub-merchants on-boarded on BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
|
Optional attribute. ‘R’ can be passed to indicate a recurring transaction. |
|||||||||||||||||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||||||||||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
The merchant who owns the marketplaces from where the authorization originated. |
|||||||||||||||||||||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type authorisations .
Amex OptBlue Merchant
This use case is intended to represent a simplfied card not present purchase transaction (message type 0200). The attributes visible have been reduced to cover this particular use case. Amex OptBlue merchants even if not linked to payment facilitators require additional attributes residing in the paymentFacilitator object to be provided. These attributes would also apply if the authorization being sent is a pre-authorization or authorization.
Note: This use case applies only to payment facilitators that do not have sub-merchants on-boarded on BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||
|
authIndicator
string (2)
|
Optional attribute. Can be passed the following:
|
|||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||
|
paymentFacilitator
object
required
|
Although this use case is intended for OptBlue merchants not linked to payment facilitators, this object contains attributes that will need to be supplied for Amex OptBlue participants.
|
|||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||
|
merchant
required |
Linked merchant from where the authorization originated. |
|||||||||||||||||||||||
Response
Amex OptBlue Merchant - Status Code 201 : HTTP 201 (Created)
Amex OptBlue Merchant - Status Code 202 : HTTP 202 (Accepted)
Amex OptBlue Merchant - Merchant Not Found : HTTP 404 (Not Found)
Response body will contain the created JSON:API resource of type authorisations .
Partial Authorization
Partial purchase authorization supports the additional authorization indicator attribute for partial authorization by sending a value of 1. The authorization must be linked to a merchant resource in BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘00’ must be provided to indicate a purchase transaction. |
|||||||||||||||||||||||||||||||||||||
|
authIndicator
string (2)
|
Optional attribute. Can be passed the following:
Applicable to Diners / Discover only
Diners only
|
|||||||||||||||||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
required
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||||||||||||||||
|
networkTraceId
string (50)
|
This field contains the trace id / transaction identifier used by the card schemes to link subsequent transactions. In the subsequent requests, RS2 should receive the original trace ID / transaction identifier returned in the response from the first authorization in a recurring series. This includes subsequent aggregate or incremental pre-authorizations, completions, recurring transactions and reversals. In responses, RS2 will return the trace ID for each transaction as returned by the schemes, which may be different than the one sent in the request. API users are to store the networkTraceId value for subsequent transaction use. Note: Currently, this field is returned for MasterCard, Visa, Discover, Diners and ELO transactions only |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Linked merchant from where the authorization originated. |
|||||||||||||||||||||||||||||||||||||
Response
Partial Authorization - Status Code 201 : HTTP 201 (Created)
Partial Authorization - Status Code 202 : HTTP 202 (Accepted)
Partial Authorization - Merchant Not Found : HTTP 404 (Not Found)
Response body will contain the created JSON:API resource of type authorisations .
Refund
Refund w/ card details
A refund is an 0200 message similar to a normal purchase authorization. This example contains a sample set of parameters than can be passed when creating a refund. Note that a refund is not the same as a reversal and is a separate transaction which may be (but not required to) related to the original authorization using the authorization code.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘20’ must be provided to indicate a refund transaction. |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Linked merchant from where the authorization originated. |
|||||||||||||||||||||||||||||||||||||
Response
Refund w/ card details - Status Code 201 : HTTP 201 (Created)
Refund w/ card details - Status Code 202 : HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type authorisations .
Refund w/o card details
A refund is an 0200 message similar to a normal purchase authorization. This example contains a sample set of parameters that can be passed when creating a refund. Note that a refund is not the same as a reversal and is a separate transaction which may be (but not required to) related to the original authorization using the authorization code. The previous refund request shown, requires a cardnumber and expiry date to be included in the request, but a refund can also be requested by sending the originalAuth relation related to the purchase.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘20’ must be provided to indicate a refund transaction. |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
independentSalesOrganisationId
string (11)
|
This attribute contains the Independent Sales Organization ID assigned by the card scheme. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
email
string (40)
|
Email of merchant or Amex OptBlue Participant. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
url
string (97)
|
Represents the merchant website address. Required by MasterCard for eCommerce transactions and in case a service telephone number (merchants.mainContactDetails.serviceTelephone) is not available. For a limited time period, this attribute can be used to supply the merchant’s URL in case of a MasterCard merchant not having the URL stored in BankWORKS. Applicable for merchants and payment facilitator merchants onboarded in BanKWORKS. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorName
string (25)
|
Optional card acceptor name, 25 character length, right space padded if the value provided is shorter. If not provided, the tradeName property of the related merchant resource is used by default. Note for Sub-Merchants Please be aware that the provided cardAcceptorName can be truncated if it exceeds 25 characters when combined with the payment facilitator details. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCity
string (13)
|
Optional card acceptor city information, 13 character length, right space padded if the value provided is shorter. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address city of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
cardAcceptorCountry
string (3)
|
Optional card acceptor country information, ISO-3 letter format. This should be provided in case the authorisation is sent through a payment facilitator sub-merchant registered in BankWORKS. Please refer to the paymentFacilitator object in case the sub-merchant is not onboarded in BankWORKS. If not provided, this information is defaulted from the clearing address country of the merchant. |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Linked merchant from where the authorization originated. |
|||||||||||||||||||||||||||||||||||||
|
originalAuth
required |
Mandatory authorization linked to this refund. |
|||||||||||||||||||||||||||||||||||||
Response
Refund w/o card details - Status Code 201 : HTTP 201 (Created)
Refund w/o card details - Status Code 202 : HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type authorisations .
Refund Payment Facilitator
A refund is an 0200 message similar to a normal purchase authorization. This example contains a sample set of parameters than can be passed when creating a refund. Note that a refund is not the same as a reversal and is a separate transaction which may be (but not required to) related to the original authorization using the authorization code.
Note: This use case applies only to payment facilitators that do not have sub-merchants on-boarded on BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘20’ must be provided to indicate a refund transaction. |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
Merchant who was linked to the payment facilitator from where the authorization originated. |
|||||||||||||||||||||||||||||||||||||
|
originalAuth
|
Optional authorization linked to this refund. |
|||||||||||||||||||||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type authorisations .
Refund Marketplace
A refund is an 0200 message similar to a normal purchase authorization. This example contains a sample set of parameters than can be passed when creating a refund. Note that a refund is not the same as a reversal and is a separate transaction which may be (but not required to) related to the original authorization using the authorization code.
Note: This use case applies only to payment facilitators that do not have sub-merchants on-boarded on BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘20’ must be provided to indicate a refund transaction. |
|||||||||||||||||||||||||||||||||||||
|
paymentGatewayId
string (11)
|
Represents the MasterCard merchant payment gateway identifier registered with the card scheme. Acquirers are required to populate this field for card-not-present (CNP) transactions, except for mail order/telephone order (MO/TO) transactions. Should the transaction involve multiple gateways, then acquirers must provide the MPG ID of the gateway that sends to the acquirer the transaction data based on which the acquirer generates the authorization message. Should contain numeric value only up to 11 digits. |
|||||||||||||||||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||||||||||||||||
|
india
object
|
Object containing attributes that must be provided for recurring payments initiated on India issued cards (VISA only). This is only used for POST request and will not be returned to the response.
|
|||||||||||||||||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||||||||||||||||
|
paymentFacilitator
object
|
Object containing attributes to support payment facilitator or marketplace requests. These attributes should only be provided when the payment facilitator sub-merchants are NOT on-boarded or represented in BankWORKS.
|
|||||||||||||||||||||||||||||||||||||
|
serviceLocation
object
|
The service location object is used to pass service location data related to the transaction as required by MasterCard. Service location data is applicable for:
|
|||||||||||||||||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||||||||||||||||
|
merchant
required |
The merchant who owns the marketplaces from where the authorization originated. |
|||||||||||||||||||||||||||||||||||||
|
originalAuth
|
Optional authorization linked to this refund. |
|||||||||||||||||||||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type authorisations .
Refund Amex OptBlue Merchant
This use case is intended to represent a simplfied refund transaction (message type 0200). The attributes visible have been reduced to cover this particular use case. Amex OptBlue merchants even if not linked to payment facilitators require additional attributes residing in the paymentFacilitator object to be provided.
Note: This use case applies only to payment facilitators that do not have sub-merchants on-boarded on BankWORKS.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
cardNumber
string (19)
required
|
The cardholder’s card number. The value is returned in masked format. To filter with this field, you will need to use the LIKE operator with wildcard(%25) and the last four digits of the card, together with a filter for other fields if needed.
|
|||||||||||||||||||||||
|
expiryDate
number (4)
required
|
The expiry date of the card in YYMM format. |
|||||||||||||||||||||||
|
messageTypeId
string (4)
required
|
‘0200’ must be provided to indicate a financial authorization. |
|||||||||||||||||||||||
|
transactionDate
date-time
required
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. |
|||||||||||||||||||||||
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|||||||||||||||||||||||
|
amount
object
required
|
Requested amount for this authorization. If the authorization will include a surcharge amount (provided in feeAmount), the amount attribute needs to include the full authorization amount, requested amount + the surcharge amount.
|
|||||||||||||||||||||||
|
feeAmount
object
|
The feeAmount can be used to add a surcharge fee to the transaction. The value accepts both a negative and positive value. A negative value indicates a credit to the cardholder. A positive value indicates a debit to the cardholder. To determine the authorisation amount the feeAmount can be added or subtracted to the amount value depending on the feeAmount sign.
|
|||||||||||||||||||||||
|
transactionType
string (2)
required
|
‘20’ must be provided to indicate a refund transaction. |
|||||||||||||||||||||||
|
authIndicator
string (2)
|
Indicates Pre-authorisations:
Settlement Transaction The following should only be used in the 0220 message to indicate that the transaction can be settled
Credentials-on-File The following value should be used for transactions which are sent using credentials stored on file, and which are not recurring or installments
For further information refer to Credentials-On-File used cases. Other
Diners / Discover only values
|
|||||||||||||||||||||||
|
additionalAuthIndicator
string (1)
|
This indicator can be used as an additional flag for specific authorization requests. An example would be for merchants with terminals accepting partial authorizations, request would need to be provided with either 1 or 3 value. Possible values:
|
|||||||||||||||||||||||
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|||||||||||||||||||||||
|
externalReference
string (36)
|
A client-specific external identifier value. The value of the externalReference must be unique for each transaction. |
|||||||||||||||||||||||
|
eCom
object
required
|
Object containing eCommerce related attributes, for eCommerce transactions.
|
|||||||||||||||||||||||
|
pos
object
required
|
Object containing point of service specific attributes.
|
|||||||||||||||||||||||
|
avs
object
|
Object containing Address Verification System attributes
|
|||||||||||||||||||||||
|
colombia
object
|
Object containing requried attributes for domestic Colombian transactions.
|
|||||||||||||||||||||||
|
paymentFacilitator
object
required
|
Although this use case is intended for OptBlue merchants not linked to payment facilitators, this object contains attributes that will need to be supplied for Amex OptBlue participants.
|
|||||||||||||||||||||||
|
additionalAmounts
object
|
This object can be used in the request message of a pre-Authorization Incremental transaction to fill the total accumulated amount of the pre-authorization. When having an Incremental transaction this field is mandatory (with amountType value ‘56’) for Discover and Diners, however, it is optional for other card schemes. This object is also used in the request message of MIT such as Recurring, Installment, Delayed Card Sale, Re-submission of Card Sale, No-Show Charge, and Unscheduled Payment to fill the amount requested in the original transaction. When having any of the mentioned MIT, this field is mandatory (with amountType value ‘57’) for Discover and Diners. However, it is optional for other card schemes.
|
|||||||||||||||||||||||
| Relationships | ||||||||||||||||||||||||
|
merchant
required |
Linked merchant from where the authorization originated. |
|||||||||||||||||||||||
|
originalAuth
|
Optional authorization linked to this refund. |
|||||||||||||||||||||||
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type authorisations .
Reversal
A reversal authorization can be sent to cancel (void) a pre-auth, purchase or completion authorization that has not been sent for clearing. Full reversals can be sent.
This request creates a new authorization to cancel out the original authorization by providing it in the originalAuth relationship field. Full amount reversals are supported. The reason for reversal must be provided. Refer to /authorisations resource documentation for a list of possible values.
Reversals Without A Response
It is recommended that in the event of not receiving a reversal response, the third party API client needs to retries the reversal up to a maximum of 10 times, with a minimum of 1 minute interval between each retry.
Reversals Declined with System Error
It is recommended that in the event of a reversal declined with a 96 response code (System Error), the third party API client needs to retries the reversal up to a maximum of 10 times, with a minimum of 1 minute interval between each retry.
Reversals Declined with other Response Codes
It is recommended that the third party API client are not to retry reversals for any other decline response except for 96 response code (System Error).
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type authorisations with the following attributes:
| Name | Description | |
|---|---|---|
|
messageTypeId
string (4)
required
|
‘0420’ must be provided to indicate a reversal advice. |
|
|
transactionDate
date-time
|
Local date and time of the transaction originating at the point of service in ISO 8601 format. If not provided, the original auth transaction date will be used as a default. |
|
|
transmissionDate
date-time
|
The transaction date and time at point of service in UTC 0, expressed in ISO 8601 format. |
|
|
reasonCode
string (2)
required
|
ISO code value to indicate the reason for reversals or advices. Possible values:
|
|
|
stan
string (6)
|
The System Trace Audit Number. A six digit code that must be unique for an online request. Used in conjunction with the transmissionDate and messageType ID to uniquely identify an authorisation. |
|
| Relationships | ||
|
merchant
required |
Linked merchant from where the authorization originated. |
|
|
originalAuth
required |
Links an authorization to another authorization for specific scenarios such as reversal, where the reversal must cancel out an existing authorization. Refer to use cases for more specific information. |
|
Response
Reversal - Status Code 201 : HTTP 201 (Created)
Reversal - Status Code 202 : HTTP 202 (Accepted)
Response body will contain the created JSON:API resource of type authorisations .
GET Merchant Authorisations
This call will return the associated contract and services of the merchant that will be closed or suspended.
Response:
a. merchantId,contractDefinition - will be used in POST call to closing /contracts (point 3 call) - NOTE: just verified that parentContracts is only used during onboarding in order to inherit the “contractDefinition” of parent node, but in case of merchant contract closure, contractDefinition should be used but should be inherited from parent’s contract definition via : Merchant Maintenance & Servicing >> Merchant Hierarchy >> Parent Contract Definition call which response can be used to the next call when closing the contract.
b. contractId - will be used in the POST call to closing /services (point 4 call)
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/merchants/clientNumber=10050000/authorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[retrievalReference] | 000063098006 |
|---|
Response
HTTP 200 (OK)
GET Authorisation
This call will return the associated contract and services of the merchant that will be closed or suspended.
Response:
a. merchantId,contractDefinition - will be used in POST call to closing /contracts (point 3 call) - NOTE: just verified that parentContracts is only used during onboarding in order to inherit the “contractDefinition” of parent node, but in case of merchant contract closure, contractDefinition should be used but should be inherited from parent’s contract definition via : Merchant Maintenance & Servicing >> Merchant Hierarchy >> Parent Contract Definition call which response can be used to the next call when closing the contract.
b. contractId - will be used in the POST call to closing /services (point 4 call)
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/authorisations/{{authorisationId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[retrievalReference] | 000063098006 |
|---|
Response
GET Authorisation : HTTP 200 (OK)
GET Authorisation w/ Addl Amt : HTTP 200 (OK)
GET Addendum L2/L3 Data
This call will return the Corporate Addendum transactions of the card issued to employees at a large company for business-related purchases.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/authorisationsAddendum/{{authorisationsAddendumId}}
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
RS2Host Authorizations
The below section provides an example request message using the RS2Host JSON format passed via the authMessage object. Clients opting to use this resource will need to refer to additional dedicated RS2Host documentation (available separately) to understand the various formats and attributes supported. The resource exposes an authMessage object and a rs2HostVersion attribute.
The response message received via the RS2Host interface is forwarded back in the API response. Please note that:
- HTTP Status Code 201: Indicates that the response has been successfully received. The response message will contain the response code within the full message among other attribute. The response code value will need to be read in order to determine if the authorisation was approved or not.
- HTTP Status Code 202: This status code would indicate that there was a communication issue with the card network. A reversal message should be sent whenever an authorisation or financial message is sent. This includes message types 0100 and 0200. Please refer to the RS2Host reversals documentation for more information on handling exceptional scenarios.
RS2Host Auth
A request to create new RS2Host Authorisations.
Request
POST https://wsmdemo.rs2.com/wsm/jsonapi/rs2HostAuthorisations
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Accept | application/vnd.api+json |
| Content-Type | application/vnd.api+json |
| Crnk-Compact | true |
Request Body
A JSON:API resource of type rs2HostAuthorisations with the following attributes:
| Name | Description | |
|---|---|---|
|
authMessage
json
required
|
The auth message accepts the RS2Host JSON message format, ensure that a valid JSON message is passed. This attribute will also contain the response auth message in the API response. Refer to supplementary documentation for the available attributes. |
|
|
rs2HostVersion
number
required
|
The version of the RS2Host to be used. |
|
Response
HTTP 201 (Created)
Response body will contain the created JSON:API resource of type rs2HostAuthorisations .
Presentments
Presentment External Reference
This use case is intended to provide an example of how to retrieved the presentments by external reference.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/presentments?filter[externalReference]=1234567890
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Request Parameters
| filter[externalReference] | 1234567890 |
|---|---|
| filter[retrievalReference] | 205111010432 |
Response
Presentment Retrieval Reference - Successful : HTTP 200 (OK)
Presentment External Reference - Successful : HTTP 200 (OK)
Presentment External Reference - Not found : HTTP 200 (OK)
Presentment Client Number
This use case is intended to provide an example of how to retrieve all presenments for a particular merchant within a specific time period.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/presentments?filter[clientNumber]=98888903&filter[date][GE]=2022-12-26T00:00:00&filter[date][LE]=2022-12-28T00:00:00
Request Headers
| Content-Type | application/vnd.api+json |
|---|---|
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
Request Parameters
| filter[clientNumber] | 98888903 |
|---|---|
| filter[date][GE] | 2022-12-26T00:00:00 |
| filter[date][LE] | 2022-12-28T00:00:00 |
Response
Presentment Client Number Successful : HTTP 200 (OK)
Presentment Client Number Not Found : HTTP 200 (OK)
System Configuration
This section covers any use case related to internal system configuration.
Posting Date
Reference resource: /postingDate
This use case provides an example of how to retrieve the posting date assigned to the current active user.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/postingDate
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)
Billing Cycle
This section covers any use case related to billing cycle.
Billing Cycle Definitions
Reference resource: /bilingCycleDefinitions
This use case provides an example of how to retrieve the billing cycle definition.
Request
GET https://wsmdemo.rs2.com/wsm/jsonapi/billingCycleDefinitions
Request Headers
| Authorization | Bearer 6c99f200-2022-4cb3-ba6b-4955843c226c |
|---|---|
| Content-Type | application/vnd.api+json |
| Accept | application/vnd.api+json |
| Crnk-Compact | true |
Response
HTTP 200 (OK)