Skip to content

Beneficiary Reference

Constructor

The beneficiaries array can contain multiple instances of the Beneficiary class. TheM.beneficiaries[0] refers to the first beneficiary belonging to the user. If multiple beneficiaries exist, TheM.beneficiaries[0] could be replaced by TheM.beneficiaries[1], TheM.beneficiaries[2], etc. Alternatively, you could reference the beneficiary based on the AFiBeneficiaryId, replacing TheM.beneficiaries[0] with TheM.beneficiaries['PUT_AFiBeneficiaryId_HERE'] or TheM.beneficiaries.beneficiary('PUT_AFiBeneficiaryId_HERE').

A new instance of the Beneficiary class is initialized when a modelBank beneficiaries pushed event occurs. A new beneficiary can also be created using await (TheM.beneficiaries.newTempBeneficiary(givenTxnType, given)).doSubmit(givenProperties), where a temporary Beneficiary instance is first created and then submitted to the server. The Beneficiary class is extendable and a Beneficiary instance may be specific to a particular transaction type (txnType). For each Beneficiary instance, there is an associated transactions array containing Transaction instances for transfers to and from the beneficiary, if any exist. The properties and methods of the Beneficiary class can be referenced by specifying the beneficiary, followed by the property or method name, like TheM.beneficiaries['PUT_AFiBeneficiaryId_HERE'].AFiBeneficiaryId. See the ampliFi SDK Beneficiary class extensions documentation (BeneficiaryUSA Reference, BeneficiaryUSA_wire Reference, etc.), as well as the PUT /beneficiaries endpoint documentation in ampliFi MODULES for more information on required properties for specific beneficiaries, dependent on txnType.

