Skip to main content

BatchTransfer

Batch transfer information returned when creating or retrieving a batch of transfers.

idstringrequired

Batch transfer id.

Example: urn:batch-transfer:01KQCRBJHMAKZ5TC59AFY0SGTY
creationTimestring<date-time>required

Represents RFC 3339, section 5.6 date-time.

Example: 2021-07-15T17:54:12Z
updatedTimestring<date-time>required

Represents RFC 3339, section 5.6 date-time.

Example: 2021-07-15T17:54:12Z
expirationTimestring<date-time>required

Represents RFC 3339, section 5.6 date-time.

Example: 2021-07-15T17:54:12Z
merchantRefNumExternalId (string)

Customer identifier used in Partner system.

Possible values: non-empty and <= 40 characters

Example: af5c8b52-0afd-4799-85ab-fe659a076932
transferDetails objectrequired

Represents the details of a fee transfer.

reasonCustomerTransferReason (string)required

The actual purpose of the transfer.

  • INITIAL_BALANCE_MIGRATION - After customer onboarding, migrations of existing balances.
  • CRYPTO_BUY - The customer is buying crypto or other assets.
  • CRYPTO_SELL - The customer is selling crypto or other assets.
  • TRADING_PAIR - The transfer represents a trading pair transaction between customers with wallets.
  • DEPOSIT - Crediting the customer's wallet via non-Paysafe deposit options.
  • WITHDRAWAL - Debiting the customer's wallet via non-Paysafe withdrawal options.
  • MERCHANT_FEE - Charging a merchant fee.
  • REFUND - Refunding the customer on a previous transaction.
  • CANCELATION - Cancelation of a previous transaction.
  • BONUS - Customer is granted a bonus.
  • CURRENCY_EXCHANGE - Converting one currency to another.
  • PURCHASE - The customer is purchasing goods or services from a merchant.
  • PAYOUT - The merchant is compensating a customer for goods or services.
  • PEER_TRANSFER - Money transfer between customers with wallets.
  • CHEQUE - Money transfer between customer and merchant. To be used for cheque payment in future.
  • CHEQUE_WITHDRAWAL - Debiting the customer's wallet for cheque payment.
  • WALLET_CHECKOUT - Money transfer between customer and merchant. Used by Wallet Checkout.
  • OTHER - Any reason not explicitly mentioned in the transfers.

Possible values: [INITIAL_BALANCE_MIGRATION, CRYPTO_BUY, CRYPTO_SELL, TRADING_PAIR, DEPOSIT, WITHDRAWAL, MERCHANT_FEE, REFUND, CANCELATION, BONUS, CURRENCY_EXCHANGE, PURCHASE, PAYOUT, PEER_TRANSFER, CHEQUE, CHEQUE_WITHDRAWAL, WALLET_CHECKOUT, OTHER]

descriptionstring

Human readable description for the transfer.

Possible values: <= 400 characters

summary objectrequired

Summary of batch transfer statuses, fees, and amounts.

statuses object

Count of transfers per status. Keys are limited to PaymentStatus values. Zero values are not included in the object.

PREVIEWinteger

Count of transfers in PREVIEW status.

PENDINGinteger

Count of transfers in PENDING status.

PROCESSINGinteger

Count of transfers in PROCESSING status.

COMPLETEDinteger

Count of transfers in COMPLETED status.

FAILEDinteger

Count of transfers in FAILED status.

SCHEDULEDinteger

Count of transfers in SCHEDULED status.

ACCEPTEDinteger

Count of transfers in ACCEPTED status.

CANCELLEDinteger

Count of transfers in CANCELLED status.

REFUNDEDinteger

Count of transfers in REFUNDED status.

fees object[]

