USE CASE
As a user you want to retrieve the best match of standard settlement instructions for both the sending and receiving bank and only a single response for the sender and receiver.
DESCRIPTION
This request allows the user to enter the details for an originator and a beneficiary by entering the details for the sender (originator) and the receiver (beneficiary) of the payment. This call will then perform a best matching and will then list just the sender and receiver SSIs for the payment. If the call cannot perform a “best match” then it will give you an error and the user if then expected to use call 2.3 to list all the available SSIs and to use a manual process to choose.
When the request is made the token entered in the request will be checked against the user’s subscription to ensure that the user has enough remaining subscription to make the call and a subscription will be deducted if the request responds with a Pass or Caution in the status field.
URL STRUCTURE
https://validate.bankersalmanac.com/validate-api/rest/convert/3.0
METHOD
GET command, in “application/json” format
PARAMETERS
The entry parameters are a brief description of the entry fields is below.
| Field name | Field description | Mandatory or Optional | Sample data |
| originCountryCode | Originator ISO 2 digit country code | M | TR |
| originBIC | BIC of the originator | M | AKBKTRISXXX |
| originAcct | Account number of the originator | O | |
| currencyCode | ISO 3 digit currency code | M | JPY |
| assetCategory | Cateogry of the payment type | M | COPA – Commercial
FINA – Financial ANYY – Any paymetn type |
| countryCode | Beneficiary ISO 2 digit country code | M | US |
| nationalId | National id or BIC of the beneficiary | M | SMBCUS33 |
| benAcct | Account number of the beneficiary | O | |
| ref | Your refernce number | O | |
| errorComment | No in use | O | |
| token | Security token | M |
REQUEST
This call will need the details for the originator and the beneficiary. The service will look up the Standard Settlement Instructions held for the originator and beneficiary and list them. If the user wishes to override the account number held by the system, then then should enter the account number in the originAcct field for the originator.
RESPONSE
The request parameters can be downloaded here Call 3.0 Response Fields
| Field Name | Field Description | Sample |
| currencyCode | ISO 3 digit currency code | “JPY”, |
| originator | Label – Originator Bank Details | { |
| nm | Bank Name | “AKBANK T.A.S.”, |
| pstlAdr | Postal address | “SABANCI CENTER LEVENT 4, ISTANBUL, 34330, TURKEY”, |
| bic | Banks BIC | “AKBKTRISXXX”, |
| acct | Account number | “”, |
| codeDetails | { | |
| codeName1 | Code value 1 name | “BIC”, |
| codeValue1 | Code value 1 | “AKBKTRISXXX”, |
| codeName2 | Code value 2 name | “CHIPS”, |
| codeValue2 | Code value 2 | “095893”, |
| codeName3 | Code value 3 name | “BIC-4”, |
| codeValue3 | Code value 3 | “AKBK”, |
| codeName4 | Code value 4 name | “Banka Kodu”, |
| codeValue4 | Code value 4 | “004699999” |
| }, | ||
| ssiDetails | LABEL | |
| assetCategory | Asset type of correspondent bank account | “ALL”, |
| corresBIC | Originator correspondent BIC | “SMBCJPJTXXX”, |
| corresAcct | Originator correspondent account number | “3088” |
| preferred | Is this the preferred correspondent | “”, |
| }, | ||
| beneficiary | Label – Beneiciary Bank Details | { |
| nm | Bank Name | “SUMITOMO MITSUI BANKING CORPORATION”, |
| pstlAdr | Postal address | “277 PARK AVENUE, NEW YORK, 10172, UNITED STATES OF AMERICA”, |
| nationalId | Bank national id | “SMBCUS33”, |
| bic | Banks BIC | “SMBCUS33XXX”, |
| acct | Account number | “”, |
| codeDetails | { | |
| codeName1 | Code value 1 name | “BIC”, |
| codeValue1 | Code value 1 | “SMBCUS33XXX”, |
| codeName2 | Code value 2 name | “CHIPS”, |
| codeValue2 | Code value 2 | “013571”, |
| codeName3 | Code value 3 name | “BIC-4”, |
| codeValue3 | Code value 3 | “SMBC”, |
| codeName4 | Code value 4 name | “ABA”, |
| codeValue4 | Code value 4 | “026009674” |
| }, | ||
| ssiDetails | LABEL | |
| assetCategory | Asset type of correspondent bank account | “ALL”, |
| corresBIC | Beneficary correspondent BIC | “IRVTUS3NXXX”, |
| corresAcct | Beneficiary correspondent account number | “8900112026”, |
| intrmyBIC1 | Beneficary intermdiary 1 BIC | “”, |
| intrmyAcct1 | Beneficiary intermediary 1 account number | “”, |
| intrmyBIC2 | Beneficary intermdiary 2 BIC | “”, |
| intrmyAcct2 | Beneficiary intermediary 2 account number | “”, |
| institutionName | Bank Name | “THE BANK OF NEW YORK MELLON”, |
| city | Bank City | “NEW YORK,NY”, |
| countryName | Bank Country | “UNITED STATES OF AMERICA”, |
| countryCode | Bank ISO 2 digit country code | “US”, |
| natId | Domestic clearing code | “021000018”, |
| preferred | Is this the preferred correspondent | “” |
| }, | ||
| recommendedAcct | “”, | |
| recommendedBIC | Recommended beneficiary bic | “SMBCUS33XXX”, |
| status | Status code | “CAUTION”, |
| comment | Error code | “Check Asset category – Originator SSI was found but with incorrect asset category (07ro)”, |
| ref | Reference number | “20191206094912411”, |
| bic8 | Was the BIC8 flag set? | “N” |
TEST
Try testing using POSTMAN which is available as a Google Chrome App and can be found here POSTMAN REST
A sample request is below and there is more sample data above in the table
https://validate.bankersalmanac.com/validate-api/rest/convert/3.0?originCountryCode=TR&originBIC=AKBKTRISXXX&originAcct=¤cyCode=JPY&assetCategory=COPA&countryCode=US&nationalId=SMBCUS33&benAcct=&ref&errorComment&token=