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

# Send a payment

> Pays a recipient from one of your accounts. The amount is reserved first; if the payment network refuses, the reservation is released and your balance is as it was.

**A `201` means the payment was accepted, not that it has arrived.** Read `status`:

| `status` | Meaning |
| --- | --- |
| `pending`, `processing` | Accepted. The money hasn't moved yet. |
| `successful` | The money has left your account. |
| `failed` | It didn't go. The reserved amount is released. `failureReason` says why. |
| `reversed` | It left and came back. |

A `200` means this idempotency key already named a payment, which is returned rather than sent again.

If the destination receives a different currency from the source account, [create an FX quote](/api-reference/payments/create-an-fx-quote) first and pass `fxQuoteId`.

A `202` means one of your approval policies holds the payment. The money is set aside and nothing is sent until it is approved.

Requires the `payments:write` scope.



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/transfers
openapi: 3.1.0
info:
  title: Talescria API
  version: 1.0.0
  description: >-
    Accounts, recipients, payments, transfers between your accounts, payment
    links, customers and invoices. Authenticate with an access token from your
    OAuth client.
servers:
  - url: https://api.talescria.com
    description: Production (test and live keys)
security:
  - bearerAuth: []
tags:
  - name: Accounts
    description: Your accounts and their balances.
  - name: Recipients
    description: People and businesses you pay, and where to pay them.
  - name: Payments
    description: Paying recipients, including across currencies.
  - name: Transfers
    description: Moving money between your own accounts.
  - name: Payment links
    description: Links anyone can open to pay you by card.
  - name: Customers
    description: People and businesses who pay you.
  - name: Invoices
    description: One-off invoices and recurring series.