const newBeneficiary = TheM.beneficiaries.newTempBeneficiary(givenTxnType, {//beneficiary properties});
await newBeneficiary.doSubmit(givenProperties);

Example

//This is an example of one type of beneficiary
const newBeneficiary = TheM.beneficiaries.newTempBeneficiary('USA', {
  txnType: 'USA',
  name: 'ACH Payee',
  bankName: 'Citibank NA', //specific to ACH transaction type
  destinationName: 'Receiving account title', //specific to ACH transaction type
  accountNumber: '1234567890123456', //specific to ACH transaction type
  routingNumber: '123456789', //specific to ACH transaction type
  defaultAmount: 20,
  narrativeDebit: 'ACH payment',
  isFavourite: true,
  type: 'CHECKING' //specific to ACH transaction type
});
await newBeneficiary.doSubmit({});

Properties

Property table for Beneficiary

Property Description Required Schema
AFiBeneficiaryId Gets (returns) the beneficiary ID in ampliFi. Yes {
  "title":
"TheM.beneficiaries[0].AFiBeneficiaryId",
  "type": "string",
  "description": "Gets (returns) the beneficiary ID
in ampliFi.",
  "examples": [
    "testpgbenlxuma31jlu"
  ],
  "nullable": false
}
beneficiaryId Gets (returns) the beneficiary ID in ampliFi. No {
  "title":
"TheM.beneficiaries[0].beneficiaryId",
  "type": "string",
  "description": "Gets (returns) the beneficiary ID
in ampliFi.",
  "examples": [
    "testpgbenlxuma31jlu"
  ]
}
AFiPayeeId Gets (returns) or sets the payee ID in ampliFi associated with this beneficiary. No {
  "title": "TheM.beneficiaries[0].AFiPayeeId",
  "type": "string",
  "description": "Gets (returns) or sets the payee ID
in ampliFi associated with this beneficiary.",
  "examples": [
    "3gzvss70aqhkjh0gcmwz6fr6eutmzmf8"
  ],
  "nullable": true
}
AFiUserId Gets (returns) the user ID in ampliFi. Yes {
  "title": "TheM.beneficiaries[0].AFiUserId",
  "type": "string",
  "description": "Gets (returns) the user ID in
ampliFi.",
  "examples": [
    "testaurlx8wfimcrw"
  ],
  "nullable": false
}
backOfficeId Gets the back-office ID associated with this beneficiary. No {
  "title":
"TheM.beneficiaries[0].backOfficeId",
  "type": "string",
  "description": "Gets the back-office ID
associated with this beneficiary.",
  "examples": [
    "connectFiBOIS"
  ]
}
backOfficeName Gets (returns) the name of the back-office associated with this beneficiary. No {
  "title":
"TheM.beneficiaries[0].backOfficeName",
  "type": "string",
  "description": "Gets (returns) the name of the
back-office associated with this beneficiary.",
  "examples": [
    "connectFiBOIS"
  ]
}
backOffices Gets (returns) an array of the back-offices associated with this beneficiary. No {
  "title":
"TheM.beneficiaries[0].backOfficeName",
  "type": "array",
  "description": "Gets (returns) an array of the
back-offices associated with this beneficiary.",
  "examples": [
    [
      {
        "AFiBeneficiaryId": "testpgbenlxuma31jlu",
        "backOfficeId": "connectFiBOIS",
        "backOfficeName": "connectFiBOIS"
      }
    ]
  ]
}
name Gets (returns) or sets the nickname associated with this beneficiary. Yes {
  "title": "TheM.beneficiaries[0].name",
  "type": "string",
  "description": "Gets (returns) or sets the
nickname associated with this beneficiary.",
  "examples": [
    "ACH Payee Account"
  ],
  "nullable": false
}
defaultSourceAccountId Gets (returns) or sets the account ID associated with the default source account in ampliFi to use when making transfers to this beneficiary. No {
  "title":
"TheM.beneficiaries[0].defaultSourceAccountId
",
  "type": "string",
  "description": "Gets (returns) or sets the account
ID associated with the default source account in
ampliFi to use when making transfers to this
beneficiary.",
  "examples": [
    null
  ],
  "nullable": true
}
defaultAmount Gets (returns) or sets the default amount to use when making a transfer to this beneficiary. No {
  "title":
"TheM.beneficiaries[0].defaultAmount",
  "type": "number",
  "description": "Gets (returns) or sets the default
amount to use when making a transfer to this
beneficiary.",
  "examples": [
    20,
    100.5,
    250.01
  ],
  "default": 0
}
defaultCurrency Gets (returns) or sets the default currency to use when making a transfer to this beneficiary. No {
  "title":
"TheM.beneficiaries[0].defaultCurrency",
  "type": "string",
  "description": "Gets (returns) or sets the default
currency to use when making a transfer to this
beneficiary.",
  "examples": [
    "USD"
  ],
  "default": "USD"
}
imageBase64 Gets (returns) or sets the image associated with the beneficiary in base 64 format. No {
  "title": "TheM.beneficiaries[0].imageBase64",
  "type": "string",
  "description": "Gets (returns) or sets the image
associated with the beneficiary in base 64
format.",
  "examples": [
    "VeryLongBase64ImageString"
  ],
  "nullable": true
}
status Gets (returns) the current beneficiary status. No {
  "title": "TheM.beneficiaries[0].status",
  "type": "string",
  "description": "Gets (returns) the current
beneficiary status.",
  "examples": [
    "Pending",
    "Active"
  ],
  "default": "Pending"
}
transactions Gets (returns) an array of transactions for the past 180 days to and from this beneficary across all of the user's accounts. Each transaction, if any exist, is an instance of the Transaction class. Beneficiary transaction instances may have txnType and beneficiary specific properties in addition to the base Transaction class properties. Common additional beneficiary transaction properties include AFiBeneficiaryId, beneficiary (a reference to the corresponding beneficiary instance), and beneficiaryName. No {
  "title":
"TheM.beneficiaries[0].transactions",
  "type": "array",
  "description": "Gets (returns) an array of
transactions for the past 180 days to and from this
beneficary across all of the user's accounts. Each
transaction, if any exist, is an instance of the
Transaction class. Beneficiary transaction
instances may have txnType and beneficiary
specific properties in addition to the base
Transaction class properties. Common additional
beneficiary transaction properties include
AFiBeneficiaryId, beneficiary (a reference to the
corresponding beneficiary instance), and
beneficiaryName.",
  "examples": [
    [
      {
        "AFiAccountId": "testgalx8wfq4sqfgb",
        "AFiUserId": "testaurlx8wfimcrw",
        "arn": "0000000000000006LBor",
        "dtsAtMerchant": "Mon Jun 10 2024 07:37:55
GMT-0400 (Eastern Daylight Time)",
        "dtsRecorded": "Mon Jun 10 2024 07:38:51 GMT-0400
(Eastern Daylight Time)",
        "fee": 0,
        "internal": {},
        "is3DSecure": false,
        "isComplete": true,
        "isDigitalWalletTrans": false,
        "isPaymentTrans": true,
        "isRecurring": false,
        "reference": "testrr8wgyjgssximb",
        "transactionIdBO": "F2167329415",
        "transactionState": "complete",
        "typeName": "",
        "amount": 10,
        "attachments": {},
        "attachmentsArray": [],
        "credit": 10,
        "currency": "USD",
        "debit": 0,
        "dtsBooked": "Mon Jun 10 2024 07:37:55 GMT-0400
(Eastern Daylight Time)",
        "dtsValue": "Mon Jun 10 2024 07:37:55 GMT-0400
(Eastern Daylight Time)",
        "isBlacklistable": false,
        "isWhitelistable": false,
        "narrative": "🎁 Welcome bonus",
        "newBalance": null,
        "transactionId":
"dcuosrklcjxpyzxagroxbbrspacuhiecwfzltzke",
        "txnType": "credit",
        "toJSON": {},
        "AFiBeneficiaryId": "testpgbenlxuma31jlu",
        "beneficiaryName": "ACH Payee Account",
        "beneficiary": {}
      }
    ]
  ],
  "default": []
}
txnType Gets (returns) the type of transaction that is used for transfers to this beneficiary. Yes {
  "title": "TheM.beneficiaries[0].txnType",
  "type": "string",
  "description": "Gets (returns) the type of
transaction that is used for transfers to this
beneficiary.",
  "examples": [
    "default",
    "USA",
    "USA_wire",
    "paypal",
    "cheque",
    "tocard"
  ],
  "nullable": false
}
validationMessage Gets (returns) or sets a validation message if the beneficiary has invalid or missing properties. Required properties and corresponding validation messages are dependent on the txnType used when making transfers to the beneficiary. No {
  "title":
"TheM.beneficiaries[0].validationMessage",
  "type": "string",
  "nullable": true,
  "default": "",
  "description": "Gets (returns) or sets a
validation message if the beneficiary has invalid
or missing properties. Required properties and
corresponding validation messages are dependent
on the txnType used when making transfers to the
beneficiary.",
  "$comment": "getter setter",
  "examples": [
    "Enter the account title",
    "Enter the bank name",
    "Enter the routing number",
    "Enter the full 9-digit routing number",
    "Enter the account number",
    "Enter the full account number",
    "Pick the account type",
    "Enter the address line 1",
    "Enter the city",
    "Enter the postal code",
    "Enter the card number"
  ]
}
toJSON Gets (returns) the beneficary properties in a JSON formatted object. The properties present may depend on the transaction type (txnType) used when making transfers to this beneficiary. Yes {
  "title": "TheM.beneficiaries[0].toJSON",
  "type": "object",
  "description": "Gets (returns) the beneficary
properties in a JSON formatted object. The
properties present may depend on the transaction
type (txnType) used when making transfers to this
beneficiary.",
  "examples": [
    {
      "AFiBeneficiaryId": "testpgbenlxuma31jlu",
      "AFiPayeeId":
"3gzvss70aqhkjh0gcmwz6fr6eutmzmf8",
      "accountNumber": "1234567890123456",
      "routingNumber": "123456789",
      "bankName": "Citibank NA",
      "defaultAmount": 20,
      "destinationName": "Receiving account title",
      "isActive": true,
      "isBusiness": false,
      "isFavourite": true,
      "isHidden": false,
      "name": "ACH Payee Account",
      "narrativeDebit": "ACH payment",
      "status": "Active",
      "txnType": "USA",
      "type": "CHECKING",
      "imageBase64":
"Very_Long_Base64_Image_String",
      "dtsCreated": "2024-06-28T11:12:10.053Z"
    }
  ],
  "nullable": false
}
isBusiness Gets (returns) or sets true if this beneficary is a business. No {
  "title": "TheM.beneficiaries[0].isBusiness",
  "type": "boolean",
  "description": "Gets (returns) or sets true if this
beneficary is a business.",
  "examples": [
    true,
    false
  ],
  "default": false
}
isFavourite Gets (returns) or sets true if this beneficary is marked as a favorite. No {
  "title": "TheM.beneficiaries[0].isFavourite",
  "type": "boolean",
  "description": "Gets (returns) or sets true if this
beneficary is marked as a favorite.",
  "examples": [
    true,
    false
  ],
  "nullable": true
}
isPaying Gets (returns) true if this if a payment to this beneficiary is currently processing. The UI is responsible for ensuring that new payments are not allowed if a payment is currently being processed. No {
  "title": "TheM.beneficiaries[0].isPaying",
  "type": "boolean",
  "description": "Gets (returns) true if this if a
payment to this beneficiary is currently
processing. The UI is responsible for ensuring that
new payments are not allowed if a payment is
currently being processed.",
  "examples": [
    true,
    false
  ],
  "default": false
}
isValid Gets (returns) true if all the required beneficiary details are present. All Beneficiary instances require the name property to be considered valid. Additional required properties depend on the txnType for the beneficiary. Yes {
  "title": "TheM.beneficiaries[0].isValid",
  "type": "boolean",
  "description": "Gets (returns) true if all the
required beneficiary details are present. All
Beneficiary instances require the name property to
be considered valid. Additional required
properties depend on the txnType for the
beneficiary.",
  "examples": [
    true,
    false
  ],
  "nullable": false
}
dtsCreated Gets (returns) the date that the beneficiary was created. Yes {
  "title": "TheM.beneficiaries[0].dtsCreated",
  "type": "Date",
  "description": "Gets (returns) the date that the
beneficiary was created.",
  "examples": [
    "Fri Jun 28 2024 07:12:10 GMT-0400 (Eastern
Daylight Time)"
  ],
  "nullable": false
}

