Overview

  2. Home
  4. API Documentation
  6. Overview
  8. Beneficiary Management

Beneficiary Management

GetBeneficiaries

Response Sample

{
        "beneId": 12345,
        "bankName": "Bank Name",
        "accountHolderName": "Test27",
        "beneficiaryAddress": "Test for API",
        "countryName": "UNITED KINGDOM",
        "currency": "GBP",
        "sortCode": "******",
        "swiftCode": "",
        "ibanNumber": "",
        "accountNumber": "********",
        "bankABARoutingNumber": "",
        "beneficiaryReference": "From: Last Name, First Name (XYZ-123)",
        "intermediaryBankDetails": "",
        "status": "Approved"
    },

Http GET

When calling this API on its own, you will retrieve all the beneficiaries listed within your account.

Currency code parameter can be added to the query to retrieve specific set of beneficiaries.

Request URL

https://api.scestaging.com/v3/Bene/GetBeneficiaries

Field In Format Description Required
token header string Authentication token Mandatory
currency query string Three-digit currency code Optional

 

Response codes

HTTP Status Description Message
200 Success Success
400 Incorrect credentials Not authorized, Please Login again.

POST Add New Beneficiary

Request Sample

{
  "bankName": "Bank Name",
  "bankAddress": "Bank Test address",
  "accountHolderName": " Joe Bloggs ",
  "beneAddress": "26 Hammersmith Grove, SL4 6ER",
  "country": 225,
  "countryName": "UNITED KINGDOM",
  "currency": "GBP",
  "sortCode": "******",
  "swiftCode": "",
  "ibanNumber": "",
  "accountNumber": "********",
  "bankABARoutingNumber": "",
  "beneficiaryReference": "From: Last Name, First Name (XYZ-123)",
  "intermediaryBankDetails": "",
  "beneEmail": “[email protected]”,
  "isBeneThirdParty": true
}

Response Sample

{
  "beneficiaryId": 12345,
  "beneficiaryReference": "test",
  "accountReference": "XYZ-123",
  "beneStatus": "Not Approved"
}

Call this API to create a new beneficiary to your account. This can happen before or after creating a contract. Please refer to ‘Link Beneficiary’ section for pairing the new beneficiary (or an existing beneficiary) to an existing contract.

Request URL

https://api.scestaging.com/v3/Bene/AddBeneficiary

Name In Type Description Required
token header string Authentication token Mandatory
bankName Body String Bank name Mandatory
bankAddress Body String Bank address Mandatory
accountHolderName Body String Account holder name Mandatory
beneAddress Body String Beneficiary’s address Mandatory
country Body Integer Numerical country code Mandatory
currency Body String Three-digit currency code Mandatory
sortCode Body String Sort code Mandatory – dependent on country-currency pairing
swiftCode Body String Swift / Bic code Mandatory – dependent on country-currency pairing
ibanNumber Body String IBAN number Mandatory – dependent on country-currency pairing
accountNumber Body String Account Number Mandatory – dependent on country-currency pairing
abaRoutingNumber Body String ABA Routing number Mandatory – dependent on country-currency pairing
beneReference Body String Beneficiary Number Manadatory
intermediaryBankDetails Body String Intermediary bank details Optional
beneEmail Body String Beneficiary Email Optional
IsBeneThirdParty Body True or False Is beneficiary a third party or not Mandatory

When adding a new beneficiary, their status will initially display as unapproved until it has been reviewed and verified by our Compliance Team. Once verified, they will then display as Approved.

Response codes

HTTP Status Code Description Message
200 Success Success
400 Token Expired or invalid token Not authorized, Please Login again.
400 UK and GBP – when account number is not 8 digits Error: The account number should be 8 digits long
400 NZ – when account number is not between 15 and 16 Error: The account number should be 15 or 16 digits long
200 When bene has been saved successfully Bene return object
400 When some issues in saving the bene Error: Couldn’t save the bene details. Please contact Smart
400 When same bene already in the system Error: Beneficiary already exists in your account
400 When a bene you trying to add has been already marked as a blacklisted bene in Smart system Error: These beneficiary details have been blacklisted. Please Contact Smart for more details
400 When some unexpected issues Error: There was a problem while processing your request, please contact Smart.

POST Link Beneficiary

Request Sample

{
  "fxId": 123456,
  "beneficiaryId": 12345,
  "beneficiaryReference": ""
}

Response Sample

{
    "status": "Success",
    "fxContractId": "FX2021-xxx"
}

This API is called to link a beneficiary to a contract.

Request URL

https://api.scestaging.com/v3/Bene/LinkBene

Field In Format Description Required
token header string Authentication token Mandatory
fxId Body Integer FX Contract ID Mandatory
beneficiaryId Body integer Beneficiary’s ID Mandatory
beneficiaryReference Body string Reference associated to beneficiary Optional

Response codes

HTTP Status Code Message Description
200 Return obj When linked successfully
400 Not authorized, Please Login again. Token Expired or invalid token
400 Error: The beneficiary Id you entered is not for this account. Please double check When bene id is not for this account
400 Error: A bene has been already linked to this contract. When a bene has been already linked to the contract
400 Error: The Fx contract has been cancelled. You are not allowed add a recipient to a cancelled contract When fx contract is already cancelled
400 Error: This is a prospect fx contract. You are not allowed add a recipient to a prospect contract When the fx contract status is prospect
400 Error: The beneficiary has been disapproved. You are not allowed to link a disapproved beneficiary to a contract When bene is already disapproved
400 Error: The Fxcontract Id you entered is not for this account. Please double check When fx contract is not for this account
400 Error: Parameters passed are not valid please check again. When params are invalid
400 Error: Couldn’t link the beneficiary to the contract. Please contact Smart When some unexpected issues occurred while trying to save the bene
400 Error: There was a problem while processing your request, please contact Smart. Exception catch

