Beneficiaries

To create a new beneficiary, first retrieve the required form fields using the following request:

POST https://api.dev.mrkter.io/beneficiaries/form_schemas/generate

Required "Authorization" header

Required "x-account-id" header

Required "x-session-id" header

Example request:

{
  "bankCountryCode": "US",
  "accountCurrency": "USD",
  "transferMethod": "LOCAL",
  "localClearingSystem": "ACH",
  "entityType": "PERSONAL"
}

Example response:

{
  "condition": {
    "accountCurrency": "USD",
    "bankCountryCode": "US",
    "entityType": "PERSONAL",
    "localClearingSystem": "ACH",
    "transferMethod": "LOCAL"
  },
  "fields": [
    {
      "enabled": true,
      "field": {
        "default": "John",
        "description": "First name of the beneficiary",
        "example": "John",
        "key": "firstName",
        "label": "First Name",
        "placeholder": "Enter first name",
        "refresh": false,
        "tip": "This is a required field",
        "type": "text"
      },
      "path": "bankDetails.accountName",
      "required": true,
      "rules": {
        "pattern": "^[a-zA-Z0-9]+$",
        "type": "string"
      }
    }
  ],
  "key": "newRecipient"
}

All fields marked "required": true in the response must be included in the next request, and their values must comply with the corresponding "rules" schema

Next, validate the new beneficiary request using the /beneficiaries/validate endpoint.

POST https://api.dev.mrkter.io/beneficiaries/validate

Required "Authorization" header

Required "x-account-id" header

Required "x-session-id" header

Example request:

{
  "beneficiary": {
    "additionalInfo": {
      "businessArea": "Travel",
      "businessPhoneNumber": "689342234",
      "businessRegistrationNumber": "IT593003",
      "legalRepBankAccountNumber": "44250100003700000000",
      "legalRepFirstNameInChinese": "小芳",
      "legalRepMobileNumber": "13651362890",
      "personalEmail": "[email protected]",
      "personalFirstNameInChinese": "大明",
      "personalIdNumber": "1234567890",
      "personalIdType": "CHINESE_NATIONAL_ID",
      "personalLastNameInChinese": "李",
      "personalMobileNumber": "13651362890"
    },
    "address": {
      "city": "Melbourne",
      "countryCode": "AU",
      "postcode": "3000",
      "state": "VIC",
      "streetAddress": "15 William Street"
    },
    "bankDetails": {
      "accountCurrency": "AUD",
      "accountName": "Lee Da Ming",
      "accountNumber": "12750852",
      "accountRoutingType1": "bsb",
      "accountRoutingType2": "sort_code",
      "accountRoutingValue1": "Melbourne",
      "accountRoutingValue2": "083064",
      "bankAccountCategory": "123456",
      "bankBranch": "Melbourne",
      "bankCountryCode": "AU",
      "bankName": "National Australia Bank",
      "bankStreetAddress": "500 Bourke Street, Melbourne 3000, Australia",
      "bindingMobileNumber": "654897612345",
      "fingerprint": "2e99758548972a8e8822ad47fa1017ff72f06f3ff6a016851f45c398732bc5",
      "iban": "ES8023100001180000012345",
      "localClearingSystem": "ACH",
      "swiftCode": "CTBAAU2S",
      "transactionReference": "4140110135"
    },
    "companyName": "Complete Concrete Pty Ltd",
    "dateOfBirth": "1976-08-26",
    "entityType": "COMPANY",
    "firstName": "John",
    "lastName": "Walker"
  },
  "nickname": "Complete Concrete Pty Ltd",
  "payerEntityType": "COMPANY",
  "transferMethods": [
    "SWIFT"
  ],
  "transferReason": "travel"
}

Example response:

OK

Finally, create and save the new beneficiary using the /beneficiaries/create endpoint.

POST https://api.dev.mrkter.io/beneficiaries/create

Required "Authorization" header

Required "x-account-id" header

Required "x-session-id" header

Example request:

