---
title: "Create an attachment (payments-api provider contract)"
method: POST
path: "/v1/attachments"
tags: ["Attachments"]
---

# Create an attachment (payments-api provider contract)

`POST /v1/attachments`

## Request

- Base URL: `https://ewallets-api.paymongo.com`
- URL: `https://ewallets-api.paymongo.com/v1/attachments`
- Auth: HTTP bearer

Called by payments-api for each attach attempt. One-time and initial_subscription: succeeded with a redirect next_action when the wallet accepted (a payment, or a wallet link to verify), failed with a catalogue error_code when it declined (or the merchant is not configured). recurring_subscription: the charge on the saved link is answered in the call — succeeded with payment{paid}, failed with the code (and payment{failed}), or processing when Maya has not settled it. 400 merchant_invalid_state for what the merchant's setup cannot take (saving a wallet, manual capture, no redirect_url on a redirect flow, subscriptions while they are switched off or not enabled for the merchant). The same attach_attempt_id answers the stored attachment. organization_id must be the token's account and livemode must be the PayMongo-Livemode header. Test mode calls no wallet: redirect flows go to the test page, renewals are answered from the amount rule.

## Headers

- `PayMongo-Livemode` 'true' | 'false', required
- `PayMongo-Correlation-Id` string

## Request body

- AttachmentsCreateRequest
  - `amount` integer
  - `attach_attempt_id` string
  - `attachment_type` 'one_time' | 'vaulting' | 'vaulted' | 'initial_subscription' | 'recurring_subscription' | 'setup'
  - `capture_type` 'automatic' | 'manual' | 'multiple'
  - `currency` string
  - `expiry_seconds` integer
  - `livemode` boolean
  - `organization_id` string
  - `payment_intent_id` string
  - `payment_method_id` string
  - `redirect_url` string
  - `setup_intent_id` string

## Response `200`

OK

- AttachmentsResponse
  - `data` AttachmentsAttachment
    - `error_code` 'generic_decline' | 'blocked' | 'insufficient_funds' | 'limit_exceeded' | 'attempts_exceeded' | 'instrument_restricted' | 'customer_cancelled' | 'provider_unavailable' | 'provider_timeout' | 'processing_error' | 'internal_error' | 'provider_not_configured' | 'amount_invalid' | 'mode_mismatch' | 'suspected_fraud' | 'instrument_not_supported' | 'duplicate_transaction' | 'authorization_expired' | 'authentication_failed' | 'payment_expired' | 'instrument_invalid'
    - `error_detail` string
    - `expires_at` string
    - `id` string
    - `next_action` object
    - `payment` AttachmentsCreateAttachmentPayment
      - `authorized_amount` integer
      - `authorized_at` string
      - `captured_amount` integer
      - `captured_at` string
      - `metadata` object
      - `provider_transaction_reference` string
      - `status` 'paid' | 'failed'
    - `status` 'processing' | 'succeeded' | 'failed' | 'cancelled' | 'expired'

## Other responses

- `400`: invalid_request_body (a field payments-api built wrong, with source.pointer) or merchant_invalid_state (relayed to the merchant)
- `401`: Missing or invalid service token
- `500`: Internal server error

---

[API](https://skmtc.dev/paymongo/apis/ewallets.md) - [All operations](https://skmtc.dev/paymongo/apis/ewallets/llms.txt) - [OpenAPI document](https://skmtc.dev/paymongo/apis/ewallets/revisions/a445ca65c132?raw)