bunq Transferwise Transfer API

openapi: 3.2.0
info:
  title: bunq Transferwise Transfer API
  description: '***UPDATE:*** *We have released a beta version of the new bunq API documentation.*


    ***NOTICE:*** *We have updated the sandbox base url to `https://public-api.sandbox.bunq.com/v1/`. Please update your applications accordingly. Check here: for more info.*


    ***PSD2 NOTICE:*** *The second Payment Services Directive (PSD2) may affect your current or planned usage of our public API, as some of the API services are now subject to a permit. Please be aware that using our public API without the required PSD2 permit is at your own risk and take notice of our updated API Terms and Conditions on for more information.*


    # Introduction


    Welcome to bunq! - The bunq API is organised around REST. JSON will be returned in almost all responses from the API, including errors but excluding binary (image) files. - Please configure your implementation to send its API requests to `https://public-api.sandbox.bunq.com/v1/`

    - There is a version of the Android app that connects to the bunq Sandbox environment. To create accounts for the Sandbox app, please follow the steps in the Android Emulator section. ## Getting started


    Before you start sending API requests, you need to get an API key and activate it. API activation happens when you install the API key and link your IP address and device to it *(create an API context)*. The steps below will guide you through what you need to do to start sending custom API requests. Here is an overview of what you can use to get started with the bunq API:

    1. **Create an API key.** You can do it either in our developer portal or in the bunq app *(Profile → Security & Settings → Developers → API keys)*. If you want to test our sandbox first, our bunq Developer is the best place to start. 2. **Register a device.** A device can be a phone (private), computer or a server (public). You can register a new device by using the `POST /installation` and `POST /device-server` calls. This will activate your API key. You only need to do this once. 3. **Open a session.** Sessions are temporary and expire after the auto-logout time set for the user account. It can be changed by the account owner in the bunq app. 4. **Make your first call!**


    !bunq_API_context


    ## Versioning


    Developments in the financial sector, changing regulatory regimes and new feature requests require us to be flexible. This means we can iterate quickly to improve the API and related tooling. Therefore, we have chosen not to attach any version numbers to the changes just yet. We will inform you in a timely manner of any important changes we make before they are deployed on together.bunq.com. You can also subscribe to our API newsletter to make sure you don''t miss any important updates. # OAuth


    ## What is OAuth? OAuth 2.0 is a protocol that will let your app connect to bunq users in a safe and easy way. Please be aware that if you will gain access to the account information of other bunq users or initiate a payment for them, you may require a PSD2 permit. ## Get started with OAuth for bunq


    To initiate authorization into the bunq user accounts, you need to create an OAuth Client and register at least 1 redirect URL for it. You can have 1 OAuth Client at a time. Reuse your OAuth credentials for every authorization request. The list of steps below will help you to get started:


    1. Register an OAuth Client by creating an app in bunq Developer_._

    2. Add one or more Redirect URLs. 3. Get your `client_id` and `secret` from your app information tab in bunq Developer. 4. Redirect your users to the OAuth authorization request URL. 5. If the user accepts the authorization request, they will be redirected to the previously specified `redirect_uri` with an authorization `code` parameter. 6. Use the token endpoint to exchange the authorization `code` for an `access_token`. 7. Use the `access_token` as a normal API Key. Open a session or use our SDKs to get started. You can set up an OAuth Client and add redirect URLs to it using the dedicated endpoints too.'
  termsOfService: http://bunq.com/terms-api/
  contact:
    name: bunq Developer Support
    url: http://bunq.com/developer
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: '1.0'
servers:
- url: https://public-api.sandbox.bunq.com/{basePath}
  description: Sandbox server
  variables:
    basePath:
      default: v1
- url: https://api.bunq.com/{basePath}
  description: Production server
  variables:
    basePath:
      default: v1
tags:
- name: transferwise-transfer
  description: ''
