> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ebury.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Instructions Model

This is a representation of a payment instruction model. When the Payment Instruction model is used as input, fields marked as REQUIRED are mandatory.

<Warning>Refer to [GET /metadata/beneficiary](/api/metadata/get-beneficiary-metadata) endpoint to identify valid beneficiary field combinations for a given country/currency combination.</Warning>

**Fields**

<ParamField body="account_id" type="string">
  The ID of the beneficiary's bank account. When this is provided, beneficiary details like account number, beneficiary name should not be.
</ParamField>

<ParamField body="beneficiary_id" type="string">
  The ID of the beneficiary. When this is provided, beneficiary details like account number, beneficiary name should not be.
</ParamField>

<ParamField body="account_number" type="string">
  Account number. When this is provided, beneficiary\_id, account\_id should not be.
</ParamField>

<ParamField body="bank_address" type="string">
  The bank address of the beneficiary. When this is provided, beneficiary\_id, account\_id should not be.
</ParamField>

<ParamField body="bank_code" type="string">
  The bank code of the beneficiary (UK sort code, US ABA/FedWire, etc.). When this is provided, beneficiary\_id, account\_id should not be.
</ParamField>

<ParamField body="bank_country" type="string">
  The bank country of the beneficiary in ISO 3166-1 format (two character alpha code). When this is provided, beneficiary\_id, account\_id should not be.
</ParamField>

<ParamField body="bank_name" type="string">
  Name of the bank account holder. When this is provided, beneficiary\_id, account\_id should not be.
</ParamField>

<ParamField body="beneficiary_address" type="string">
  The beneficiary address. When this is provided, beneficiary\_id, account\_id should not be. (deprecated)\*
</ParamField>

<ParamField body="beneficiary_street_name" type="string">
  The street name of the beneficiary.\*
</ParamField>

<ParamField body="beneficiary_building_number" type="string">
  The building number of the beneficiary.\*
</ParamField>

<ParamField body="beneficiary_floor" type="string">
  The floor of the beneficiary.\*
</ParamField>

<ParamField body="beneficiary_apartment_office_number" type="string">
  The apartment/office number of the beneficiary.\*
</ParamField>

<ParamField body="beneficiary_city" type="string" required>
  The city of the beneficiary.\*
</ParamField>

<ParamField body="beneficiary_state_region" type="string">
  The state/region of the beneficiary.\*
</ParamField>

<ParamField body="beneficiary_post_code" type="string">
  The postcode of the beneficiary.\*
</ParamField>

<ParamField body="beneficiary_country" type="string" required>
  The beneficiary country in ISO 3166-1 format (two character alpha code). When this is provided, beneficiary\_id, account\_id should not be.
</ParamField>

<ParamField body="beneficiary_name" type="string">
  The beneficiary name. When this is provided, beneficiary\_id, account\_id should not be.
</ParamField>

<ParamField body="beneficiary_reference" type="string">
  Permanent reference to add to a beneficiary for all future payments. When this is provided, beneficiary\_id, account\_id should not be.
</ParamField>