Methods

Method Name Parameter Descriptions Description Example
doDelete 
[]
 Calls the DELETE /beneficiaries/:AFiBeneficiaryId endpoint in ampliFi in order to delete the beneficiary. If successful, a 'modelBank beneficiary deleted' event will occur. TheM.beneficiaries[0].doDelete();
doPay 
[
  {
    "title": "given",
    "type": "object",
    "nullable": false,
    "properties": {
      "amount": {
        "title": "amount",
        "type": "number",
        "nullable": false,
        "example": 20.01
      },
      "currency": {
        "title": "currency",
        "type": "string",
        "nullable": false,
        "example": "USD"
      },
      "narrativeSource": {
        "title": "narrativeSource",
        "type": "string",
        "nullable": true,
        "example": "A brief narrative"
      },
      "narrativeDestination": {
        "title":
"narrativeDestination",
        "type": "string",
        "nullable": true,
        "example": "A brief narrative"
      },
      "narrativeDebit": {
        "title": "narrativeDebit",
        "type": "string",
        "nullable": true,
        "example": "A brief narrative"
      },
      "narrativeCredit": {
        "title": "narrativeCredit",
        "type": "string",
        "nullable": true,
        "example": "A brief narrative"
      },
      "narrative": {
        "title": "narrative",
        "type": "string",
        "nullable": true,
        "example": "A brief narrative"
      },
      "extrasDebit": {
        "title": "extrasDebit",
        "type": "object",
        "nullable": true,
        "example": {}
      },
      "extrasCredit": {
        "title": "extrasCredit",
        "type": "object",
        "nullable": true,
        "example": {}
      }
    },
    "example": {
      "amount": 20.01,
      "currency": "USD",
      "narrativeDebit": "Payment",
      "extrasDebit": {},
      "extrasCredit": {}
    }
  }
]
 Calls the POST /transfer/acc2ben/:AFiBeneficiaryId endpoint in ampliFi in order to make a payment from the user's main account in ampliFi to the beneficiary using the transfer method configured for this beneficiary (txnType). TheM.beneficiaries[0].doPay(
  {
    "amount": 20.01,
    "currency": "USD",
    "narrativeDebit": "Payment",
    "extrasDebit": {},
    "extrasCredit": {}
  }
);
doSubmit 
[]
 The doSubmit method is only available on a newly created beneficiary initialized through a TheM.beneficiaries.newTempBeneficiary(givenTxnType, given = {}) call. This method will submit the newly created temporary beneficiary to the server in a PUT /beneficiaries ampliFi endpoint request. (TheM.beneficiaries.newTempBeneficiary(givenTxnType, given = {})).doSubmit();

Submodules

Submodule Name Link
Transaction Transaction Reference