Skip to content

Transfer Attempts

When a user attempts to make a payment using a Checkout Form or Payment Link, or a recipient submitting details with a Payout Link—a Transfer Attempt is created.

Using transfer attempts, you can track the lifecycle of a payment or a series of payments if you are using a multi-use Payment Link.

A Transfer Attempt records the original entity_id and the resulting transfer_id (or authorization_id for payment links that authorize a payment).

You cannot create transfer attempts directly. They are created automatically when a user submits a form using one of these methods.

Key Details

  • Relationship to Transfers: Each payment using a Checkout Form or Payment Link creates a Transfer with a corresponding Transfer Attempt to track it. Multiple transfers can occur when buyers retry failed payments or when multiple buyers use a multi-use payment link. Payout links create a Transfer for each payout, with a corresponding Transfer Attempt to track it.
  • Relationship to Authorizations: Payment links configured to authorize a payment reference the resulting Authorization instead of a Transfer.
  • 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.