<ParamField body="direction" type="string" required>
  Acceptable values:

  * `buy`
  * `sell`

  Direction field determines whether the payment\_amount reflects the amount of currency to buy or amount of currency to sell. Example provided in [notes](#notes).
</ParamField>

<ParamField body="external_reference_id" type="string">
  Unique reference submitted by the client to identify the payment.
</ParamField>

<ParamField body="iban" type="string">
  When this is provided, beneficiary\_id, account\_id should not be.
</ParamField>

<ParamField body="inn" type="string">
  Unique Taxpayer Personal Identification Number for legal entities registered in Russia.
</ParamField>

<ParamField body="kio" type="string">
  Tax ID for foreign legal entities in Russia.
</ParamField>

<ParamField body="payment_currency" type="string" required>
  Buy currency code ISO 4217
</ParamField>

<ParamField body="payment_amount" type="number" required>
  Buy amount
</ParamField>

<ParamField body="payment_reference" type="string" required>
  Payment reference
</ParamField>

<ParamField body="purpose_of_payment" type="string">
  The [purpose of payment](#purposeofpayment) is mandatory when the beneficiary account has specific currency types. See the section [PurposeOfPayment](#purposeofpayment) for the currencies and their acceptable values.
</ParamField>

<ParamField body="reason_for_trade" type="string" required>
  Reason for trade. See [ReasonForTradeValues](#reasonfortradevalues) for acceptable values.
</ParamField>

<ParamField body="russian_central_bank_account" type="string">
  20-digit code for Russian banks.
</ParamField>

<ParamField body="swift_code" type="string">
  When this is provided, beneficiary\_id, account\_id should not be.
</ParamField>

<ParamField body="trade_type" type="string" required>
  Type of trade. Acceptable values:

  * `spot`
</ParamField>

<ParamField body="value_date" type="string" required>
  Date of the payment (YYYY-MM-DD)
</ParamField>

<ParamField body="vo" type="string">
  Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment.
</ParamField>

\* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.

```json Response theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1

[
   {
      "account_number":"string",
      "bank_address":"string",
      "bank_code":"string",
      "bank_country":"string",
      "bank_name":"string",
      "beneficiary_address":"string",
      "beneficiary_street_name":"string",
      "beneficiary_building_number":"string",
      "beneficiary_floor":"string",
      "beneficiary_apartment_office_number":"string",
      "beneficiary_city":"string",
      "beneficiary_state_region":"string",
      "beneficiary_post_code":"string",
      "beneficiary_name":"string",
      "beneficiary_country":"string",
      "beneficiary_reference":"string",
      "direction":"string",
      "external_reference_id":"string",
      "iban":"string",
      "inn":"string",
      "kio":"string",
      "payment_currency":"string",
      "payment_amount":"number",
      "payment_reference":"string",
      "purpose_of_payment":"Purpose of Payment",
      "reason_for_trade":"string",
      "russian_central_bank_account":"string",
      "swift_code":"string",
      "trade_type":"string",
      "value_date":"string",
      "vo":"string"
   }
]
```

## Notes

**Example:**

At the time of submission of mass-payment (POST /mass-payment) sell\_currency field is set as GBP or trade\_id provided contains sell\_currency as GBP. In the payment instruction payment\_currency is set as EUR, payment\_amount is set as 100 and direction is set as sell.

```json theme={null}
{
    "auto_commit": "false",
    "sell_currency": "GBP",
    "external_reference_id": "",
    "payment_instructions": [
        {
            "account_number": "",
            "bank_address": "",
            "bank_code": "",
            "bank_country": "IT",
            "bank_name": "",
            "beneficiary_address": "",
            "beneficiary_street_name": "string",
            "beneficiary_building_number": "string",
            "beneficiary_floor": "string",
            "beneficiary_apartment_office_number": "string",
            "beneficiary_city": "string",
            "beneficiary_state_region": "string",
            "beneficiary_post_code": "string",
            "beneficiary_name": "Beneficiary Name",
            "beneficiary_country": "IT",
            "direction": "sell",
            "external_reference_id": "",
            "iban": "IT28E0300203280787878415564",
            "payment_currency": "EUR",
            "payment_amount": 100,
            "reason_for_trade": "ben1",
            "reference": "reference",
            "swift_code": "UNCRITMMXXX",
            "value_date": null,
            "trade_type": "spot"
        }
    ]
}
```

In this case the client is giving an instruction to calculate EUR amount equivalent to 100 GBP. The payment\_amount will be calculated based on the exchange rate of converting 100 GBP to EUR.

```json theme={null}
[
    {
        "account_number": "",
        "amount": 116.21,
        "authorisation_workflow": "4-eyes",
        "authorised_by": null,
        "authorised_date": null,
        "bank_identifier": "",
        "beneficiary_name": "Beneficiary Name",
        "cancelled_by": null,
        "cancelled_date": null,
        "contact_id": "EBPCON36429",
        "created_date": "2021-08-20",
        "external_reference_id": "",
        "fee_amount": 12.85,
        "fee_currency": "EUR",
        "iban": "IT03V0300203280998885565948",
        "invoice_required": false,
        "payment_currency": "EUR",
        "payment_date": "2021-08-24",
        "payment_id": "PI2305652",
        "payment_instruction": "/documents?type=pi&id=PI2305652&client_id=EBPCLI00003",
        "payment_receipt": "/documents?type=pr&id=PI2305652&client_id=EBPCLI00003",
        "reference": "reference",
        "rejected_by": null,
        "rejected_date": null,
        "status": "Validating beneficiary information",
        "swift_code": "UNCRITMMXXX",
        "trade_id": "EBPOTR2162767"
    }
]
```