---
title: "transaction"
method: POST
path: "/v2/transaction"
tags: ["Create & Manage Transactions"]
---

# transaction

`POST /v2/transaction`

Create an Aeropay Transaction Object where funds will move from a user to a merchant.

The `userForMerchant` token specifies the paying user. The merchant being paid is specified by the `merchantId` in the request body. The user's default bank account will be selected if no `bankAccountId` is specified.

**Attributes** are AeroPay formatted data that you may wish to include with your transaction. For example, an invoice number or the tracking of a tip amount.

**NOTE:** Tip amounts will be added to the 'amount' value.

<details>
<summary><strong>Error Glossary</strong> (click to expand)</summary>

| Code | HTTP Status | Message |
|------|-------------|-------------|
| `AP101` | 401 | No authenticated user |
| `AP103` | 200 | Unable to set user reputation level |
| `AP109` | 200 | Delinquent activity on account |
| `AP110` | 200 | User profile incomplete |
| `AP114` | 200 | Account restricted by merchant |
| `AP201` | 200 | No merchant found for merchant id |
| `AP203` | 200 | Unable to get location for merchant |
| `AP205` | 200 | Unable to get rewards and fees for merchant |
| `AP206` | 200 | Unable to get merchant account |
| `AP300` | 200 | Unable to connect to bank |
| `AP302` | 200 | Insufficient funds |
| `AP303` | 200 | Transaction missing location |
| `AP304` | 200 | Transaction amount exceeds limit |
| `AP306` | 200 | Insufficient balance |
| `AP307` | 200 | Payment declined  -  try a lower amount |
| `AP308` | 200 | Invalid amount |
| `AP314` | 200 | Transaction already exists |
| `AP315` | 200 | Payment rejected  -  threshold or suspended bank |
| `AP400` | 200 | No bank account linked |
| `AP401` | 400 | Cannot validate bank account |
| `AP402` | 200 | No bank account for merchant |
| `AP403` | 200 | Bank not supported |
| `AP404` | 200 | Invalid routing number |
| `AP411` | 200 | Invalid account type  -  connect a checking account |
| `AP412` | 200 | Bank account already removed |
| `AP700` | 400 | Missing or invalid required parameter |
| `AP701` | 400 | Improperly formatted parameter |
| `AP1400` | 400 | Idempotency key reused with different payload |
| `AP1401` | 400 | Request with same idempotency key still processing |
| `AP1402` | 400 | Invalid idempotency key structure |

</details>

## Headers

- `Content-Type` string, required
- `authorization` string, required
- `Idempotency-Key` string, uuid

## Request body

- object
  - `bankAccountId` integer — default bank account for the user will be used if not specified
  - `merchantId` integer, required — MerchantId
  - `amount` object, required — Dictionary with currency and amount in pennies. Only USD supported at this time
    - `amount` integer — Payment amount in pennies
    - `currency` string — Currency. Currently only supports USD
  - `referenceId` string — Merchant reference id of transaction
  - `attributes` object — Dictionary with attributes. Tip and invoice are standard formats. Custom attributes must follow value/description dictionary formatting.
    - `CUSTOM ATTRIBUTE` object
      - `value` string — Value identifier of custom attribute
      - `description` string — Description of custom attribute
    - `invoice` object
      - `value` string — Value identifier of invoice
      - `description` string — Description of invoice
    - `tip` object
      - `tipAmount` string — Required. Amount of tip, in format XX.XX
      - `label` string — Required. String representation of tip, including $
      - `totalAmount` string — Required. Amount + tip, in format XX.XX. This can be used for reconciliation and to guarantee accurate amount value

## Response `200`

Success or Business Logic Error

- union
  - TransactionResponse
    - `transaction` object
      - `id` string
      - `amount` object
        - `amount` integer
        - `currency` string
      - `status` string
      - `paymentType` string
      - `userId` string
      - `title` string
      - `referenceId` string
      - `attributes` object[]
      - `isRtp` boolean
      - `merchantId` integer
      - `locationId` integer
      - `userAccountId` integer
  - 200failure
    - `error` object
      - `code` string
      - `message` string
      - `help` string — Support contact information

## Other responses

- `400` — Bad Request - Validation Errors

---

[API](https://skmtc.net/aero/apis/aeropay-v2-api.md) · [All operations](https://skmtc.net/aero/apis/aeropay-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aero/aeropay-v2-api/revisions/4700c4ceeaad/schema)