Aggregated fees for the batch.

  • Array [
    • amountinteger<int64>required

    Amount of the merchant payment, in mintor units. If currency is not specified, then the main transaction currency is used.

    Possible values: >= 0

    Default value: 0
    Example: 1000
    currencyCurrency (string)

    Currency alphabetic code as specified by ISO 4217

    Possible values: >= 3 characters and <= 3 characters

    Example: EUR
    paymentReasonFeePaymentReason (string)required

    Fee payment reason.

    • SENDER_FEE - Fee that will be applied to sender party of transfer collected into partner merchant wallet.
    • RECIPIENT_FEE - Fee that will be applied to recipient client of transfer collected into partner merchant wallet.
    • DEPOSIT_FEE - Fee charged for deposit transactions collected into partner merchant wallet.
    • WITHDRAWAL_FEE - Fee charged for withdrawal transactions collected into partner merchant wallet.
    • MERCHANT_FEE - Fee for the payment service collected into partner merchant wallet.
    • PAYSAFE_FEE - Fee collected by Paysafe for the provided payment service. Usually Paysafe Fee is not directly applied to customer transactions.
    • ATM_FEE - Fee for ATM service, when using prepaid cards.
    • FX_FEE - Fee applied, when payment requires currency exchange.
    • VAT_FEE - Consumer VAT fee (when applicable)
    • OTHER_FEE - It could be used for any additional, unspecified fees that may be applied to a transaction

    Possible values: [MERCHANT_FEE, ATM_FEE, FX_FEE, PAYSAFE_FEE, OTHER_FEE, SENDER_FEE, RECIPIENT_FEE, DEPOSIT_FEE, VAT_FEE, WITHDRAWAL_FEE]

    Default value: OTHER_FEE
  • ]
    • amounts object[]

    Total debited amount in minor units per currency.

  • Array [
    • amountinteger<int64>

    Total debited amount in minor units.

    Example: 1000
    currencyCurrency (string)

    Currency alphabetic code as specified by ISO 4217

    Possible values: >= 3 characters and <= 3 characters

    Example: EUR
  • ]
    • actionPayment Action (string)

    Specifies action required to complete to be able to continue to the next payment status:

    • NONE – No action is required, you can proceed to the next deposit status.
    • REDIRECT – The user must be redirected in order to complete a payment, for example, when an alternate payment method like Paysafecard is used.
    • SCA - The user must complete a Strong Customer Authentication (SCA) process.
    • ONBOARD - A transfer-specific action is required. The recipient customer must be registered with the corresponding email address.
    • USER_INPUT - Additional information from the user is required to complete the payment.

    Possible values: [NONE, REDIRECT, SCA, ONBOARD, USER_INPUT]

    Default value: NONE
    Example: NONE
    scaDetails object

    SCA authentication details, including information about the authentication process. It should be present in the response of any wallet operation that requires it due to PSD2 regulatory requirements.

    • Present in the response - operation requires SCA authentication, and the user should proceed with the SCA process.
    • Not present in the response - operation does not require SCA authentication and is authorized to proceed.
    eventIdstringrequired

    The distinct identifier for the SCA authentication event.

    Example: 06bdcd2c-0cce-4b36-97ec-281c8f5d743c
    walletOperationIdstringrequired

    The distinct identifier for the wallet operation. This identifier is used to associate the wallet operation with the SCA authentication event.

    Example: a5865fd6-18c2-45a8-9953-1c00eac36c36
    authenticationModeSCA Authentication Mode (string)required

    Mode of the Strong Customer Authentication (SCA) authentication process.

    • OUTSOURCED - The partner is responsible for handling the entire SCA process.
    • EMBEDDED - Paysafe is responsible for handling the entire SCA process, including user authentication and compliance with regulations like PSD2.
    • HYBRID - Paysafe manages the entire SCA process, excluding the communication with the end-user.

    Possible values: [OUTSOURCED, EMBEDDED, HYBRID]

    Example: OUTSOURCED
    availableVerificationsobject[]

    List of available verifications for the SCA authentication event. If none are specified, the user can proceed with any agreed-upon verification method.

    creationTimestring<date-time>required

    Represents RFC 3339, section 5.6 date-time.

    Example: 2021-07-15T17:54:12Z
    expirationTimestring<date-time>

    Represents RFC 3339, section 5.6 date-time.

    Example: 2021-07-15T17:54:12Z
    statusPayment Status (string)required

    The payment status:

    • PREVIEW - Payment preview.
    • PENDING - Payment transaction is created and further action is required by the customer.
    • PROCESSING - Payment is scheduled for processing by the payment provider.
    • COMPLETED - Payment is completed. Note that some transactions might be completed from Embedded Wallet point of view, but not from customer point of view, since money movement might take some time outside of the Embedded Wallet network.
    • FAILED - Payment has failed. Check STATUS_REASON property for details.
    • CANCELLED - Payment have been cancelled
    • REFUNDED - Payment has been refunded. Valid only for deposits.
    • SCHEDULED - Payment is scheduled funds are blocked, but some action is required. Check action response object property for details
    • ACCEPTED - Payment has been accepted by the recipient and will be automatically processed.

    Possible values: [PREVIEW, PENDING, PROCESSING, COMPLETED, FAILED, SCHEDULED, ACCEPTED, CANCELLED, REFUNDED]

    Example: FAILED
    nextStatusPayment Status (string)[]

    Provides the next possible status update the client can request, depending on the chosen payment type and option.

    Possible values: [PREVIEW, PENDING, PROCESSING, COMPLETED, FAILED, SCHEDULED, ACCEPTED, CANCELLED, REFUNDED]

    BatchTransfer
    {
      "id": "urn:batch-transfer:01KQCRBJHMAKZ5TC59AFY0SGTY",
      "creationTime": "2021-07-15T17:54:12Z",
      "updatedTime": "2021-07-15T17:54:12Z",
      "expirationTime": "2021-07-15T17:54:12Z",
      "merchantRefNum": "af5c8b52-0afd-4799-85ab-fe659a076932",
      "transferDetails": {
        "reason": "INITIAL_BALANCE_MIGRATION",
        "description": "string"
      },
      "summary": {
        "statuses": {
          "PREVIEW": 2
        },
        "fees": [
          {
            "amount": 1000,
            "currency": "EUR",
            "paymentReason": "OTHER_FEE"
          }
        ],
        "amounts": [
          {
            "amount": 1000,
            "currency": "EUR"
          }
        ]
      },
      "action": "NONE",
      "scaDetails": {
        "eventId": "06bdcd2c-0cce-4b36-97ec-281c8f5d743c",
        "walletOperationId": "a5865fd6-18c2-45a8-9953-1c00eac36c36",
        "authenticationMode": "OUTSOURCED",
        "availableVerifications": [
          {
            "method": "OTP",
            "channel": "SMS",
            "target": "jo***@example.com",
            "action": {
              "language": "en",
              "returnUrl": "https://some-process.paysafe.com/",
              "redirectUrl": "https://some-process.paysafe.com/"
            }
          }
        ],
        "creationTime": "2021-07-15T17:54:12Z",
        "expirationTime": "2021-07-15T17:54:12Z"
      },
      "status": "FAILED",
      "nextStatus": [
        "FAILED"
      ]
    }