paths:
  /v1/transfers:
    post:
      tags:
        - Payments
      summary: Send a payment
      description: >-
        Pays a recipient from one of your accounts. The amount is reserved
        first; if the payment network refuses, the reservation is released and
        your balance is as it was.


        **A `201` means the payment was accepted, not that it has arrived.**
        Read `status`:


        | `status` | Meaning |

        | --- | --- |

        | `pending`, `processing` | Accepted. The money hasn't moved yet. |

        | `successful` | The money has left your account. |

        | `failed` | It didn't go. The reserved amount is released.
        `failureReason` says why. |

        | `reversed` | It left and came back. |


        A `200` means this idempotency key already named a payment, which is
        returned rather than sent again.


        If the destination receives a different currency from the source
        account, [create an FX
        quote](/api-reference/payments/create-an-fx-quote) first and pass
        `fxQuoteId`.


        A `202` means one of your approval policies holds the payment. The money
        is set aside and nothing is sent until it is approved.


        Requires the `payments:write` scope.
      operationId: sendTransfer
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendTransfer'
            examples:
              invoice:
                summary: Paying an invoice
                value:
                  fromAccountId: acct_01M2P8GP7RSDXN81CXRFM2HFV7
                  recipientId: rcp_9f2c1e4a7b8d4e0f9a1b2c3d4e5f6071
                  destinationId: dst_4a7b8d4e0f9a1b2c3d4e5f60719f2c1e
                  minorUnits: '125000'
                  currency: GBP
                  narration: July invoice
                  idempotencyKey: form_7c1e4a7b8d4e
      responses:
        '200':
          description: >-
            This `idempotencyKey` already named a transfer. Returned, not sent
            again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transfer:
                    $ref: '#/components/schemas/Transfer'
        '201':
          description: The instruction was accepted. Read `status` for whether money moved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transfer:
                    $ref: '#/components/schemas/Transfer'
        '202':
          description: Held for approval.
        '400':
          description: >-
            `VALIDATION`: A field is missing or malformed. `message` says which.


            `IDEMPOTENCY_KEY_REQUIRED`: This operation needs an
            `Idempotency-Key` header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            `UNAUTHENTICATED`: The access token is missing, expired or revoked.
            Get a new token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            `INSUFFICIENT_FUNDS`: The account doesn't have enough available
            balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            `BLOCKED`: Compliance screening refused this payment.


            `ENVIRONMENT_UNAVAILABLE`: Live mode isn't available until your
            account is approved.


            `INSUFFICIENT_SCOPE`: Your API key lacks the scope this operation
            needs. The scope is named in `message` and the `WWW-Authenticate`
            header.


            `ENVIRONMENT_MISMATCH`: The request named a different environment
            from the key's.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            `NOT_FOUND`: It doesn't exist, or isn't yours. The answer is the
            same for both.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `REVIEW`: Compliance screening wants a person to look at this
            payment. Nothing was reserved or sent.


            `NOT_VERIFIED`: Your account hasn't finished verification. Finish
            onboarding, then retry.


            `IDEMPOTENCY_IN_PROGRESS`: A request with this `Idempotency-Key` is
            still running. Retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            `UNSUPPORTED`: This can't work as asked, for example an unsupported
            currency, corridor or account. `message` says why.


            `REJECTED`: The payment network rejected the recipient's or
            destination's details. `message` has its words. Sending again
            unchanged will fail the same way.


            `IDEMPOTENCY_KEY_REUSED`: This `Idempotency-Key` was used for a
            different request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`RATE_LIMITED`: Too many requests. Wait for `Retry-After` seconds.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: >-
            `MISCONFIGURED`: Something is wrong on our side. Contact support
            with the `x-request-id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: >-
            `UPSTREAM_ERROR`: A service we depend on answered unexpectedly.
            Retry, and contact support with the `x-request-id` if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: '`UPSTREAM_UNAVAILABLE`: Temporarily unavailable. Retry with backoff.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  parameters:
    IdempotencyKeyRequired:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        A unique key for this operation. Send the same key when you retry it.
        Kept for 24 hours.
      schema:
        type: string
        minLength: 8
        maxLength: 255
        pattern: ^[A-Za-z0-9_\-:.]+$
  schemas:
    SendTransfer:
      type: object
      required:
        - fromAccountId
        - recipientId
        - destinationId
        - minorUnits
        - currency
      properties:
        fromAccountId:
          type: string
          description: The account to pay from, as returned by List accounts.
        recipientId:
          type: string
        destinationId:
          type: string
          description: >-
            One of the recipient's destinations. Retrieve a recipient to list
            them.
        minorUnits:
          type: string
          pattern: ^\d+$
          description: >-
            Integer minor units, as a **string**. Not a number: JSON numbers
            lose precision above 2^53, and an amount is the last thing that
            should discover that.
          example: '125000'
        currency:
          type: string
          description: Upper-cased for you.
        narration:
          type: string
          maxLength: 200
          description: >-
            What the recipient sees on their statement, where the rail carries
            one.
        reason:
          type: string
          maxLength: 64
          description: >-
            Why they're being paid: one of List payment reasons. Some
            destinations require it.
          example: goods_purchased
        idempotencyKey:
          type: string
          maxLength: 200
          description: >-
            Optional with an API key: the `Idempotency-Key` header is used when
            you leave it out.
        fxQuoteId:
          type: string
          description: >-
            An FX quote, required when the destination receives a currency the
            account doesn't hold. `minorUnits` must equal the quote's
            `amountFromMinorUnits`.
    Transfer:
      type: object
      required:
        - id
        - fromAccountId
        - destinationId
        - minorUnits
        - currency
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        fromAccountId:
          type: string
        recipientId:
          type: string
          description: Returned when the payment is sent; absent on reads.
        destinationId:
          type: string
        minorUnits:
          type: string
          description: Integer minor units as a string.
        currency:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - successful
            - failed
            - reversed
          description: >-
            `pending` and `processing`: accepted, money hasn't moved.
            `successful`: it left. `failed`: it didn't, and the reservation was
            released. `reversed`: it left and came back.
        narration:
          type: string
        reason:
          type: string
          description: Why it was paid, as `SendTransfer.reason`.
        failureReason:
          type: string
          description: Why it failed, in the payment network's words.
        createdAt:
          type: integer
          format: int64
          description: Epoch milliseconds.
        updatedAt:
          type: integer
          format: int64
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Branch on this, not on `message`. See Errors.
            message:
              type: string
              description: For people. Wording can change.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An access token (`at_test_…` or `at_live_…`) from `POST
        https://idp.talescria.com/oauth/token`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.