---
title: "Create a payment transaction"
method: POST
path: "/payments/transactions"
tags: ["Transactions"]
---

# Create a payment transaction

`POST /payments/transactions`

Use this endpoint to create a payment transaction. You can find sample code in our public Postman collection, or build it in the adjacent API explorer. The link to our postman collection is: [https://www.postman.com/meldeng/workspace/meld-io-public-api-collection](https://www.postman.com/meldeng/workspace/meld-io-public-api-collection)

**IDEMPOTENT REQUESTS**: Please refer to [Idempotency Key](https://docs.meld.io/docs/idempotency-key)

**PASSTHROUGH ENABLED REQUESTS**: Please refer to [Passthrough Headers](https://docs.meld.io/docs/credential-passthrough)

**ERRORS**: Please refer to [Error Responses](https://docs.meld.io/docs/fiat-error-responses)

## Headers

- `X-Idempotency-Key` string, uuid
- `Meld-Passthrough-Reference` string
- `Meld-Passthrough-Key-Id` string
- `Meld-Passthrough-Key-Public` string
- `Meld-Passthrough-Key-Private` string
- `Meld-Passthrough-Oauth` string

## Request body

- PaymentTransactionRequest
  - `3ds` ThreeDeeEssInput
    - `enabled` boolean
  - `capture` boolean — Should the payment be captured immediately, if set to false an authorization will be performed instead
  - `customer` CustomerInput
    - `addresses` CustomerAddressInput[] — Your customer's addresses, such as BILLING, SHIPPING, RESIDENCE, etc.
      - `addressDetails` CustomerAddressDetails
        - `addressDetailsFields` object
        - `city` string — City, district, suburb, town, or village
        - `country` string — Two-letter country code (ISO 3166-1 alpha-2)
        - `firstName` string — The first name on the address
        - `lastName` string — The last name on the address
        - `lineOne` string — Address line 1 (e.g., street, PO Box, or company name)
        - `lineTwo` string — Address line 2 (e.g., apartment, suite, unit, or building)
        - `postalCode` string — ZIP or postal code
        - `region` string — State, county, province, or region
      - `type` 'BILLING' | 'SHIPPING' | 'RESIDENCE' — Address type such as BILLING, SHIPPING, RESIDENCE, etc.
    - `billingAddress` CustomerAddressInput
      - `addressDetails` CustomerAddressDetails
        - `addressDetailsFields` object
        - `city` string — City, district, suburb, town, or village
        - `country` string — Two-letter country code (ISO 3166-1 alpha-2)
        - `firstName` string — The first name on the address
        - `lastName` string — The last name on the address
        - `lineOne` string — Address line 1 (e.g., street, PO Box, or company name)
        - `lineTwo` string — Address line 2 (e.g., apartment, suite, unit, or building)
        - `postalCode` string — ZIP or postal code
        - `region` string — State, county, province, or region
      - `type` 'BILLING' | 'SHIPPING' | 'RESIDENCE' — Address type such as BILLING, SHIPPING, RESIDENCE, etc.
    - `billingAddressDetails` CustomerAddressDetails
      - `addressDetailsFields` object
      - `city` string — City, district, suburb, town, or village
      - `country` string — Two-letter country code (ISO 3166-1 alpha-2)
      - `firstName` string — The first name on the address
      - `lastName` string — The last name on the address
      - `lineOne` string — Address line 1 (e.g., street, PO Box, or company name)
      - `lineTwo` string — Address line 2 (e.g., apartment, suite, unit, or building)
      - `postalCode` string — ZIP or postal code
      - `region` string — State, county, province, or region
    - `email` string, email — Your customer's email address.
    - `externalId` string — Your (optional) Id for this customer, for example an id or reference from your database which you may supply during customer creation
    - `id` string — Meld's internal Id for the Customer
    - `name` CustomerName
      - `firstName` string — Your customer's first name
      - `lastName` string — Your customer's last name
    - `nameEmpty` boolean
    - `nameJSONB` unknown
    - `nameOrEmptyString` string
    - `nameOrNull` string
    - `phone` string — Your customer's phone number
    - `residenceAddress` CustomerAddressInput
      - `addressDetails` CustomerAddressDetails
        - `addressDetailsFields` object
        - `city` string — City, district, suburb, town, or village
        - `country` string — Two-letter country code (ISO 3166-1 alpha-2)
        - `firstName` string — The first name on the address
        - `lastName` string — The last name on the address
        - `lineOne` string — Address line 1 (e.g., street, PO Box, or company name)
        - `lineTwo` string — Address line 2 (e.g., apartment, suite, unit, or building)
        - `postalCode` string — ZIP or postal code
        - `region` string — State, county, province, or region
      - `type` 'BILLING' | 'SHIPPING' | 'RESIDENCE' — Address type such as BILLING, SHIPPING, RESIDENCE, etc.
    - `residenceAddressDetails` CustomerAddressDetails
      - `addressDetailsFields` object
      - `city` string — City, district, suburb, town, or village
      - `country` string — Two-letter country code (ISO 3166-1 alpha-2)
      - `firstName` string — The first name on the address
      - `lastName` string — The last name on the address
      - `lineOne` string — Address line 1 (e.g., street, PO Box, or company name)
      - `lineTwo` string — Address line 2 (e.g., apartment, suite, unit, or building)
      - `postalCode` string — ZIP or postal code
      - `region` string — State, county, province, or region
    - `shippingAddress` CustomerAddressInput
      - `addressDetails` CustomerAddressDetails
        - `addressDetailsFields` object
        - `city` string — City, district, suburb, town, or village
        - `country` string — Two-letter country code (ISO 3166-1 alpha-2)
        - `firstName` string — The first name on the address
        - `lastName` string — The last name on the address
        - `lineOne` string — Address line 1 (e.g., street, PO Box, or company name)
        - `lineTwo` string — Address line 2 (e.g., apartment, suite, unit, or building)
        - `postalCode` string — ZIP or postal code
        - `region` string — State, county, province, or region
      - `type` 'BILLING' | 'SHIPPING' | 'RESIDENCE' — Address type such as BILLING, SHIPPING, RESIDENCE, etc.
    - `shippingAddressDetails` CustomerAddressDetails
      - `addressDetailsFields` object
      - `city` string — City, district, suburb, town, or village
      - `country` string — Two-letter country code (ISO 3166-1 alpha-2)
      - `firstName` string — The first name on the address
      - `lastName` string — The last name on the address
      - `lineOne` string — Address line 1 (e.g., street, PO Box, or company name)
      - `lineTwo` string — Address line 2 (e.g., apartment, suite, unit, or building)
      - `postalCode` string — ZIP or postal code
      - `region` string — State, county, province, or region
  - `customerId` string — Meld's internal Id for the Customer
  - `description` string — A description about the transaction
  - `externalCustomerId` string — Your (optional) Id for this customer, for example an id or reference from your database which you may supply during customer creation
  - `nonce` string — A payment method nonce is a secure, one-time-use reference to payment information. It's the key element that allows your server to communicate sensitive payment information to the service provider without ever touching the raw data.
  - `paymentMethod` PaymentMethodInput — PaymentMethod objects represent your customer's payment instruments
    - `details` union, required — [Details of the payment method used for this transaction](https://docs.meld.io/docs/payment-methods-and-tokenization)
      - object — Credit card details
        - `cvc` string, required — Card CVC
        - `expiration` CardExpiration
          - `month` integer — Integer value for the expiration month
          - `year` integer — Integer value for the expiration year
        - `name` string — The cardholder's name
        - `number` string, required — Card number
      - object — ACH details
        - `accountNumber` string, required — Account number
        - `accountType` 'BUSINESS_CHECKING' | 'CHECKING' | 'SAVINGS', required — Bank account type
        - `name` Name
          - `firstName` string, required
          - `lastName` string, required
        - `routingNumber` string, required — Routing number
      - object — Meld payment token details
        - `meldPaymentToken` string, required — Meld Payment Token
    - `type` 'ACH' | 'CARD' | 'MELD_PAYMENT_TOKEN' | 'PLAID_TRANSFER_AUTHORIZATION', required — Payment method type used for this transaction, some methods may only apply for some providers, e.g. PLAID_TRANSFER_AUTHORIZATION for PLAID
  - `serviceProvider` 'AUTHORIZENET' | 'BRAINTREE' | 'CHECKOUT' | 'CIRCLE' | 'NMI' | 'STRIPE' — The service provider used for this transaction. Required when using a nonce or passthrough credentials, as they are tied to a specific service provider. Do not pass this in if you would like to use [routing](https://docs.meld.io/docs/routing-overview#payments-routing) to select a service provider.
  - `serviceProviderDetails` object — Provider specific details which may can be provided for this transaction, if supported by the Service Provider. For example, you can set a custom billing descriptor for your transaction using Checkout.com
  - `sourceAmount` string, required — Amount intended to be collected by this payment
  - `sourceCurrencyCode` string, required — Three-letter ISO currency code, in lowercase. Must be a supported currency

## Response `201`

Payment transaction created successfully

## Other responses

- `400` — Bad Request : check request values and format
- `401` — Invalid credentials
- `403` — Unauthenticated or authenticated with insufficient access
- `425` — It is too early for a retry
- `500` — Internal Error

---

[API](https://skmtc.net/meld/apis/bank-linking.md) · [All operations](https://skmtc.net/meld/apis/bank-linking/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/meld/bank-linking/versions/818d6079a611/schema)