# Transfer Attempts A `Transfer Attempt` tracks the initiation and progression of a payment using a `Checkout Form`, `Payment Link`, or a payout using a `Payout Link`. Each is referred to by the `Transfer Attempt` as the initiating "entity". You cannot create transfer attempts directly. They are created automatically when a user submits a form using one of these methods. When a user submits a form—such as a user using a [Checkout Form](/guides/online-payments/low-code-no-code/checkout-pages) or [Payment Link](/guides/online-payments/low-code-no-code/payment-links), or a recipient submitting details with a [Payout Link](http://127.0.0.1:4000/guides/payouts/payout-links)—a `Transfer Attempt` is created. This records the original `entity_id` and the resulting `transfer_id` (or `authorization_id` for payment links that authorize a payment). ## Key Details - **Relationship to Transfers**: Entities generate a single `Transfer`. Multi-use payment links can generate multiple transfers over time. Checkout forms and payment links are single-use and create one `Transfer` resource. Payment links used to authorize a payment reference the resulting `Authorization`. - **Multiple Attempts**: Entities can generate several transfer attempts, such as when users retry invalid payment details or multiple users submit payments (multi-use payment links only). - **Every Transfer Attempt contains two main identifiers**: `transfer_id` (points to the `Transfer`) and `entity_id` that references the entity that initiated the payment. An `authorization_id` is present for payment links that authorize a payment. ## How Checkout Form, Payment Link, or Payout Links Relate to Transfer Attempts and Transfers Here’s how checkout Forms, payment Links, and payout links relate to transfer attempts and transfers: 1. **Checkout Form, Payment Link, or Payout Link:** These entities allow users enter payment details. Multi-use payment links allow multiple submissions, each creating a new `Transfer Attempt` and `Transfer`. Checkout forms and payout links are single-use, creating only one `Transfer Attempt` and `Transfer`. 2. **Transfer Attempt:** Each payment attempt creates a `Transfer Attempt` resource that contains: - The originating entity (via the `entity_id` field) - The resulting `Transfer` (via the `transfer_id` field) This structure lets you trace each `Transfer` back to its originating entity. You can see every attempt, whether it succeeded or not, for that entity. 3. **Transfer:** This is the final payment resource created if a transfer attempt is successful. Transfer Attempts ## Transfer Attempt States When a user submits a form, the system creates a `Transfer Attempt` in `PENDING` state. If the payment is accepted, the state changes to `SUCCEEDED`. If it fails, it changes to `FAILED`. ## Transfer Attempt Webhooks Users often want to track the relationships between entities and the resulting transfers. The best approach is to subscribe to the [Transfer Attempt - Created](/additional-resources/developers/webhooks/webhook-events#transfer-attempt-created) and [Transfer Attempt - Updated](/additional-resources/developers/webhooks/webhook-events#transfer-attempt-updated) webhooks. These webhooks provide both `entity_id` and `transfer_id`, allowing you to associate a `Transfer` with the original entity. For example, when listening to the `Transfer Attempt - Created` webhook, the payload will show the `transfer_id` and `entity_id`. The `entity_type` field indicates whether the entity is a `Checkout Form`, `Payment Link`, or `Payout Link`. ```json { "type": "created", "entity": "transfer_attempt", "occurred_at": "2020-04-29T20:31:32.348", "_embedded": { "transfer_attempts": [ { "id": "transfer_attempt_ciACBK59kDhfx2Mi4Vy81", "created_at": "2024-12-27T05:52:07.44Z", "updated_at": "2024-12-27T05:52:07.44Z", "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "amount": 200, "currency": "USD", "state": "SUCCEEDED", "payment_frequency": "ONE_TIME", "transfer_id": "TRodANv8j3CVRUQz4sgZa8sK", // [!code highlight] "payment_instrument_id": "PI7AS61AmsnJQ5Y7sL7dM1Ux", "entity_id": "checkout_form_ciADaDNMFAHdyNbDPuByS", // [!code highlight] "entity_type": "CHECKOUT_FORM", // [!code highlight] "buyer_details": { "first_name": "", "last_name": "", "email": "test@gmail.com", "identity_id": "IDew6Bkcj1AwEP2aWhjjfdqS", "phone": null, "billing_address": null, "shipping_address": { "city": null, "country": "USA", "line1": null, "line2": null, "postal_code": null, "region": null } }, "failure_code": null, "failure_message": null, "tags": {}, "recipient_details": null, "operation_key": "SALE", "type": "DEBIT", "recipient_merchant_id": null, "receipt_requested_delivery_methods": [ { "type": "EMAIL", "destinations": ["test@gmail.com"] } ], "additional_buyer_charges": null, "amount_requested": 200 } ] } } ``` ## Propagating Tags to Transfers Tags are often used on checkout forms, payment links, and payout links to store reference data, such as invoice numbers. These tags do not copy to the `Transfer`. Tags stay with the entity where they are added. *To synchronize tags onto the resultant transfers*: 1. Subscribe to the [Transfer Attempt - Created](/additional-resources/developers/webhooks/webhook-events#transfer-attempt-created) webhook. Refer to the [Webhooks API reference](/api/webhooks) for more information on how to subscribe to webhooks. 2. When you get a webhook, record the `entity_id` (form or link ID) and the `transfer_id`. 3. Use the `entity_id` to query the entity and extract the tags (e.g., [GET /checkout_forms/{checkout_form_id}](/api/checkout-forms/getcheckoutform)). 4. Using the `transfer_id`, send a request to the [PUT /transfers/transfer_id](/api/transfers/updatetransfer) endpoint to update the `Transfer` with the entity's tags.