Endpoint: https://api.validate.bankersalmanac.com/payment-purpose-code
Swagger link: https://api.validate.bankersalmanac.com/swagger-ui/index.html#/conversion-service-endpoint/paymentPurposeCode
Overview
Retrieving PPCs and descriptions for an existing validation
If you have already validated the payment details, then you can use the Free Token and the Bank Token to retrieve the payment purpose codes.
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 Purpose Code is not completed.
If the field Purpose Code is completed, then we will validate the purpose code entered in that field.
Validating an existing payment purpose code
By entering the payment purpose code that a user has you will be able to validate the code and return the codes text description.
Endpoint inputs
The request will only require the user to enter a valid freeToken and branchToken from a validation call or a Token and ISO country code to retrieve the holiday.
| Field Name | Description | Format | Mandatory or Optional | Default Value |
| countryCode | ISO Country Code | Alpha | Mandatory | |
| purposeCode | The purpose code that a user has entered for valdiation | Alphanumeric & Extended Characters | Optional | |
| bankToken | This is similar to “token” but for a specific bank only. Required to be used with “freeToken” | Alphanumeric | Mandatory | |
| token | Security token returned after calling the /authenticate endpoint | Alphanumeric & Extended Characters | Mandatory | |
| freeToken | This is similar to “token” but when used, the validation will be free | Alphanumeric & Extended Characters | Mandatory | |
| ref | Request reference | Alphanumeric & Extended Characters | Optional | |
| errorComment | if the field is set to E then you will be able to edit the error text in the self service hub | E | Optional |
Payment Purpose Code list retrieval for a country
If you require the holiday for a country then you can enter the following details in a request:
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 or Optional |
| token | Security token retrieved with the account security call. | Alphanumeric & Extended Characters | Mandatory |
| purposeCode | The purpose code that a user has entered for validation | 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 or Optional |
| 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 modifications
No modification can be done to the response.
Response outcomes
To understand the responses, please refer to Swagger – https://api.validate.bankersalmanac.com/swagger-ui/index.html#/conversion-service-endpoint/paymentPurposeCode
The response will have the format below but can contain payment reason codes.
| Field Name | Description | Format | ||
| status | Status of the response PASS, CAUTION or FAIL | Alpha | ||
| comment | Description of the status | Alpha | ||
| ref | Reference | Alphanumeric & Extended Characters | ||
| paymentReasonCodes | ||||
| codeUse | Will this be used for the sender or the receiver of the money. Sender, receiver or all | S,R,A | ||
| countryCode | ISO Country Code list | Alpha | ||
| currencyCode | ISO Currency Code list | Alpha | ||
| payPurpCode | This will be the code that is validated against or retrieved | Alphanumeric | ||
| primaryDecOff | Official primary description of the payment purpose code | Alphanumeric with spaces | ||
| primaryDecClean | Cleansed secondary description of the payment purpose code | Alphanumeric with spaces | ||
| secondaryDecOff | Official secondary description of the payment purpose code | Alphanumeric with spaces | ||
| secondaryDecClean | Cleansed secondary description of the payment purpose code | Alphanumeric with spaces | ||
| networkServiceCode | Clearing network unique code | Alphanumeric | ||
| networkServiceDesc | Clearing network name | Alphanumeric with spaces | ||
| usageType | All, corporate or personal account type | A All, C Corporate, P Personal | ||
| mandOpt | Is the code mandatory or optional by default | Alpha | ||
| swiftFieldUsageMT | Which SWIFT MT field should it be used in by default | Numeric | ||
| swiftFieldUsageISO | Contents of the SWIFT field | Alphanumeric with spaces | ||
| mtFieldContents | Which SWIFT ISO field should it be used in by default | Alphanumeric | ||
| isoFieldContents | Contents of the ISO field | Alphanumeric with spaces |
Test Examples
You only need to enter a valid freeToken and branchToken from a validation call or a Token and ISO country code:
token
country code “US”