Get beneficiary requirements

GET/partner/v1/beneficiary-requirements

Auth Bearer tokenScope partner.read

Returns what a beneficiary on one corridor must contain: its fields, the rules each value must meet, and the documents it may carry. Build your form, or map your stored data, from this response, then send the values to Create beneficiary under the same field names.

The answer is the same whether the beneficiary is for you or for one of your customers, because your customers are offered your corridors. It can change when Ryno changes how a corridor is paid, so read it before you create a beneficiary rather than caching it for long.

Query

corridorIduuidqueryrequired

A corridorId from List payout corridors.

Response

corridorIduuid

The corridor you asked about.

destinationCountrystring

The beneficiary's country, ISO 3166-1 alpha-3, for example CHN.

currencystring

The currency the beneficiary receives, for example USD.

railstring

How the beneficiary is paid on this corridor, for example RTGS. Informational; you never send it.

fieldsobject[]

The fields a beneficiary on this corridor can have, in the order to show them. Send each value in details on Create beneficiary, keyed by name. A field that is not in this list is refused.

Show propertiesHide properties

namestring

The key to use in details, for example accountNumber.

requiredboolean

true when the beneficiary cannot be saved without a value.

notBlankboolean

true when a value made only of spaces is refused.

noControlCharactersboolean

true when a value with a control character, such as a line break or tab, is refused.

minLengthinteger

The fewest characters a value may have. Absent when there is no minimum.

maxLengthinteger

The most characters a value may have. Absent when there is no maximum.

patternsstring[]

Regular expressions the value must match, all of them. Absent when there are none. They are written for .NET, where $(?!\n) means the end of the value; most other engines read them the same way.

choicesobject[]

The only values accepted, when the field is a fixed list, such as the banks of a country. Absent for free-text fields. Each choice has a value to send, and may have attributes: other fields' values that go with that choice.

filledFromstring

Present when this field's value comes from the choice made for another field. For example, swiftCode with filledFrom: "bankName" must be the swiftCode attribute of the chosen bank. Fill it in for the user rather than asking for it.

documentsobject

The supporting documents a beneficiary on this corridor may carry. Documents are optional.

Show propertiesHide properties

maxCountinteger

The most documents one beneficiary can carry.

typesstring[]

The accepted document types. Send one as documentCategory when you request the upload link; the link accepts Invoice or Contract.

contentTypesstring[]

The accepted file types, for example application/pdf.

maxSizeBytesinteger

The largest file accepted, in bytes.

These rules let you check values before you send them. Ryno checks them again on Create beneficiary and names the first field that fails.

Errors

Code	HTTP	Meaning
BeneficiaryRequirement.InvalidRequest	400	corridorId is missing.
Request.Invalid	400	corridorId is not a uuid.
Auth.Unauthorized	401	The token is missing or invalid.
Auth.Forbidden	403	The token is not a partner credential, or lacks partner.read.
BeneficiaryRequirement.CustomerInactive	403	Your account is not active. Contact support.
BeneficiaryRequirement.CustomerNotFound	404	Your account could not be found. Contact support.
BeneficiaryRequirement.CorridorNotFound	404	The corridor is not one you are offered. Use an id from List payout corridors.
BeneficiaryRequirement.NotAvailable	422	The corridor cannot take beneficiaries yet. Do not retry unchanged; contact support if you need it.
BeneficiaryRequirement.Unavailable	503	Requirements cannot be read right now. Retry with backoff.

The 401, 429 and 503 responses from the API gateway use a different body. See Errors.

Request

curl "https://gateway.sandbox.rynopay.io/api/partner/v1/beneficiary-requirements?corridorId=c2f6d7a4-3b1e-4e8a-9d0c-5a7b1e2f3c44" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

200

{
  "value": {
    "corridorId": "c2f6d7a4-3b1e-4e8a-9d0c-5a7b1e2f3c44",
    "destinationCountry": "CHN",
    "currency": "USD",
    "rail": "RTGS",
    "fields": [
      {
        "name": "beneficiaryType",
        "required": true,
        "notBlank": false,
        "noControlCharacters": false,
        "choices": [{ "value": "Business" }]
      },
      {
        "name": "accountName",
        "required": true,
        "notBlank": true,
        "noControlCharacters": true,
        "minLength": 2,
        "maxLength": 128
      },
      {
        "name": "accountNumber",
        "required": true,
        "notBlank": true,
        "noControlCharacters": true,
        "minLength": 8,
        "maxLength": 64,
        "patterns": ["^[A-Z0-9]{8,64}$(?!\\n)"]
      },
      {
        "name": "bankName",
        "required": true,
        "notBlank": false,
        "noControlCharacters": false,
        "choices": [
          {
            "value": "Bank of China",
            "attributes": { "swiftCode": "BKCHCNBJXXX" }
          },
          {
            "value": "China Merchants Bank",
            "attributes": { "swiftCode": "CMBCCNBSXXX" }
          }
        ]
      },
      {
        "name": "swiftCode",
        "required": true,
        "notBlank": false,
        "noControlCharacters": false,
        "filledFrom": "bankName"
      },
      {
        "name": "beneficiaryAddress",
        "required": true,
        "notBlank": true,
        "noControlCharacters": true,
        "minLength": 1,
        "maxLength": 255
      },
      {
        "name": "beneficiaryCity",
        "required": true,
        "notBlank": true,
        "noControlCharacters": true,
        "minLength": 1,
        "maxLength": 64
      }
    ],
    "documents": {
      "maxCount": 10,
      "types": ["Invoice", "Contract"],
      "contentTypes": ["application/pdf", "image/png", "image/jpeg"],
      "maxSizeBytes": 8388608
    }
  },
  "isSuccess": true,
  "isFailure": false,
  "error": { "code": "", "name": "" },
  "title": null,
  "traceId": "0HN..."
}

The real China list has many more banks, and a few more optional fields. It is shortened here.

404

{
  "value": null,
  "isSuccess": false,
  "isFailure": true,
  "error": {
    "code": "BeneficiaryRequirement.CorridorNotFound",
    "name": "The payout corridor could not be found"
  },
  "title": "Resource not found",
  "traceId": "0HN..."
}