{
  "beneficiary": {
    "additionalInfo": {
      "businessArea": "Travel",
      "businessPhoneNumber": "689342234",
      "businessRegistrationNumber": "IT593003",
      "legalRepBankAccountNumber": "44250100003700000000",
      "legalRepFirstNameInChinese": "小芳",
      "legalRepMobileNumber": "13651362890",
      "personalEmail": "[email protected]",
      "personalFirstNameInChinese": "大明",
      "personalIdNumber": "1234567890",
      "personalIdType": "CHINESE_NATIONAL_ID",
      "personalLastNameInChinese": "李",
      "personalMobileNumber": "13651362890"
    },
    "address": {
      "city": "Melbourne",
      "countryCode": "AU",
      "postcode": "3000",
      "state": "VIC",
      "streetAddress": "15 William Street"
    },
    "bankDetails": {
      "accountCurrency": "AUD",
      "accountName": "Lee Da Ming",
      "accountNumber": "12750852",
      "accountRoutingType1": "bsb",
      "accountRoutingType2": "sort_code",
      "accountRoutingValue1": "Melbourne",
      "accountRoutingValue2": "083064",
      "bankAccountCategory": "123456",
      "bankBranch": "Melbourne",
      "bankCountryCode": "AU",
      "bankName": "National Australia Bank",
      "bankStreetAddress": "500 Bourke Street, Melbourne 3000, Australia",
      "bindingMobileNumber": "654897612345",
      "fingerprint": "2e99758548972a8e8822ad47fa1017ff72f06f3ff6a016851f45c398732bc5",
      "iban": "ES8023100001180000012345",
      "localClearingSystem": "ACH",
      "swiftCode": "CTBAAU2S",
      "transactionReference": "4140110135"
    },
    "companyName": "Complete Concrete Pty Ltd",
    "dateOfBirth": "1976-08-26",
    "entityType": "COMPANY",
    "firstName": "John",
    "lastName": "Walker"
  },
  "nickname": "Complete Concrete Pty Ltd",
  "payerEntityType": "COMPANY",
  "transferMethods": [
    "SWIFT"
  ],
  "transferReason": "travel"
}

Example response:

{
  "beneficiary": {
    "additionalInfo": {
      "businessArea": "Travel",
      "businessPhoneNumber": "689342234",
      "businessRegistrationNumber": "IT593003",
      "legalRepBankAccountNumber": "44250100003700000000",
      "legalRepFirstNameInChinese": "小芳",
      "legalRepMobileNumber": "13651362890",
      "personalEmail": "[email protected]",
      "personalFirstNameInChinese": "大明",
      "personalIdNumber": "1234567890",
      "personalIdType": "CHINESE_NATIONAL_ID",
      "personalLastNameInChinese": "李",
      "personalMobileNumber": "13651362890"
    },
    "address": {
      "city": "Melbourne",
      "countryCode": "AU",
      "postcode": "3000",
      "state": "VIC",
      "streetAddress": "15 William Street"
    },
    "bankDetails": {
      "accountCurrency": "AUD",
      "accountName": "Lee Da Ming",
      "accountNumber": "12750852",
      "accountRoutingType1": "bsb",
      "accountRoutingType2": "sort_code",
      "accountRoutingValue1": "Melbourne",
      "accountRoutingValue2": "083064",
      "bankAccountCategory": "123456",
      "bankBranch": "Melbourne",
      "bankCountryCode": "AU",
      "bankName": "National Australia Bank",
      "bankStreetAddress": "500 Bourke Street, Melbourne 3000, Australia",
      "bindingMobileNumber": "654897612345",
      "fingerprint": "2e99758548972a8e8822ad47fa1017ff72f06f3ff6a016851f45c398732bc5",
      "iban": "ES8023100001180000012345",
      "localClearingSystem": "ACH",
      "swiftCode": "CTBAAU2S",
      "transactionReference": "4140110135"
    },
    "companyName": "Complete Concrete Pty Ltd",
    "dateOfBirth": "1976-08-26",
    "entityType": "COMPANY",
    "firstName": "John",
    "lastName": "Walker"
  },
  "beneficiaryId": "8365ea88-2946-4877-abe1-e02a1015288d",
  "nickname": "Complete Concrete Pty Ltd",
  "payerEntityType": "COMPANY",
  "paymentTypes": [
    "SWIFT"
  ]
}