paths:
  /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-transfer:
    post:
      tags:
      - transferwise-transfer
      summary: CREATE transferwise transfer for user transferwise quote
      operationId: CREATE_TransferwiseTransfer_for_User_TransferwiseQuote
      description: Used to create Transferwise payments.
      parameters:
      - in: path
        name: userID
        description: ''
        required: true
        schema:
          type: integer
      - in: path
        name: transferwise-quoteID
        description: ''
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/Cache-Control'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/X-Bunq-Language'
      - $ref: '#/components/parameters/X-Bunq-Region'
      - $ref: '#/components/parameters/X-Bunq-Client-Request-Id'
      - $ref: '#/components/parameters/X-Bunq-Geolocation'
      - $ref: '#/components/parameters/X-Bunq-Client-Authentication'
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferwiseTransfer'
      responses:
        '200':
          description: Used to create Transferwise payments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferwiseTransferCreate'
          headers:
            X-Bunq-Client-Response-Id:
              $ref: '#/components/headers/X-Bunq-Client-Response-Id'
            X-Bunq-Client-Request-Id:
              $ref: '#/components/headers/X-Bunq-Client-Request-Id'
            X-Bunq-Server-Signature:
              $ref: '#/components/headers/X-Bunq-Server-Signature'
        '400':
          $ref: '#/components/responses/GenericError'
      x-summary-source: derived
    get:
      tags:
      - transferwise-transfer
      summary: List all transferwise transfer for user transferwise quote
      operationId: List_all_TransferwiseTransfer_for_User_TransferwiseQuote
      description: Used to create Transferwise payments.
      parameters:
      - in: path
        name: userID
        description: ''
        required: true
        schema:
          type: integer
      - in: path
        name: transferwise-quoteID
        description: ''
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/Cache-Control'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/X-Bunq-Language'
      - $ref: '#/components/parameters/X-Bunq-Region'
      - $ref: '#/components/parameters/X-Bunq-Client-Request-Id'
      - $ref: '#/components/parameters/X-Bunq-Geolocation'
      - $ref: '#/components/parameters/X-Bunq-Client-Authentication'
      responses:
        '200':
          description: Used to create Transferwise payments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransferwiseTransferListing'
          headers:
            X-Bunq-Client-Response-Id:
              $ref: '#/components/headers/X-Bunq-Client-Response-Id'
            X-Bunq-Client-Request-Id:
              $ref: '#/components/headers/X-Bunq-Client-Request-Id'
            X-Bunq-Server-Signature:
              $ref: '#/components/headers/X-Bunq-Server-Signature'
        '400':
          $ref: '#/components/responses/GenericError'
      x-summary-source: derived
  /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-transfer/{itemId}:
    get:
      tags:
      - transferwise-transfer
      summary: READ transferwise transfer for user transferwise quote
      operationId: READ_TransferwiseTransfer_for_User_TransferwiseQuote
      description: Used to create Transferwise payments.
      parameters:
      - in: path
        name: userID
        description: ''
        required: true
        schema:
          type: integer
      - in: path
        name: transferwise-quoteID
        description: ''
        required: true
        schema:
          type: integer
      - in: path
        name: itemId
        description: ''
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/Cache-Control'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/X-Bunq-Language'
      - $ref: '#/components/parameters/X-Bunq-Region'
      - $ref: '#/components/parameters/X-Bunq-Client-Request-Id'
      - $ref: '#/components/parameters/X-Bunq-Geolocation'
      - $ref: '#/components/parameters/X-Bunq-Client-Authentication'
      responses:
        '200':
          description: Used to create Transferwise payments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferwiseTransferRead'
          headers:
            X-Bunq-Client-Response-Id:
              $ref: '#/components/headers/X-Bunq-Client-Response-Id'
            X-Bunq-Client-Request-Id:
              $ref: '#/components/headers/X-Bunq-Client-Request-Id'
            X-Bunq-Server-Signature:
              $ref: '#/components/headers/X-Bunq-Server-Signature'
        '400':
          $ref: '#/components/responses/GenericError'
      x-summary-source: derived
