> ## 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.

# Create a multi payment instruction

Create a new multi payment instruction. Requires either a sell currency or existing trade ID to create the instruction


## OpenAPI

````yaml /openapi.json post /multipayments
openapi: 3.0.0
info:
  description: |
    Ebury API allows customers:
      to retrieve accounts, balances, beneficiaries, and transactions;
      to get buy/sell estimates and quotes, book trades and retrieve trade history;
      to allocate payments to a trade and beneficiary, and to submit payments in bulk;
      to download documents such as trade receipt, payment instruction and payment receipt;
      to manage the authorised persons on their account.
    The Metadata API allows applications to clarify some parts of the Ebury API
      that are impractical to express schematically.
  termsOfService: https://docs.ebury.io/#terms-of-use
  title: Ebury API
  version: '0.1'
servers:
  - url: https://{environment}.ebury.io
    variables:
      environment:
        default: api
        enum:
          - api
          - sandbox
security:
  - api_key: []
paths:
  /multipayments:
    post:
      tags:
        - Multi Payments
      summary: Create a multi payment instruction
      description: >-
        Create a new multi payment instruction. Requires either a sell currency
        or existing trade ID to create the instruction
      parameters:
        - description: The ID of the client
          in: query
          name: client_id
          required: true
          schema:
            type: string
        - description: >-
            Trade ID to book payments against. Omit if trade should be executed
            to fund payments
          in: query
          name: trade_id
          required: false
          schema:
            type: string
        - description: If trade_id omitted, a sell currency must be supplied
          in: query
          name: sell_currency
          required: false
          schema:
            type: string
        - description: >-
            Accept a partially successful instruction. If true, send successful
            instructions for payment. If false, reject the entire instruction
          in: query
          name: accept_partial
          required: false
          schema:
            type: boolean
            default: true
        - description: Set to true. Accept quote immediately, do not require confirmation
          in: query
          name: accept_immediately
          required: true
          schema:
            type: boolean
        - name: Authorization
          in: header
          description: The access token
          required: true
          schema:
            type: string
        - description: The ID of the contact
          in: header
          name: X-Contact-ID
          required: false
          schema:
            type: string
        - description: VoP authorization ID to confirm not full-match payment
          in: query
          name: vop_authorization_id
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMultiPayment'
        description: Request Payload
        required: true
      responses:
        '201':
          description: Multi payment created, see response body for status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiPaymentResponse'
        '202':
          description: Multi payment accepted with errors, see response body for status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiPaymentResponse'
        '400':
          description: >-
            Formatting or schema validation error. See error message for further
            details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Access denied due to authentication failure
        '403':
          description: >-
            Could not complete action due to data constraints. Refer to error
            message for additional details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Client ID not found
        '409':
          description: >-
            All payments invalid or partial instruction not allowed, see
            response body for details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiPaymentErrorMessage'
        '422':
          description: VoP check failed, or provided `vop_authorization_id` is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '502':
          description: Internal integration error. Contact support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    NewMultiPayment:
      example:
        - account_number: 9999999999
          bank_address: 1 Test Street
          bank_code: 999999
          bank_country: 'N'
          bank_name: Test Bank 1
          beneficiary_address: 2 Test Street
          beneficiary_country: NZ
          beneficiary_name: Functional Test New Zealand
          beneficiary_reference: Beneficiary bank
          direction: buy
          iban: null
          inn: null
          kio: null
          payment_amount: 110.01
          payment_currency: NZD
          payment_reference: MULTIPAYMENTSTEST
          purpose_of_payment: null
          reason_for_trade: Execute payments
          russian_central_bank_account: null
          swift_code: TESTNZ99
          trade_type: spot
          value_date: '2016-04-18T00:00:00.000Z'
          vo: null
        - account_number: null
          bank_address: 1 Test Street
          bank_code: null
          bank_country: ES,
          bank_name: Test Bank 2
          beneficiary_address: 2 Test Street
          beneficiary_country: GB
          beneficiary_name: Test beneficiary
          beneficiary_reference: null
          direction: buy
          iban: ES6710067038260971665568
          inn: null
          kio: null
          payment_amount: 32.02
          payment_currency: EUR
          payment_reference: MULTIPAYMENTSTEST
          purpose_of_payment: null
          reason_for_trade: Execute payments
          russian_central_bank_account: null
          swift_code: TESTES99
          trade_type: spot
          value_date: '2016-04-18T00:00:00.000Z'
          vo: null
      items:
        $ref: '#/components/schemas/NewMultiPaymentItem'
      type: array
    MultiPaymentResponse:
      example:
        account_details:
          - account_number: 99999999
            bank_identifier: 999999
            bank_identifier_type: SC UK Sort Code
            iban: GB82TEST9999999999999999
            swift_code: TESTGB99
        multipayment_id: 1
        trade_details:
          - buy_amount: 32
            buy_currency: EUR
            client_rate: 0.814273
            client_rate_symbol: EURGBP
            inverse_rate: 1.228089
            inverse_rate_symbol: GBPEUR
            sell_amount: 26.06
            sell_currency: GBP
            value_date: '2016-04-18T00:00:00.000Z'
          - buy_amount: 110
            buy_currency: NZD
            client_rate: 2.013132
            client_rate_symbol: GBPNZD
            inverse_rate: 0.496738
            inverse_rate_symbol: NZDGBP
            sell_amount: 54.64
            sell_currency: GBP
            value_date: '2016-04-18T00:00:00.000Z'
      properties:
        account_details:
          allOf:
            - $ref: '#/components/schemas/BankAccount'
          type: object
        invalid_payments:
          items:
            $ref: '#/components/schemas/MultiPaymentError'
          type: array
        multipayment_id:
          description: The multipayment ID
          format: int32
          type: integer
        trade_details:
          items:
            properties:
              buy_amount:
                format: float
                type: number
              buy_currency:
                type: string
              client_rate:
                format: float
                type: number
              client_rate_symbol:
                type: string
              inverse_rate:
                format: float
                type: number
              inverse_rate_symbol:
                type: string
              sell_amount:
                format: float
                type: number
              sell_currency:
                type: string
              value_date:
                format: date
                type: string
            type: object
          type: array
      required:
        - multipayment_id
      type: object
    ErrorMessage:
      description: An error message.
      properties:
        code:
          type: string
          description: The code for the error.
        details:
          description: Error details
          type: string
        message:
          type: string
          description: A short description of the cause of the error.
      required:
        - code
        - message
        - details
      type: object
    MultiPaymentErrorMessage:
      items:
        $ref: '#/components/schemas/MultiPaymentError'
      type: array
    NewMultiPaymentItem:
      required:
        - account_number
        - bank_address
        - bank_code
        - bank_country
        - bank_name
        - beneficiary_address
        - beneficiary_country
        - beneficiary_name
        - direction
        - iban
        - payment_amount
        - payment_currency
        - reason_for_trade
        - swift_code
        - trade_type
        - value_date
      properties:
        account_number:
          description: Destination account number
          type: string
          nullable: true
        bank_address:
          description: Destination bank address
          type: string
          nullable: true
        bank_code:
          description: Destination bank code
          type: string
          nullable: true
        bank_country:
          description: Destination bank country
          type: string
          minLength: 1
        bank_name:
          description: Destination bank name
          type: string
          nullable: true
        beneficiary_address:
          description: Address of beneficiary
          type: string
          nullable: true
        beneficiary_name:
          description: Name of beneficiary
          type: string
          nullable: true
        beneficiary_country:
          description: Country of beneficiary
          type: string
          nullable: true
        direction:
          description: Type of payment, 'buy' or 'sell'
          type: string
          enum:
            - buy
            - sell
        iban:
          description: IBAN of the destination account
          type: string
          nullable: true
        payment_currency:
          description: Destination currency
          type: string
          minLength: 1
        payment_amount:
          description: Amount to be paid
          type: number
          format: float
          minimum: 0
        reason_for_trade:
          description: Reason for trade
          type: string
          nullable: true
        payment_reference:
          description: Reference of payment
          type: string
          nullable: true
        swift_code:
          description: SWIFT code of destination bank
          type: string
          nullable: true
        trade_type:
          description: Type of trade. 'spot' is the only supported value at the moment
          type: string
          enum:
            - spot
        value_date:
          description: Date when the transaction will be performed
          type: string
          nullable: true
        beneficiary_reference:
          description: Reference of beneficiary
          type: string
          nullable: true
        purpose_of_payment:
          description: Text describing the purpose of the payment
          type: string
          nullable: true
        reference:
          description: Payment reference
          type: string
          nullable: true
        inn:
          description: The INN of the bank account
          type: string
          pattern: ^[0-9]{10}([0-9]{2})?$
          nullable: true
        vo:
          description: The VO of the bank account
          type: string
          nullable: true
        kio:
          description: The KIO of the bank account
          type: string
          nullable: true
        russian_central_bank_account:
          description: Russian central bank account
          type: string
          nullable: true
      type: object
    BankAccount:
      allOf:
        - $ref: '#/components/schemas/BankAccountCoreData'
      description: A bank account.
      properties:
        account_id:
          description: The identifier of the bank account.
          type: integer
      required:
        - account_id
      type: object
    MultiPaymentError:
      allOf:
        - $ref: '#/components/schemas/NewPayment'
        - items:
            properties:
              code:
                description: The exception label
                type: string
              message:
                description: The exception message
                type: string
            required:
              - code
              - message
            type: object
          type: array
    BankAccountCoreData:
      description: >-
        The data of the bank account. Refer to the Metadata API for valid field
        combinations.
      properties:
        account_number:
          description: The account number of the bank account.
          type: string
        bank_address_line_1:
          description: The first address line of the bank.
          type: string
        bank_country_code:
          description: The ISO 3166-1 alpha-2 code of the bank's country.
          pattern: '[A-Z]{2}'
          type: string
        bank_currency_code:
          description: The ISO 4217 code of the bank account's currency.
          pattern: '[A-Z]{3}'
          type: string
        bank_identifier:
          description: The identifier of the bank.
          type: string
        bank_name:
          description: Name of the bank account holder.
          type: string
        correspondent_account:
          description: The account for the correspondant account of the bank.
          type: string
        correspondent_swift_code:
          description: The SWIFT code for the correspondant account of the bank.
          type: string
        iban:
          description: The IBAN of the bank account.
          type: string
        inn:
          description: The INN of the bank account.
          type: string
        kbk:
          description: The KBK of the bank account.
          type: string
        kio:
          description: The KIO of the bank account.
          type: string
        kpp:
          description: The KPP of the bank account.
          type: string
        purpose_of_payment:
          description: >-
            Text explaining the purpose of payment. Required by the Central Bank
            for all payments sent to China (CHN) in the Chinese Renminbi (CNY)
            currency or United Arab Emirates in any currency (GDE to RDA)
            [Coming soon].
          enum:
            - /CGODDR/
            - /CGODDR/PART/
            - /CGODDR/RETN/
            - /CSTRDR/
            - /CSTRDR/PART/
            - /CSTRDR/RETN/
            - /COCADR/
            - /COCADR/RTN/
            - /CCTFDR/
            - /CCTFDR/PART/
            - /CCTFDR/RETN/
            - /CCDNDR/
            - /CCDNDR/RTN/
            - GDE
            - GDI
            - GMS
            - STS
            - ATS
            - OTS
            - STR
            - SCO
            - INS
            - FIS
            - IPC
            - TCS
            - ITS
            - IFS
            - RDS
            - PMS
            - TTS
            - PRS
            - GOS
            - SAL
            - IGD
            - IID
            - PIP
            - PRR
            - DOE
            - ISH
            - ISL
            - ISS
            - IOL
            - IOD
            - GRI
            - CHC
            - EDU
            - ALW
            - AES
            - LAS
            - OVT
            - TKT
            - SAA
            - COP
            - COM
            - EOS
            - BON
            - PEN
            - UTL
            - DCP
            - LND
            - LIP
            - IPO
            - POR
            - RNT
            - LNC
            - EMI
            - DIV
            - ACM
            - CCP
            - POS
            - MCR
            - CIN
            - TOF
            - IGT
            - OAT
            - SVI
            - SVO
            - SVP
            - MWI
            - MWO
            - MWP
            - PRP
            - PRW
            - IRP
            - IRW
            - CEA
            - PPA
            - DSF
            - DLF
            - FSA
            - FIA
            - DSA
            - DLA
            - FDA
            - AFA
            - SLA
            - LLA
            - LEA
            - RFS
            - TCR
            - CEL
            - PPL
            - LDS
            - LDL
            - FSL
            - FIL
            - DSL
            - DLL
            - FDL
            - AFL
            - SLL
            - LLL
            - LEL
            - RLS
            - TCP
            - TAX
            - REL
            - RDL
            - REA
            - RDA
          type: string
        reason_for_trade:
          description: The reason for trade of the bank account.
          type: string
        reference_information:
          description: The reference information of the bank account.
          type: string
        russian_central_bank_account:
          description: The Russian central account number of the bank account.
          type: string
        swift_code:
          description: The SWIFT code of the bank account.
          type: string
        vo:
          description: The VO of the bank account.
          type: string
      required:
        - bank_country_code
        - bank_currency_code
      type: object
    NewPayment:
      description: A list of payments with known beneficiary/bank account IDs.
      properties:
        async:
          description: >-
            Create the payment(s) asynchronously. Payments are created
            synchronously by default.
          type: boolean
        is_pad:
          description: >-
            Whether to fund payments via Pre-Authorized Debit (direct debit).
            Only valid for CAD and AUD payments with available credit.
            Deprecated; set is_pad per payment instead. Not honoured on the SCA
            (2FA) path.
          deprecated: true
          type: boolean
          default: false
        payments:
          description: A list of payments
          items:
            properties:
              account_id:
                description: The ID of the beneficiary's bank account
                type: string
              amount:
                description: The payment amount
                format: float
                type: number
              beneficiary_id:
                description: The ID of the beneficiary
                type: string
              email_beneficiary:
                default: false
                description: Whether the beneficiary should receive and email on payment
                type: boolean
              payment_date:
                description: The date on which payment is required
                format: date
                type: string
              reference:
                description: Payment reference
                type: string
              is_pad:
                description: >-
                  Whether to fund this payment via Pre-Authorized Debit (direct
                  debit). Only valid for CAD and AUD payments with available
                  credit. Applies per payment; falls back to the request-level
                  is_pad when omitted.
                type: boolean
                default: false
            required:
              - beneficiary_id
              - account_id
              - amount
              - payment_date
              - reference
            type: object
          type: array
        trade_id:
          description: Unique identifier of the trade the payment is allocated to
          type: string
      type: object
  securitySchemes:
    api_key:
      description: An API Key.
      in: header
      name: x-api-key
      type: apiKey

````