If you are trying to retrieve the payment purpose codes or validate a payment purpose code that your client has, then this call will allow you to perform both functions.
By entering a country code or bank tokens you will be able to retrieve the list of payment reason codes for a country.
By entering the payment reason code that a user has you will be able to validate the code and return the codes text description.
By just entering the country then we will return the list of codes with their text description.
The response will give the payment purpose codes and descriptions for the country if the field purposeCode is not completed. If the field purposeCode is completed then we will validate the purpose code entered in that field.
URL Structure
https://validate.bankersalmanac.com/validate-api/rest/convert/4.5.1
Method
GET command, in “application/json” format
Request
The request will only require the user to enter a valid freeToken and branchToken froma a validation call or a Token and ISO country code to retrieve the holiday.
| FIELD NAME | DESCRIPTION | FORMAT | MANDATORY |
| token | Security token retrieved with the account security call. | Alphanumeric & Extended Characters | Mandatory |
| freeToken | Free security token retrieved with a validation call. | Alphanumeric & Extended Characters | Mandatory |
| countryCode | ISO Country Code | 2 alpha | Mandatory |
| purposeCode | The purpose code that a user has entered for valdiation | Alphanumeric & Extended Characters | Optional |
| bankToken | Token that defined the bank branch from a validation call. | Alphanumeric | Optional |
| ref | Request reference | Alphanumeric | Optional |
| errorComment | Text description of error | Alphanumeric & Extended Characters | Optional |
The options for requests are
Holiday for a country
If you require the holiday for a country then you can enter the following details in a request
| FIELD NAME | DESCRIPTION | FORMAT | MANDATORY |
| token | Security token retrieved with the account security call. | Alphanumeric & Extended Characters | Mandatory |
| countryCode | ISO Country Code | 2 alpha | Mandatory |
| ref | Request reference | Alphanumeric | Optional |
Validating an existing payment purpose code
If your user has an existing payment purpose code and you want to validate the code is still correct and the description of it then you can use these fields in the request
| FIELD NAME | DESCRIPTION | FORMAT | MANDATORY |
| token | Security token retrieved with the account security call. | Alphanumeric & Extended Characters | Mandatory |
| purposeCode | The purpose code that a user has entered for valdiation | Alphanumeric & Extended Characters | Mandatory |
| ref | Request reference | Alphanumeric | Optional |
| errorComment | Text description of error | Alphanumeric & Extended Characters | Optional |
Requesting the codes and descriptions for an existing validation
If you’ve already validated the payment details then you can use the freeToken and the bankToken to retrieve the payment purpose codes.
| FIELD NAME | DESCRIPTION | FORMAT | MANDATORY |
| freeToken | Free security token retrieved with a validation call. | Alphanumeric & Extended Characters | Mandatory |
| bankToken | Token that defined the bank branch from a validation call. | Alphanumeric | Mandatory |
| ref | Request reference | Alphanumeric | Optional |
| errorComment | Text description of error | Alphanumeric & Extended Characters | Optional |
Response
The response will have the format below but can contain payment reason codes.
| Field | Size | Format | Values | Description |
| codeUse | 1 | alpha | S, R, A | Will this be used for the sender or the receiver of the money. Sender, receiver or all |
| countryCode | 2 | alpha | ISO Country Code list | This will be the country that the code relates to |
| currencyCode | 256 | alpha | ISO Currency Code list | This will list the currency codes that the description is used for |
| payPurpCode | 10 | alpha numeric | This will be the code that is validated against or retrieved | |
| primaryDecOff | 256 | alpha numeric with spaces | Official primary description of the payment purpose code | |
| primaryDecClean | 72 | alpha numeric with spaces | Cleansed primary description of the payment purpose code | |
| secondaryDecOff | 256 | alpha numeric with spaces | Official secondary description of the payment purpose code | |
| secondaryDecClean | 72 | alpha numeric with spaces | Cleansed secondary description of the payment purpose code | |
| networkService code | 5 | alpha numeric | Clearing network unique code | |
| networkServicedesc | 72 | alpha numeric with spaces | Clearing network name | |
| userType | 1 | Alpha | A, C, P | All, corporate or personal account type |
| mandOpt | 1 | alpha | Is the code mandatory or optional by default | |
| swiftFieldUsageMT | 2 | numeric | Which SWIFT MT field should it be used in by default | |
| swiftFieldUsageISO | 36 | alpha numeric | Which SWIFT ISO field should it be used in by default |