components:
  schemas:
    TransferwiseTransferListing:
      type: object
      properties:
        alias:
          type: object
          description: The LabelMonetaryAccount containing the public information of 'this' (party) side of the Payment.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/LabelMonetaryAccount'
        counterparty_alias:
          type: object
          description: The LabelMonetaryAccount containing the public information of the other (counterparty) side of the Payment.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/LabelMonetaryAccount'
        status:
          type: string
          description: The status.
          readOnly: true
          writeOnly: false
        sub_status:
          type: string
          description: The subStatus.
          readOnly: true
          writeOnly: false
        status_transferwise:
          type: string
          description: The status as Transferwise reports it.
          readOnly: true
          writeOnly: false
        status_transferwise_issue:
          type: string
          description: A status to indicatie if Transferwise has an issue with this payment and requires more information.
          readOnly: true
          writeOnly: false
        amount_source:
          type: object
          description: The source amount.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/Amount'
        amount_target:
          type: object
          description: The target amount.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/Amount'
        rate:
          type: string
          description: The rate of the payment.
          readOnly: true
          writeOnly: false
        reference:
          type: string
          description: The reference of the payment.
          readOnly: true
          writeOnly: false
        pay_in_reference:
          type: string
          description: The Pay-In reference of the payment.
          readOnly: true
          writeOnly: false
        time_delivery_estimate:
          type: string
          description: The estimated delivery time.
          readOnly: true
          writeOnly: false
        quote:
          type: object
          description: The quote details used to created the payment.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/TransferwiseQuote'
    TransferwiseTransferRead:
      type: object
      properties:
        alias:
          type: object
          description: The LabelMonetaryAccount containing the public information of 'this' (party) side of the Payment.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/LabelMonetaryAccount'
        counterparty_alias:
          type: object
          description: The LabelMonetaryAccount containing the public information of the other (counterparty) side of the Payment.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/LabelMonetaryAccount'
        status:
          type: string
          description: The status.
          readOnly: true
          writeOnly: false
        sub_status:
          type: string
          description: The subStatus.
          readOnly: true
          writeOnly: false
        status_transferwise:
          type: string
          description: The status as Transferwise reports it.
          readOnly: true
          writeOnly: false
        status_transferwise_issue:
          type: string
          description: A status to indicatie if Transferwise has an issue with this payment and requires more information.
          readOnly: true
          writeOnly: false
        amount_source:
          type: object
          description: The source amount.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/Amount'
        amount_target:
          type: object
          description: The target amount.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/Amount'
        rate:
          type: string
          description: The rate of the payment.
          readOnly: true
          writeOnly: false
        reference:
          type: string
          description: The reference of the payment.
          readOnly: true
          writeOnly: false
        pay_in_reference:
          type: string
          description: The Pay-In reference of the payment.
          readOnly: true
          writeOnly: false
        time_delivery_estimate:
          type: string
          description: The estimated delivery time.
          readOnly: true
          writeOnly: false
        quote:
          type: object
          description: The quote details used to created the payment.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/TransferwiseQuote'
    TransferwiseTransfer:
      type: object
      properties:
        monetary_account_id:
          type: string
          description: The id of the monetary account the payment should be made from.
          readOnly: false
          writeOnly: true
        recipient_id:
          type: string
          description: The id of the target account.
          readOnly: false
          writeOnly: true
        alias:
          type: object
          description: The LabelMonetaryAccount containing the public information of 'this' (party) side of the Payment.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/LabelMonetaryAccount'
        counterparty_alias:
          type: object
          description: The LabelMonetaryAccount containing the public information of the other (counterparty) side of the Payment.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/LabelMonetaryAccount'
        status:
          type: string
          description: The status.
          readOnly: true
          writeOnly: false
        sub_status:
          type: string
          description: The subStatus.
          readOnly: true
          writeOnly: false
        status_transferwise:
          type: string
          description: The status as Transferwise reports it.
          readOnly: true
          writeOnly: false
        status_transferwise_issue:
          type: string
          description: A status to indicatie if Transferwise has an issue with this payment and requires more information.
          readOnly: true
          writeOnly: false
        amount_source:
          type: object
          description: The source amount.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/Amount'
        amount_target:
          type: object
          description: The target amount.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/Amount'
        rate:
          type: string
          description: The rate of the payment.
          readOnly: true
          writeOnly: false
        reference:
          type: string
          description: The reference of the payment.
          readOnly: true
          writeOnly: false
        pay_in_reference:
          type: string
          description: The Pay-In reference of the payment.
          readOnly: true
          writeOnly: false
        time_delivery_estimate:
          type: string
          description: The estimated delivery time.
          readOnly: true
          writeOnly: false
        quote:
          type: object
          description: The quote details used to created the payment.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/TransferwiseQuote'
      required:
      - monetary_account_id
      - recipient_id
    TransferwiseQuote:
      type: object
      properties:
        currency_source:
          type: string
          description: The source currency.
          readOnly: false
          writeOnly: true
        currency_target:
          type: string
          description: The target currency.
          readOnly: false
          writeOnly: true
        amount_source:
          type: object
          description: The source amount.
          readOnly: false
          writeOnly: false
          $ref: '#/components/schemas/Amount'
        amount_target:
          type: object
          description: The target amount.
          readOnly: false
          writeOnly: false
          $ref: '#/components/schemas/Amount'
        id:
          type: integer
          description: The id of the quote.
          readOnly: true
          writeOnly: false
        created:
          type: string
          description: The timestamp of the quote's creation.
          readOnly: true
          writeOnly: false
        updated:
          type: string
          description: The timestamp of the quote's last update.
          readOnly: true
          writeOnly: false
        time_expiry:
          type: string
          description: The expiration timestamp of the quote.
          readOnly: true
          writeOnly: false
        quote_id:
          type: string
          description: The quote id Transferwise needs.
          readOnly: true
          writeOnly: false
        amount_fee:
          type: object
          description: The fee amount.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/Amount'
        rate:
          type: string
          description: The rate.
          readOnly: true
          writeOnly: false
        time_delivery_estimate:
          type: string
          description: The estimated delivery time.
          readOnly: true
          writeOnly: false
      required:
      - currency_source
      - currency_target
    Amount:
      type: object
      properties:
        value:
          type: string
          description: The amount formatted to two decimal places.
          readOnly: false
          writeOnly: false
        currency:
          type: string
          description: The currency of the amount. It is an ISO 4217 formatted currency code.
          readOnly: false
          writeOnly: false
    LabelUser:
      type: object
      properties:
        uuid:
          type: string
          description: The public UUID of the label-user.
          readOnly: false
          writeOnly: false
        display_name:
          type: string
          description: The name to be displayed for this user, as it was given on the request.
          readOnly: false
          writeOnly: false
        country:
          type: string
          description: The country of the user. 000 stands for "unknown"
          readOnly: false
          writeOnly: false
        avatar:
          type: object
          description: The current avatar of the user.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/Avatar'
        public_nick_name:
          type: string
          description: The current nickname of the user.
          readOnly: true
          writeOnly: false
    Error:
      type: array
      items:
        type: object
        properties:
          error_description:
            type: string
            description: The error description in English.
          error_description_translated:
            type: string
            description: The error description translated to the user's language.
    Avatar:
      type: object
      properties:
        uuid:
          type: string
          description: The public UUID of the avatar.
          readOnly: false
          writeOnly: false
        anchor_uuid:
          type: string
          description: The public UUID of object this avatar is anchored to.
          readOnly: true
          writeOnly: false
        image:
          type: array
          description: The actual image information of this avatar.
          readOnly: true
          writeOnly: false
          items:
            $ref: '#/components/schemas/Image'
        style:
          type: string
          description: The style (if applicable) for this Avatar.
          readOnly: true
          writeOnly: false
    Pointer:
      type: object
      properties:
        type:
          type: string
          description: 'The alias type, can be: EMAIL|PHONE_NUMBER|IBAN.'
          readOnly: false
          writeOnly: false
        value:
          type: string
          description: The alias value.
          readOnly: false
          writeOnly: false
        name:
          type: string
          description: The alias name.
          readOnly: false
          writeOnly: false
        service:
          type: string
          description: The pointer service. Only required for external counterparties.
          readOnly: false
          writeOnly: true
    BunqId:
      type: object
      properties:
        id:
          type: integer
          description: An integer ID of an object. Unique per object type.
          readOnly: false
          writeOnly: false
    LabelMonetaryAccount:
      type: object
      properties:
        iban:
          type: string
          description: The IBAN of the monetary account.
          readOnly: true
          writeOnly: false
        display_name:
          type: string
          description: The name to display with this monetary account.
          readOnly: true
          writeOnly: false
        avatar:
          type: object
          description: The avatar of the monetary account.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/Avatar'
        label_user:
          type: object
          description: The user this monetary account belongs to.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/LabelUser'
        country:
          type: string
          description: The country of the user. Formatted as a ISO 3166-1 alpha-2 country code.
          readOnly: true
          writeOnly: false
        bunq_me:
          type: object
          description: Bunq.me pointer with type and value.
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/Pointer'
        is_light:
          type: boolean
          description: Whether or not the monetary account is light.
          readOnly: true
          writeOnly: false
        swift_bic:
          type: string
          description: The BIC used for a SWIFT payment.
          readOnly: true
          writeOnly: false
        swift_account_number:
          type: string
          description: The account number used for a SWIFT payment. May or may not be an IBAN.
          readOnly: true
          writeOnly: false
        transferwise_account_number:
          type: string
          description: The account number used for a Transferwise payment. May or may not be an IBAN.
          readOnly: true
          writeOnly: false
        transferwise_bank_code:
          type: string
          description: The bank code used for a Transferwise payment. May or may not be a BIC.
          readOnly: true
          writeOnly: false
        merchant_category_code:
          type: string
          description: The merchant category code.
          readOnly: true
          writeOnly: false
    Image:
      type: object
      properties:
        attachment_public_uuid:
          type: string
          description: The public UUID of the public attachment containing the image.
          readOnly: true
          writeOnly: false
        content_type:
          type: string
          description: The content-type as a MIME filetype.
          readOnly: true
          writeOnly: false
        height:
          type: integer
          description: The image height in pixels.
          readOnly: true
          writeOnly: false
        width:
          type: integer
          description: The image width in pixels.
          readOnly: true
          writeOnly: false
    TransferwiseTransferCreate:
      type: object
      properties:
        Id:
          type: object
          description: The id of the created item
          readOnly: true
          writeOnly: false
          $ref: '#/components/schemas/BunqId'
  parameters:
    X-Bunq-Geolocation:
      description: This header must specify the geolocation of the device. The format of this value is longitude latitude altitude radius country. The country is expected to be formatted of an ISO 3166-1 alpha-2 country code. When no geolocation is available or known the header must still be included but can be zero valued.
      schema:
        type: string
      required: false
      in: header
      name: X-Bunq-Geolocation
    Cache-Control:
      description: The standard HTTP Cache-Control header is required for all signed requests.
      schema:
        type: string
      required: false
      in: header
      name: Cache-Control
    User-Agent:
      description: The User-Agent header field should contain information about the user agent originating the request. There are no restrictions on the value of this header.
      schema:
        type: string
      required: true
      in: header
      name: User-Agent
    X-Bunq-Client-Request-Id:
      description: This header must specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer.
      schema:
        type: string
      required: false
      in: header
      name: X-Bunq-Client-Request-Id
    X-Bunq-Region:
      description: The X-Bunq-Region header must contain the region (country) of the client device. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore.
      schema:
        type: string
      required: false
      in: header
      name: X-Bunq-Region
    X-Bunq-Language:
      description: The X-Bunq-Language header must contain a preferred language indication. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore. Currently only the languages en_US and nl_NL are supported. Anything else will default to en_US.
      schema:
        type: string
      required: false
      in: header
      name: X-Bunq-Language
    X-Bunq-Client-Authentication:
      description: The authentication token is used to authenticate the source of the API call. It is required by all API calls except for POST /v1/installation. It is important to note that the device and session calls are using the token from the response of the installation call, while all the other calls use the token from the response of the session-server call
      schema:
        type: string
      required: true
      in: header
      name: X-Bunq-Client-Authentication
  headers:
    X-Bunq-Server-Signature:
      description: The server's signature for this response. See the signing page for details on how to verify this signature.
      schema:
        type: string
    X-Bunq-Client-Request-Id:
      description: This header must specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer.
      schema:
        type: string
      required: false
    X-Bunq-Client-Response-Id:
      description: A unique ID for the response formatted as a UUID. Clients can use it to add extra protection against replay attacks.
      schema:
        type: string
  responses:
    GenericError:
      description: This is how the error response looks like for 4XX response codes
      headers:
        X-Bunq-Client-Response-Id:
          $ref: '#/components/headers/X-Bunq-Client-Response-Id'
        X-Bunq-Client-Request-Id:
          $ref: '#/components/headers/X-Bunq-Client-Request-Id'
        X-Bunq-Server-Signature:
          $ref: '#/components/headers/X-Bunq-Server-Signature'
      content:
        application/json:
          schema:
            type: object
            properties:
              Error:
                $ref: '#/components/schemas/Error'
x-provenance:
  method: harvested
  publisher: bunq
  source: https://raw.githubusercontent.com/bunq/doc/master/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)