POST UnLink Beneficiary

If the incorrect beneficiary has been linked to a contract, this API can be called to remove that beneficiary from the contract.

Request URL

https://api.scestaging.com/v3/Bene/UnLinkBene

Field In Format Description Required
token header string Authentication token Mandatory
fxId Body Integer FX Contract ID Mandatory
beneficiaryId Body integer Beneficiary’s ID Mandatory

Response codes

HTTP Status Description Message
200 Success Success
400 Incorrect credentials Not authorized, Please Login again.

PUT Disapprove Beneficiary

Request Sample

{
  "fxId": 12345,
  "beneficiaryId": 54321
}

Response Sample

The beneficiary has been removed from the contract

If you have added a beneficiary with incorrect details, call this API to disapprove that beneficiary. Once disapproved, this beneficiary’s status cannot be amended.

Request URL

https://api.scestaging.com/v3/Bene/DisapproveBene

Field In Format Description Required
token header string Authentication token Mandatory
beneficiaryId query integer Beneficiary’s ID Mandatory

Request Sample
Include the beneficiaryId as a parameter when calling the API.

https://api.scestaging.com/v3/Bene/DisapproveBene/?beneficiaryId=12345

Response Sample

The beneficiary has been disapproved

Response codes

HTTP Status Description Message
200 Request is successful and when that beneficiary is associated to a contract The beneficiary has been disapproved. Please note that the disapproved bene has been linked to open contract/s FX2021-12345 Please make sure you allocate new beneficiaries to these contracts and remove the disapproved beneficiary from those contracts
200 Request is successful where beneficiary isn’t associated to any contracts The beneficiary has been disapproved
400 Incorrect credentials Not authorized, Please Login again.

GET Payment Parameters

Response Sample

{
    "currency": "GBP",
    "countryCode": "GB",
    "iBan": false,
    "swiftcode": true,
    "accountNumber": true,
    "nationalCode": "Sort Code"
}

This API can be called to retrieve the required payment parameters for any country and currency pairing.

Request URL

https://api.scestaging.com/v3/Bene/GetPaymentParameters

Field In Format Description Required
token header string Authentication token Mandatory
countryId query integer Country code Mandatory
currency query string Three-digit currency code Mandatory

 

Request Sample

https://api.scestaging.com/v3/Bene/GetPaymentParameters?countryId=225&currency=GBP

Response codes

HTTP Status Description Message
200 Success Success
400 Incorrect credentials Not authorized, Please Login again.
400 Success ERROR: Couldn’t retrieve the payment paraeters for the coutry currency combination provided.”

GET IBAN Details

Response Sample

{
    "institutionName": "NATIONAL WESTMINSTER BANK PLC",
    "bankAddress": "Test address",
    "nationalID": null,
    "biC8": "ABCDEF12",
    "bankAccountNumber": "12345678",
    "countryName": "UNITED KINGDOM"
}

Call this API to validate an IBAN and get the bank details  for that IBAN if it’s valid

Request URL

https://api.scestaging.com/v3/Bene/GetIBANDetails

Field In Format Description Required
token header string Authentication token Mandatory
countryId query integer Country code Mandatory
iban query string IBAN code Mandatory

Request Sample

https://api.scestaging.com/v3/Bene/GetIBANDetails?countryId=***&iban=***********

Response codes

HTTP Status Description Message
200 Success Success
400 Incorrect credentials Not authorized, Please Login again.

GET Swift Details

Response Sample

{
        "institutionName": "Bank Name",
        "bankAddress": "Bank address   ",
        "nationalID": "123456789",
        "biC8": "AABBCCDD",
        "countryName": "SPAIN"
    }

Call this API to check if the beneficiary’s country and Swift code pairing is valid.

Request URL

https://api.scestaging.com/v3/Bene/GetSwiftDetails

Field In Format Description Required
token header string Authentication token Mandatory
countryId query integer Country code Mandatory
swiftCode query string Swift code Mandatory

 

Request Sample
https://api.scestaging.com/v3/Bene/GetSwiftDetails?countryId=***&swiftCode=***********

Response codes

HTTP Status Description Message
200 Success Success
400 Incorrect credentials Not authorized, Please Login again.

GET Bank Code Details

Request Sample

https://api.scestaging.com/v3/Bene/GetBankCodeDetails?<strong>countryId=***&amp;bankCode=***********</strong>

Response Sample

{
    "institutionName": "Bank’s Name",
    "bankAddress": "Test Bank Address   ",
    "nationalID": null,
    "biC8": "ABCDGB22",
    "countryName": "UNITED KINGDOM"
}

Call this API to check if the beneficiary’s country and country specific bank code (IFSC, BSB, Sort code, Transit code etc) pairing is valid.

Request URL

https://api.scestaging.com/v3/Bene/GetBankCodeDetails

Field In Format Description Required
token header string Authentication token Mandatory
countryId query integer Country code Mandatory
bankCode query string Bank code Mandatory

 

Response codes

HTTP Status Description Message
200 Success Success
400 Incorrect credentials Not authorized, Please Login again.