Skip to content

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 or Payment Link, or a recipient submitting details with a Payout Link—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.

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 and 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.

{
  "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", 
        "payment_instrument_id": "PI7AS61AmsnJQ5Y7sL7dM1Ux",
        "entity_id": "checkout_form_ciADaDNMFAHdyNbDPuByS", 
        "entity_type": "CHECKOUT_FORM", 
        "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 webhook. Refer to the Webhooks API reference 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}).

  4. Using the transfer_id, send a request to the PUT /transfers/transfer_id endpoint to update the Transfer with the entity's tags.